1@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001, 2@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 3@c Free Software Foundation, Inc. 4@c This is part of the GCC manual. 5@c For copying conditions, see the file gcc.texi. 6 7@node Target Macros 8@chapter Target Description Macros and Functions 9@cindex machine description macros 10@cindex target description macros 11@cindex macros, target description 12@cindex @file{tm.h} macros 13 14In addition to the file @file{@var{machine}.md}, a machine description 15includes a C header file conventionally given the name 16@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}. 17The header file defines numerous macros that convey the information 18about the target machine that does not fit into the scheme of the 19@file{.md} file. The file @file{tm.h} should be a link to 20@file{@var{machine}.h}. The header file @file{config.h} includes 21@file{tm.h} and most compiler source files include @file{config.h}. The 22source file defines a variable @code{targetm}, which is a structure 23containing pointers to functions and data relating to the target 24machine. @file{@var{machine}.c} should also contain their definitions, 25if they are not defined elsewhere in GCC, and other functions called 26through the macros defined in the @file{.h} file. 27 28@menu 29* Target Structure:: The @code{targetm} variable. 30* Driver:: Controlling how the driver runs the compilation passes. 31* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}. 32* Per-Function Data:: Defining data structures for per-function information. 33* Storage Layout:: Defining sizes and alignments of data. 34* Type Layout:: Defining sizes and properties of basic user data types. 35* Registers:: Naming and describing the hardware registers. 36* Register Classes:: Defining the classes of hardware registers. 37* Old Constraints:: The old way to define machine-specific constraints. 38* Stack and Calling:: Defining which way the stack grows and by how much. 39* Varargs:: Defining the varargs macros. 40* Trampolines:: Code set up at run time to enter a nested function. 41* Library Calls:: Controlling how library routines are implicitly called. 42* Addressing Modes:: Defining addressing modes valid for memory operands. 43* Anchored Addresses:: Defining how @option{-fsection-anchors} should work. 44* Condition Code:: Defining how insns update the condition code. 45* Costs:: Defining relative costs of different operations. 46* Scheduling:: Adjusting the behavior of the instruction scheduler. 47* Sections:: Dividing storage into text, data, and other sections. 48* PIC:: Macros for position independent code. 49* Assembler Format:: Defining how to write insns and pseudo-ops to output. 50* Debugging Info:: Defining the format of debugging output. 51* Floating Point:: Handling floating point for cross-compilers. 52* Mode Switching:: Insertion of mode-switching instructions. 53* Target Attributes:: Defining target-specific uses of @code{__attribute__}. 54* Emulated TLS:: Emulated TLS support. 55* MIPS Coprocessors:: MIPS coprocessor support and how to customize it. 56* PCH Target:: Validity checking for precompiled headers. 57* C++ ABI:: Controlling C++ ABI changes. 58* Named Address Spaces:: Adding support for named address spaces 59* Misc:: Everything else. 60@end menu 61 62@node Target Structure 63@section The Global @code{targetm} Variable 64@cindex target hooks 65@cindex target functions 66 67@deftypevar {struct gcc_target} targetm 68The target @file{.c} file must define the global @code{targetm} variable 69which contains pointers to functions and data relating to the target 70machine. The variable is declared in @file{target.h}; 71@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is 72used to initialize the variable, and macros for the default initializers 73for elements of the structure. The @file{.c} file should override those 74macros for which the default definition is inappropriate. For example: 75@smallexample 76#include "target.h" 77#include "target-def.h" 78 79/* @r{Initialize the GCC target structure.} */ 80 81#undef TARGET_COMP_TYPE_ATTRIBUTES 82#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes 83 84struct gcc_target targetm = TARGET_INITIALIZER; 85@end smallexample 86@end deftypevar 87 88Where a macro should be defined in the @file{.c} file in this manner to 89form part of the @code{targetm} structure, it is documented below as a 90``Target Hook'' with a prototype. Many macros will change in future 91from being defined in the @file{.h} file to being part of the 92@code{targetm} structure. 93 94Similarly, there is a @code{targetcm} variable for hooks that are 95specific to front ends for C-family languages, documented as ``C 96Target Hook''. This is declared in @file{c-family/c-target.h}, the 97initializer @code{TARGETCM_INITIALIZER} in 98@file{c-family/c-target-def.h}. If targets initialize @code{targetcm} 99themselves, they should set @code{target_has_targetcm=yes} in 100@file{config.gcc}; otherwise a default definition is used. 101 102Similarly, there is a @code{targetm_common} variable for hooks that 103are shared between the compiler driver and the compilers proper, 104documented as ``Common Target Hook''. This is declared in 105@file{common/common-target.h}, the initializer 106@code{TARGETM_COMMON_INITIALIZER} in 107@file{common/common-target-def.h}. If targets initialize 108@code{targetm_common} themselves, they should set 109@code{target_has_targetm_common=yes} in @file{config.gcc}; otherwise a 110default definition is used. 111 112@node Driver 113@section Controlling the Compilation Driver, @file{gcc} 114@cindex driver 115@cindex controlling the compilation driver 116 117@c prevent bad page break with this line 118You can control the compilation driver. 119 120@defmac DRIVER_SELF_SPECS 121A list of specs for the driver itself. It should be a suitable 122initializer for an array of strings, with no surrounding braces. 123 124The driver applies these specs to its own command line between loading 125default @file{specs} files (but not command-line specified ones) and 126choosing the multilib directory or running any subcommands. It 127applies them in the order given, so each spec can depend on the 128options added by earlier ones. It is also possible to remove options 129using @samp{%<@var{option}} in the usual way. 130 131This macro can be useful when a port has several interdependent target 132options. It provides a way of standardizing the command line so 133that the other specs are easier to write. 134 135Do not define this macro if it does not need to do anything. 136@end defmac 137 138@defmac OPTION_DEFAULT_SPECS 139A list of specs used to support configure-time default options (i.e.@: 140@option{--with} options) in the driver. It should be a suitable initializer 141for an array of structures, each containing two strings, without the 142outermost pair of surrounding braces. 143 144The first item in the pair is the name of the default. This must match 145the code in @file{config.gcc} for the target. The second item is a spec 146to apply if a default with this name was specified. The string 147@samp{%(VALUE)} in the spec will be replaced by the value of the default 148everywhere it occurs. 149 150The driver will apply these specs to its own command line between loading 151default @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using 152the same mechanism as @code{DRIVER_SELF_SPECS}. 153 154Do not define this macro if it does not need to do anything. 155@end defmac 156 157@defmac CPP_SPEC 158A C string constant that tells the GCC driver program options to 159pass to CPP@. It can also specify how to translate options you 160give to GCC into options for GCC to pass to the CPP@. 161 162Do not define this macro if it does not need to do anything. 163@end defmac 164 165@defmac CPLUSPLUS_CPP_SPEC 166This macro is just like @code{CPP_SPEC}, but is used for C++, rather 167than C@. If you do not define this macro, then the value of 168@code{CPP_SPEC} (if any) will be used instead. 169@end defmac 170 171@defmac CC1_SPEC 172A C string constant that tells the GCC driver program options to 173pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language 174front ends. 175It can also specify how to translate options you give to GCC into options 176for GCC to pass to front ends. 177 178Do not define this macro if it does not need to do anything. 179@end defmac 180 181@defmac CC1PLUS_SPEC 182A C string constant that tells the GCC driver program options to 183pass to @code{cc1plus}. It can also specify how to translate options you 184give to GCC into options for GCC to pass to the @code{cc1plus}. 185 186Do not define this macro if it does not need to do anything. 187Note that everything defined in CC1_SPEC is already passed to 188@code{cc1plus} so there is no need to duplicate the contents of 189CC1_SPEC in CC1PLUS_SPEC@. 190@end defmac 191 192@defmac ASM_SPEC 193A C string constant that tells the GCC driver program options to 194pass to the assembler. It can also specify how to translate options 195you give to GCC into options for GCC to pass to the assembler. 196See the file @file{sun3.h} for an example of this. 197 198Do not define this macro if it does not need to do anything. 199@end defmac 200 201@defmac ASM_FINAL_SPEC 202A C string constant that tells the GCC driver program how to 203run any programs which cleanup after the normal assembler. 204Normally, this is not needed. See the file @file{mips.h} for 205an example of this. 206 207Do not define this macro if it does not need to do anything. 208@end defmac 209 210@defmac AS_NEEDS_DASH_FOR_PIPED_INPUT 211Define this macro, with no value, if the driver should give the assembler 212an argument consisting of a single dash, @option{-}, to instruct it to 213read from its standard input (which will be a pipe connected to the 214output of the compiler proper). This argument is given after any 215@option{-o} option specifying the name of the output file. 216 217If you do not define this macro, the assembler is assumed to read its 218standard input if given no non-option arguments. If your assembler 219cannot read standard input at all, use a @samp{%@{pipe:%e@}} construct; 220see @file{mips.h} for instance. 221@end defmac 222 223@defmac LINK_SPEC 224A C string constant that tells the GCC driver program options to 225pass to the linker. It can also specify how to translate options you 226give to GCC into options for GCC to pass to the linker. 227 228Do not define this macro if it does not need to do anything. 229@end defmac 230 231@defmac LIB_SPEC 232Another C string constant used much like @code{LINK_SPEC}. The difference 233between the two is that @code{LIB_SPEC} is used at the end of the 234command given to the linker. 235 236If this macro is not defined, a default is provided that 237loads the standard C library from the usual place. See @file{gcc.c}. 238@end defmac 239 240@defmac LIBGCC_SPEC 241Another C string constant that tells the GCC driver program 242how and when to place a reference to @file{libgcc.a} into the 243linker command line. This constant is placed both before and after 244the value of @code{LIB_SPEC}. 245 246If this macro is not defined, the GCC driver provides a default that 247passes the string @option{-lgcc} to the linker. 248@end defmac 249 250@defmac REAL_LIBGCC_SPEC 251By default, if @code{ENABLE_SHARED_LIBGCC} is defined, the 252@code{LIBGCC_SPEC} is not directly used by the driver program but is 253instead modified to refer to different versions of @file{libgcc.a} 254depending on the values of the command line flags @option{-static}, 255@option{-shared}, @option{-static-libgcc}, and @option{-shared-libgcc}. On 256targets where these modifications are inappropriate, define 257@code{REAL_LIBGCC_SPEC} instead. @code{REAL_LIBGCC_SPEC} tells the 258driver how to place a reference to @file{libgcc} on the link command 259line, but, unlike @code{LIBGCC_SPEC}, it is used unmodified. 260@end defmac 261 262@defmac USE_LD_AS_NEEDED 263A macro that controls the modifications to @code{LIBGCC_SPEC} 264mentioned in @code{REAL_LIBGCC_SPEC}. If nonzero, a spec will be 265generated that uses --as-needed and the shared libgcc in place of the 266static exception handler library, when linking without any of 267@code{-static}, @code{-static-libgcc}, or @code{-shared-libgcc}. 268@end defmac 269 270@defmac LINK_EH_SPEC 271If defined, this C string constant is added to @code{LINK_SPEC}. 272When @code{USE_LD_AS_NEEDED} is zero or undefined, it also affects 273the modifications to @code{LIBGCC_SPEC} mentioned in 274@code{REAL_LIBGCC_SPEC}. 275@end defmac 276 277@defmac STARTFILE_SPEC 278Another C string constant used much like @code{LINK_SPEC}. The 279difference between the two is that @code{STARTFILE_SPEC} is used at 280the very beginning of the command given to the linker. 281 282If this macro is not defined, a default is provided that loads the 283standard C startup file from the usual place. See @file{gcc.c}. 284@end defmac 285 286@defmac ENDFILE_SPEC 287Another C string constant used much like @code{LINK_SPEC}. The 288difference between the two is that @code{ENDFILE_SPEC} is used at 289the very end of the command given to the linker. 290 291Do not define this macro if it does not need to do anything. 292@end defmac 293 294@defmac THREAD_MODEL_SPEC 295GCC @code{-v} will print the thread model GCC was configured to use. 296However, this doesn't work on platforms that are multilibbed on thread 297models, such as AIX 4.3. On such platforms, define 298@code{THREAD_MODEL_SPEC} such that it evaluates to a string without 299blanks that names one of the recognized thread models. @code{%*}, the 300default value of this macro, will expand to the value of 301@code{thread_file} set in @file{config.gcc}. 302@end defmac 303 304@defmac SYSROOT_SUFFIX_SPEC 305Define this macro to add a suffix to the target sysroot when GCC is 306configured with a sysroot. This will cause GCC to search for usr/lib, 307et al, within sysroot+suffix. 308@end defmac 309 310@defmac SYSROOT_HEADERS_SUFFIX_SPEC 311Define this macro to add a headers_suffix to the target sysroot when 312GCC is configured with a sysroot. This will cause GCC to pass the 313updated sysroot+headers_suffix to CPP, causing it to search for 314usr/include, et al, within sysroot+headers_suffix. 315@end defmac 316 317@defmac EXTRA_SPECS 318Define this macro to provide additional specifications to put in the 319@file{specs} file that can be used in various specifications like 320@code{CC1_SPEC}. 321 322The definition should be an initializer for an array of structures, 323containing a string constant, that defines the specification name, and a 324string constant that provides the specification. 325 326Do not define this macro if it does not need to do anything. 327 328@code{EXTRA_SPECS} is useful when an architecture contains several 329related targets, which have various @code{@dots{}_SPECS} which are similar 330to each other, and the maintainer would like one central place to keep 331these definitions. 332 333For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to 334define either @code{_CALL_SYSV} when the System V calling sequence is 335used or @code{_CALL_AIX} when the older AIX-based calling sequence is 336used. 337 338The @file{config/rs6000/rs6000.h} target file defines: 339 340@smallexample 341#define EXTRA_SPECS \ 342 @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, 343 344#define CPP_SYS_DEFAULT "" 345@end smallexample 346 347The @file{config/rs6000/sysv.h} target file defines: 348@smallexample 349#undef CPP_SPEC 350#define CPP_SPEC \ 351"%@{posix: -D_POSIX_SOURCE @} \ 352%@{mcall-sysv: -D_CALL_SYSV @} \ 353%@{!mcall-sysv: %(cpp_sysv_default) @} \ 354%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" 355 356#undef CPP_SYSV_DEFAULT 357#define CPP_SYSV_DEFAULT "-D_CALL_SYSV" 358@end smallexample 359 360while the @file{config/rs6000/eabiaix.h} target file defines 361@code{CPP_SYSV_DEFAULT} as: 362 363@smallexample 364#undef CPP_SYSV_DEFAULT 365#define CPP_SYSV_DEFAULT "-D_CALL_AIX" 366@end smallexample 367@end defmac 368 369@defmac LINK_LIBGCC_SPECIAL_1 370Define this macro if the driver program should find the library 371@file{libgcc.a}. If you do not define this macro, the driver program will pass 372the argument @option{-lgcc} to tell the linker to do the search. 373@end defmac 374 375@defmac LINK_GCC_C_SEQUENCE_SPEC 376The sequence in which libgcc and libc are specified to the linker. 377By default this is @code{%G %L %G}. 378@end defmac 379 380@defmac LINK_COMMAND_SPEC 381A C string constant giving the complete command line need to execute the 382linker. When you do this, you will need to update your port each time a 383change is made to the link command line within @file{gcc.c}. Therefore, 384define this macro only if you need to completely redefine the command 385line for invoking the linker and there is no other way to accomplish 386the effect you need. Overriding this macro may be avoidable by overriding 387@code{LINK_GCC_C_SEQUENCE_SPEC} instead. 388@end defmac 389 390@defmac LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 391A nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search 392directories from linking commands. Do not give it a nonzero value if 393removing duplicate search directories changes the linker's semantics. 394@end defmac 395 396@deftypevr {Common Target Hook} bool TARGET_ALWAYS_STRIP_DOTDOT 397True if @file{..} components should always be removed from directory names computed relative to GCC's internal directories, false (default) if such components should be preserved and directory names containing them passed to other tools such as the linker. 398@end deftypevr 399 400@defmac MULTILIB_DEFAULTS 401Define this macro as a C expression for the initializer of an array of 402string to tell the driver program which options are defaults for this 403target and thus do not need to be handled specially when using 404@code{MULTILIB_OPTIONS}. 405 406Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in 407the target makefile fragment or if none of the options listed in 408@code{MULTILIB_OPTIONS} are set by default. 409@xref{Target Fragment}. 410@end defmac 411 412@defmac RELATIVE_PREFIX_NOT_LINKDIR 413Define this macro to tell @command{gcc} that it should only translate 414a @option{-B} prefix into a @option{-L} linker option if the prefix 415indicates an absolute file name. 416@end defmac 417 418@defmac MD_EXEC_PREFIX 419If defined, this macro is an additional prefix to try after 420@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched 421when the compiler is built as a cross 422compiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it 423to the list of directories used to find the assembler in @file{configure.in}. 424@end defmac 425 426@defmac STANDARD_STARTFILE_PREFIX 427Define this macro as a C string constant if you wish to override the 428standard choice of @code{libdir} as the default prefix to 429try when searching for startup files such as @file{crt0.o}. 430@code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler 431is built as a cross compiler. 432@end defmac 433 434@defmac STANDARD_STARTFILE_PREFIX_1 435Define this macro as a C string constant if you wish to override the 436standard choice of @code{/lib} as a prefix to try after the default prefix 437when searching for startup files such as @file{crt0.o}. 438@code{STANDARD_STARTFILE_PREFIX_1} is not searched when the compiler 439is built as a cross compiler. 440@end defmac 441 442@defmac STANDARD_STARTFILE_PREFIX_2 443Define this macro as a C string constant if you wish to override the 444standard choice of @code{/lib} as yet another prefix to try after the 445default prefix when searching for startup files such as @file{crt0.o}. 446@code{STANDARD_STARTFILE_PREFIX_2} is not searched when the compiler 447is built as a cross compiler. 448@end defmac 449 450@defmac MD_STARTFILE_PREFIX 451If defined, this macro supplies an additional prefix to try after the 452standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the 453compiler is built as a cross compiler. 454@end defmac 455 456@defmac MD_STARTFILE_PREFIX_1 457If defined, this macro supplies yet another prefix to try after the 458standard prefixes. It is not searched when the compiler is built as a 459cross compiler. 460@end defmac 461 462@defmac INIT_ENVIRONMENT 463Define this macro as a C string constant if you wish to set environment 464variables for programs called by the driver, such as the assembler and 465loader. The driver passes the value of this macro to @code{putenv} to 466initialize the necessary environment variables. 467@end defmac 468 469@defmac LOCAL_INCLUDE_DIR 470Define this macro as a C string constant if you wish to override the 471standard choice of @file{/usr/local/include} as the default prefix to 472try when searching for local header files. @code{LOCAL_INCLUDE_DIR} 473comes before @code{NATIVE_SYSTEM_HEADER_DIR} (set in 474@file{config.gcc}, normally @file{/usr/include}) in the search order. 475 476Cross compilers do not search either @file{/usr/local/include} or its 477replacement. 478@end defmac 479 480@defmac NATIVE_SYSTEM_HEADER_COMPONENT 481The ``component'' corresponding to @code{NATIVE_SYSTEM_HEADER_DIR}. 482See @code{INCLUDE_DEFAULTS}, below, for the description of components. 483If you do not define this macro, no component is used. 484@end defmac 485 486@defmac INCLUDE_DEFAULTS 487Define this macro if you wish to override the entire default search path 488for include files. For a native compiler, the default search path 489usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, 490@code{GPLUSPLUS_INCLUDE_DIR}, and 491@code{NATIVE_SYSTEM_HEADER_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} 492and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, 493and specify private search areas for GCC@. The directory 494@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. 495 496The definition should be an initializer for an array of structures. 497Each array element should have four elements: the directory name (a 498string constant), the component name (also a string constant), a flag 499for C++-only directories, 500and a flag showing that the includes in the directory don't need to be 501wrapped in @code{extern @samp{C}} when compiling C++. Mark the end of 502the array with a null element. 503 504The component name denotes what GNU package the include file is part of, 505if any, in all uppercase letters. For example, it might be @samp{GCC} 506or @samp{BINUTILS}. If the package is part of a vendor-supplied 507operating system, code the component name as @samp{0}. 508 509For example, here is the definition used for VAX/VMS: 510 511@smallexample 512#define INCLUDE_DEFAULTS \ 513@{ \ 514 @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ 515 @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \ 516 @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \ 517 @{ ".", 0, 0, 0@}, \ 518 @{ 0, 0, 0, 0@} \ 519@} 520@end smallexample 521@end defmac 522 523Here is the order of prefixes tried for exec files: 524 525@enumerate 526@item 527Any prefixes specified by the user with @option{-B}. 528 529@item 530The environment variable @code{GCC_EXEC_PREFIX} or, if @code{GCC_EXEC_PREFIX} 531is not set and the compiler has not been installed in the configure-time 532@var{prefix}, the location in which the compiler has actually been installed. 533 534@item 535The directories specified by the environment variable @code{COMPILER_PATH}. 536 537@item 538The macro @code{STANDARD_EXEC_PREFIX}, if the compiler has been installed 539in the configured-time @var{prefix}. 540 541@item 542The location @file{/usr/libexec/gcc/}, but only if this is a native compiler. 543 544@item 545The location @file{/usr/lib/gcc/}, but only if this is a native compiler. 546 547@item 548The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 549compiler. 550@end enumerate 551 552Here is the order of prefixes tried for startfiles: 553 554@enumerate 555@item 556Any prefixes specified by the user with @option{-B}. 557 558@item 559The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined 560value based on the installed toolchain location. 561 562@item 563The directories specified by the environment variable @code{LIBRARY_PATH} 564(or port-specific name; native only, cross compilers do not use this). 565 566@item 567The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed 568in the configured @var{prefix} or this is a native compiler. 569 570@item 571The location @file{/usr/lib/gcc/}, but only if this is a native compiler. 572 573@item 574The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 575compiler. 576 577@item 578The macro @code{MD_STARTFILE_PREFIX}, if defined, but only if this is a 579native compiler, or we have a target system root. 580 581@item 582The macro @code{MD_STARTFILE_PREFIX_1}, if defined, but only if this is a 583native compiler, or we have a target system root. 584 585@item 586The macro @code{STANDARD_STARTFILE_PREFIX}, with any sysroot modifications. 587If this path is relative it will be prefixed by @code{GCC_EXEC_PREFIX} and 588the machine suffix or @code{STANDARD_EXEC_PREFIX} and the machine suffix. 589 590@item 591The macro @code{STANDARD_STARTFILE_PREFIX_1}, but only if this is a native 592compiler, or we have a target system root. The default for this macro is 593@file{/lib/}. 594 595@item 596The macro @code{STANDARD_STARTFILE_PREFIX_2}, but only if this is a native 597compiler, or we have a target system root. The default for this macro is 598@file{/usr/lib/}. 599@end enumerate 600 601@node Run-time Target 602@section Run-time Target Specification 603@cindex run-time target specification 604@cindex predefined macros 605@cindex target specifications 606 607@c prevent bad page break with this line 608Here are run-time target specifications. 609 610@defmac TARGET_CPU_CPP_BUILTINS () 611This function-like macro expands to a block of code that defines 612built-in preprocessor macros and assertions for the target CPU, using 613the functions @code{builtin_define}, @code{builtin_define_std} and 614@code{builtin_assert}. When the front end 615calls this macro it provides a trailing semicolon, and since it has 616finished command line option processing your code can use those 617results freely. 618 619@code{builtin_assert} takes a string in the form you pass to the 620command-line option @option{-A}, such as @code{cpu=mips}, and creates 621the assertion. @code{builtin_define} takes a string in the form 622accepted by option @option{-D} and unconditionally defines the macro. 623 624@code{builtin_define_std} takes a string representing the name of an 625object-like macro. If it doesn't lie in the user's namespace, 626@code{builtin_define_std} defines it unconditionally. Otherwise, it 627defines a version with two leading underscores, and another version 628with two leading and trailing underscores, and defines the original 629only if an ISO standard was not requested on the command line. For 630example, passing @code{unix} defines @code{__unix}, @code{__unix__} 631and possibly @code{unix}; passing @code{_mips} defines @code{__mips}, 632@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64} 633defines only @code{_ABI64}. 634 635You can also test for the C dialect being compiled. The variable 636@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus} 637or @code{clk_objective_c}. Note that if we are preprocessing 638assembler, this variable will be @code{clk_c} but the function-like 639macro @code{preprocessing_asm_p()} will return true, so you might want 640to check for that first. If you need to check for strict ANSI, the 641variable @code{flag_iso} can be used. The function-like macro 642@code{preprocessing_trad_p()} can be used to check for traditional 643preprocessing. 644@end defmac 645 646@defmac TARGET_OS_CPP_BUILTINS () 647Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional 648and is used for the target operating system instead. 649@end defmac 650 651@defmac TARGET_OBJFMT_CPP_BUILTINS () 652Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional 653and is used for the target object format. @file{elfos.h} uses this 654macro to define @code{__ELF__}, so you probably do not need to define 655it yourself. 656@end defmac 657 658@deftypevar {extern int} target_flags 659This variable is declared in @file{options.h}, which is included before 660any target-specific headers. 661@end deftypevar 662 663@deftypevr {Common Target Hook} int TARGET_DEFAULT_TARGET_FLAGS 664This variable specifies the initial value of @code{target_flags}. 665Its default setting is 0. 666@end deftypevr 667 668@cindex optional hardware or system features 669@cindex features, optional, in system conventions 670 671@deftypefn {Common Target Hook} bool TARGET_HANDLE_OPTION (struct gcc_options *@var{opts}, struct gcc_options *@var{opts_set}, const struct cl_decoded_option *@var{decoded}, location_t @var{loc}) 672This hook is called whenever the user specifies one of the 673target-specific options described by the @file{.opt} definition files 674(@pxref{Options}). It has the opportunity to do some option-specific 675processing and should return true if the option is valid. The default 676definition does nothing but return true. 677 678@var{decoded} specifies the option and its arguments. @var{opts} and 679@var{opts_set} are the @code{gcc_options} structures to be used for 680storing option state, and @var{loc} is the location at which the 681option was passed (@code{UNKNOWN_LOCATION} except for options passed 682via attributes). 683@end deftypefn 684 685@deftypefn {C Target Hook} bool TARGET_HANDLE_C_OPTION (size_t @var{code}, const char *@var{arg}, int @var{value}) 686This target hook is called whenever the user specifies one of the 687target-specific C language family options described by the @file{.opt} 688definition files(@pxref{Options}). It has the opportunity to do some 689option-specific processing and should return true if the option is 690valid. The arguments are like for @code{TARGET_HANDLE_OPTION}. The 691default definition does nothing but return false. 692 693In general, you should use @code{TARGET_HANDLE_OPTION} to handle 694options. However, if processing an option requires routines that are 695only available in the C (and related language) front ends, then you 696should use @code{TARGET_HANDLE_C_OPTION} instead. 697@end deftypefn 698 699@deftypefn {C Target Hook} tree TARGET_OBJC_CONSTRUCT_STRING_OBJECT (tree @var{string}) 700Targets may provide a string object type that can be used within and between C, C++ and their respective Objective-C dialects. A string object might, for example, embed encoding and length information. These objects are considered opaque to the compiler and handled as references. An ideal implementation makes the composition of the string object match that of the Objective-C @code{NSString} (@code{NXString} for GNUStep), allowing efficient interworking between C-only and Objective-C code. If a target implements string objects then this hook should return a reference to such an object constructed from the normal `C' string representation provided in @var{string}. At present, the hook is used by Objective-C only, to obtain a common-format string object when the target provides one. 701@end deftypefn 702 703@deftypefn {C Target Hook} bool TARGET_STRING_OBJECT_REF_TYPE_P (const_tree @var{stringref}) 704If a target implements string objects then this hook should return @code{true} if @var{stringref} is a valid reference to such an object. 705@end deftypefn 706 707@deftypefn {C Target Hook} void TARGET_CHECK_STRING_OBJECT_FORMAT_ARG (tree @var{format_arg}, tree @var{args_list}) 708If a target implements string objects then this hook should should provide a facility to check the function arguments in @var{args_list} against the format specifiers in @var{format_arg} where the type of @var{format_arg} is one recognized as a valid string reference type. 709@end deftypefn 710 711@deftypefn {Target Hook} void TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE (void) 712This target function is similar to the hook @code{TARGET_OPTION_OVERRIDE} 713but is called when the optimize level is changed via an attribute or 714pragma or when it is reset at the end of the code affected by the 715attribute or pragma. It is not called at the beginning of compilation 716when @code{TARGET_OPTION_OVERRIDE} is called so if you want to perform these 717actions then, you should have @code{TARGET_OPTION_OVERRIDE} call 718@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}. 719@end deftypefn 720 721@defmac C_COMMON_OVERRIDE_OPTIONS 722This is similar to the @code{TARGET_OPTION_OVERRIDE} hook 723but is only used in the C 724language frontends (C, Objective-C, C++, Objective-C++) and so can be 725used to alter option flag variables which only exist in those 726frontends. 727@end defmac 728 729@deftypevr {Common Target Hook} {const struct default_options *} TARGET_OPTION_OPTIMIZATION_TABLE 730Some machines may desire to change what optimizations are performed for 731various optimization levels. This variable, if defined, describes 732options to enable at particular sets of optimization levels. These 733options are processed once 734just after the optimization level is determined and before the remainder 735of the command options have been parsed, so may be overridden by other 736options passed explicitly. 737 738This processing is run once at program startup and when the optimization 739options are changed via @code{#pragma GCC optimize} or by using the 740@code{optimize} attribute. 741@end deftypevr 742 743@deftypefn {Common Target Hook} void TARGET_OPTION_INIT_STRUCT (struct gcc_options *@var{opts}) 744Set target-dependent initial values of fields in @var{opts}. 745@end deftypefn 746 747@deftypefn {Common Target Hook} void TARGET_OPTION_DEFAULT_PARAMS (void) 748Set target-dependent default values for @option{--param} settings, using calls to @code{set_default_param_value}. 749@end deftypefn 750 751@defmac SWITCHABLE_TARGET 752Some targets need to switch between substantially different subtargets 753during compilation. For example, the MIPS target has one subtarget for 754the traditional MIPS architecture and another for MIPS16. Source code 755can switch between these two subarchitectures using the @code{mips16} 756and @code{nomips16} attributes. 757 758Such subtargets can differ in things like the set of available 759registers, the set of available instructions, the costs of various 760operations, and so on. GCC caches a lot of this type of information 761in global variables, and recomputing them for each subtarget takes a 762significant amount of time. The compiler therefore provides a facility 763for maintaining several versions of the global variables and quickly 764switching between them; see @file{target-globals.h} for details. 765 766Define this macro to 1 if your target needs this facility. The default 767is 0. 768@end defmac 769 770@node Per-Function Data 771@section Defining data structures for per-function information. 772@cindex per-function data 773@cindex data structures 774 775If the target needs to store information on a per-function basis, GCC 776provides a macro and a couple of variables to allow this. Note, just 777using statics to store the information is a bad idea, since GCC supports 778nested functions, so you can be halfway through encoding one function 779when another one comes along. 780 781GCC defines a data structure called @code{struct function} which 782contains all of the data specific to an individual function. This 783structure contains a field called @code{machine} whose type is 784@code{struct machine_function *}, which can be used by targets to point 785to their own specific data. 786 787If a target needs per-function specific data it should define the type 788@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. 789This macro should be used to initialize the function pointer 790@code{init_machine_status}. This pointer is explained below. 791 792One typical use of per-function, target specific data is to create an 793RTX to hold the register containing the function's return address. This 794RTX can then be used to implement the @code{__builtin_return_address} 795function, for level 0. 796 797Note---earlier implementations of GCC used a single data area to hold 798all of the per-function information. Thus when processing of a nested 799function began the old per-function data had to be pushed onto a 800stack, and when the processing was finished, it had to be popped off the 801stack. GCC used to provide function pointers called 802@code{save_machine_status} and @code{restore_machine_status} to handle 803the saving and restoring of the target specific information. Since the 804single data area approach is no longer used, these pointers are no 805longer supported. 806 807@defmac INIT_EXPANDERS 808Macro called to initialize any target specific information. This macro 809is called once per function, before generation of any RTL has begun. 810The intention of this macro is to allow the initialization of the 811function pointer @code{init_machine_status}. 812@end defmac 813 814@deftypevar {void (*)(struct function *)} init_machine_status 815If this function pointer is non-@code{NULL} it will be called once per 816function, before function compilation starts, in order to allow the 817target to perform any target specific initialization of the 818@code{struct function} structure. It is intended that this would be 819used to initialize the @code{machine} of that structure. 820 821@code{struct machine_function} structures are expected to be freed by GC@. 822Generally, any memory that they reference must be allocated by using 823GC allocation, including the structure itself. 824@end deftypevar 825 826@node Storage Layout 827@section Storage Layout 828@cindex storage layout 829 830Note that the definitions of the macros in this table which are sizes or 831alignments measured in bits do not need to be constant. They can be C 832expressions that refer to static variables, such as the @code{target_flags}. 833@xref{Run-time Target}. 834 835@defmac BITS_BIG_ENDIAN 836Define this macro to have the value 1 if the most significant bit in a 837byte has the lowest number; otherwise define it to have the value zero. 838This means that bit-field instructions count from the most significant 839bit. If the machine has no bit-field instructions, then this must still 840be defined, but it doesn't matter which value it is defined to. This 841macro need not be a constant. 842 843This macro does not affect the way structure fields are packed into 844bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 845@end defmac 846 847@defmac BYTES_BIG_ENDIAN 848Define this macro to have the value 1 if the most significant byte in a 849word has the lowest number. This macro need not be a constant. 850@end defmac 851 852@defmac WORDS_BIG_ENDIAN 853Define this macro to have the value 1 if, in a multiword object, the 854most significant word has the lowest number. This applies to both 855memory locations and registers; see @code{REG_WORDS_BIG_ENDIAN} if the 856order of words in memory is not the same as the order in registers. This 857macro need not be a constant. 858@end defmac 859 860@defmac REG_WORDS_BIG_ENDIAN 861On some machines, the order of words in a multiword object differs between 862registers in memory. In such a situation, define this macro to describe 863the order of words in a register. The macro @code{WORDS_BIG_ENDIAN} controls 864the order of words in memory. 865@end defmac 866 867@defmac FLOAT_WORDS_BIG_ENDIAN 868Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 869@code{TFmode} floating point numbers are stored in memory with the word 870containing the sign bit at the lowest address; otherwise define it to 871have the value 0. This macro need not be a constant. 872 873You need not define this macro if the ordering is the same as for 874multi-word integers. 875@end defmac 876 877@defmac BITS_PER_UNIT 878Define this macro to be the number of bits in an addressable storage 879unit (byte). If you do not define this macro the default is 8. 880@end defmac 881 882@defmac BITS_PER_WORD 883Number of bits in a word. If you do not define this macro, the default 884is @code{BITS_PER_UNIT * UNITS_PER_WORD}. 885@end defmac 886 887@defmac MAX_BITS_PER_WORD 888Maximum number of bits in a word. If this is undefined, the default is 889@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 890largest value that @code{BITS_PER_WORD} can have at run-time. 891@end defmac 892 893@defmac UNITS_PER_WORD 894Number of storage units in a word; normally the size of a general-purpose 895register, a power of two from 1 or 8. 896@end defmac 897 898@defmac MIN_UNITS_PER_WORD 899Minimum number of units in a word. If this is undefined, the default is 900@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 901smallest value that @code{UNITS_PER_WORD} can have at run-time. 902@end defmac 903 904@defmac POINTER_SIZE 905Width of a pointer, in bits. You must specify a value no wider than the 906width of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 907you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify 908a value the default is @code{BITS_PER_WORD}. 909@end defmac 910 911@defmac POINTERS_EXTEND_UNSIGNED 912A C expression that determines how pointers should be extended from 913@code{ptr_mode} to either @code{Pmode} or @code{word_mode}. It is 914greater than zero if pointers should be zero-extended, zero if they 915should be sign-extended, and negative if some other sort of conversion 916is needed. In the last case, the extension is done by the target's 917@code{ptr_extend} instruction. 918 919You need not define this macro if the @code{ptr_mode}, @code{Pmode} 920and @code{word_mode} are all the same width. 921@end defmac 922 923@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 924A macro to update @var{m} and @var{unsignedp} when an object whose type 925is @var{type} and which has the specified mode and signedness is to be 926stored in a register. This macro is only called when @var{type} is a 927scalar type. 928 929On most RISC machines, which only have operations that operate on a full 930register, define this macro to set @var{m} to @code{word_mode} if 931@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 932cases, only integer modes should be widened because wider-precision 933floating-point operations are usually more expensive than their narrower 934counterparts. 935 936For most machines, the macro definition does not change @var{unsignedp}. 937However, some machines, have instructions that preferentially handle 938either signed or unsigned quantities of certain modes. For example, on 939the DEC Alpha, 32-bit loads from memory and 32-bit add instructions 940sign-extend the result to 64 bits. On such machines, set 941@var{unsignedp} according to which kind of extension is more efficient. 942 943Do not define this macro if it would never modify @var{m}. 944@end defmac 945 946@deftypefn {Target Hook} {enum machine_mode} TARGET_PROMOTE_FUNCTION_MODE (const_tree @var{type}, enum machine_mode @var{mode}, int *@var{punsignedp}, const_tree @var{funtype}, int @var{for_return}) 947Like @code{PROMOTE_MODE}, but it is applied to outgoing function arguments or 948function return values. The target hook should return the new mode 949and possibly change @code{*@var{punsignedp}} if the promotion should 950change signedness. This function is called only for scalar @emph{or 951pointer} types. 952 953@var{for_return} allows to distinguish the promotion of arguments and 954return values. If it is @code{1}, a return value is being promoted and 955@code{TARGET_FUNCTION_VALUE} must perform the same promotions done here. 956If it is @code{2}, the returned mode should be that of the register in 957which an incoming parameter is copied, or the outgoing result is computed; 958then the hook should return the same mode as @code{promote_mode}, though 959the signedness may be different. 960 961@var{type} can be NULL when promoting function arguments of libcalls. 962 963The default is to not promote arguments and return values. You can 964also define the hook to @code{default_promote_function_mode_always_promote} 965if you would like to apply the same rules given by @code{PROMOTE_MODE}. 966@end deftypefn 967 968@defmac PARM_BOUNDARY 969Normal alignment required for function parameters on the stack, in 970bits. All stack parameters receive at least this much alignment 971regardless of data type. On most machines, this is the same as the 972size of an integer. 973@end defmac 974 975@defmac STACK_BOUNDARY 976Define this macro to the minimum alignment enforced by hardware for the 977stack pointer on this machine. The definition is a C expression for the 978desired alignment (measured in bits). This value is used as a default 979if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 980this should be the same as @code{PARM_BOUNDARY}. 981@end defmac 982 983@defmac PREFERRED_STACK_BOUNDARY 984Define this macro if you wish to preserve a certain alignment for the 985stack pointer, greater than what the hardware enforces. The definition 986is a C expression for the desired alignment (measured in bits). This 987macro must evaluate to a value equal to or larger than 988@code{STACK_BOUNDARY}. 989@end defmac 990 991@defmac INCOMING_STACK_BOUNDARY 992Define this macro if the incoming stack boundary may be different 993from @code{PREFERRED_STACK_BOUNDARY}. This macro must evaluate 994to a value equal to or larger than @code{STACK_BOUNDARY}. 995@end defmac 996 997@defmac FUNCTION_BOUNDARY 998Alignment required for a function entry point, in bits. 999@end defmac 1000 1001@defmac BIGGEST_ALIGNMENT 1002Biggest alignment that any data type can require on this machine, in 1003bits. Note that this is not the biggest alignment that is supported, 1004just the biggest alignment that, when violated, may cause a fault. 1005@end defmac 1006 1007@defmac MALLOC_ABI_ALIGNMENT 1008Alignment, in bits, a C conformant malloc implementation has to 1009provide. If not defined, the default value is @code{BITS_PER_WORD}. 1010@end defmac 1011 1012@defmac ATTRIBUTE_ALIGNED_VALUE 1013Alignment used by the @code{__attribute__ ((aligned))} construct. If 1014not defined, the default value is @code{BIGGEST_ALIGNMENT}. 1015@end defmac 1016 1017@defmac MINIMUM_ATOMIC_ALIGNMENT 1018If defined, the smallest alignment, in bits, that can be given to an 1019object that can be referenced in one operation, without disturbing any 1020nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 1021on machines that don't have byte or half-word store operations. 1022@end defmac 1023 1024@defmac BIGGEST_FIELD_ALIGNMENT 1025Biggest alignment that any structure or union field can require on this 1026machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 1027structure and union fields only, unless the field alignment has been set 1028by the @code{__attribute__ ((aligned (@var{n})))} construct. 1029@end defmac 1030 1031@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 1032An expression for the alignment of a structure field @var{field} if the 1033alignment computed in the usual way (including applying of 1034@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the 1035alignment) is @var{computed}. It overrides alignment only if the 1036field alignment has not been set by the 1037@code{__attribute__ ((aligned (@var{n})))} construct. 1038@end defmac 1039 1040@defmac MAX_STACK_ALIGNMENT 1041Biggest stack alignment guaranteed by the backend. Use this macro 1042to specify the maximum alignment of a variable on stack. 1043 1044If not defined, the default value is @code{STACK_BOUNDARY}. 1045 1046@c FIXME: The default should be @code{PREFERRED_STACK_BOUNDARY}. 1047@c But the fix for PR 32893 indicates that we can only guarantee 1048@c maximum stack alignment on stack up to @code{STACK_BOUNDARY}, not 1049@c @code{PREFERRED_STACK_BOUNDARY}, if stack alignment isn't supported. 1050@end defmac 1051 1052@defmac MAX_OFILE_ALIGNMENT 1053Biggest alignment supported by the object file format of this machine. 1054Use this macro to limit the alignment which can be specified using the 1055@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 1056the default value is @code{BIGGEST_ALIGNMENT}. 1057 1058On systems that use ELF, the default (in @file{config/elfos.h}) is 1059the largest supported 32-bit ELF section alignment representable on 1060a 32-bit host e.g. @samp{(((unsigned HOST_WIDEST_INT) 1 << 28) * 8)}. 1061On 32-bit ELF the largest supported section alignment in bits is 1062@samp{(0x80000000 * 8)}, but this is not representable on 32-bit hosts. 1063@end defmac 1064 1065@defmac DATA_ALIGNMENT (@var{type}, @var{basic-align}) 1066If defined, a C expression to compute the alignment for a variable in 1067the static store. @var{type} is the data type, and @var{basic-align} is 1068the alignment that the object would ordinarily have. The value of this 1069macro is used instead of that alignment to align the object. 1070 1071If this macro is not defined, then @var{basic-align} is used. 1072 1073@findex strcpy 1074One use of this macro is to increase alignment of medium-size data to 1075make it all fit in fewer cache lines. Another is to cause character 1076arrays to be word-aligned so that @code{strcpy} calls that copy 1077constants to character arrays can be done inline. 1078@end defmac 1079 1080@defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 1081If defined, a C expression to compute the alignment given to a constant 1082that is being placed in memory. @var{constant} is the constant and 1083@var{basic-align} is the alignment that the object would ordinarily 1084have. The value of this macro is used instead of that alignment to 1085align the object. 1086 1087If this macro is not defined, then @var{basic-align} is used. 1088 1089The typical use of this macro is to increase alignment for string 1090constants to be word aligned so that @code{strcpy} calls that copy 1091constants can be done inline. 1092@end defmac 1093 1094@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 1095If defined, a C expression to compute the alignment for a variable in 1096the local store. @var{type} is the data type, and @var{basic-align} is 1097the alignment that the object would ordinarily have. The value of this 1098macro is used instead of that alignment to align the object. 1099 1100If this macro is not defined, then @var{basic-align} is used. 1101 1102One use of this macro is to increase alignment of medium-size data to 1103make it all fit in fewer cache lines. 1104 1105If the value of this macro has a type, it should be an unsigned type. 1106@end defmac 1107 1108@deftypefn {Target Hook} HOST_WIDE_INT TARGET_VECTOR_ALIGNMENT (const_tree @var{type}) 1109This hook can be used to define the alignment for a vector of type 1110@var{type}, in order to comply with a platform ABI. The default is to 1111require natural alignment for vector types. The alignment returned by 1112this hook must be a power-of-two multiple of the default alignment of 1113the vector element type. 1114@end deftypefn 1115 1116@defmac STACK_SLOT_ALIGNMENT (@var{type}, @var{mode}, @var{basic-align}) 1117If defined, a C expression to compute the alignment for stack slot. 1118@var{type} is the data type, @var{mode} is the widest mode available, 1119and @var{basic-align} is the alignment that the slot would ordinarily 1120have. The value of this macro is used instead of that alignment to 1121align the slot. 1122 1123If this macro is not defined, then @var{basic-align} is used when 1124@var{type} is @code{NULL}. Otherwise, @code{LOCAL_ALIGNMENT} will 1125be used. 1126 1127This macro is to set alignment of stack slot to the maximum alignment 1128of all possible modes which the slot may have. 1129 1130If the value of this macro has a type, it should be an unsigned type. 1131@end defmac 1132 1133@defmac LOCAL_DECL_ALIGNMENT (@var{decl}) 1134If defined, a C expression to compute the alignment for a local 1135variable @var{decl}. 1136 1137If this macro is not defined, then 1138@code{LOCAL_ALIGNMENT (TREE_TYPE (@var{decl}), DECL_ALIGN (@var{decl}))} 1139is used. 1140 1141One use of this macro is to increase alignment of medium-size data to 1142make it all fit in fewer cache lines. 1143 1144If the value of this macro has a type, it should be an unsigned type. 1145@end defmac 1146 1147@defmac MINIMUM_ALIGNMENT (@var{exp}, @var{mode}, @var{align}) 1148If defined, a C expression to compute the minimum required alignment 1149for dynamic stack realignment purposes for @var{exp} (a type or decl), 1150@var{mode}, assuming normal alignment @var{align}. 1151 1152If this macro is not defined, then @var{align} will be used. 1153@end defmac 1154 1155@defmac EMPTY_FIELD_BOUNDARY 1156Alignment in bits to be given to a structure bit-field that follows an 1157empty field such as @code{int : 0;}. 1158 1159If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro. 1160@end defmac 1161 1162@defmac STRUCTURE_SIZE_BOUNDARY 1163Number of bits which any structure or union's size must be a multiple of. 1164Each structure or union's size is rounded up to a multiple of this. 1165 1166If you do not define this macro, the default is the same as 1167@code{BITS_PER_UNIT}. 1168@end defmac 1169 1170@defmac STRICT_ALIGNMENT 1171Define this macro to be the value 1 if instructions will fail to work 1172if given data not on the nominal alignment. If instructions will merely 1173go slower in that case, define this macro as 0. 1174@end defmac 1175 1176@defmac PCC_BITFIELD_TYPE_MATTERS 1177Define this if you wish to imitate the way many other C compilers handle 1178alignment of bit-fields and the structures that contain them. 1179 1180The behavior is that the type written for a named bit-field (@code{int}, 1181@code{short}, or other integer type) imposes an alignment for the entire 1182structure, as if the structure really did contain an ordinary field of 1183that type. In addition, the bit-field is placed within the structure so 1184that it would fit within such a field, not crossing a boundary for it. 1185 1186Thus, on most machines, a named bit-field whose type is written as 1187@code{int} would not cross a four-byte boundary, and would force 1188four-byte alignment for the whole structure. (The alignment used may 1189not be four bytes; it is controlled by the other alignment parameters.) 1190 1191An unnamed bit-field will not affect the alignment of the containing 1192structure. 1193 1194If the macro is defined, its definition should be a C expression; 1195a nonzero value for the expression enables this behavior. 1196 1197Note that if this macro is not defined, or its value is zero, some 1198bit-fields may cross more than one alignment boundary. The compiler can 1199support such references if there are @samp{insv}, @samp{extv}, and 1200@samp{extzv} insns that can directly reference memory. 1201 1202The other known way of making bit-fields work is to define 1203@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 1204Then every structure can be accessed with fullwords. 1205 1206Unless the machine has bit-field instructions or you define 1207@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 1208@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 1209 1210If your aim is to make GCC use the same conventions for laying out 1211bit-fields as are used by another compiler, here is how to investigate 1212what the other compiler does. Compile and run this program: 1213 1214@smallexample 1215struct foo1 1216@{ 1217 char x; 1218 char :0; 1219 char y; 1220@}; 1221 1222struct foo2 1223@{ 1224 char x; 1225 int :0; 1226 char y; 1227@}; 1228 1229main () 1230@{ 1231 printf ("Size of foo1 is %d\n", 1232 sizeof (struct foo1)); 1233 printf ("Size of foo2 is %d\n", 1234 sizeof (struct foo2)); 1235 exit (0); 1236@} 1237@end smallexample 1238 1239If this prints 2 and 5, then the compiler's behavior is what you would 1240get from @code{PCC_BITFIELD_TYPE_MATTERS}. 1241@end defmac 1242 1243@defmac BITFIELD_NBYTES_LIMITED 1244Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 1245to aligning a bit-field within the structure. 1246@end defmac 1247 1248@deftypefn {Target Hook} bool TARGET_ALIGN_ANON_BITFIELD (void) 1249When @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine 1250whether unnamed bitfields affect the alignment of the containing 1251structure. The hook should return true if the structure should inherit 1252the alignment requirements of an unnamed bitfield's type. 1253@end deftypefn 1254 1255@deftypefn {Target Hook} bool TARGET_NARROW_VOLATILE_BITFIELD (void) 1256This target hook should return @code{true} if accesses to volatile bitfields 1257should use the narrowest mode possible. It should return @code{false} if 1258these accesses should use the bitfield container type. 1259 1260The default is @code{!TARGET_STRICT_ALIGN}. 1261@end deftypefn 1262 1263@defmac MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) 1264Return 1 if a structure or array containing @var{field} should be accessed using 1265@code{BLKMODE}. 1266 1267If @var{field} is the only field in the structure, @var{mode} is its 1268mode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the 1269case where structures of one field would require the structure's mode to 1270retain the field's mode. 1271 1272Normally, this is not needed. 1273@end defmac 1274 1275@defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 1276Define this macro as an expression for the alignment of a type (given 1277by @var{type} as a tree node) if the alignment computed in the usual 1278way is @var{computed} and the alignment explicitly specified was 1279@var{specified}. 1280 1281The default is to use @var{specified} if it is larger; otherwise, use 1282the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 1283@end defmac 1284 1285@defmac MAX_FIXED_MODE_SIZE 1286An integer expression for the size in bits of the largest integer 1287machine mode that should actually be used. All integer machine modes of 1288this size or smaller can be used for structures and unions with the 1289appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 1290(DImode)} is assumed. 1291@end defmac 1292 1293@defmac STACK_SAVEAREA_MODE (@var{save_level}) 1294If defined, an expression of type @code{enum machine_mode} that 1295specifies the mode of the save area operand of a 1296@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 1297@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 1298@code{SAVE_NONLOCAL} and selects which of the three named patterns is 1299having its mode specified. 1300 1301You need not define this macro if it always returns @code{Pmode}. You 1302would most commonly define this macro if the 1303@code{save_stack_@var{level}} patterns need to support both a 32- and a 130464-bit mode. 1305@end defmac 1306 1307@defmac STACK_SIZE_MODE 1308If defined, an expression of type @code{enum machine_mode} that 1309specifies the mode of the size increment operand of an 1310@code{allocate_stack} named pattern (@pxref{Standard Names}). 1311 1312You need not define this macro if it always returns @code{word_mode}. 1313You would most commonly define this macro if the @code{allocate_stack} 1314pattern needs to support both a 32- and a 64-bit mode. 1315@end defmac 1316 1317@deftypefn {Target Hook} {enum machine_mode} TARGET_LIBGCC_CMP_RETURN_MODE (void) 1318This target hook should return the mode to be used for the return value 1319of compare instructions expanded to libgcc calls. If not defined 1320@code{word_mode} is returned which is the right choice for a majority of 1321targets. 1322@end deftypefn 1323 1324@deftypefn {Target Hook} {enum machine_mode} TARGET_LIBGCC_SHIFT_COUNT_MODE (void) 1325This target hook should return the mode to be used for the shift count operand 1326of shift instructions expanded to libgcc calls. If not defined 1327@code{word_mode} is returned which is the right choice for a majority of 1328targets. 1329@end deftypefn 1330 1331@deftypefn {Target Hook} {enum machine_mode} TARGET_UNWIND_WORD_MODE (void) 1332Return machine mode to be used for @code{_Unwind_Word} type. 1333The default is to use @code{word_mode}. 1334@end deftypefn 1335 1336@defmac ROUND_TOWARDS_ZERO 1337If defined, this macro should be true if the prevailing rounding 1338mode is towards zero. 1339 1340Defining this macro only affects the way @file{libgcc.a} emulates 1341floating-point arithmetic. 1342 1343Not defining this macro is equivalent to returning zero. 1344@end defmac 1345 1346@defmac LARGEST_EXPONENT_IS_NORMAL (@var{size}) 1347This macro should return true if floats with @var{size} 1348bits do not have a NaN or infinity representation, but use the largest 1349exponent for normal numbers instead. 1350 1351Defining this macro only affects the way @file{libgcc.a} emulates 1352floating-point arithmetic. 1353 1354The default definition of this macro returns false for all sizes. 1355@end defmac 1356 1357@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (const_tree @var{record_type}) 1358This target hook returns @code{true} if bit-fields in the given 1359@var{record_type} are to be laid out following the rules of Microsoft 1360Visual C/C++, namely: (i) a bit-field won't share the same storage 1361unit with the previous bit-field if their underlying types have 1362different sizes, and the bit-field will be aligned to the highest 1363alignment of the underlying types of itself and of the previous 1364bit-field; (ii) a zero-sized bit-field will affect the alignment of 1365the whole enclosing structure, even if it is unnamed; except that 1366(iii) a zero-sized bit-field will be disregarded unless it follows 1367another bit-field of nonzero size. If this hook returns @code{true}, 1368other macros that control bit-field layout are ignored. 1369 1370When a bit-field is inserted into a packed record, the whole size 1371of the underlying type is used by one or more same-size adjacent 1372bit-fields (that is, if its long:3, 32 bits is used in the record, 1373and any additional adjacent long bit-fields are packed into the same 1374chunk of 32 bits. However, if the size changes, a new field of that 1375size is allocated). In an unpacked record, this is the same as using 1376alignment, but not equivalent when packing. 1377 1378If both MS bit-fields and @samp{__attribute__((packed))} are used, 1379the latter will take precedence. If @samp{__attribute__((packed))} is 1380used on a single field when MS bit-fields are in use, it will take 1381precedence for that field, but the alignment of the rest of the structure 1382may affect its placement. 1383@end deftypefn 1384 1385@deftypefn {Target Hook} bool TARGET_DECIMAL_FLOAT_SUPPORTED_P (void) 1386Returns true if the target supports decimal floating point. 1387@end deftypefn 1388 1389@deftypefn {Target Hook} bool TARGET_FIXED_POINT_SUPPORTED_P (void) 1390Returns true if the target supports fixed-point arithmetic. 1391@end deftypefn 1392 1393@deftypefn {Target Hook} void TARGET_EXPAND_TO_RTL_HOOK (void) 1394This hook is called just before expansion into rtl, allowing the target 1395to perform additional initializations or analysis before the expansion. 1396For example, the rs6000 port uses it to allocate a scratch stack slot 1397for use in copying SDmode values between memory and floating point 1398registers whenever the function being expanded has any SDmode 1399usage. 1400@end deftypefn 1401 1402@deftypefn {Target Hook} void TARGET_INSTANTIATE_DECLS (void) 1403This hook allows the backend to perform additional instantiations on rtl 1404that are not actually in any insns yet, but will be later. 1405@end deftypefn 1406 1407@deftypefn {Target Hook} {const char *} TARGET_MANGLE_TYPE (const_tree @var{type}) 1408If your target defines any fundamental types, or any types your target 1409uses should be mangled differently from the default, define this hook 1410to return the appropriate encoding for these types as part of a C++ 1411mangled name. The @var{type} argument is the tree structure representing 1412the type to be mangled. The hook may be applied to trees which are 1413not target-specific fundamental types; it should return @code{NULL} 1414for all such types, as well as arguments it does not recognize. If the 1415return value is not @code{NULL}, it must point to a statically-allocated 1416string constant. 1417 1418Target-specific fundamental types might be new fundamental types or 1419qualified versions of ordinary fundamental types. Encode new 1420fundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name} 1421is the name used for the type in source code, and @var{n} is the 1422length of @var{name} in decimal. Encode qualified versions of 1423ordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where 1424@var{name} is the name used for the type qualifier in source code, 1425@var{n} is the length of @var{name} as above, and @var{code} is the 1426code used to represent the unqualified version of this type. (See 1427@code{write_builtin_type} in @file{cp/mangle.c} for the list of 1428codes.) In both cases the spaces are for clarity; do not include any 1429spaces in your string. 1430 1431This hook is applied to types prior to typedef resolution. If the mangled 1432name for a particular type depends only on that type's main variant, you 1433can perform typedef resolution yourself using @code{TYPE_MAIN_VARIANT} 1434before mangling. 1435 1436The default version of this hook always returns @code{NULL}, which is 1437appropriate for a target that does not define any new fundamental 1438types. 1439@end deftypefn 1440 1441@node Type Layout 1442@section Layout of Source Language Data Types 1443 1444These macros define the sizes and other characteristics of the standard 1445basic data types used in programs being compiled. Unlike the macros in 1446the previous section, these apply to specific features of C and related 1447languages, rather than to fundamental aspects of storage layout. 1448 1449@defmac INT_TYPE_SIZE 1450A C expression for the size in bits of the type @code{int} on the 1451target machine. If you don't define this, the default is one word. 1452@end defmac 1453 1454@defmac SHORT_TYPE_SIZE 1455A C expression for the size in bits of the type @code{short} on the 1456target machine. If you don't define this, the default is half a word. 1457(If this would be less than one storage unit, it is rounded up to one 1458unit.) 1459@end defmac 1460 1461@defmac LONG_TYPE_SIZE 1462A C expression for the size in bits of the type @code{long} on the 1463target machine. If you don't define this, the default is one word. 1464@end defmac 1465 1466@defmac ADA_LONG_TYPE_SIZE 1467On some machines, the size used for the Ada equivalent of the type 1468@code{long} by a native Ada compiler differs from that used by C@. In 1469that situation, define this macro to be a C expression to be used for 1470the size of that type. If you don't define this, the default is the 1471value of @code{LONG_TYPE_SIZE}. 1472@end defmac 1473 1474@defmac LONG_LONG_TYPE_SIZE 1475A C expression for the size in bits of the type @code{long long} on the 1476target machine. If you don't define this, the default is two 1477words. If you want to support GNU Ada on your machine, the value of this 1478macro must be at least 64. 1479@end defmac 1480 1481@defmac CHAR_TYPE_SIZE 1482A C expression for the size in bits of the type @code{char} on the 1483target machine. If you don't define this, the default is 1484@code{BITS_PER_UNIT}. 1485@end defmac 1486 1487@defmac BOOL_TYPE_SIZE 1488A C expression for the size in bits of the C++ type @code{bool} and 1489C99 type @code{_Bool} on the target machine. If you don't define 1490this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 1491@end defmac 1492 1493@defmac FLOAT_TYPE_SIZE 1494A C expression for the size in bits of the type @code{float} on the 1495target machine. If you don't define this, the default is one word. 1496@end defmac 1497 1498@defmac DOUBLE_TYPE_SIZE 1499A C expression for the size in bits of the type @code{double} on the 1500target machine. If you don't define this, the default is two 1501words. 1502@end defmac 1503 1504@defmac LONG_DOUBLE_TYPE_SIZE 1505A C expression for the size in bits of the type @code{long double} on 1506the target machine. If you don't define this, the default is two 1507words. 1508@end defmac 1509 1510@defmac SHORT_FRACT_TYPE_SIZE 1511A C expression for the size in bits of the type @code{short _Fract} on 1512the target machine. If you don't define this, the default is 1513@code{BITS_PER_UNIT}. 1514@end defmac 1515 1516@defmac FRACT_TYPE_SIZE 1517A C expression for the size in bits of the type @code{_Fract} on 1518the target machine. If you don't define this, the default is 1519@code{BITS_PER_UNIT * 2}. 1520@end defmac 1521 1522@defmac LONG_FRACT_TYPE_SIZE 1523A C expression for the size in bits of the type @code{long _Fract} on 1524the target machine. If you don't define this, the default is 1525@code{BITS_PER_UNIT * 4}. 1526@end defmac 1527 1528@defmac LONG_LONG_FRACT_TYPE_SIZE 1529A C expression for the size in bits of the type @code{long long _Fract} on 1530the target machine. If you don't define this, the default is 1531@code{BITS_PER_UNIT * 8}. 1532@end defmac 1533 1534@defmac SHORT_ACCUM_TYPE_SIZE 1535A C expression for the size in bits of the type @code{short _Accum} on 1536the target machine. If you don't define this, the default is 1537@code{BITS_PER_UNIT * 2}. 1538@end defmac 1539 1540@defmac ACCUM_TYPE_SIZE 1541A C expression for the size in bits of the type @code{_Accum} on 1542the target machine. If you don't define this, the default is 1543@code{BITS_PER_UNIT * 4}. 1544@end defmac 1545 1546@defmac LONG_ACCUM_TYPE_SIZE 1547A C expression for the size in bits of the type @code{long _Accum} on 1548the target machine. If you don't define this, the default is 1549@code{BITS_PER_UNIT * 8}. 1550@end defmac 1551 1552@defmac LONG_LONG_ACCUM_TYPE_SIZE 1553A C expression for the size in bits of the type @code{long long _Accum} on 1554the target machine. If you don't define this, the default is 1555@code{BITS_PER_UNIT * 16}. 1556@end defmac 1557 1558@defmac LIBGCC2_LONG_DOUBLE_TYPE_SIZE 1559Define this macro if @code{LONG_DOUBLE_TYPE_SIZE} is not constant or 1560if you want routines in @file{libgcc2.a} for a size other than 1561@code{LONG_DOUBLE_TYPE_SIZE}. If you don't define this, the 1562default is @code{LONG_DOUBLE_TYPE_SIZE}. 1563@end defmac 1564 1565@defmac LIBGCC2_HAS_DF_MODE 1566Define this macro if neither @code{DOUBLE_TYPE_SIZE} nor 1567@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 1568@code{DFmode} but you want @code{DFmode} routines in @file{libgcc2.a} 1569anyway. If you don't define this and either @code{DOUBLE_TYPE_SIZE} 1570or @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64 then the default is 1, 1571otherwise it is 0. 1572@end defmac 1573 1574@defmac LIBGCC2_HAS_XF_MODE 1575Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1576@code{XFmode} but you want @code{XFmode} routines in @file{libgcc2.a} 1577anyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1578is 80 then the default is 1, otherwise it is 0. 1579@end defmac 1580 1581@defmac LIBGCC2_HAS_TF_MODE 1582Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1583@code{TFmode} but you want @code{TFmode} routines in @file{libgcc2.a} 1584anyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1585is 128 then the default is 1, otherwise it is 0. 1586@end defmac 1587 1588@defmac LIBGCC2_GNU_PREFIX 1589This macro corresponds to the @code{TARGET_LIBFUNC_GNU_PREFIX} target 1590hook and should be defined if that hook is overriden to be true. It 1591causes function names in libgcc to be changed to use a @code{__gnu_} 1592prefix for their name rather than the default @code{__}. A port which 1593uses this macro should also arrange to use @file{t-gnu-prefix} in 1594the libgcc @file{config.host}. 1595@end defmac 1596 1597@defmac SF_SIZE 1598@defmacx DF_SIZE 1599@defmacx XF_SIZE 1600@defmacx TF_SIZE 1601Define these macros to be the size in bits of the mantissa of 1602@code{SFmode}, @code{DFmode}, @code{XFmode} and @code{TFmode} values, 1603if the defaults in @file{libgcc2.h} are inappropriate. By default, 1604@code{FLT_MANT_DIG} is used for @code{SF_SIZE}, @code{LDBL_MANT_DIG} 1605for @code{XF_SIZE} and @code{TF_SIZE}, and @code{DBL_MANT_DIG} or 1606@code{LDBL_MANT_DIG} for @code{DF_SIZE} according to whether 1607@code{DOUBLE_TYPE_SIZE} or 1608@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64. 1609@end defmac 1610 1611@defmac TARGET_FLT_EVAL_METHOD 1612A C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, 1613assuming, if applicable, that the floating-point control word is in its 1614default state. If you do not define this macro the value of 1615@code{FLT_EVAL_METHOD} will be zero. 1616@end defmac 1617 1618@defmac WIDEST_HARDWARE_FP_SIZE 1619A C expression for the size in bits of the widest floating-point format 1620supported by the hardware. If you define this macro, you must specify a 1621value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 1622If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 1623is the default. 1624@end defmac 1625 1626@defmac DEFAULT_SIGNED_CHAR 1627An expression whose value is 1 or 0, according to whether the type 1628@code{char} should be signed or unsigned by default. The user can 1629always override this default with the options @option{-fsigned-char} 1630and @option{-funsigned-char}. 1631@end defmac 1632 1633@deftypefn {Target Hook} bool TARGET_DEFAULT_SHORT_ENUMS (void) 1634This target hook should return true if the compiler should give an 1635@code{enum} type only as many bytes as it takes to represent the range 1636of possible values of that type. It should return false if all 1637@code{enum} types should be allocated like @code{int}. 1638 1639The default is to return false. 1640@end deftypefn 1641 1642@defmac SIZE_TYPE 1643A C expression for a string describing the name of the data type to use 1644for size values. The typedef name @code{size_t} is defined using the 1645contents of the string. 1646 1647The string can contain more than one keyword. If so, separate them with 1648spaces, and write first any length keyword, then @code{unsigned} if 1649appropriate, and finally @code{int}. The string must exactly match one 1650of the data type names defined in the function 1651@code{init_decl_processing} in the file @file{c-decl.c}. You may not 1652omit @code{int} or change the order---that would cause the compiler to 1653crash on startup. 1654 1655If you don't define this macro, the default is @code{"long unsigned 1656int"}. 1657@end defmac 1658 1659@defmac PTRDIFF_TYPE 1660A C expression for a string describing the name of the data type to use 1661for the result of subtracting two pointers. The typedef name 1662@code{ptrdiff_t} is defined using the contents of the string. See 1663@code{SIZE_TYPE} above for more information. 1664 1665If you don't define this macro, the default is @code{"long int"}. 1666@end defmac 1667 1668@defmac WCHAR_TYPE 1669A C expression for a string describing the name of the data type to use 1670for wide characters. The typedef name @code{wchar_t} is defined using 1671the contents of the string. See @code{SIZE_TYPE} above for more 1672information. 1673 1674If you don't define this macro, the default is @code{"int"}. 1675@end defmac 1676 1677@defmac WCHAR_TYPE_SIZE 1678A C expression for the size in bits of the data type for wide 1679characters. This is used in @code{cpp}, which cannot make use of 1680@code{WCHAR_TYPE}. 1681@end defmac 1682 1683@defmac WINT_TYPE 1684A C expression for a string describing the name of the data type to 1685use for wide characters passed to @code{printf} and returned from 1686@code{getwc}. The typedef name @code{wint_t} is defined using the 1687contents of the string. See @code{SIZE_TYPE} above for more 1688information. 1689 1690If you don't define this macro, the default is @code{"unsigned int"}. 1691@end defmac 1692 1693@defmac INTMAX_TYPE 1694A C expression for a string describing the name of the data type that 1695can represent any value of any standard or extended signed integer type. 1696The typedef name @code{intmax_t} is defined using the contents of the 1697string. See @code{SIZE_TYPE} above for more information. 1698 1699If you don't define this macro, the default is the first of 1700@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 1701much precision as @code{long long int}. 1702@end defmac 1703 1704@defmac UINTMAX_TYPE 1705A C expression for a string describing the name of the data type that 1706can represent any value of any standard or extended unsigned integer 1707type. The typedef name @code{uintmax_t} is defined using the contents 1708of the string. See @code{SIZE_TYPE} above for more information. 1709 1710If you don't define this macro, the default is the first of 1711@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 1712unsigned int"} that has as much precision as @code{long long unsigned 1713int}. 1714@end defmac 1715 1716@defmac SIG_ATOMIC_TYPE 1717@defmacx INT8_TYPE 1718@defmacx INT16_TYPE 1719@defmacx INT32_TYPE 1720@defmacx INT64_TYPE 1721@defmacx UINT8_TYPE 1722@defmacx UINT16_TYPE 1723@defmacx UINT32_TYPE 1724@defmacx UINT64_TYPE 1725@defmacx INT_LEAST8_TYPE 1726@defmacx INT_LEAST16_TYPE 1727@defmacx INT_LEAST32_TYPE 1728@defmacx INT_LEAST64_TYPE 1729@defmacx UINT_LEAST8_TYPE 1730@defmacx UINT_LEAST16_TYPE 1731@defmacx UINT_LEAST32_TYPE 1732@defmacx UINT_LEAST64_TYPE 1733@defmacx INT_FAST8_TYPE 1734@defmacx INT_FAST16_TYPE 1735@defmacx INT_FAST32_TYPE 1736@defmacx INT_FAST64_TYPE 1737@defmacx UINT_FAST8_TYPE 1738@defmacx UINT_FAST16_TYPE 1739@defmacx UINT_FAST32_TYPE 1740@defmacx UINT_FAST64_TYPE 1741@defmacx INTPTR_TYPE 1742@defmacx UINTPTR_TYPE 1743C expressions for the standard types @code{sig_atomic_t}, 1744@code{int8_t}, @code{int16_t}, @code{int32_t}, @code{int64_t}, 1745@code{uint8_t}, @code{uint16_t}, @code{uint32_t}, @code{uint64_t}, 1746@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, 1747@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, 1748@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, 1749@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, 1750@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, 1751@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t}. See 1752@code{SIZE_TYPE} above for more information. 1753 1754If any of these macros evaluates to a null pointer, the corresponding 1755type is not supported; if GCC is configured to provide 1756@code{<stdint.h>} in such a case, the header provided may not conform 1757to C99, depending on the type in question. The defaults for all of 1758these macros are null pointers. 1759@end defmac 1760 1761@defmac TARGET_PTRMEMFUNC_VBIT_LOCATION 1762The C++ compiler represents a pointer-to-member-function with a struct 1763that looks like: 1764 1765@smallexample 1766 struct @{ 1767 union @{ 1768 void (*fn)(); 1769 ptrdiff_t vtable_index; 1770 @}; 1771 ptrdiff_t delta; 1772 @}; 1773@end smallexample 1774 1775@noindent 1776The C++ compiler must use one bit to indicate whether the function that 1777will be called through a pointer-to-member-function is virtual. 1778Normally, we assume that the low-order bit of a function pointer must 1779always be zero. Then, by ensuring that the vtable_index is odd, we can 1780distinguish which variant of the union is in use. But, on some 1781platforms function pointers can be odd, and so this doesn't work. In 1782that case, we use the low-order bit of the @code{delta} field, and shift 1783the remainder of the @code{delta} field to the left. 1784 1785GCC will automatically make the right selection about where to store 1786this bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 1787However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 1788set such that functions always start at even addresses, but the lowest 1789bit of pointers to functions indicate whether the function at that 1790address is in ARM or Thumb mode. If this is the case of your 1791architecture, you should define this macro to 1792@code{ptrmemfunc_vbit_in_delta}. 1793 1794In general, you should not have to define this macro. On architectures 1795in which function addresses are always even, according to 1796@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 1797@code{ptrmemfunc_vbit_in_pfn}. 1798@end defmac 1799 1800@defmac TARGET_VTABLE_USES_DESCRIPTORS 1801Normally, the C++ compiler uses function pointers in vtables. This 1802macro allows the target to change to use ``function descriptors'' 1803instead. Function descriptors are found on targets for whom a 1804function pointer is actually a small data structure. Normally the 1805data structure consists of the actual code address plus a data 1806pointer to which the function's data is relative. 1807 1808If vtables are used, the value of this macro should be the number 1809of words that the function descriptor occupies. 1810@end defmac 1811 1812@defmac TARGET_VTABLE_ENTRY_ALIGN 1813By default, the vtable entries are void pointers, the so the alignment 1814is the same as pointer alignment. The value of this macro specifies 1815the alignment of the vtable entry in bits. It should be defined only 1816when special alignment is necessary. */ 1817@end defmac 1818 1819@defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE 1820There are a few non-descriptor entries in the vtable at offsets below 1821zero. If these entries must be padded (say, to preserve the alignment 1822specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number 1823of words in each data entry. 1824@end defmac 1825 1826@node Registers 1827@section Register Usage 1828@cindex register usage 1829 1830This section explains how to describe what registers the target machine 1831has, and how (in general) they can be used. 1832 1833The description of which registers a specific instruction can use is 1834done with register classes; see @ref{Register Classes}. For information 1835on using registers to access a stack frame, see @ref{Frame Registers}. 1836For passing values in registers, see @ref{Register Arguments}. 1837For returning values in registers, see @ref{Scalar Return}. 1838 1839@menu 1840* Register Basics:: Number and kinds of registers. 1841* Allocation Order:: Order in which registers are allocated. 1842* Values in Registers:: What kinds of values each reg can hold. 1843* Leaf Functions:: Renumbering registers for leaf functions. 1844* Stack Registers:: Handling a register stack such as 80387. 1845@end menu 1846 1847@node Register Basics 1848@subsection Basic Characteristics of Registers 1849 1850@c prevent bad page break with this line 1851Registers have various characteristics. 1852 1853@defmac FIRST_PSEUDO_REGISTER 1854Number of hardware registers known to the compiler. They receive 1855numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 1856pseudo register's number really is assigned the number 1857@code{FIRST_PSEUDO_REGISTER}. 1858@end defmac 1859 1860@defmac FIXED_REGISTERS 1861@cindex fixed register 1862An initializer that says which registers are used for fixed purposes 1863all throughout the compiled code and are therefore not available for 1864general allocation. These would include the stack pointer, the frame 1865pointer (except on machines where that can be used as a general 1866register when no frame pointer is needed), the program counter on 1867machines where that is considered one of the addressable registers, 1868and any other numbered register with a standard use. 1869 1870This information is expressed as a sequence of numbers, separated by 1871commas and surrounded by braces. The @var{n}th number is 1 if 1872register @var{n} is fixed, 0 otherwise. 1873 1874The table initialized from this macro, and the table initialized by 1875the following one, may be overridden at run time either automatically, 1876by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 1877the user with the command options @option{-ffixed-@var{reg}}, 1878@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. 1879@end defmac 1880 1881@defmac CALL_USED_REGISTERS 1882@cindex call-used register 1883@cindex call-clobbered register 1884@cindex call-saved register 1885Like @code{FIXED_REGISTERS} but has 1 for each register that is 1886clobbered (in general) by function calls as well as for fixed 1887registers. This macro therefore identifies the registers that are not 1888available for general allocation of values that must live across 1889function calls. 1890 1891If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 1892automatically saves it on function entry and restores it on function 1893exit, if the register is used within the function. 1894@end defmac 1895 1896@defmac CALL_REALLY_USED_REGISTERS 1897@cindex call-used register 1898@cindex call-clobbered register 1899@cindex call-saved register 1900Like @code{CALL_USED_REGISTERS} except this macro doesn't require 1901that the entire set of @code{FIXED_REGISTERS} be included. 1902(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). 1903This macro is optional. If not specified, it defaults to the value 1904of @code{CALL_USED_REGISTERS}. 1905@end defmac 1906 1907@defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) 1908@cindex call-used register 1909@cindex call-clobbered register 1910@cindex call-saved register 1911A C expression that is nonzero if it is not permissible to store a 1912value of mode @var{mode} in hard register number @var{regno} across a 1913call without some part of it being clobbered. For most machines this 1914macro need not be defined. It is only required for machines that do not 1915preserve the entire contents of a register across a call. 1916@end defmac 1917 1918@findex fixed_regs 1919@findex call_used_regs 1920@findex global_regs 1921@findex reg_names 1922@findex reg_class_contents 1923@deftypefn {Target Hook} void TARGET_CONDITIONAL_REGISTER_USAGE (void) 1924This hook may conditionally modify five variables 1925@code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, 1926@code{reg_names}, and @code{reg_class_contents}, to take into account 1927any dependence of these register sets on target flags. The first three 1928of these are of type @code{char []} (interpreted as Boolean vectors). 1929@code{global_regs} is a @code{const char *[]}, and 1930@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is 1931called, @code{fixed_regs}, @code{call_used_regs}, 1932@code{reg_class_contents}, and @code{reg_names} have been initialized 1933from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, 1934@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. 1935@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, 1936@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} 1937command options have been applied. 1938 1939@cindex disabling certain registers 1940@cindex controlling register usage 1941If the usage of an entire class of registers depends on the target 1942flags, you may indicate this to GCC by using this macro to modify 1943@code{fixed_regs} and @code{call_used_regs} to 1 for each of the 1944registers in the classes which should not be used by GCC@. Also define 1945the macro @code{REG_CLASS_FROM_LETTER} / @code{REG_CLASS_FROM_CONSTRAINT} 1946to return @code{NO_REGS} if it 1947is called with a letter for a class that shouldn't be used. 1948 1949(However, if this class is not included in @code{GENERAL_REGS} and all 1950of the insn patterns whose constraints permit this class are 1951controlled by target switches, then GCC will automatically avoid using 1952these registers when the target switches are opposed to them.) 1953@end deftypefn 1954 1955@defmac INCOMING_REGNO (@var{out}) 1956Define this macro if the target machine has register windows. This C 1957expression returns the register number as seen by the called function 1958corresponding to the register number @var{out} as seen by the calling 1959function. Return @var{out} if register number @var{out} is not an 1960outbound register. 1961@end defmac 1962 1963@defmac OUTGOING_REGNO (@var{in}) 1964Define this macro if the target machine has register windows. This C 1965expression returns the register number as seen by the calling function 1966corresponding to the register number @var{in} as seen by the called 1967function. Return @var{in} if register number @var{in} is not an inbound 1968register. 1969@end defmac 1970 1971@defmac LOCAL_REGNO (@var{regno}) 1972Define this macro if the target machine has register windows. This C 1973expression returns true if the register is call-saved but is in the 1974register window. Unlike most call-saved registers, such registers 1975need not be explicitly restored on function exit or during non-local 1976gotos. 1977@end defmac 1978 1979@defmac PC_REGNUM 1980If the program counter has a register number, define this as that 1981register number. Otherwise, do not define it. 1982@end defmac 1983 1984@node Allocation Order 1985@subsection Order of Allocation of Registers 1986@cindex order of register allocation 1987@cindex register allocation order 1988 1989@c prevent bad page break with this line 1990Registers are allocated in order. 1991 1992@defmac REG_ALLOC_ORDER 1993If defined, an initializer for a vector of integers, containing the 1994numbers of hard registers in the order in which GCC should prefer 1995to use them (from most preferred to least). 1996 1997If this macro is not defined, registers are used lowest numbered first 1998(all else being equal). 1999 2000One use of this macro is on machines where the highest numbered 2001registers must always be saved and the save-multiple-registers 2002instruction supports only sequences of consecutive registers. On such 2003machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 2004the highest numbered allocable register first. 2005@end defmac 2006 2007@defmac ADJUST_REG_ALLOC_ORDER 2008A C statement (sans semicolon) to choose the order in which to allocate 2009hard registers for pseudo-registers local to a basic block. 2010 2011Store the desired register order in the array @code{reg_alloc_order}. 2012Element 0 should be the register to allocate first; element 1, the next 2013register; and so on. 2014 2015The macro body should not assume anything about the contents of 2016@code{reg_alloc_order} before execution of the macro. 2017 2018On most machines, it is not necessary to define this macro. 2019@end defmac 2020 2021@defmac HONOR_REG_ALLOC_ORDER 2022Normally, IRA tries to estimate the costs for saving a register in the 2023prologue and restoring it in the epilogue. This discourages it from 2024using call-saved registers. If a machine wants to ensure that IRA 2025allocates registers in the order given by REG_ALLOC_ORDER even if some 2026call-saved registers appear earlier than call-used ones, this macro 2027should be defined. 2028@end defmac 2029 2030@defmac IRA_HARD_REGNO_ADD_COST_MULTIPLIER (@var{regno}) 2031In some case register allocation order is not enough for the 2032Integrated Register Allocator (@acronym{IRA}) to generate a good code. 2033If this macro is defined, it should return a floating point value 2034based on @var{regno}. The cost of using @var{regno} for a pseudo will 2035be increased by approximately the pseudo's usage frequency times the 2036value returned by this macro. Not defining this macro is equivalent 2037to having it always return @code{0.0}. 2038 2039On most machines, it is not necessary to define this macro. 2040@end defmac 2041 2042@node Values in Registers 2043@subsection How Values Fit in Registers 2044 2045This section discusses the macros that describe which kinds of values 2046(specifically, which machine modes) each register can hold, and how many 2047consecutive registers are needed for a given mode. 2048 2049@defmac HARD_REGNO_NREGS (@var{regno}, @var{mode}) 2050A C expression for the number of consecutive hard registers, starting 2051at register number @var{regno}, required to hold a value of mode 2052@var{mode}. This macro must never return zero, even if a register 2053cannot hold the requested mode - indicate that with HARD_REGNO_MODE_OK 2054and/or CANNOT_CHANGE_MODE_CLASS instead. 2055 2056On a machine where all registers are exactly one word, a suitable 2057definition of this macro is 2058 2059@smallexample 2060#define HARD_REGNO_NREGS(REGNO, MODE) \ 2061 ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 2062 / UNITS_PER_WORD) 2063@end smallexample 2064@end defmac 2065 2066@defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode}) 2067A C expression that is nonzero if a value of mode @var{mode}, stored 2068in memory, ends with padding that causes it to take up more space than 2069in registers starting at register number @var{regno} (as determined by 2070multiplying GCC's notion of the size of the register when containing 2071this mode by the number of registers returned by 2072@code{HARD_REGNO_NREGS}). By default this is zero. 2073 2074For example, if a floating-point value is stored in three 32-bit 2075registers but takes up 128 bits in memory, then this would be 2076nonzero. 2077 2078This macros only needs to be defined if there are cases where 2079@code{subreg_get_info} 2080would otherwise wrongly determine that a @code{subreg} can be 2081represented by an offset to the register number, when in fact such a 2082@code{subreg} would contain some of the padding not stored in 2083registers and so not be representable. 2084@end defmac 2085 2086@defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode}) 2087For values of @var{regno} and @var{mode} for which 2088@code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression 2089returning the greater number of registers required to hold the value 2090including any padding. In the example above, the value would be four. 2091@end defmac 2092 2093@defmac REGMODE_NATURAL_SIZE (@var{mode}) 2094Define this macro if the natural size of registers that hold values 2095of mode @var{mode} is not the word size. It is a C expression that 2096should give the natural size in bytes for the specified mode. It is 2097used by the register allocator to try to optimize its results. This 2098happens for example on SPARC 64-bit where the natural size of 2099floating-point registers is still 32-bit. 2100@end defmac 2101 2102@defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 2103A C expression that is nonzero if it is permissible to store a value 2104of mode @var{mode} in hard register number @var{regno} (or in several 2105registers starting with that one). For a machine where all registers 2106are equivalent, a suitable definition is 2107 2108@smallexample 2109#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 2110@end smallexample 2111 2112You need not include code to check for the numbers of fixed registers, 2113because the allocation mechanism considers them to be always occupied. 2114 2115@cindex register pairs 2116On some machines, double-precision values must be kept in even/odd 2117register pairs. You can implement that by defining this macro to reject 2118odd register numbers for such modes. 2119 2120The minimum requirement for a mode to be OK in a register is that the 2121@samp{mov@var{mode}} instruction pattern support moves between the 2122register and other hard register in the same class and that moving a 2123value into the register and back out not alter it. 2124 2125Since the same instruction used to move @code{word_mode} will work for 2126all narrower integer modes, it is not necessary on any machine for 2127@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 2128you define patterns @samp{movhi}, etc., to take advantage of this. This 2129is useful because of the interaction between @code{HARD_REGNO_MODE_OK} 2130and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 2131to be tieable. 2132 2133Many machines have special registers for floating point arithmetic. 2134Often people assume that floating point machine modes are allowed only 2135in floating point registers. This is not true. Any registers that 2136can hold integers can safely @emph{hold} a floating point machine 2137mode, whether or not floating arithmetic can be done on it in those 2138registers. Integer move instructions can be used to move the values. 2139 2140On some machines, though, the converse is true: fixed-point machine 2141modes may not go in floating registers. This is true if the floating 2142registers normalize any value stored in them, because storing a 2143non-floating value there would garble it. In this case, 2144@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 2145floating registers. But if the floating registers do not automatically 2146normalize, if you can store any bit pattern in one and retrieve it 2147unchanged without a trap, then any machine mode may go in a floating 2148register, so you can define this macro to say so. 2149 2150The primary significance of special floating registers is rather that 2151they are the registers acceptable in floating point arithmetic 2152instructions. However, this is of no concern to 2153@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 2154constraints for those instructions. 2155 2156On some machines, the floating registers are especially slow to access, 2157so that it is better to store a value in a stack frame than in such a 2158register if floating point arithmetic is not being done. As long as the 2159floating registers are not in class @code{GENERAL_REGS}, they will not 2160be used unless some pattern's constraint asks for one. 2161@end defmac 2162 2163@defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to}) 2164A C expression that is nonzero if it is OK to rename a hard register 2165@var{from} to another hard register @var{to}. 2166 2167One common use of this macro is to prevent renaming of a register to 2168another register that is not saved by a prologue in an interrupt 2169handler. 2170 2171The default is always nonzero. 2172@end defmac 2173 2174@defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 2175A C expression that is nonzero if a value of mode 2176@var{mode1} is accessible in mode @var{mode2} without copying. 2177 2178If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 2179@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for 2180any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})} 2181should be nonzero. If they differ for any @var{r}, you should define 2182this macro to return zero unless some other mechanism ensures the 2183accessibility of the value in a narrower mode. 2184 2185You should define this macro to return nonzero in as many cases as 2186possible since doing so will allow GCC to perform better register 2187allocation. 2188@end defmac 2189 2190@deftypefn {Target Hook} bool TARGET_HARD_REGNO_SCRATCH_OK (unsigned int @var{regno}) 2191This target hook should return @code{true} if it is OK to use a hard register 2192@var{regno} as scratch reg in peephole2. 2193 2194One common use of this macro is to prevent using of a register that 2195is not saved by a prologue in an interrupt handler. 2196 2197The default version of this hook always returns @code{true}. 2198@end deftypefn 2199 2200@defmac AVOID_CCMODE_COPIES 2201Define this macro if the compiler should avoid copies to/from @code{CCmode} 2202registers. You should only define this macro if support for copying to/from 2203@code{CCmode} is incomplete. 2204@end defmac 2205 2206@node Leaf Functions 2207@subsection Handling Leaf Functions 2208 2209@cindex leaf functions 2210@cindex functions, leaf 2211On some machines, a leaf function (i.e., one which makes no calls) can run 2212more efficiently if it does not make its own register window. Often this 2213means it is required to receive its arguments in the registers where they 2214are passed by the caller, instead of the registers where they would 2215normally arrive. 2216 2217The special treatment for leaf functions generally applies only when 2218other conditions are met; for example, often they may use only those 2219registers for its own variables and temporaries. We use the term ``leaf 2220function'' to mean a function that is suitable for this special 2221handling, so that functions with no calls are not necessarily ``leaf 2222functions''. 2223 2224GCC assigns register numbers before it knows whether the function is 2225suitable for leaf function treatment. So it needs to renumber the 2226registers in order to output a leaf function. The following macros 2227accomplish this. 2228 2229@defmac LEAF_REGISTERS 2230Name of a char vector, indexed by hard register number, which 2231contains 1 for a register that is allowable in a candidate for leaf 2232function treatment. 2233 2234If leaf function treatment involves renumbering the registers, then the 2235registers marked here should be the ones before renumbering---those that 2236GCC would ordinarily allocate. The registers which will actually be 2237used in the assembler code, after renumbering, should not be marked with 1 2238in this vector. 2239 2240Define this macro only if the target machine offers a way to optimize 2241the treatment of leaf functions. 2242@end defmac 2243 2244@defmac LEAF_REG_REMAP (@var{regno}) 2245A C expression whose value is the register number to which @var{regno} 2246should be renumbered, when a function is treated as a leaf function. 2247 2248If @var{regno} is a register number which should not appear in a leaf 2249function before renumbering, then the expression should yield @minus{}1, which 2250will cause the compiler to abort. 2251 2252Define this macro only if the target machine offers a way to optimize the 2253treatment of leaf functions, and registers need to be renumbered to do 2254this. 2255@end defmac 2256 2257@findex current_function_is_leaf 2258@findex current_function_uses_only_leaf_regs 2259@code{TARGET_ASM_FUNCTION_PROLOGUE} and 2260@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions 2261specially. They can test the C variable @code{current_function_is_leaf} 2262which is nonzero for leaf functions. @code{current_function_is_leaf} is 2263set prior to local register allocation and is valid for the remaining 2264compiler passes. They can also test the C variable 2265@code{current_function_uses_only_leaf_regs} which is nonzero for leaf 2266functions which only use leaf registers. 2267@code{current_function_uses_only_leaf_regs} is valid after all passes 2268that modify the instructions have been run and is only useful if 2269@code{LEAF_REGISTERS} is defined. 2270@c changed this to fix overfull. ALSO: why the "it" at the beginning 2271@c of the next paragraph?! --mew 2feb93 2272 2273@node Stack Registers 2274@subsection Registers That Form a Stack 2275 2276There are special features to handle computers where some of the 2277``registers'' form a stack. Stack registers are normally written by 2278pushing onto the stack, and are numbered relative to the top of the 2279stack. 2280 2281Currently, GCC can only handle one group of stack-like registers, and 2282they must be consecutively numbered. Furthermore, the existing 2283support for stack-like registers is specific to the 80387 floating 2284point coprocessor. If you have a new architecture that uses 2285stack-like registers, you will need to do substantial work on 2286@file{reg-stack.c} and write your machine description to cooperate 2287with it, as well as defining these macros. 2288 2289@defmac STACK_REGS 2290Define this if the machine has any stack-like registers. 2291@end defmac 2292 2293@defmac STACK_REG_COVER_CLASS 2294This is a cover class containing the stack registers. Define this if 2295the machine has any stack-like registers. 2296@end defmac 2297 2298@defmac FIRST_STACK_REG 2299The number of the first stack-like register. This one is the top 2300of the stack. 2301@end defmac 2302 2303@defmac LAST_STACK_REG 2304The number of the last stack-like register. This one is the bottom of 2305the stack. 2306@end defmac 2307 2308@node Register Classes 2309@section Register Classes 2310@cindex register class definitions 2311@cindex class definitions, register 2312 2313On many machines, the numbered registers are not all equivalent. 2314For example, certain registers may not be allowed for indexed addressing; 2315certain registers may not be allowed in some instructions. These machine 2316restrictions are described to the compiler using @dfn{register classes}. 2317 2318You define a number of register classes, giving each one a name and saying 2319which of the registers belong to it. Then you can specify register classes 2320that are allowed as operands to particular instruction patterns. 2321 2322@findex ALL_REGS 2323@findex NO_REGS 2324In general, each register will belong to several classes. In fact, one 2325class must be named @code{ALL_REGS} and contain all the registers. Another 2326class must be named @code{NO_REGS} and contain no registers. Often the 2327union of two classes will be another class; however, this is not required. 2328 2329@findex GENERAL_REGS 2330One of the classes must be named @code{GENERAL_REGS}. There is nothing 2331terribly special about the name, but the operand constraint letters 2332@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 2333the same as @code{ALL_REGS}, just define it as a macro which expands 2334to @code{ALL_REGS}. 2335 2336Order the classes so that if class @var{x} is contained in class @var{y} 2337then @var{x} has a lower class number than @var{y}. 2338 2339The way classes other than @code{GENERAL_REGS} are specified in operand 2340constraints is through machine-dependent operand constraint letters. 2341You can define such letters to correspond to various classes, then use 2342them in operand constraints. 2343 2344You must define the narrowest register classes for allocatable 2345registers, so that each class either has no subclasses, or that for 2346some mode, the move cost between registers within the class is 2347cheaper than moving a register in the class to or from memory 2348(@pxref{Costs}). 2349 2350You should define a class for the union of two classes whenever some 2351instruction allows both classes. For example, if an instruction allows 2352either a floating point (coprocessor) register or a general register for a 2353certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 2354which includes both of them. Otherwise you will get suboptimal code, 2355or even internal compiler errors when reload cannot find a register in the 2356class computed via @code{reg_class_subunion}. 2357 2358You must also specify certain redundant information about the register 2359classes: for each class, which classes contain it and which ones are 2360contained in it; for each pair of classes, the largest class contained 2361in their union. 2362 2363When a value occupying several consecutive registers is expected in a 2364certain class, all the registers used must belong to that class. 2365Therefore, register classes cannot be used to enforce a requirement for 2366a register pair to start with an even-numbered register. The way to 2367specify this requirement is with @code{HARD_REGNO_MODE_OK}. 2368 2369Register classes used for input-operands of bitwise-and or shift 2370instructions have a special requirement: each such class must have, for 2371each fixed-point machine mode, a subclass whose registers can transfer that 2372mode to or from memory. For example, on some machines, the operations for 2373single-byte values (@code{QImode}) are limited to certain registers. When 2374this is so, each register class that is used in a bitwise-and or shift 2375instruction must have a subclass consisting of registers from which 2376single-byte values can be loaded or stored. This is so that 2377@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 2378 2379@deftp {Data type} {enum reg_class} 2380An enumerated type that must be defined with all the register class names 2381as enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS} 2382must be the last register class, followed by one more enumerated value, 2383@code{LIM_REG_CLASSES}, which is not a register class but rather 2384tells how many classes there are. 2385 2386Each register class has a number, which is the value of casting 2387the class name to type @code{int}. The number serves as an index 2388in many of the tables described below. 2389@end deftp 2390 2391@defmac N_REG_CLASSES 2392The number of distinct register classes, defined as follows: 2393 2394@smallexample 2395#define N_REG_CLASSES (int) LIM_REG_CLASSES 2396@end smallexample 2397@end defmac 2398 2399@defmac REG_CLASS_NAMES 2400An initializer containing the names of the register classes as C string 2401constants. These names are used in writing some of the debugging dumps. 2402@end defmac 2403 2404@defmac REG_CLASS_CONTENTS 2405An initializer containing the contents of the register classes, as integers 2406which are bit masks. The @var{n}th integer specifies the contents of class 2407@var{n}. The way the integer @var{mask} is interpreted is that 2408register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 2409 2410When the machine has more than 32 registers, an integer does not suffice. 2411Then the integers are replaced by sub-initializers, braced groupings containing 2412several integers. Each sub-initializer must be suitable as an initializer 2413for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 2414In this situation, the first integer in each sub-initializer corresponds to 2415registers 0 through 31, the second integer to registers 32 through 63, and 2416so on. 2417@end defmac 2418 2419@defmac REGNO_REG_CLASS (@var{regno}) 2420A C expression whose value is a register class containing hard register 2421@var{regno}. In general there is more than one such class; choose a class 2422which is @dfn{minimal}, meaning that no smaller class also contains the 2423register. 2424@end defmac 2425 2426@defmac BASE_REG_CLASS 2427A macro whose definition is the name of the class to which a valid 2428base register must belong. A base register is one used in an address 2429which is the register value plus a displacement. 2430@end defmac 2431 2432@defmac MODE_BASE_REG_CLASS (@var{mode}) 2433This is a variation of the @code{BASE_REG_CLASS} macro which allows 2434the selection of a base register in a mode dependent manner. If 2435@var{mode} is VOIDmode then it should return the same value as 2436@code{BASE_REG_CLASS}. 2437@end defmac 2438 2439@defmac MODE_BASE_REG_REG_CLASS (@var{mode}) 2440A C expression whose value is the register class to which a valid 2441base register must belong in order to be used in a base plus index 2442register address. You should define this macro if base plus index 2443addresses have different requirements than other base register uses. 2444@end defmac 2445 2446@defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{address_space}, @var{outer_code}, @var{index_code}) 2447A C expression whose value is the register class to which a valid 2448base register for a memory reference in mode @var{mode} to address 2449space @var{address_space} must belong. @var{outer_code} and @var{index_code} 2450define the context in which the base register occurs. @var{outer_code} is 2451the code of the immediately enclosing expression (@code{MEM} for the top level 2452of an address, @code{ADDRESS} for something that occurs in an 2453@code{address_operand}). @var{index_code} is the code of the corresponding 2454index expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise. 2455@end defmac 2456 2457@defmac INDEX_REG_CLASS 2458A macro whose definition is the name of the class to which a valid 2459index register must belong. An index register is one used in an 2460address where its value is either multiplied by a scale factor or 2461added to another register (as well as added to a displacement). 2462@end defmac 2463 2464@defmac REGNO_OK_FOR_BASE_P (@var{num}) 2465A C expression which is nonzero if register number @var{num} is 2466suitable for use as a base register in operand addresses. 2467@end defmac 2468 2469@defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) 2470A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that 2471that expression may examine the mode of the memory reference in 2472@var{mode}. You should define this macro if the mode of the memory 2473reference affects whether a register may be used as a base register. If 2474you define this macro, the compiler will use it instead of 2475@code{REGNO_OK_FOR_BASE_P}. The mode may be @code{VOIDmode} for 2476addresses that appear outside a @code{MEM}, i.e., as an 2477@code{address_operand}. 2478@end defmac 2479 2480@defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode}) 2481A C expression which is nonzero if register number @var{num} is suitable for 2482use as a base register in base plus index operand addresses, accessing 2483memory in mode @var{mode}. It may be either a suitable hard register or a 2484pseudo register that has been allocated such a hard register. You should 2485define this macro if base plus index addresses have different requirements 2486than other base register uses. 2487 2488Use of this macro is deprecated; please use the more general 2489@code{REGNO_MODE_CODE_OK_FOR_BASE_P}. 2490@end defmac 2491 2492@defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{address_space}, @var{outer_code}, @var{index_code}) 2493A C expression which is nonzero if register number @var{num} is 2494suitable for use as a base register in operand addresses, accessing 2495memory in mode @var{mode} in address space @var{address_space}. 2496This is similar to @code{REGNO_MODE_OK_FOR_BASE_P}, except 2497that that expression may examine the context in which the register 2498appears in the memory reference. @var{outer_code} is the code of the 2499immediately enclosing expression (@code{MEM} if at the top level of the 2500address, @code{ADDRESS} for something that occurs in an 2501@code{address_operand}). @var{index_code} is the code of the 2502corresponding index expression if @var{outer_code} is @code{PLUS}; 2503@code{SCRATCH} otherwise. The mode may be @code{VOIDmode} for addresses 2504that appear outside a @code{MEM}, i.e., as an @code{address_operand}. 2505@end defmac 2506 2507@defmac REGNO_OK_FOR_INDEX_P (@var{num}) 2508A C expression which is nonzero if register number @var{num} is 2509suitable for use as an index register in operand addresses. It may be 2510either a suitable hard register or a pseudo register that has been 2511allocated such a hard register. 2512 2513The difference between an index register and a base register is that 2514the index register may be scaled. If an address involves the sum of 2515two registers, neither one of them scaled, then either one may be 2516labeled the ``base'' and the other the ``index''; but whichever 2517labeling is used must fit the machine's constraints of which registers 2518may serve in each capacity. The compiler will try both labelings, 2519looking for one that is valid, and will reload one or both registers 2520only if neither labeling works. 2521@end defmac 2522 2523@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RENAME_CLASS (reg_class_t @var{rclass}) 2524A target hook that places additional preference on the register class to use when it is necessary to rename a register in class @var{rclass} to another class, or perhaps @var{NO_REGS}, if no preferred register class is found or hook @code{preferred_rename_class} is not implemented. Sometimes returning a more restrictive class makes better code. For example, on ARM, thumb-2 instructions using @code{LO_REGS} may be smaller than instructions using @code{GENERIC_REGS}. By returning @code{LO_REGS} from @code{preferred_rename_class}, code size can be reduced. 2525@end deftypefn 2526 2527@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass}) 2528A target hook that places additional restrictions on the register class 2529to use when it is necessary to copy value @var{x} into a register in class 2530@var{rclass}. The value is a register class; perhaps @var{rclass}, or perhaps 2531another, smaller class. 2532 2533The default version of this hook always returns value of @code{rclass} argument. 2534 2535Sometimes returning a more restrictive class makes better code. For 2536example, on the 68000, when @var{x} is an integer constant that is in range 2537for a @samp{moveq} instruction, the value of this macro is always 2538@code{DATA_REGS} as long as @var{rclass} includes the data registers. 2539Requiring a data register guarantees that a @samp{moveq} will be used. 2540 2541One case where @code{TARGET_PREFERRED_RELOAD_CLASS} must not return 2542@var{rclass} is if @var{x} is a legitimate constant which cannot be 2543loaded into some register class. By returning @code{NO_REGS} you can 2544force @var{x} into a memory location. For example, rs6000 can load 2545immediate values into general-purpose registers, but does not have an 2546instruction for loading an immediate value into a floating-point 2547register, so @code{TARGET_PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when 2548@var{x} is a floating-point constant. If the constant can't be loaded 2549into any kind of register, code generation will be better if 2550@code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead 2551of using @code{TARGET_PREFERRED_RELOAD_CLASS}. 2552 2553If an insn has pseudos in it after register allocation, reload will go 2554through the alternatives and call repeatedly @code{TARGET_PREFERRED_RELOAD_CLASS} 2555to find the best one. Returning @code{NO_REGS}, in this case, makes 2556reload add a @code{!} in front of the constraint: the x86 back-end uses 2557this feature to discourage usage of 387 registers when math is done in 2558the SSE registers (and vice versa). 2559@end deftypefn 2560 2561@defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 2562A C expression that places additional restrictions on the register class 2563to use when it is necessary to copy value @var{x} into a register in class 2564@var{class}. The value is a register class; perhaps @var{class}, or perhaps 2565another, smaller class. On many machines, the following definition is 2566safe: 2567 2568@smallexample 2569#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 2570@end smallexample 2571 2572Sometimes returning a more restrictive class makes better code. For 2573example, on the 68000, when @var{x} is an integer constant that is in range 2574for a @samp{moveq} instruction, the value of this macro is always 2575@code{DATA_REGS} as long as @var{class} includes the data registers. 2576Requiring a data register guarantees that a @samp{moveq} will be used. 2577 2578One case where @code{PREFERRED_RELOAD_CLASS} must not return 2579@var{class} is if @var{x} is a legitimate constant which cannot be 2580loaded into some register class. By returning @code{NO_REGS} you can 2581force @var{x} into a memory location. For example, rs6000 can load 2582immediate values into general-purpose registers, but does not have an 2583instruction for loading an immediate value into a floating-point 2584register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when 2585@var{x} is a floating-point constant. If the constant can't be loaded 2586into any kind of register, code generation will be better if 2587@code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead 2588of using @code{TARGET_PREFERRED_RELOAD_CLASS}. 2589 2590If an insn has pseudos in it after register allocation, reload will go 2591through the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS} 2592to find the best one. Returning @code{NO_REGS}, in this case, makes 2593reload add a @code{!} in front of the constraint: the x86 back-end uses 2594this feature to discourage usage of 387 registers when math is done in 2595the SSE registers (and vice versa). 2596@end defmac 2597 2598@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_OUTPUT_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass}) 2599Like @code{TARGET_PREFERRED_RELOAD_CLASS}, but for output reloads instead of 2600input reloads. 2601 2602The default version of this hook always returns value of @code{rclass} 2603argument. 2604 2605You can also use @code{TARGET_PREFERRED_OUTPUT_RELOAD_CLASS} to discourage 2606reload from using some alternatives, like @code{TARGET_PREFERRED_RELOAD_CLASS}. 2607@end deftypefn 2608 2609@defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 2610A C expression that places additional restrictions on the register class 2611to use when it is necessary to be able to hold a value of mode 2612@var{mode} in a reload register for which class @var{class} would 2613ordinarily be used. 2614 2615Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 2616there are certain modes that simply can't go in certain reload classes. 2617 2618The value is a register class; perhaps @var{class}, or perhaps another, 2619smaller class. 2620 2621Don't define this macro unless the target machine has limitations which 2622require the macro to do something nontrivial. 2623@end defmac 2624 2625@deftypefn {Target Hook} reg_class_t TARGET_SECONDARY_RELOAD (bool @var{in_p}, rtx @var{x}, reg_class_t @var{reload_class}, enum machine_mode @var{reload_mode}, secondary_reload_info *@var{sri}) 2626Many machines have some registers that cannot be copied directly to or 2627from memory or even from other types of registers. An example is the 2628@samp{MQ} register, which on most machines, can only be copied to or 2629from general registers, but not memory. Below, we shall be using the 2630term 'intermediate register' when a move operation cannot be performed 2631directly, but has to be done by copying the source into the intermediate 2632register first, and then copying the intermediate register to the 2633destination. An intermediate register always has the same mode as 2634source and destination. Since it holds the actual value being copied, 2635reload might apply optimizations to re-use an intermediate register 2636and eliding the copy from the source when it can determine that the 2637intermediate register still holds the required value. 2638 2639Another kind of secondary reload is required on some machines which 2640allow copying all registers to and from memory, but require a scratch 2641register for stores to some memory locations (e.g., those with symbolic 2642address on the RT, and those with certain symbolic address on the SPARC 2643when compiling PIC)@. Scratch registers need not have the same mode 2644as the value being copied, and usually hold a different value than 2645that being copied. Special patterns in the md file are needed to 2646describe how the copy is performed with the help of the scratch register; 2647these patterns also describe the number, register class(es) and mode(s) 2648of the scratch register(s). 2649 2650In some cases, both an intermediate and a scratch register are required. 2651 2652For input reloads, this target hook is called with nonzero @var{in_p}, 2653and @var{x} is an rtx that needs to be copied to a register of class 2654@var{reload_class} in @var{reload_mode}. For output reloads, this target 2655hook is called with zero @var{in_p}, and a register of class @var{reload_class} 2656needs to be copied to rtx @var{x} in @var{reload_mode}. 2657 2658If copying a register of @var{reload_class} from/to @var{x} requires 2659an intermediate register, the hook @code{secondary_reload} should 2660return the register class required for this intermediate register. 2661If no intermediate register is required, it should return NO_REGS. 2662If more than one intermediate register is required, describe the one 2663that is closest in the copy chain to the reload register. 2664 2665If scratch registers are needed, you also have to describe how to 2666perform the copy from/to the reload register to/from this 2667closest intermediate register. Or if no intermediate register is 2668required, but still a scratch register is needed, describe the 2669copy from/to the reload register to/from the reload operand @var{x}. 2670 2671You do this by setting @code{sri->icode} to the instruction code of a pattern 2672in the md file which performs the move. Operands 0 and 1 are the output 2673and input of this copy, respectively. Operands from operand 2 onward are 2674for scratch operands. These scratch operands must have a mode, and a 2675single-register-class 2676@c [later: or memory] 2677output constraint. 2678 2679When an intermediate register is used, the @code{secondary_reload} 2680hook will be called again to determine how to copy the intermediate 2681register to/from the reload operand @var{x}, so your hook must also 2682have code to handle the register class of the intermediate operand. 2683 2684@c [For later: maybe we'll allow multi-alternative reload patterns - 2685@c the port maintainer could name a mov<mode> pattern that has clobbers - 2686@c and match the constraints of input and output to determine the required 2687@c alternative. A restriction would be that constraints used to match 2688@c against reloads registers would have to be written as register class 2689@c constraints, or we need a new target macro / hook that tells us if an 2690@c arbitrary constraint can match an unknown register of a given class. 2691@c Such a macro / hook would also be useful in other places.] 2692 2693 2694@var{x} might be a pseudo-register or a @code{subreg} of a 2695pseudo-register, which could either be in a hard register or in memory. 2696Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2697in memory and the hard register number if it is in a register. 2698 2699Scratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are 2700currently not supported. For the time being, you will have to continue 2701to use @code{SECONDARY_MEMORY_NEEDED} for that purpose. 2702 2703@code{copy_cost} also uses this target hook to find out how values are 2704copied. If you want it to include some extra cost for the need to allocate 2705(a) scratch register(s), set @code{sri->extra_cost} to the additional cost. 2706Or if two dependent moves are supposed to have a lower cost than the sum 2707of the individual moves due to expected fortuitous scheduling and/or special 2708forwarding logic, you can set @code{sri->extra_cost} to a negative amount. 2709@end deftypefn 2710 2711@defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2712@defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2713@defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2714These macros are obsolete, new ports should use the target hook 2715@code{TARGET_SECONDARY_RELOAD} instead. 2716 2717These are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD} 2718target hook. Older ports still define these macros to indicate to the 2719reload phase that it may 2720need to allocate at least one register for a reload in addition to the 2721register to contain the data. Specifically, if copying @var{x} to a 2722register @var{class} in @var{mode} requires an intermediate register, 2723you were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 2724largest register class all of whose registers can be used as 2725intermediate registers or scratch registers. 2726 2727If copying a register @var{class} in @var{mode} to @var{x} requires an 2728intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} 2729was supposed to be defined be defined to return the largest register 2730class required. If the 2731requirements for input and output reloads were the same, the macro 2732@code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both 2733macros identically. 2734 2735The values returned by these macros are often @code{GENERAL_REGS}. 2736Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 2737can be directly copied to or from a register of @var{class} in 2738@var{mode} without requiring a scratch register. Do not define this 2739macro if it would always return @code{NO_REGS}. 2740 2741If a scratch register is required (either with or without an 2742intermediate register), you were supposed to define patterns for 2743@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 2744(@pxref{Standard Names}. These patterns, which were normally 2745implemented with a @code{define_expand}, should be similar to the 2746@samp{mov@var{m}} patterns, except that operand 2 is the scratch 2747register. 2748 2749These patterns need constraints for the reload register and scratch 2750register that 2751contain a single register class. If the original reload register (whose 2752class is @var{class}) can meet the constraint given in the pattern, the 2753value returned by these macros is used for the class of the scratch 2754register. Otherwise, two additional reload registers are required. 2755Their classes are obtained from the constraints in the insn pattern. 2756 2757@var{x} might be a pseudo-register or a @code{subreg} of a 2758pseudo-register, which could either be in a hard register or in memory. 2759Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2760in memory and the hard register number if it is in a register. 2761 2762These macros should not be used in the case where a particular class of 2763registers can only be copied to memory and not to another class of 2764registers. In that case, secondary reload registers are not needed and 2765would not be helpful. Instead, a stack location must be used to perform 2766the copy and the @code{mov@var{m}} pattern should use memory as an 2767intermediate storage. This case often occurs between floating-point and 2768general registers. 2769@end defmac 2770 2771@defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 2772Certain machines have the property that some registers cannot be copied 2773to some other registers without using memory. Define this macro on 2774those machines to be a C expression that is nonzero if objects of mode 2775@var{m} in registers of @var{class1} can only be copied to registers of 2776class @var{class2} by storing a register of @var{class1} into memory 2777and loading that memory location into a register of @var{class2}. 2778 2779Do not define this macro if its value would always be zero. 2780@end defmac 2781 2782@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) 2783Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler 2784allocates a stack slot for a memory location needed for register copies. 2785If this macro is defined, the compiler instead uses the memory location 2786defined by this macro. 2787 2788Do not define this macro if you do not define 2789@code{SECONDARY_MEMORY_NEEDED}. 2790@end defmac 2791 2792@defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) 2793When the compiler needs a secondary memory location to copy between two 2794registers of mode @var{mode}, it normally allocates sufficient memory to 2795hold a quantity of @code{BITS_PER_WORD} bits and performs the store and 2796load operations in a mode that many bits wide and whose class is the 2797same as that of @var{mode}. 2798 2799This is right thing to do on most machines because it ensures that all 2800bits of the register are copied and prevents accesses to the registers 2801in a narrower mode, which some machines prohibit for floating-point 2802registers. 2803 2804However, this default behavior is not correct on some machines, such as 2805the DEC Alpha, that store short integers in floating-point registers 2806differently than in integer registers. On those machines, the default 2807widening will not work correctly and you must define this macro to 2808suppress that widening in some cases. See the file @file{alpha.h} for 2809details. 2810 2811Do not define this macro if you do not define 2812@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that 2813is @code{BITS_PER_WORD} bits wide is correct for your machine. 2814@end defmac 2815 2816@deftypefn {Target Hook} bool TARGET_CLASS_LIKELY_SPILLED_P (reg_class_t @var{rclass}) 2817A target hook which returns @code{true} if pseudos that have been assigned 2818to registers of class @var{rclass} would likely be spilled because 2819registers of @var{rclass} are needed for spill registers. 2820 2821The default version of this target hook returns @code{true} if @var{rclass} 2822has exactly one register and @code{false} otherwise. On most machines, this 2823default should be used. Only use this target hook to some other expression 2824if pseudos allocated by @file{local-alloc.c} end up in memory because their 2825hard registers were needed for spill registers. If this target hook returns 2826@code{false} for those classes, those pseudos will only be allocated by 2827@file{global.c}, which knows how to reallocate the pseudo to another 2828register. If there would not be another register available for reallocation, 2829you should not change the implementation of this target hook since 2830the only effect of such implementation would be to slow down register 2831allocation. 2832@end deftypefn 2833 2834@deftypefn {Target Hook} {unsigned char} TARGET_CLASS_MAX_NREGS (reg_class_t @var{rclass}, enum machine_mode @var{mode}) 2835A target hook returns the maximum number of consecutive registers 2836of class @var{rclass} needed to hold a value of mode @var{mode}. 2837 2838This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 2839the value returned by @code{TARGET_CLASS_MAX_NREGS (@var{rclass}, 2840@var{mode})} target hook should be the maximum value of 2841@code{HARD_REGNO_NREGS (@var{regno}, @var{mode})} for all @var{regno} 2842values in the class @var{rclass}. 2843 2844This target hook helps control the handling of multiple-word values 2845in the reload pass. 2846 2847The default version of this target hook returns the size of @var{mode} 2848in words. 2849@end deftypefn 2850 2851@defmac CLASS_MAX_NREGS (@var{class}, @var{mode}) 2852A C expression for the maximum number of consecutive registers 2853of class @var{class} needed to hold a value of mode @var{mode}. 2854 2855This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 2856the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 2857should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, 2858@var{mode})} for all @var{regno} values in the class @var{class}. 2859 2860This macro helps control the handling of multiple-word values 2861in the reload pass. 2862@end defmac 2863 2864@defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class}) 2865If defined, a C expression that returns nonzero for a @var{class} for which 2866a change from mode @var{from} to mode @var{to} is invalid. 2867 2868For the example, loading 32-bit integer or floating-point objects into 2869floating-point registers on the Alpha extends them to 64 bits. 2870Therefore loading a 64-bit object and then storing it as a 32-bit object 2871does not store the low-order 32 bits, as would be the case for a normal 2872register. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS} 2873as below: 2874 2875@smallexample 2876#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \ 2877 (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \ 2878 ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0) 2879@end smallexample 2880@end defmac 2881 2882@node Old Constraints 2883@section Obsolete Macros for Defining Constraints 2884@cindex defining constraints, obsolete method 2885@cindex constraints, defining, obsolete method 2886 2887Machine-specific constraints can be defined with these macros instead 2888of the machine description constructs described in @ref{Define 2889Constraints}. This mechanism is obsolete. New ports should not use 2890it; old ports should convert to the new mechanism. 2891 2892@defmac CONSTRAINT_LEN (@var{char}, @var{str}) 2893For the constraint at the start of @var{str}, which starts with the letter 2894@var{c}, return the length. This allows you to have register class / 2895constant / extra constraints that are longer than a single letter; 2896you don't need to define this macro if you can do with single-letter 2897constraints only. The definition of this macro should use 2898DEFAULT_CONSTRAINT_LEN for all the characters that you don't want 2899to handle specially. 2900There are some sanity checks in genoutput.c that check the constraint lengths 2901for the md file, so you can also use this macro to help you while you are 2902transitioning from a byzantine single-letter-constraint scheme: when you 2903return a negative length for a constraint you want to re-use, genoutput 2904will complain about every instance where it is used in the md file. 2905@end defmac 2906 2907@defmac REG_CLASS_FROM_LETTER (@var{char}) 2908A C expression which defines the machine-dependent operand constraint 2909letters for register classes. If @var{char} is such a letter, the 2910value should be the register class corresponding to it. Otherwise, 2911the value should be @code{NO_REGS}. The register letter @samp{r}, 2912corresponding to class @code{GENERAL_REGS}, will not be passed 2913to this macro; you do not need to handle it. 2914@end defmac 2915 2916@defmac REG_CLASS_FROM_CONSTRAINT (@var{char}, @var{str}) 2917Like @code{REG_CLASS_FROM_LETTER}, but you also get the constraint string 2918passed in @var{str}, so that you can use suffixes to distinguish between 2919different variants. 2920@end defmac 2921 2922@defmac CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 2923A C expression that defines the machine-dependent operand constraint 2924letters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify 2925particular ranges of integer values. If @var{c} is one of those 2926letters, the expression should check that @var{value}, an integer, is in 2927the appropriate range and return 1 if so, 0 otherwise. If @var{c} is 2928not one of those letters, the value should be 0 regardless of 2929@var{value}. 2930@end defmac 2931 2932@defmac CONST_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2933Like @code{CONST_OK_FOR_LETTER_P}, but you also get the constraint 2934string passed in @var{str}, so that you can use suffixes to distinguish 2935between different variants. 2936@end defmac 2937 2938@defmac CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 2939A C expression that defines the machine-dependent operand constraint 2940letters that specify particular ranges of @code{const_double} values 2941(@samp{G} or @samp{H}). 2942 2943If @var{c} is one of those letters, the expression should check that 2944@var{value}, an RTX of code @code{const_double}, is in the appropriate 2945range and return 1 if so, 0 otherwise. If @var{c} is not one of those 2946letters, the value should be 0 regardless of @var{value}. 2947 2948@code{const_double} is used for all floating-point constants and for 2949@code{DImode} fixed-point constants. A given letter can accept either 2950or both kinds of values. It can use @code{GET_MODE} to distinguish 2951between these kinds. 2952@end defmac 2953 2954@defmac CONST_DOUBLE_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2955Like @code{CONST_DOUBLE_OK_FOR_LETTER_P}, but you also get the constraint 2956string passed in @var{str}, so that you can use suffixes to distinguish 2957between different variants. 2958@end defmac 2959 2960@defmac EXTRA_CONSTRAINT (@var{value}, @var{c}) 2961A C expression that defines the optional machine-dependent constraint 2962letters that can be used to segregate specific types of operands, usually 2963memory references, for the target machine. Any letter that is not 2964elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} / 2965@code{REG_CLASS_FROM_CONSTRAINT} 2966may be used. Normally this macro will not be defined. 2967 2968If it is required for a particular target machine, it should return 1 2969if @var{value} corresponds to the operand type represented by the 2970constraint letter @var{c}. If @var{c} is not defined as an extra 2971constraint, the value returned should be 0 regardless of @var{value}. 2972 2973For example, on the ROMP, load instructions cannot have their output 2974in r0 if the memory reference contains a symbolic address. Constraint 2975letter @samp{Q} is defined as representing a memory address that does 2976@emph{not} contain a symbolic address. An alternative is specified with 2977a @samp{Q} constraint on the input and @samp{r} on the output. The next 2978alternative specifies @samp{m} on the input and a register class that 2979does not include r0 on the output. 2980@end defmac 2981 2982@defmac EXTRA_CONSTRAINT_STR (@var{value}, @var{c}, @var{str}) 2983Like @code{EXTRA_CONSTRAINT}, but you also get the constraint string passed 2984in @var{str}, so that you can use suffixes to distinguish between different 2985variants. 2986@end defmac 2987 2988@defmac EXTRA_MEMORY_CONSTRAINT (@var{c}, @var{str}) 2989A C expression that defines the optional machine-dependent constraint 2990letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should 2991be treated like memory constraints by the reload pass. 2992 2993It should return 1 if the operand type represented by the constraint 2994at the start of @var{str}, the first letter of which is the letter @var{c}, 2995comprises a subset of all memory references including 2996all those whose address is simply a base register. This allows the reload 2997pass to reload an operand, if it does not directly correspond to the operand 2998type of @var{c}, by copying its address into a base register. 2999 3000For example, on the S/390, some instructions do not accept arbitrary 3001memory references, but only those that do not make use of an index 3002register. The constraint letter @samp{Q} is defined via 3003@code{EXTRA_CONSTRAINT} as representing a memory address of this type. 3004If the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT}, 3005a @samp{Q} constraint can handle any memory operand, because the 3006reload pass knows it can be reloaded by copying the memory address 3007into a base register if required. This is analogous to the way 3008an @samp{o} constraint can handle any memory operand. 3009@end defmac 3010 3011@defmac EXTRA_ADDRESS_CONSTRAINT (@var{c}, @var{str}) 3012A C expression that defines the optional machine-dependent constraint 3013letters, amongst those accepted by @code{EXTRA_CONSTRAINT} / 3014@code{EXTRA_CONSTRAINT_STR}, that should 3015be treated like address constraints by the reload pass. 3016 3017It should return 1 if the operand type represented by the constraint 3018at the start of @var{str}, which starts with the letter @var{c}, comprises 3019a subset of all memory addresses including 3020all those that consist of just a base register. This allows the reload 3021pass to reload an operand, if it does not directly correspond to the operand 3022type of @var{str}, by copying it into a base register. 3023 3024Any constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only 3025be used with the @code{address_operand} predicate. It is treated 3026analogously to the @samp{p} constraint. 3027@end defmac 3028 3029@node Stack and Calling 3030@section Stack Layout and Calling Conventions 3031@cindex calling conventions 3032 3033@c prevent bad page break with this line 3034This describes the stack layout and calling conventions. 3035 3036@menu 3037* Frame Layout:: 3038* Exception Handling:: 3039* Stack Checking:: 3040* Frame Registers:: 3041* Elimination:: 3042* Stack Arguments:: 3043* Register Arguments:: 3044* Scalar Return:: 3045* Aggregate Return:: 3046* Caller Saves:: 3047* Function Entry:: 3048* Profiling:: 3049* Tail Calls:: 3050* Stack Smashing Protection:: 3051@end menu 3052 3053@node Frame Layout 3054@subsection Basic Stack Layout 3055@cindex stack frame layout 3056@cindex frame layout 3057 3058@c prevent bad page break with this line 3059Here is the basic stack layout. 3060 3061@defmac STACK_GROWS_DOWNWARD 3062Define this macro if pushing a word onto the stack moves the stack 3063pointer to a smaller address. 3064 3065When we say, ``define this macro if @dots{}'', it means that the 3066compiler checks this macro only with @code{#ifdef} so the precise 3067definition used does not matter. 3068@end defmac 3069 3070@defmac STACK_PUSH_CODE 3071This macro defines the operation used when something is pushed 3072on the stack. In RTL, a push operation will be 3073@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} 3074 3075The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, 3076and @code{POST_INC}. Which of these is correct depends on 3077the stack direction and on whether the stack pointer points 3078to the last item on the stack or whether it points to the 3079space for the next item on the stack. 3080 3081The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is 3082defined, which is almost always right, and @code{PRE_INC} otherwise, 3083which is often wrong. 3084@end defmac 3085 3086@defmac FRAME_GROWS_DOWNWARD 3087Define this macro to nonzero value if the addresses of local variable slots 3088are at negative offsets from the frame pointer. 3089@end defmac 3090 3091@defmac ARGS_GROW_DOWNWARD 3092Define this macro if successive arguments to a function occupy decreasing 3093addresses on the stack. 3094@end defmac 3095 3096@defmac STARTING_FRAME_OFFSET 3097Offset from the frame pointer to the first local variable slot to be allocated. 3098 3099If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by 3100subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. 3101Otherwise, it is found by adding the length of the first slot to the 3102value @code{STARTING_FRAME_OFFSET}. 3103@c i'm not sure if the above is still correct.. had to change it to get 3104@c rid of an overfull. --mew 2feb93 3105@end defmac 3106 3107@defmac STACK_ALIGNMENT_NEEDED 3108Define to zero to disable final alignment of the stack during reload. 3109The nonzero default for this macro is suitable for most ports. 3110 3111On ports where @code{STARTING_FRAME_OFFSET} is nonzero or where there 3112is a register save block following the local block that doesn't require 3113alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable 3114stack alignment and do it in the backend. 3115@end defmac 3116 3117@defmac STACK_POINTER_OFFSET 3118Offset from the stack pointer register to the first location at which 3119outgoing arguments are placed. If not specified, the default value of 3120zero is used. This is the proper value for most machines. 3121 3122If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 3123the first location at which outgoing arguments are placed. 3124@end defmac 3125 3126@defmac FIRST_PARM_OFFSET (@var{fundecl}) 3127Offset from the argument pointer register to the first argument's 3128address. On some machines it may depend on the data type of the 3129function. 3130 3131If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 3132the first argument's address. 3133@end defmac 3134 3135@defmac STACK_DYNAMIC_OFFSET (@var{fundecl}) 3136Offset from the stack pointer register to an item dynamically allocated 3137on the stack, e.g., by @code{alloca}. 3138 3139The default value for this macro is @code{STACK_POINTER_OFFSET} plus the 3140length of the outgoing arguments. The default is correct for most 3141machines. See @file{function.c} for details. 3142@end defmac 3143 3144@defmac INITIAL_FRAME_ADDRESS_RTX 3145A C expression whose value is RTL representing the address of the initial 3146stack frame. This address is passed to @code{RETURN_ADDR_RTX} and 3147@code{DYNAMIC_CHAIN_ADDRESS}. If you don't define this macro, a reasonable 3148default value will be used. Define this macro in order to make frame pointer 3149elimination work in the presence of @code{__builtin_frame_address (count)} and 3150@code{__builtin_return_address (count)} for @code{count} not equal to zero. 3151@end defmac 3152 3153@defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 3154A C expression whose value is RTL representing the address in a stack 3155frame where the pointer to the caller's frame is stored. Assume that 3156@var{frameaddr} is an RTL expression for the address of the stack frame 3157itself. 3158 3159If you don't define this macro, the default is to return the value 3160of @var{frameaddr}---that is, the stack frame address is also the 3161address of the stack word that points to the previous frame. 3162@end defmac 3163 3164@defmac SETUP_FRAME_ADDRESSES 3165If defined, a C expression that produces the machine-specific code to 3166setup the stack so that arbitrary frames can be accessed. For example, 3167on the SPARC, we must flush all of the register windows to the stack 3168before we can access arbitrary stack frames. You will seldom need to 3169define this macro. 3170@end defmac 3171 3172@deftypefn {Target Hook} rtx TARGET_BUILTIN_SETJMP_FRAME_VALUE (void) 3173This target hook should return an rtx that is used to store 3174the address of the current frame into the built in @code{setjmp} buffer. 3175The default value, @code{virtual_stack_vars_rtx}, is correct for most 3176machines. One reason you may need to define this target hook is if 3177@code{hard_frame_pointer_rtx} is the appropriate value on your machine. 3178@end deftypefn 3179 3180@defmac FRAME_ADDR_RTX (@var{frameaddr}) 3181A C expression whose value is RTL representing the value of the frame 3182address for the current frame. @var{frameaddr} is the frame pointer 3183of the current frame. This is used for __builtin_frame_address. 3184You need only define this macro if the frame address is not the same 3185as the frame pointer. Most machines do not need to define it. 3186@end defmac 3187 3188@defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) 3189A C expression whose value is RTL representing the value of the return 3190address for the frame @var{count} steps up from the current frame, after 3191the prologue. @var{frameaddr} is the frame pointer of the @var{count} 3192frame, or the frame pointer of the @var{count} @minus{} 1 frame if 3193@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. 3194 3195The value of the expression must always be the correct address when 3196@var{count} is zero, but may be @code{NULL_RTX} if there is no way to 3197determine the return address of other frames. 3198@end defmac 3199 3200@defmac RETURN_ADDR_IN_PREVIOUS_FRAME 3201Define this if the return address of a particular stack frame is accessed 3202from the frame pointer of the previous stack frame. 3203@end defmac 3204 3205@defmac INCOMING_RETURN_ADDR_RTX 3206A C expression whose value is RTL representing the location of the 3207incoming return address at the beginning of any function, before the 3208prologue. This RTL is either a @code{REG}, indicating that the return 3209value is saved in @samp{REG}, or a @code{MEM} representing a location in 3210the stack. 3211 3212You only need to define this macro if you want to support call frame 3213debugging information like that provided by DWARF 2. 3214 3215If this RTL is a @code{REG}, you should also define 3216@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. 3217@end defmac 3218 3219@defmac DWARF_ALT_FRAME_RETURN_COLUMN 3220A C expression whose value is an integer giving a DWARF 2 column 3221number that may be used as an alternative return column. The column 3222must not correspond to any gcc hard register (that is, it must not 3223be in the range of @code{DWARF_FRAME_REGNUM}). 3224 3225This macro can be useful if @code{DWARF_FRAME_RETURN_COLUMN} is set to a 3226general register, but an alternative column needs to be used for signal 3227frames. Some targets have also used different frame return columns 3228over time. 3229@end defmac 3230 3231@defmac DWARF_ZERO_REG 3232A C expression whose value is an integer giving a DWARF 2 register 3233number that is considered to always have the value zero. This should 3234only be defined if the target has an architected zero register, and 3235someone decided it was a good idea to use that register number to 3236terminate the stack backtrace. New ports should avoid this. 3237@end defmac 3238 3239@deftypefn {Target Hook} void TARGET_DWARF_HANDLE_FRAME_UNSPEC (const char *@var{label}, rtx @var{pattern}, int @var{index}) 3240This target hook allows the backend to emit frame-related insns that 3241contain UNSPECs or UNSPEC_VOLATILEs. The DWARF 2 call frame debugging 3242info engine will invoke it on insns of the form 3243@smallexample 3244(set (reg) (unspec [@dots{}] UNSPEC_INDEX)) 3245@end smallexample 3246and 3247@smallexample 3248(set (reg) (unspec_volatile [@dots{}] UNSPECV_INDEX)). 3249@end smallexample 3250to let the backend emit the call frame instructions. @var{label} is 3251the CFI label attached to the insn, @var{pattern} is the pattern of 3252the insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}. 3253@end deftypefn 3254 3255@defmac INCOMING_FRAME_SP_OFFSET 3256A C expression whose value is an integer giving the offset, in bytes, 3257from the value of the stack pointer register to the top of the stack 3258frame at the beginning of any function, before the prologue. The top of 3259the frame is defined to be the value of the stack pointer in the 3260previous frame, just before the call instruction. 3261 3262You only need to define this macro if you want to support call frame 3263debugging information like that provided by DWARF 2. 3264@end defmac 3265 3266@defmac ARG_POINTER_CFA_OFFSET (@var{fundecl}) 3267A C expression whose value is an integer giving the offset, in bytes, 3268from the argument pointer to the canonical frame address (cfa). The 3269final value should coincide with that calculated by 3270@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable 3271during virtual register instantiation. 3272 3273The default value for this macro is 3274@code{FIRST_PARM_OFFSET (fundecl) + crtl->args.pretend_args_size}, 3275which is correct for most machines; in general, the arguments are found 3276immediately before the stack frame. Note that this is not the case on 3277some targets that save registers into the caller's frame, such as SPARC 3278and rs6000, and so such targets need to define this macro. 3279 3280You only need to define this macro if the default is incorrect, and you 3281want to support call frame debugging information like that provided by 3282DWARF 2. 3283@end defmac 3284 3285@defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl}) 3286If defined, a C expression whose value is an integer giving the offset 3287in bytes from the frame pointer to the canonical frame address (cfa). 3288The final value should coincide with that calculated by 3289@code{INCOMING_FRAME_SP_OFFSET}. 3290 3291Normally the CFA is calculated as an offset from the argument pointer, 3292via @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is 3293variable due to the ABI, this may not be possible. If this macro is 3294defined, it implies that the virtual register instantiation should be 3295based on the frame pointer instead of the argument pointer. Only one 3296of @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET} 3297should be defined. 3298@end defmac 3299 3300@defmac CFA_FRAME_BASE_OFFSET (@var{fundecl}) 3301If defined, a C expression whose value is an integer giving the offset 3302in bytes from the canonical frame address (cfa) to the frame base used 3303in DWARF 2 debug information. The default is zero. A different value 3304may reduce the size of debug information on some ports. 3305@end defmac 3306 3307@node Exception Handling 3308@subsection Exception Handling Support 3309@cindex exception handling 3310 3311@defmac EH_RETURN_DATA_REGNO (@var{N}) 3312A C expression whose value is the @var{N}th register number used for 3313data by exception handlers, or @code{INVALID_REGNUM} if fewer than 3314@var{N} registers are usable. 3315 3316The exception handling library routines communicate with the exception 3317handlers via a set of agreed upon registers. Ideally these registers 3318should be call-clobbered; it is possible to use call-saved registers, 3319but may negatively impact code size. The target must support at least 33202 data registers, but should define 4 if there are enough free registers. 3321 3322You must define this macro if you want to support call frame exception 3323handling like that provided by DWARF 2. 3324@end defmac 3325 3326@defmac EH_RETURN_STACKADJ_RTX 3327A C expression whose value is RTL representing a location in which 3328to store a stack adjustment to be applied before function return. 3329This is used to unwind the stack to an exception handler's call frame. 3330It will be assigned zero on code paths that return normally. 3331 3332Typically this is a call-clobbered hard register that is otherwise 3333untouched by the epilogue, but could also be a stack slot. 3334 3335Do not define this macro if the stack pointer is saved and restored 3336by the regular prolog and epilog code in the call frame itself; in 3337this case, the exception handling library routines will update the 3338stack location to be restored in place. Otherwise, you must define 3339this macro if you want to support call frame exception handling like 3340that provided by DWARF 2. 3341@end defmac 3342 3343@defmac EH_RETURN_HANDLER_RTX 3344A C expression whose value is RTL representing a location in which 3345to store the address of an exception handler to which we should 3346return. It will not be assigned on code paths that return normally. 3347 3348Typically this is the location in the call frame at which the normal 3349return address is stored. For targets that return by popping an 3350address off the stack, this might be a memory address just below 3351the @emph{target} call frame rather than inside the current call 3352frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already 3353been assigned, so it may be used to calculate the location of the 3354target call frame. 3355 3356Some targets have more complex requirements than storing to an 3357address calculable during initial code generation. In that case 3358the @code{eh_return} instruction pattern should be used instead. 3359 3360If you want to support call frame exception handling, you must 3361define either this macro or the @code{eh_return} instruction pattern. 3362@end defmac 3363 3364@defmac RETURN_ADDR_OFFSET 3365If defined, an integer-valued C expression for which rtl will be generated 3366to add it to the exception handler address before it is searched in the 3367exception handling tables, and to subtract it again from the address before 3368using it to return to the exception handler. 3369@end defmac 3370 3371@defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global}) 3372This macro chooses the encoding of pointers embedded in the exception 3373handling sections. If at all possible, this should be defined such 3374that the exception handling section will not require dynamic relocations, 3375and so may be read-only. 3376 3377@var{code} is 0 for data, 1 for code labels, 2 for function pointers. 3378@var{global} is true if the symbol may be affected by dynamic relocations. 3379The macro should return a combination of the @code{DW_EH_PE_*} defines 3380as found in @file{dwarf2.h}. 3381 3382If this macro is not defined, pointers will not be encoded but 3383represented directly. 3384@end defmac 3385 3386@defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) 3387This macro allows the target to emit whatever special magic is required 3388to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. 3389Generic code takes care of pc-relative and indirect encodings; this must 3390be defined if the target uses text-relative or data-relative encodings. 3391 3392This is a C statement that branches to @var{done} if the format was 3393handled. @var{encoding} is the format chosen, @var{size} is the number 3394of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} 3395to be emitted. 3396@end defmac 3397 3398@defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs}) 3399This macro allows the target to add CPU and operating system specific 3400code to the call-frame unwinder for use when there is no unwind data 3401available. The most common reason to implement this macro is to unwind 3402through signal frames. 3403 3404This macro is called from @code{uw_frame_state_for} in 3405@file{unwind-dw2.c}, @file{unwind-dw2-xtensa.c} and 3406@file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; 3407@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} 3408for the address of the code being executed and @code{context->cfa} for 3409the stack pointer value. If the frame can be decoded, the register 3410save addresses should be updated in @var{fs} and the macro should 3411evaluate to @code{_URC_NO_REASON}. If the frame cannot be decoded, 3412the macro should evaluate to @code{_URC_END_OF_STACK}. 3413 3414For proper signal handling in Java this macro is accompanied by 3415@code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers. 3416@end defmac 3417 3418@defmac MD_HANDLE_UNWABI (@var{context}, @var{fs}) 3419This macro allows the target to add operating system specific code to the 3420call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive, 3421usually used for signal or interrupt frames. 3422 3423This macro is called from @code{uw_update_context} in @file{unwind-ia64.c}. 3424@var{context} is an @code{_Unwind_Context}; 3425@var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi} 3426for the abi and context in the @code{.unwabi} directive. If the 3427@code{.unwabi} directive can be handled, the register save addresses should 3428be updated in @var{fs}. 3429@end defmac 3430 3431@defmac TARGET_USES_WEAK_UNWIND_INFO 3432A C expression that evaluates to true if the target requires unwind 3433info to be given comdat linkage. Define it to be @code{1} if comdat 3434linkage is necessary. The default is @code{0}. 3435@end defmac 3436 3437@node Stack Checking 3438@subsection Specifying How Stack Checking is Done 3439 3440GCC will check that stack references are within the boundaries of the 3441stack, if the option @option{-fstack-check} is specified, in one of 3442three ways: 3443 3444@enumerate 3445@item 3446If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC 3447will assume that you have arranged for full stack checking to be done 3448at appropriate places in the configuration files. GCC will not do 3449other special processing. 3450 3451@item 3452If @code{STACK_CHECK_BUILTIN} is zero and the value of the 3453@code{STACK_CHECK_STATIC_BUILTIN} macro is nonzero, GCC will assume 3454that you have arranged for static stack checking (checking of the 3455static stack frame of functions) to be done at appropriate places 3456in the configuration files. GCC will only emit code to do dynamic 3457stack checking (checking on dynamic stack allocations) using the third 3458approach below. 3459 3460@item 3461If neither of the above are true, GCC will generate code to periodically 3462``probe'' the stack pointer using the values of the macros defined below. 3463@end enumerate 3464 3465If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined, 3466GCC will change its allocation strategy for large objects if the option 3467@option{-fstack-check} is specified: they will always be allocated 3468dynamically if their size exceeds @code{STACK_CHECK_MAX_VAR_SIZE} bytes. 3469 3470@defmac STACK_CHECK_BUILTIN 3471A nonzero value if stack checking is done by the configuration files in a 3472machine-dependent manner. You should define this macro if stack checking 3473is required by the ABI of your machine or if you would like to do stack 3474checking in some more efficient way than the generic approach. The default 3475value of this macro is zero. 3476@end defmac 3477 3478@defmac STACK_CHECK_STATIC_BUILTIN 3479A nonzero value if static stack checking is done by the configuration files 3480in a machine-dependent manner. You should define this macro if you would 3481like to do static stack checking in some more efficient way than the generic 3482approach. The default value of this macro is zero. 3483@end defmac 3484 3485@defmac STACK_CHECK_PROBE_INTERVAL_EXP 3486An integer specifying the interval at which GCC must generate stack probe 3487instructions, defined as 2 raised to this integer. You will normally 3488define this macro so that the interval be no larger than the size of 3489the ``guard pages'' at the end of a stack area. The default value 3490of 12 (4096-byte interval) is suitable for most systems. 3491@end defmac 3492 3493@defmac STACK_CHECK_MOVING_SP 3494An integer which is nonzero if GCC should move the stack pointer page by page 3495when doing probes. This can be necessary on systems where the stack pointer 3496contains the bottom address of the memory area accessible to the executing 3497thread at any point in time. In this situation an alternate signal stack 3498is required in order to be able to recover from a stack overflow. The 3499default value of this macro is zero. 3500@end defmac 3501 3502@defmac STACK_CHECK_PROTECT 3503The number of bytes of stack needed to recover from a stack overflow, for 3504languages where such a recovery is supported. The default value of 75 words 3505with the @code{setjmp}/@code{longjmp}-based exception handling mechanism and 35068192 bytes with other exception handling mechanisms should be adequate for 3507most machines. 3508@end defmac 3509 3510The following macros are relevant only if neither STACK_CHECK_BUILTIN 3511nor STACK_CHECK_STATIC_BUILTIN is defined; you can omit them altogether 3512in the opposite case. 3513 3514@defmac STACK_CHECK_MAX_FRAME_SIZE 3515The maximum size of a stack frame, in bytes. GCC will generate probe 3516instructions in non-leaf functions to ensure at least this many bytes of 3517stack are available. If a stack frame is larger than this size, stack 3518checking will not be reliable and GCC will issue a warning. The 3519default is chosen so that GCC only generates one instruction on most 3520systems. You should normally not change the default value of this macro. 3521@end defmac 3522 3523@defmac STACK_CHECK_FIXED_FRAME_SIZE 3524GCC uses this value to generate the above warning message. It 3525represents the amount of fixed frame used by a function, not including 3526space for any callee-saved registers, temporaries and user variables. 3527You need only specify an upper bound for this amount and will normally 3528use the default of four words. 3529@end defmac 3530 3531@defmac STACK_CHECK_MAX_VAR_SIZE 3532The maximum size, in bytes, of an object that GCC will place in the 3533fixed area of the stack frame when the user specifies 3534@option{-fstack-check}. 3535GCC computed the default from the values of the above macros and you will 3536normally not need to override that default. 3537@end defmac 3538 3539@need 2000 3540@node Frame Registers 3541@subsection Registers That Address the Stack Frame 3542 3543@c prevent bad page break with this line 3544This discusses registers that address the stack frame. 3545 3546@defmac STACK_POINTER_REGNUM 3547The register number of the stack pointer register, which must also be a 3548fixed register according to @code{FIXED_REGISTERS}. On most machines, 3549the hardware determines which register this is. 3550@end defmac 3551 3552@defmac FRAME_POINTER_REGNUM 3553The register number of the frame pointer register, which is used to 3554access automatic variables in the stack frame. On some machines, the 3555hardware determines which register this is. On other machines, you can 3556choose any register you wish for this purpose. 3557@end defmac 3558 3559@defmac HARD_FRAME_POINTER_REGNUM 3560On some machines the offset between the frame pointer and starting 3561offset of the automatic variables is not known until after register 3562allocation has been done (for example, because the saved registers are 3563between these two locations). On those machines, define 3564@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to 3565be used internally until the offset is known, and define 3566@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number 3567used for the frame pointer. 3568 3569You should define this macro only in the very rare circumstances when it 3570is not possible to calculate the offset between the frame pointer and 3571the automatic variables until after register allocation has been 3572completed. When this macro is defined, you must also indicate in your 3573definition of @code{ELIMINABLE_REGS} how to eliminate 3574@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} 3575or @code{STACK_POINTER_REGNUM}. 3576 3577Do not define this macro if it would be the same as 3578@code{FRAME_POINTER_REGNUM}. 3579@end defmac 3580 3581@defmac ARG_POINTER_REGNUM 3582The register number of the arg pointer register, which is used to access 3583the function's argument list. On some machines, this is the same as the 3584frame pointer register. On some machines, the hardware determines which 3585register this is. On other machines, you can choose any register you 3586wish for this purpose. If this is not the same register as the frame 3587pointer register, then you must mark it as a fixed register according to 3588@code{FIXED_REGISTERS}, or arrange to be able to eliminate it 3589(@pxref{Elimination}). 3590@end defmac 3591 3592@defmac HARD_FRAME_POINTER_IS_FRAME_POINTER 3593Define this to a preprocessor constant that is nonzero if 3594@code{hard_frame_pointer_rtx} and @code{frame_pointer_rtx} should be 3595the same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM 3596== FRAME_POINTER_REGNUM)}; you only need to define this macro if that 3597definition is not suitable for use in preprocessor conditionals. 3598@end defmac 3599 3600@defmac HARD_FRAME_POINTER_IS_ARG_POINTER 3601Define this to a preprocessor constant that is nonzero if 3602@code{hard_frame_pointer_rtx} and @code{arg_pointer_rtx} should be the 3603same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM == 3604ARG_POINTER_REGNUM)}; you only need to define this macro if that 3605definition is not suitable for use in preprocessor conditionals. 3606@end defmac 3607 3608@defmac RETURN_ADDRESS_POINTER_REGNUM 3609The register number of the return address pointer register, which is used to 3610access the current function's return address from the stack. On some 3611machines, the return address is not at a fixed offset from the frame 3612pointer or stack pointer or argument pointer. This register can be defined 3613to point to the return address on the stack, and then be converted by 3614@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. 3615 3616Do not define this macro unless there is no other way to get the return 3617address from the stack. 3618@end defmac 3619 3620@defmac STATIC_CHAIN_REGNUM 3621@defmacx STATIC_CHAIN_INCOMING_REGNUM 3622Register numbers used for passing a function's static chain pointer. If 3623register windows are used, the register number as seen by the called 3624function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register 3625number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If 3626these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need 3627not be defined. 3628 3629The static chain register need not be a fixed register. 3630 3631If the static chain is passed in memory, these macros should not be 3632defined; instead, the @code{TARGET_STATIC_CHAIN} hook should be used. 3633@end defmac 3634 3635@deftypefn {Target Hook} rtx TARGET_STATIC_CHAIN (const_tree @var{fndecl}, bool @var{incoming_p}) 3636This hook replaces the use of @code{STATIC_CHAIN_REGNUM} et al for 3637targets that may use different static chain locations for different 3638nested functions. This may be required if the target has function 3639attributes that affect the calling conventions of the function and 3640those calling conventions use different static chain locations. 3641 3642The default version of this hook uses @code{STATIC_CHAIN_REGNUM} et al. 3643 3644If the static chain is passed in memory, this hook should be used to 3645provide rtx giving @code{mem} expressions that denote where they are stored. 3646Often the @code{mem} expression as seen by the caller will be at an offset 3647from the stack pointer and the @code{mem} expression as seen by the callee 3648will be at an offset from the frame pointer. 3649@findex stack_pointer_rtx 3650@findex frame_pointer_rtx 3651@findex arg_pointer_rtx 3652The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 3653@code{arg_pointer_rtx} will have been initialized and should be used 3654to refer to those items. 3655@end deftypefn 3656 3657@defmac DWARF_FRAME_REGISTERS 3658This macro specifies the maximum number of hard registers that can be 3659saved in a call frame. This is used to size data structures used in 3660DWARF2 exception handling. 3661 3662Prior to GCC 3.0, this macro was needed in order to establish a stable 3663exception handling ABI in the face of adding new hard registers for ISA 3664extensions. In GCC 3.0 and later, the EH ABI is insulated from changes 3665in the number of hard registers. Nevertheless, this macro can still be 3666used to reduce the runtime memory requirements of the exception handling 3667routines, which can be substantial if the ISA contains a lot of 3668registers that are not call-saved. 3669 3670If this macro is not defined, it defaults to 3671@code{FIRST_PSEUDO_REGISTER}. 3672@end defmac 3673 3674@defmac PRE_GCC3_DWARF_FRAME_REGISTERS 3675 3676This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided 3677for backward compatibility in pre GCC 3.0 compiled code. 3678 3679If this macro is not defined, it defaults to 3680@code{DWARF_FRAME_REGISTERS}. 3681@end defmac 3682 3683@defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno}) 3684 3685Define this macro if the target's representation for dwarf registers 3686is different than the internal representation for unwind column. 3687Given a dwarf register, this macro should return the internal unwind 3688column number to use instead. 3689 3690See the PowerPC's SPE target for an example. 3691@end defmac 3692 3693@defmac DWARF_FRAME_REGNUM (@var{regno}) 3694 3695Define this macro if the target's representation for dwarf registers 3696used in .eh_frame or .debug_frame is different from that used in other 3697debug info sections. Given a GCC hard register number, this macro 3698should return the .eh_frame register number. The default is 3699@code{DBX_REGISTER_NUMBER (@var{regno})}. 3700 3701@end defmac 3702 3703@defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh}) 3704 3705Define this macro to map register numbers held in the call frame info 3706that GCC has collected using @code{DWARF_FRAME_REGNUM} to those that 3707should be output in .debug_frame (@code{@var{for_eh}} is zero) and 3708.eh_frame (@code{@var{for_eh}} is nonzero). The default is to 3709return @code{@var{regno}}. 3710 3711@end defmac 3712 3713@defmac REG_VALUE_IN_UNWIND_CONTEXT 3714 3715Define this macro if the target stores register values as 3716@code{_Unwind_Word} type in unwind context. It should be defined if 3717target register size is larger than the size of @code{void *}. The 3718default is to store register values as @code{void *} type. 3719 3720@end defmac 3721 3722@defmac ASSUME_EXTENDED_UNWIND_CONTEXT 3723 3724Define this macro to be 1 if the target always uses extended unwind 3725context with version, args_size and by_value fields. If it is undefined, 3726it will be defined to 1 when @code{REG_VALUE_IN_UNWIND_CONTEXT} is 3727defined and 0 otherwise. 3728 3729@end defmac 3730 3731@node Elimination 3732@subsection Eliminating Frame Pointer and Arg Pointer 3733 3734@c prevent bad page break with this line 3735This is about eliminating the frame pointer and arg pointer. 3736 3737@deftypefn {Target Hook} bool TARGET_FRAME_POINTER_REQUIRED (void) 3738This target hook should return @code{true} if a function must have and use 3739a frame pointer. This target hook is called in the reload pass. If its return 3740value is @code{true} the function will have a frame pointer. 3741 3742This target hook can in principle examine the current function and decide 3743according to the facts, but on most machines the constant @code{false} or the 3744constant @code{true} suffices. Use @code{false} when the machine allows code 3745to be generated with no frame pointer, and doing so saves some time or space. 3746Use @code{true} when there is no possible advantage to avoiding a frame 3747pointer. 3748 3749In certain cases, the compiler does not know how to produce valid code 3750without a frame pointer. The compiler recognizes those cases and 3751automatically gives the function a frame pointer regardless of what 3752@code{TARGET_FRAME_POINTER_REQUIRED} returns. You don't need to worry about 3753them. 3754 3755In a function that does not require a frame pointer, the frame pointer 3756register can be allocated for ordinary usage, unless you mark it as a 3757fixed register. See @code{FIXED_REGISTERS} for more information. 3758 3759Default return value is @code{false}. 3760@end deftypefn 3761 3762@findex get_frame_size 3763@defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 3764A C statement to store in the variable @var{depth-var} the difference 3765between the frame pointer and the stack pointer values immediately after 3766the function prologue. The value would be computed from information 3767such as the result of @code{get_frame_size ()} and the tables of 3768registers @code{regs_ever_live} and @code{call_used_regs}. 3769 3770If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 3771need not be defined. Otherwise, it must be defined even if 3772@code{TARGET_FRAME_POINTER_REQUIRED} always returns true; in that 3773case, you may set @var{depth-var} to anything. 3774@end defmac 3775 3776@defmac ELIMINABLE_REGS 3777If defined, this macro specifies a table of register pairs used to 3778eliminate unneeded registers that point into the stack frame. If it is not 3779defined, the only elimination attempted by the compiler is to replace 3780references to the frame pointer with references to the stack pointer. 3781 3782The definition of this macro is a list of structure initializations, each 3783of which specifies an original and replacement register. 3784 3785On some machines, the position of the argument pointer is not known until 3786the compilation is completed. In such a case, a separate hard register 3787must be used for the argument pointer. This register can be eliminated by 3788replacing it with either the frame pointer or the argument pointer, 3789depending on whether or not the frame pointer has been eliminated. 3790 3791In this case, you might specify: 3792@smallexample 3793#define ELIMINABLE_REGS \ 3794@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 3795 @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 3796 @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 3797@end smallexample 3798 3799Note that the elimination of the argument pointer with the stack pointer is 3800specified first since that is the preferred elimination. 3801@end defmac 3802 3803@deftypefn {Target Hook} bool TARGET_CAN_ELIMINATE (const int @var{from_reg}, const int @var{to_reg}) 3804This target hook should returns @code{true} if the compiler is allowed to 3805try to replace register number @var{from_reg} with register number 3806@var{to_reg}. This target hook need only be defined if @code{ELIMINABLE_REGS} 3807is defined, and will usually be @code{true}, since most of the cases 3808preventing register elimination are things that the compiler already 3809knows about. 3810 3811Default return value is @code{true}. 3812@end deftypefn 3813 3814@defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 3815This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 3816specifies the initial difference between the specified pair of 3817registers. This macro must be defined if @code{ELIMINABLE_REGS} is 3818defined. 3819@end defmac 3820 3821@node Stack Arguments 3822@subsection Passing Function Arguments on the Stack 3823@cindex arguments on stack 3824@cindex stack arguments 3825 3826The macros in this section control how arguments are passed 3827on the stack. See the following section for other macros that 3828control passing certain arguments in registers. 3829 3830@deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (const_tree @var{fntype}) 3831This target hook returns @code{true} if an argument declared in a 3832prototype as an integral type smaller than @code{int} should actually be 3833passed as an @code{int}. In addition to avoiding errors in certain 3834cases of mismatch, it also makes for better code on certain machines. 3835The default is to not promote prototypes. 3836@end deftypefn 3837 3838@defmac PUSH_ARGS 3839A C expression. If nonzero, push insns will be used to pass 3840outgoing arguments. 3841If the target machine does not have a push instruction, set it to zero. 3842That directs GCC to use an alternate strategy: to 3843allocate the entire argument block and then store the arguments into 3844it. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. 3845@end defmac 3846 3847@defmac PUSH_ARGS_REVERSED 3848A C expression. If nonzero, function arguments will be evaluated from 3849last to first, rather than from first to last. If this macro is not 3850defined, it defaults to @code{PUSH_ARGS} on targets where the stack 3851and args grow in opposite directions, and 0 otherwise. 3852@end defmac 3853 3854@defmac PUSH_ROUNDING (@var{npushed}) 3855A C expression that is the number of bytes actually pushed onto the 3856stack when an instruction attempts to push @var{npushed} bytes. 3857 3858On some machines, the definition 3859 3860@smallexample 3861#define PUSH_ROUNDING(BYTES) (BYTES) 3862@end smallexample 3863 3864@noindent 3865will suffice. But on other machines, instructions that appear 3866to push one byte actually push two bytes in an attempt to maintain 3867alignment. Then the definition should be 3868 3869@smallexample 3870#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 3871@end smallexample 3872 3873If the value of this macro has a type, it should be an unsigned type. 3874@end defmac 3875 3876@findex current_function_outgoing_args_size 3877@defmac ACCUMULATE_OUTGOING_ARGS 3878A C expression. If nonzero, the maximum amount of space required for outgoing arguments 3879will be computed and placed into the variable 3880@code{current_function_outgoing_args_size}. No space will be pushed 3881onto the stack for each call; instead, the function prologue should 3882increase the stack frame size by this amount. 3883 3884Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 3885is not proper. 3886@end defmac 3887 3888@defmac REG_PARM_STACK_SPACE (@var{fndecl}) 3889Define this macro if functions should assume that stack space has been 3890allocated for arguments even when their values are passed in 3891registers. 3892 3893The value of this macro is the size, in bytes, of the area reserved for 3894arguments passed in registers for the function represented by @var{fndecl}, 3895which can be zero if GCC is calling a library function. 3896The argument @var{fndecl} can be the FUNCTION_DECL, or the type itself 3897of the function. 3898 3899This space can be allocated by the caller, or be a part of the 3900machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 3901which. 3902@end defmac 3903@c above is overfull. not sure what to do. --mew 5feb93 did 3904@c something, not sure if it looks good. --mew 10feb93 3905 3906@defmac OUTGOING_REG_PARM_STACK_SPACE (@var{fntype}) 3907Define this to a nonzero value if it is the responsibility of the 3908caller to allocate the area reserved for arguments passed in registers 3909when calling a function of @var{fntype}. @var{fntype} may be NULL 3910if the function called is a library function. 3911 3912If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 3913whether the space for these arguments counts in the value of 3914@code{current_function_outgoing_args_size}. 3915@end defmac 3916 3917@defmac STACK_PARMS_IN_REG_PARM_AREA 3918Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 3919stack parameters don't skip the area specified by it. 3920@c i changed this, makes more sens and it should have taken care of the 3921@c overfull.. not as specific, tho. --mew 5feb93 3922 3923Normally, when a parameter is not passed in registers, it is placed on the 3924stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 3925suppresses this behavior and causes the parameter to be passed on the 3926stack in its natural location. 3927@end defmac 3928 3929@deftypefn {Target Hook} int TARGET_RETURN_POPS_ARGS (tree @var{fundecl}, tree @var{funtype}, int @var{size}) 3930This target hook returns the number of bytes of its own arguments that 3931a function pops on returning, or 0 if the function pops no arguments 3932and the caller must therefore pop them all after the function returns. 3933 3934@var{fundecl} is a C variable whose value is a tree node that describes 3935the function in question. Normally it is a node of type 3936@code{FUNCTION_DECL} that describes the declaration of the function. 3937From this you can obtain the @code{DECL_ATTRIBUTES} of the function. 3938 3939@var{funtype} is a C variable whose value is a tree node that 3940describes the function in question. Normally it is a node of type 3941@code{FUNCTION_TYPE} that describes the data type of the function. 3942From this it is possible to obtain the data types of the value and 3943arguments (if known). 3944 3945When a call to a library function is being considered, @var{fundecl} 3946will contain an identifier node for the library function. Thus, if 3947you need to distinguish among various library functions, you can do so 3948by their names. Note that ``library function'' in this context means 3949a function used to perform arithmetic, whose name is known specially 3950in the compiler and was not mentioned in the C code being compiled. 3951 3952@var{size} is the number of bytes of arguments passed on the 3953stack. If a variable number of bytes is passed, it is zero, and 3954argument popping will always be the responsibility of the calling function. 3955 3956On the VAX, all functions always pop their arguments, so the definition 3957of this macro is @var{size}. On the 68000, using the standard 3958calling convention, no functions pop their arguments, so the value of 3959the macro is always 0 in this case. But an alternative calling 3960convention is available in which functions that take a fixed number of 3961arguments pop them but other functions (such as @code{printf}) pop 3962nothing (the caller pops all). When this convention is in use, 3963@var{funtype} is examined to determine whether a function takes a fixed 3964number of arguments. 3965@end deftypefn 3966 3967@defmac CALL_POPS_ARGS (@var{cum}) 3968A C expression that should indicate the number of bytes a call sequence 3969pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 3970when compiling a function call. 3971 3972@var{cum} is the variable in which all arguments to the called function 3973have been accumulated. 3974 3975On certain architectures, such as the SH5, a call trampoline is used 3976that pops certain registers off the stack, depending on the arguments 3977that have been passed to the function. Since this is a property of the 3978call site, not of the called function, @code{RETURN_POPS_ARGS} is not 3979appropriate. 3980@end defmac 3981 3982@node Register Arguments 3983@subsection Passing Arguments in Registers 3984@cindex arguments in registers 3985@cindex registers arguments 3986 3987This section describes the macros which let you control how various 3988types of arguments are passed in registers or how they are arranged in 3989the stack. 3990 3991@deftypefn {Target Hook} rtx TARGET_FUNCTION_ARG (cumulative_args_t @var{ca}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named}) 3992Return an RTX indicating whether a function argument is passed in a 3993register and if so, which register. 3994 3995The arguments are @var{ca}, which summarizes all the previous 3996arguments; @var{mode}, the machine mode of the argument; @var{type}, 3997the data type of the argument as a tree node or 0 if that is not known 3998(which happens for C support library functions); and @var{named}, 3999which is @code{true} for an ordinary argument and @code{false} for 4000nameless arguments that correspond to @samp{@dots{}} in the called 4001function's prototype. @var{type} can be an incomplete type if a 4002syntax error has previously occurred. 4003 4004The return value is usually either a @code{reg} RTX for the hard 4005register in which to pass the argument, or zero to pass the argument 4006on the stack. 4007 4008The value of the expression can also be a @code{parallel} RTX@. This is 4009used when an argument is passed in multiple locations. The mode of the 4010@code{parallel} should be the mode of the entire argument. The 4011@code{parallel} holds any number of @code{expr_list} pairs; each one 4012describes where part of the argument is passed. In each 4013@code{expr_list} the first operand must be a @code{reg} RTX for the hard 4014register in which to pass this part of the argument, and the mode of the 4015register RTX indicates how large this part of the argument is. The 4016second operand of the @code{expr_list} is a @code{const_int} which gives 4017the offset in bytes into the entire argument of where this part starts. 4018As a special exception the first @code{expr_list} in the @code{parallel} 4019RTX may have a first operand of zero. This indicates that the entire 4020argument is also stored on the stack. 4021 4022The last time this hook is called, it is called with @code{MODE == 4023VOIDmode}, and its result is passed to the @code{call} or @code{call_value} 4024pattern as operands 2 and 3 respectively. 4025 4026@cindex @file{stdarg.h} and register arguments 4027The usual way to make the ISO library @file{stdarg.h} work on a 4028machine where some arguments are usually passed in registers, is to 4029cause nameless arguments to be passed on the stack instead. This is 4030done by making @code{TARGET_FUNCTION_ARG} return 0 whenever 4031@var{named} is @code{false}. 4032 4033@cindex @code{TARGET_MUST_PASS_IN_STACK}, and @code{TARGET_FUNCTION_ARG} 4034@cindex @code{REG_PARM_STACK_SPACE}, and @code{TARGET_FUNCTION_ARG} 4035You may use the hook @code{targetm.calls.must_pass_in_stack} 4036in the definition of this macro to determine if this argument is of a 4037type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 4038is not defined and @code{TARGET_FUNCTION_ARG} returns nonzero for such an 4039argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 4040defined, the argument will be computed in the stack and then loaded into 4041a register. 4042@end deftypefn 4043 4044@deftypefn {Target Hook} bool TARGET_MUST_PASS_IN_STACK (enum machine_mode @var{mode}, const_tree @var{type}) 4045This target hook should return @code{true} if we should not pass @var{type} 4046solely in registers. The file @file{expr.h} defines a 4047definition that is usually appropriate, refer to @file{expr.h} for additional 4048documentation. 4049@end deftypefn 4050 4051@deftypefn {Target Hook} rtx TARGET_FUNCTION_INCOMING_ARG (cumulative_args_t @var{ca}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named}) 4052Define this hook if the target machine has ``register windows'', so 4053that the register in which a function sees an arguments is not 4054necessarily the same as the one in which the caller passed the 4055argument. 4056 4057For such machines, @code{TARGET_FUNCTION_ARG} computes the register in 4058which the caller passes the value, and 4059@code{TARGET_FUNCTION_INCOMING_ARG} should be defined in a similar 4060fashion to tell the function being called where the arguments will 4061arrive. 4062 4063If @code{TARGET_FUNCTION_INCOMING_ARG} is not defined, 4064@code{TARGET_FUNCTION_ARG} serves both purposes. 4065@end deftypefn 4066 4067@deftypefn {Target Hook} int TARGET_ARG_PARTIAL_BYTES (cumulative_args_t @var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 4068This target hook returns the number of bytes at the beginning of an 4069argument that must be put in registers. The value must be zero for 4070arguments that are passed entirely in registers or that are entirely 4071pushed on the stack. 4072 4073On some machines, certain arguments must be passed partially in 4074registers and partially in memory. On these machines, typically the 4075first few words of arguments are passed in registers, and the rest 4076on the stack. If a multi-word argument (a @code{double} or a 4077structure) crosses that boundary, its first few words must be passed 4078in registers and the rest must be pushed. This macro tells the 4079compiler when this occurs, and how many bytes should go in registers. 4080 4081@code{TARGET_FUNCTION_ARG} for these arguments should return the first 4082register to be used by the caller for this argument; likewise 4083@code{TARGET_FUNCTION_INCOMING_ARG}, for the called function. 4084@end deftypefn 4085 4086@deftypefn {Target Hook} bool TARGET_PASS_BY_REFERENCE (cumulative_args_t @var{cum}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named}) 4087This target hook should return @code{true} if an argument at the 4088position indicated by @var{cum} should be passed by reference. This 4089predicate is queried after target independent reasons for being 4090passed by reference, such as @code{TREE_ADDRESSABLE (type)}. 4091 4092If the hook returns true, a copy of that argument is made in memory and a 4093pointer to the argument is passed instead of the argument itself. 4094The pointer is passed in whatever way is appropriate for passing a pointer 4095to that type. 4096@end deftypefn 4097 4098@deftypefn {Target Hook} bool TARGET_CALLEE_COPIES (cumulative_args_t @var{cum}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named}) 4099The function argument described by the parameters to this hook is 4100known to be passed by reference. The hook should return true if the 4101function argument should be copied by the callee instead of copied 4102by the caller. 4103 4104For any argument for which the hook returns true, if it can be 4105determined that the argument is not modified, then a copy need 4106not be generated. 4107 4108The default version of this hook always returns false. 4109@end deftypefn 4110 4111@defmac CUMULATIVE_ARGS 4112A C type for declaring a variable that is used as the first argument 4113of @code{TARGET_FUNCTION_ARG} and other related values. For some 4114target machines, the type @code{int} suffices and can hold the number 4115of bytes of argument so far. 4116 4117There is no need to record in @code{CUMULATIVE_ARGS} anything about the 4118arguments that have been passed on the stack. The compiler has other 4119variables to keep track of that. For target machines on which all 4120arguments are passed on the stack, there is no need to store anything in 4121@code{CUMULATIVE_ARGS}; however, the data structure must exist and 4122should not be empty, so use @code{int}. 4123@end defmac 4124 4125@defmac OVERRIDE_ABI_FORMAT (@var{fndecl}) 4126If defined, this macro is called before generating any code for a 4127function, but after the @var{cfun} descriptor for the function has been 4128created. The back end may use this macro to update @var{cfun} to 4129reflect an ABI other than that which would normally be used by default. 4130If the compiler is generating code for a compiler-generated function, 4131@var{fndecl} may be @code{NULL}. 4132@end defmac 4133 4134@defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args}) 4135A C statement (sans semicolon) for initializing the variable 4136@var{cum} for the state at the beginning of the argument list. The 4137variable has type @code{CUMULATIVE_ARGS}. The value of @var{fntype} 4138is the tree node for the data type of the function which will receive 4139the args, or 0 if the args are to a compiler support library function. 4140For direct calls that are not libcalls, @var{fndecl} contain the 4141declaration node of the function. @var{fndecl} is also set when 4142@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 4143being compiled. @var{n_named_args} is set to the number of named 4144arguments, including a structure return address if it is passed as a 4145parameter, when making a call. When processing incoming arguments, 4146@var{n_named_args} is set to @minus{}1. 4147 4148When processing a call to a compiler support library function, 4149@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 4150contains the name of the function, as a string. @var{libname} is 0 when 4151an ordinary C function call is being processed. Thus, each time this 4152macro is called, either @var{libname} or @var{fntype} is nonzero, but 4153never both of them at once. 4154@end defmac 4155 4156@defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 4157Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 4158it gets a @code{MODE} argument instead of @var{fntype}, that would be 4159@code{NULL}. @var{indirect} would always be zero, too. If this macro 4160is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 41610)} is used instead. 4162@end defmac 4163 4164@defmac INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 4165Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 4166finding the arguments for the function being compiled. If this macro is 4167undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 4168 4169The value passed for @var{libname} is always 0, since library routines 4170with special calling conventions are never compiled with GCC@. The 4171argument @var{libname} exists for symmetry with 4172@code{INIT_CUMULATIVE_ARGS}. 4173@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 4174@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 4175@end defmac 4176 4177@deftypefn {Target Hook} void TARGET_FUNCTION_ARG_ADVANCE (cumulative_args_t @var{ca}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named}) 4178This hook updates the summarizer variable pointed to by @var{ca} to 4179advance past an argument in the argument list. The values @var{mode}, 4180@var{type} and @var{named} describe that argument. Once this is done, 4181the variable @var{cum} is suitable for analyzing the @emph{following} 4182argument with @code{TARGET_FUNCTION_ARG}, etc. 4183 4184This hook need not do anything if the argument in question was passed 4185on the stack. The compiler knows how to track the amount of stack space 4186used for arguments without any special help. 4187@end deftypefn 4188 4189@defmac FUNCTION_ARG_OFFSET (@var{mode}, @var{type}) 4190If defined, a C expression that is the number of bytes to add to the 4191offset of the argument passed in memory. This is needed for the SPU, 4192which passes @code{char} and @code{short} arguments in the preferred 4193slot that is in the middle of the quad word instead of starting at the 4194top. 4195@end defmac 4196 4197@defmac FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 4198If defined, a C expression which determines whether, and in which direction, 4199to pad out an argument with extra space. The value should be of type 4200@code{enum direction}: either @code{upward} to pad above the argument, 4201@code{downward} to pad below, or @code{none} to inhibit padding. 4202 4203The @emph{amount} of padding is not controlled by this macro, but by the 4204target hook @code{TARGET_FUNCTION_ARG_ROUND_BOUNDARY}. It is 4205always just enough to reach the next multiple of that boundary. 4206 4207This macro has a default definition which is right for most systems. 4208For little-endian machines, the default is to pad upward. For 4209big-endian machines, the default is to pad downward for an argument of 4210constant size shorter than an @code{int}, and upward otherwise. 4211@end defmac 4212 4213@defmac PAD_VARARGS_DOWN 4214If defined, a C expression which determines whether the default 4215implementation of va_arg will attempt to pad down before reading the 4216next argument, if that argument is smaller than its aligned space as 4217controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 4218arguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 4219@end defmac 4220 4221@defmac BLOCK_REG_PADDING (@var{mode}, @var{type}, @var{first}) 4222Specify padding for the last element of a block move between registers and 4223memory. @var{first} is nonzero if this is the only element. Defining this 4224macro allows better control of register function parameters on big-endian 4225machines, without using @code{PARALLEL} rtl. In particular, 4226@code{MUST_PASS_IN_STACK} need not test padding and mode of types in 4227registers, as there is no longer a "wrong" part of a register; For example, 4228a three byte aggregate may be passed in the high part of a register if so 4229required. 4230@end defmac 4231 4232@deftypefn {Target Hook} {unsigned int} TARGET_FUNCTION_ARG_BOUNDARY (enum machine_mode @var{mode}, const_tree @var{type}) 4233This hook returns the alignment boundary, in bits, of an argument 4234with the specified mode and type. The default hook returns 4235@code{PARM_BOUNDARY} for all arguments. 4236@end deftypefn 4237 4238@deftypefn {Target Hook} {unsigned int} TARGET_FUNCTION_ARG_ROUND_BOUNDARY (enum machine_mode @var{mode}, const_tree @var{type}) 4239Normally, the size of an argument is rounded up to @code{PARM_BOUNDARY}, 4240which is the default value for this hook. You can define this hook to 4241return a different value if an argument size must be rounded to a larger 4242value. 4243@end deftypefn 4244 4245@defmac FUNCTION_ARG_REGNO_P (@var{regno}) 4246A C expression that is nonzero if @var{regno} is the number of a hard 4247register in which function arguments are sometimes passed. This does 4248@emph{not} include implicit arguments such as the static chain and 4249the structure-value address. On many machines, no registers can be 4250used for this purpose since all function arguments are pushed on the 4251stack. 4252@end defmac 4253 4254@deftypefn {Target Hook} bool TARGET_SPLIT_COMPLEX_ARG (const_tree @var{type}) 4255This hook should return true if parameter of type @var{type} are passed 4256as two scalar parameters. By default, GCC will attempt to pack complex 4257arguments into the target's word size. Some ABIs require complex arguments 4258to be split and treated as their individual components. For example, on 4259AIX64, complex floats should be passed in a pair of floating point 4260registers, even though a complex float would fit in one 64-bit floating 4261point register. 4262 4263The default value of this hook is @code{NULL}, which is treated as always 4264false. 4265@end deftypefn 4266 4267@deftypefn {Target Hook} tree TARGET_BUILD_BUILTIN_VA_LIST (void) 4268This hook returns a type node for @code{va_list} for the target. 4269The default version of the hook returns @code{void*}. 4270@end deftypefn 4271 4272@deftypefn {Target Hook} int TARGET_ENUM_VA_LIST_P (int @var{idx}, const char **@var{pname}, tree *@var{ptree}) 4273This target hook is used in function @code{c_common_nodes_and_builtins} 4274to iterate through the target specific builtin types for va_list. The 4275variable @var{idx} is used as iterator. @var{pname} has to be a pointer 4276to a @code{const char *} and @var{ptree} a pointer to a @code{tree} typed 4277variable. 4278The arguments @var{pname} and @var{ptree} are used to store the result of 4279this macro and are set to the name of the va_list builtin type and its 4280internal type. 4281If the return value of this macro is zero, then there is no more element. 4282Otherwise the @var{IDX} should be increased for the next call of this 4283macro to iterate through all types. 4284@end deftypefn 4285 4286@deftypefn {Target Hook} tree TARGET_FN_ABI_VA_LIST (tree @var{fndecl}) 4287This hook returns the va_list type of the calling convention specified by 4288@var{fndecl}. 4289The default version of this hook returns @code{va_list_type_node}. 4290@end deftypefn 4291 4292@deftypefn {Target Hook} tree TARGET_CANONICAL_VA_LIST_TYPE (tree @var{type}) 4293This hook returns the va_list type of the calling convention specified by the 4294type of @var{type}. If @var{type} is not a valid va_list type, it returns 4295@code{NULL_TREE}. 4296@end deftypefn 4297 4298@deftypefn {Target Hook} tree TARGET_GIMPLIFY_VA_ARG_EXPR (tree @var{valist}, tree @var{type}, gimple_seq *@var{pre_p}, gimple_seq *@var{post_p}) 4299This hook performs target-specific gimplification of 4300@code{VA_ARG_EXPR}. The first two parameters correspond to the 4301arguments to @code{va_arg}; the latter two are as in 4302@code{gimplify.c:gimplify_expr}. 4303@end deftypefn 4304 4305@deftypefn {Target Hook} bool TARGET_VALID_POINTER_MODE (enum machine_mode @var{mode}) 4306Define this to return nonzero if the port can handle pointers 4307with machine mode @var{mode}. The default version of this 4308hook returns true for both @code{ptr_mode} and @code{Pmode}. 4309@end deftypefn 4310 4311@deftypefn {Target Hook} bool TARGET_REF_MAY_ALIAS_ERRNO (struct ao_ref_s *@var{ref}) 4312Define this to return nonzero if the memory reference @var{ref} may alias with the system C library errno location. The default version of this hook assumes the system C library errno location is either a declaration of type int or accessed by dereferencing a pointer to int. 4313@end deftypefn 4314 4315@deftypefn {Target Hook} bool TARGET_SCALAR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4316Define this to return nonzero if the port is prepared to handle 4317insns involving scalar mode @var{mode}. For a scalar mode to be 4318considered supported, all the basic arithmetic and comparisons 4319must work. 4320 4321The default version of this hook returns true for any mode 4322required to handle the basic C types (as defined by the port). 4323Included here are the double-word arithmetic supported by the 4324code in @file{optabs.c}. 4325@end deftypefn 4326 4327@deftypefn {Target Hook} bool TARGET_VECTOR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4328Define this to return nonzero if the port is prepared to handle 4329insns involving vector mode @var{mode}. At the very least, it 4330must have move patterns for this mode. 4331@end deftypefn 4332 4333@deftypefn {Target Hook} bool TARGET_ARRAY_MODE_SUPPORTED_P (enum machine_mode @var{mode}, unsigned HOST_WIDE_INT @var{nelems}) 4334Return true if GCC should try to use a scalar mode to store an array 4335of @var{nelems} elements, given that each element has mode @var{mode}. 4336Returning true here overrides the usual @code{MAX_FIXED_MODE} limit 4337and allows GCC to use any defined integer mode. 4338 4339One use of this hook is to support vector load and store operations 4340that operate on several homogeneous vectors. For example, ARM NEON 4341has operations like: 4342 4343@smallexample 4344int8x8x3_t vld3_s8 (const int8_t *) 4345@end smallexample 4346 4347where the return type is defined as: 4348 4349@smallexample 4350typedef struct int8x8x3_t 4351@{ 4352 int8x8_t val[3]; 4353@} int8x8x3_t; 4354@end smallexample 4355 4356If this hook allows @code{val} to have a scalar mode, then 4357@code{int8x8x3_t} can have the same mode. GCC can then store 4358@code{int8x8x3_t}s in registers rather than forcing them onto the stack. 4359@end deftypefn 4360 4361@deftypefn {Target Hook} bool TARGET_SMALL_REGISTER_CLASSES_FOR_MODE_P (enum machine_mode @var{mode}) 4362Define this to return nonzero for machine modes for which the port has 4363small register classes. If this target hook returns nonzero for a given 4364@var{mode}, the compiler will try to minimize the lifetime of registers 4365in @var{mode}. The hook may be called with @code{VOIDmode} as argument. 4366In this case, the hook is expected to return nonzero if it returns nonzero 4367for any mode. 4368 4369On some machines, it is risky to let hard registers live across arbitrary 4370insns. Typically, these machines have instructions that require values 4371to be in specific registers (like an accumulator), and reload will fail 4372if the required hard register is used for another purpose across such an 4373insn. 4374 4375Passes before reload do not know which hard registers will be used 4376in an instruction, but the machine modes of the registers set or used in 4377the instruction are already known. And for some machines, register 4378classes are small for, say, integer registers but not for floating point 4379registers. For example, the AMD x86-64 architecture requires specific 4380registers for the legacy x86 integer instructions, but there are many 4381SSE registers for floating point operations. On such targets, a good 4382strategy may be to return nonzero from this hook for @code{INTEGRAL_MODE_P} 4383machine modes but zero for the SSE register classes. 4384 4385The default version of this hook returns false for any mode. It is always 4386safe to redefine this hook to return with a nonzero value. But if you 4387unnecessarily define it, you will reduce the amount of optimizations 4388that can be performed in some cases. If you do not define this hook 4389to return a nonzero value when it is required, the compiler will run out 4390of spill registers and print a fatal error message. 4391@end deftypefn 4392 4393@deftypevr {Target Hook} {unsigned int} TARGET_FLAGS_REGNUM 4394If the target has a dedicated flags register, and it needs to use the post-reload comparison elimination pass, then this value should be set appropriately. 4395@end deftypevr 4396 4397@node Scalar Return 4398@subsection How Scalar Function Values Are Returned 4399@cindex return values in registers 4400@cindex values, returned by functions 4401@cindex scalars, returned as values 4402 4403This section discusses the macros that control returning scalars as 4404values---values that can fit in registers. 4405 4406@deftypefn {Target Hook} rtx TARGET_FUNCTION_VALUE (const_tree @var{ret_type}, const_tree @var{fn_decl_or_type}, bool @var{outgoing}) 4407 4408Define this to return an RTX representing the place where a function 4409returns or receives a value of data type @var{ret_type}, a tree node 4410representing a data type. @var{fn_decl_or_type} is a tree node 4411representing @code{FUNCTION_DECL} or @code{FUNCTION_TYPE} of a 4412function being called. If @var{outgoing} is false, the hook should 4413compute the register in which the caller will see the return value. 4414Otherwise, the hook should return an RTX representing the place where 4415a function returns a value. 4416 4417On many machines, only @code{TYPE_MODE (@var{ret_type})} is relevant. 4418(Actually, on most machines, scalar values are returned in the same 4419place regardless of mode.) The value of the expression is usually a 4420@code{reg} RTX for the hard register where the return value is stored. 4421The value can also be a @code{parallel} RTX, if the return value is in 4422multiple places. See @code{TARGET_FUNCTION_ARG} for an explanation of the 4423@code{parallel} form. Note that the callee will populate every 4424location specified in the @code{parallel}, but if the first element of 4425the @code{parallel} contains the whole return value, callers will use 4426that element as the canonical location and ignore the others. The m68k 4427port uses this type of @code{parallel} to return pointers in both 4428@samp{%a0} (the canonical location) and @samp{%d0}. 4429 4430If @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply 4431the same promotion rules specified in @code{PROMOTE_MODE} if 4432@var{valtype} is a scalar type. 4433 4434If the precise function being called is known, @var{func} is a tree 4435node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 4436pointer. This makes it possible to use a different value-returning 4437convention for specific functions when all their calls are 4438known. 4439 4440Some target machines have ``register windows'' so that the register in 4441which a function returns its value is not the same as the one in which 4442the caller sees the value. For such machines, you should return 4443different RTX depending on @var{outgoing}. 4444 4445@code{TARGET_FUNCTION_VALUE} is not used for return values with 4446aggregate data types, because these are returned in another way. See 4447@code{TARGET_STRUCT_VALUE_RTX} and related macros, below. 4448@end deftypefn 4449 4450@defmac FUNCTION_VALUE (@var{valtype}, @var{func}) 4451This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for 4452a new target instead. 4453@end defmac 4454 4455@defmac LIBCALL_VALUE (@var{mode}) 4456A C expression to create an RTX representing the place where a library 4457function returns a value of mode @var{mode}. 4458 4459Note that ``library function'' in this context means a compiler 4460support routine, used to perform arithmetic, whose name is known 4461specially by the compiler and was not mentioned in the C code being 4462compiled. 4463@end defmac 4464 4465@deftypefn {Target Hook} rtx TARGET_LIBCALL_VALUE (enum machine_mode @var{mode}, const_rtx @var{fun}) 4466Define this hook if the back-end needs to know the name of the libcall 4467function in order to determine where the result should be returned. 4468 4469The mode of the result is given by @var{mode} and the name of the called 4470library function is given by @var{fun}. The hook should return an RTX 4471representing the place where the library function result will be returned. 4472 4473If this hook is not defined, then LIBCALL_VALUE will be used. 4474@end deftypefn 4475 4476@defmac FUNCTION_VALUE_REGNO_P (@var{regno}) 4477A C expression that is nonzero if @var{regno} is the number of a hard 4478register in which the values of called function may come back. 4479 4480A register whose use for returning values is limited to serving as the 4481second of a pair (for a value of type @code{double}, say) need not be 4482recognized by this macro. So for most machines, this definition 4483suffices: 4484 4485@smallexample 4486#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 4487@end smallexample 4488 4489If the machine has register windows, so that the caller and the called 4490function use different registers for the return value, this macro 4491should recognize only the caller's register numbers. 4492 4493This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE_REGNO_P} 4494for a new target instead. 4495@end defmac 4496 4497@deftypefn {Target Hook} bool TARGET_FUNCTION_VALUE_REGNO_P (const unsigned int @var{regno}) 4498A target hook that return @code{true} if @var{regno} is the number of a hard 4499register in which the values of called function may come back. 4500 4501A register whose use for returning values is limited to serving as the 4502second of a pair (for a value of type @code{double}, say) need not be 4503recognized by this target hook. 4504 4505If the machine has register windows, so that the caller and the called 4506function use different registers for the return value, this target hook 4507should recognize only the caller's register numbers. 4508 4509If this hook is not defined, then FUNCTION_VALUE_REGNO_P will be used. 4510@end deftypefn 4511 4512@defmac APPLY_RESULT_SIZE 4513Define this macro if @samp{untyped_call} and @samp{untyped_return} 4514need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 4515saving and restoring an arbitrary return value. 4516@end defmac 4517 4518@deftypefn {Target Hook} bool TARGET_RETURN_IN_MSB (const_tree @var{type}) 4519This hook should return true if values of type @var{type} are returned 4520at the most significant end of a register (in other words, if they are 4521padded at the least significant end). You can assume that @var{type} 4522is returned in a register; the caller is required to check this. 4523 4524Note that the register provided by @code{TARGET_FUNCTION_VALUE} must 4525be able to hold the complete return value. For example, if a 1-, 2- 4526or 3-byte structure is returned at the most significant end of a 45274-byte register, @code{TARGET_FUNCTION_VALUE} should provide an 4528@code{SImode} rtx. 4529@end deftypefn 4530 4531@node Aggregate Return 4532@subsection How Large Values Are Returned 4533@cindex aggregates as return values 4534@cindex large return values 4535@cindex returning aggregate values 4536@cindex structure value address 4537 4538When a function value's mode is @code{BLKmode} (and in some other 4539cases), the value is not returned according to 4540@code{TARGET_FUNCTION_VALUE} (@pxref{Scalar Return}). Instead, the 4541caller passes the address of a block of memory in which the value 4542should be stored. This address is called the @dfn{structure value 4543address}. 4544 4545This section describes how to control returning structure values in 4546memory. 4547 4548@deftypefn {Target Hook} bool TARGET_RETURN_IN_MEMORY (const_tree @var{type}, const_tree @var{fntype}) 4549This target hook should return a nonzero value to say to return the 4550function value in memory, just as large structures are always returned. 4551Here @var{type} will be the data type of the value, and @var{fntype} 4552will be the type of the function doing the returning, or @code{NULL} for 4553libcalls. 4554 4555Note that values of mode @code{BLKmode} must be explicitly handled 4556by this function. Also, the option @option{-fpcc-struct-return} 4557takes effect regardless of this macro. On most systems, it is 4558possible to leave the hook undefined; this causes a default 4559definition to be used, whose value is the constant 1 for @code{BLKmode} 4560values, and 0 otherwise. 4561 4562Do not use this hook to indicate that structures and unions should always 4563be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 4564to indicate this. 4565@end deftypefn 4566 4567@defmac DEFAULT_PCC_STRUCT_RETURN 4568Define this macro to be 1 if all structure and union return values must be 4569in memory. Since this results in slower code, this should be defined 4570only if needed for compatibility with other compilers or with an ABI@. 4571If you define this macro to be 0, then the conventions used for structure 4572and union return values are decided by the @code{TARGET_RETURN_IN_MEMORY} 4573target hook. 4574 4575If not defined, this defaults to the value 1. 4576@end defmac 4577 4578@deftypefn {Target Hook} rtx TARGET_STRUCT_VALUE_RTX (tree @var{fndecl}, int @var{incoming}) 4579This target hook should return the location of the structure value 4580address (normally a @code{mem} or @code{reg}), or 0 if the address is 4581passed as an ``invisible'' first argument. Note that @var{fndecl} may 4582be @code{NULL}, for libcalls. You do not need to define this target 4583hook if the address is always passed as an ``invisible'' first 4584argument. 4585 4586On some architectures the place where the structure value address 4587is found by the called function is not the same place that the 4588caller put it. This can be due to register windows, or it could 4589be because the function prologue moves it to a different place. 4590@var{incoming} is @code{1} or @code{2} when the location is needed in 4591the context of the called function, and @code{0} in the context of 4592the caller. 4593 4594If @var{incoming} is nonzero and the address is to be found on the 4595stack, return a @code{mem} which refers to the frame pointer. If 4596@var{incoming} is @code{2}, the result is being used to fetch the 4597structure value address at the beginning of a function. If you need 4598to emit adjusting code, you should do it at this point. 4599@end deftypefn 4600 4601@defmac PCC_STATIC_STRUCT_RETURN 4602Define this macro if the usual system convention on the target machine 4603for returning structures and unions is for the called function to return 4604the address of a static variable containing the value. 4605 4606Do not define this if the usual system convention is for the caller to 4607pass an address to the subroutine. 4608 4609This macro has effect in @option{-fpcc-struct-return} mode, but it does 4610nothing when you use @option{-freg-struct-return} mode. 4611@end defmac 4612 4613@deftypefn {Target Hook} {enum machine_mode} TARGET_GET_RAW_RESULT_MODE (int @var{regno}) 4614This target hook returns the mode to be used when accessing raw return registers in @code{__builtin_return}. Define this macro if the value in @var{reg_raw_mode} is not correct. 4615@end deftypefn 4616 4617@deftypefn {Target Hook} {enum machine_mode} TARGET_GET_RAW_ARG_MODE (int @var{regno}) 4618This target hook returns the mode to be used when accessing raw argument registers in @code{__builtin_apply_args}. Define this macro if the value in @var{reg_raw_mode} is not correct. 4619@end deftypefn 4620 4621@node Caller Saves 4622@subsection Caller-Saves Register Allocation 4623 4624If you enable it, GCC can save registers around function calls. This 4625makes it possible to use call-clobbered registers to hold variables that 4626must live across calls. 4627 4628@defmac CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 4629A C expression to determine whether it is worthwhile to consider placing 4630a pseudo-register in a call-clobbered hard register and saving and 4631restoring it around each function call. The expression should be 1 when 4632this is worth doing, and 0 otherwise. 4633 4634If you don't define this macro, a default is used which is good on most 4635machines: @code{4 * @var{calls} < @var{refs}}. 4636@end defmac 4637 4638@defmac HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 4639A C expression specifying which mode is required for saving @var{nregs} 4640of a pseudo-register in call-clobbered hard register @var{regno}. If 4641@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 4642returned. For most machines this macro need not be defined since GCC 4643will select the smallest suitable mode. 4644@end defmac 4645 4646@node Function Entry 4647@subsection Function Entry and Exit 4648@cindex function entry and exit 4649@cindex prologue 4650@cindex epilogue 4651 4652This section describes the macros that output function entry 4653(@dfn{prologue}) and exit (@dfn{epilogue}) code. 4654 4655@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 4656If defined, a function that outputs the assembler code for entry to a 4657function. The prologue is responsible for setting up the stack frame, 4658initializing the frame pointer register, saving registers that must be 4659saved, and allocating @var{size} additional bytes of storage for the 4660local variables. @var{size} is an integer. @var{file} is a stdio 4661stream to which the assembler code should be output. 4662 4663The label for the beginning of the function need not be output by this 4664macro. That has already been done when the macro is run. 4665 4666@findex regs_ever_live 4667To determine which registers to save, the macro can refer to the array 4668@code{regs_ever_live}: element @var{r} is nonzero if hard register 4669@var{r} is used anywhere within the function. This implies the function 4670prologue should save register @var{r}, provided it is not one of the 4671call-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 4672@code{regs_ever_live}.) 4673 4674On machines that have ``register windows'', the function entry code does 4675not save on the stack the registers that are in the windows, even if 4676they are supposed to be preserved by function calls; instead it takes 4677appropriate steps to ``push'' the register stack, if any non-call-used 4678registers are used in the function. 4679 4680@findex frame_pointer_needed 4681On machines where functions may or may not have frame-pointers, the 4682function entry code must vary accordingly; it must set up the frame 4683pointer if one is wanted, and not otherwise. To determine whether a 4684frame pointer is in wanted, the macro can refer to the variable 4685@code{frame_pointer_needed}. The variable's value will be 1 at run 4686time in a function that needs a frame pointer. @xref{Elimination}. 4687 4688The function entry code is responsible for allocating any stack space 4689required for the function. This stack space consists of the regions 4690listed below. In most cases, these regions are allocated in the 4691order listed, with the last listed region closest to the top of the 4692stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 4693the highest address if it is not defined). You can use a different order 4694for a machine if doing so is more convenient or required for 4695compatibility reasons. Except in cases where required by standard 4696or by a debugger, there is no reason why the stack layout used by GCC 4697need agree with that used by other compilers for a machine. 4698@end deftypefn 4699 4700@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 4701If defined, a function that outputs assembler code at the end of a 4702prologue. This should be used when the function prologue is being 4703emitted as RTL, and you have some extra assembler that needs to be 4704emitted. @xref{prologue instruction pattern}. 4705@end deftypefn 4706 4707@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 4708If defined, a function that outputs assembler code at the start of an 4709epilogue. This should be used when the function epilogue is being 4710emitted as RTL, and you have some extra assembler that needs to be 4711emitted. @xref{epilogue instruction pattern}. 4712@end deftypefn 4713 4714@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 4715If defined, a function that outputs the assembler code for exit from a 4716function. The epilogue is responsible for restoring the saved 4717registers and stack pointer to their values when the function was 4718called, and returning control to the caller. This macro takes the 4719same arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 4720registers to restore are determined from @code{regs_ever_live} and 4721@code{CALL_USED_REGISTERS} in the same way. 4722 4723On some machines, there is a single instruction that does all the work 4724of returning from the function. On these machines, give that 4725instruction the name @samp{return} and do not define the macro 4726@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 4727 4728Do not define a pattern named @samp{return} if you want the 4729@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 4730switches to control whether return instructions or epilogues are used, 4731define a @samp{return} pattern with a validity condition that tests the 4732target switches appropriately. If the @samp{return} pattern's validity 4733condition is false, epilogues will be used. 4734 4735On machines where functions may or may not have frame-pointers, the 4736function exit code must vary accordingly. Sometimes the code for these 4737two cases is completely different. To determine whether a frame pointer 4738is wanted, the macro can refer to the variable 4739@code{frame_pointer_needed}. The variable's value will be 1 when compiling 4740a function that needs a frame pointer. 4741 4742Normally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 4743@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 4744The C variable @code{current_function_is_leaf} is nonzero for such a 4745function. @xref{Leaf Functions}. 4746 4747On some machines, some functions pop their arguments on exit while 4748others leave that for the caller to do. For example, the 68020 when 4749given @option{-mrtd} pops arguments in functions that take a fixed 4750number of arguments. 4751 4752@findex current_function_pops_args 4753Your definition of the macro @code{RETURN_POPS_ARGS} decides which 4754functions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 4755needs to know what was decided. The number of bytes of the current 4756function's arguments that this function should pop is available in 4757@code{crtl->args.pops_args}. @xref{Scalar Return}. 4758@end deftypefn 4759 4760@itemize @bullet 4761@item 4762@findex current_function_pretend_args_size 4763A region of @code{current_function_pretend_args_size} bytes of 4764uninitialized space just underneath the first argument arriving on the 4765stack. (This may not be at the very start of the allocated stack region 4766if the calling sequence has pushed anything else since pushing the stack 4767arguments. But usually, on such machines, nothing else has been pushed 4768yet, because the function prologue itself does all the pushing.) This 4769region is used on machines where an argument may be passed partly in 4770registers and partly in memory, and, in some cases to support the 4771features in @code{<stdarg.h>}. 4772 4773@item 4774An area of memory used to save certain registers used by the function. 4775The size of this area, which may also include space for such things as 4776the return address and pointers to previous stack frames, is 4777machine-specific and usually depends on which registers have been used 4778in the function. Machines with register windows often do not require 4779a save area. 4780 4781@item 4782A region of at least @var{size} bytes, possibly rounded up to an allocation 4783boundary, to contain the local variables of the function. On some machines, 4784this region and the save area may occur in the opposite order, with the 4785save area closer to the top of the stack. 4786 4787@item 4788@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 4789Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 4790@code{current_function_outgoing_args_size} bytes to be used for outgoing 4791argument lists of the function. @xref{Stack Arguments}. 4792@end itemize 4793 4794@defmac EXIT_IGNORE_STACK 4795Define this macro as a C expression that is nonzero if the return 4796instruction or the function epilogue ignores the value of the stack 4797pointer; in other words, if it is safe to delete an instruction to 4798adjust the stack pointer before a return from the function. The 4799default is 0. 4800 4801Note that this macro's value is relevant only for functions for which 4802frame pointers are maintained. It is never safe to delete a final 4803stack adjustment in a function that has no frame pointer, and the 4804compiler knows this regardless of @code{EXIT_IGNORE_STACK}. 4805@end defmac 4806 4807@defmac EPILOGUE_USES (@var{regno}) 4808Define this macro as a C expression that is nonzero for registers that are 4809used by the epilogue or the @samp{return} pattern. The stack and frame 4810pointer registers are already assumed to be used as needed. 4811@end defmac 4812 4813@defmac EH_USES (@var{regno}) 4814Define this macro as a C expression that is nonzero for registers that are 4815used by the exception handling mechanism, and so should be considered live 4816on entry to an exception edge. 4817@end defmac 4818 4819@defmac DELAY_SLOTS_FOR_EPILOGUE 4820Define this macro if the function epilogue contains delay slots to which 4821instructions from the rest of the function can be ``moved''. The 4822definition should be a C expression whose value is an integer 4823representing the number of delay slots there. 4824@end defmac 4825 4826@defmac ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 4827A C expression that returns 1 if @var{insn} can be placed in delay 4828slot number @var{n} of the epilogue. 4829 4830The argument @var{n} is an integer which identifies the delay slot now 4831being considered (since different slots may have different rules of 4832eligibility). It is never negative and is always less than the number 4833of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 4834If you reject a particular insn for a given delay slot, in principle, it 4835may be reconsidered for a subsequent delay slot. Also, other insns may 4836(at least in principle) be considered for the so far unfilled delay 4837slot. 4838 4839@findex current_function_epilogue_delay_list 4840@findex final_scan_insn 4841The insns accepted to fill the epilogue delay slots are put in an RTL 4842list made with @code{insn_list} objects, stored in the variable 4843@code{current_function_epilogue_delay_list}. The insn for the first 4844delay slot comes first in the list. Your definition of the macro 4845@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 4846outputting the insns in this list, usually by calling 4847@code{final_scan_insn}. 4848 4849You need not define this macro if you did not define 4850@code{DELAY_SLOTS_FOR_EPILOGUE}. 4851@end defmac 4852 4853@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, HOST_WIDE_INT @var{vcall_offset}, tree @var{function}) 4854A function that outputs the assembler code for a thunk 4855function, used to implement C++ virtual function calls with multiple 4856inheritance. The thunk acts as a wrapper around a virtual function, 4857adjusting the implicit object parameter before handing control off to 4858the real function. 4859 4860First, emit code to add the integer @var{delta} to the location that 4861contains the incoming first argument. Assume that this argument 4862contains a pointer, and is the one used to pass the @code{this} pointer 4863in C++. This is the incoming argument @emph{before} the function prologue, 4864e.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 4865all other incoming arguments. 4866 4867Then, if @var{vcall_offset} is nonzero, an additional adjustment should be 4868made after adding @code{delta}. In particular, if @var{p} is the 4869adjusted pointer, the following adjustment should be made: 4870 4871@smallexample 4872p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] 4873@end smallexample 4874 4875After the additions, emit code to jump to @var{function}, which is a 4876@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 4877not touch the return address. Hence returning from @var{FUNCTION} will 4878return to whoever called the current @samp{thunk}. 4879 4880The effect must be as if @var{function} had been called directly with 4881the adjusted first argument. This macro is responsible for emitting all 4882of the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 4883and @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 4884 4885The @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 4886have already been extracted from it.) It might possibly be useful on 4887some targets, but probably not. 4888 4889If you do not define this macro, the target-independent code in the C++ 4890front end will generate a less efficient heavyweight thunk that calls 4891@var{function} instead of jumping to it. The generic approach does 4892not support varargs. 4893@end deftypefn 4894 4895@deftypefn {Target Hook} bool TARGET_ASM_CAN_OUTPUT_MI_THUNK (const_tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, HOST_WIDE_INT @var{vcall_offset}, const_tree @var{function}) 4896A function that returns true if TARGET_ASM_OUTPUT_MI_THUNK would be able 4897to output the assembler code for the thunk function specified by the 4898arguments it is passed, and false otherwise. In the latter case, the 4899generic approach will be used by the C++ front end, with the limitations 4900previously exposed. 4901@end deftypefn 4902 4903@node Profiling 4904@subsection Generating Code for Profiling 4905@cindex profiling, code generation 4906 4907These macros will help you generate code for profiling. 4908 4909@defmac FUNCTION_PROFILER (@var{file}, @var{labelno}) 4910A C statement or compound statement to output to @var{file} some 4911assembler code to call the profiling subroutine @code{mcount}. 4912 4913@findex mcount 4914The details of how @code{mcount} expects to be called are determined by 4915your operating system environment, not by GCC@. To figure them out, 4916compile a small program for profiling using the system's installed C 4917compiler and look at the assembler code that results. 4918 4919Older implementations of @code{mcount} expect the address of a counter 4920variable to be loaded into some register. The name of this variable is 4921@samp{LP} followed by the number @var{labelno}, so you would generate 4922the name using @samp{LP%d} in a @code{fprintf}. 4923@end defmac 4924 4925@defmac PROFILE_HOOK 4926A C statement or compound statement to output to @var{file} some assembly 4927code to call the profiling subroutine @code{mcount} even the target does 4928not support profiling. 4929@end defmac 4930 4931@defmac NO_PROFILE_COUNTERS 4932Define this macro to be an expression with a nonzero value if the 4933@code{mcount} subroutine on your system does not need a counter variable 4934allocated for each function. This is true for almost all modern 4935implementations. If you define this macro, you must not use the 4936@var{labelno} argument to @code{FUNCTION_PROFILER}. 4937@end defmac 4938 4939@defmac PROFILE_BEFORE_PROLOGUE 4940Define this macro if the code for function profiling should come before 4941the function prologue. Normally, the profiling code comes after. 4942@end defmac 4943 4944@node Tail Calls 4945@subsection Permitting tail calls 4946@cindex tail calls 4947 4948@deftypefn {Target Hook} bool TARGET_FUNCTION_OK_FOR_SIBCALL (tree @var{decl}, tree @var{exp}) 4949True if it is ok to do sibling call optimization for the specified 4950call expression @var{exp}. @var{decl} will be the called function, 4951or @code{NULL} if this is an indirect call. 4952 4953It is not uncommon for limitations of calling conventions to prevent 4954tail calls to functions outside the current unit of translation, or 4955during PIC compilation. The hook is used to enforce these restrictions, 4956as the @code{sibcall} md pattern can not fail, or fall over to a 4957``normal'' call. The criteria for successful sibling call optimization 4958may vary greatly between different architectures. 4959@end deftypefn 4960 4961@deftypefn {Target Hook} void TARGET_EXTRA_LIVE_ON_ENTRY (bitmap @var{regs}) 4962Add any hard registers to @var{regs} that are live on entry to the 4963function. This hook only needs to be defined to provide registers that 4964cannot be found by examination of FUNCTION_ARG_REGNO_P, the callee saved 4965registers, STATIC_CHAIN_INCOMING_REGNUM, STATIC_CHAIN_REGNUM, 4966TARGET_STRUCT_VALUE_RTX, FRAME_POINTER_REGNUM, EH_USES, 4967FRAME_POINTER_REGNUM, ARG_POINTER_REGNUM, and the PIC_OFFSET_TABLE_REGNUM. 4968@end deftypefn 4969 4970@deftypefn {Target Hook} void TARGET_SET_UP_BY_PROLOGUE (struct hard_reg_set_container *@var{}) 4971This hook should add additional registers that are computed by the prologue to the hard regset for shrink-wrapping optimization purposes. 4972@end deftypefn 4973 4974@node Stack Smashing Protection 4975@subsection Stack smashing protection 4976@cindex stack smashing protection 4977 4978@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_GUARD (void) 4979This hook returns a @code{DECL} node for the external variable to use 4980for the stack protection guard. This variable is initialized by the 4981runtime to some random value and is used to initialize the guard value 4982that is placed at the top of the local stack frame. The type of this 4983variable must be @code{ptr_type_node}. 4984 4985The default version of this hook creates a variable called 4986@samp{__stack_chk_guard}, which is normally defined in @file{libgcc2.c}. 4987@end deftypefn 4988 4989@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_FAIL (void) 4990This hook returns a tree expression that alerts the runtime that the 4991stack protect guard variable has been modified. This expression should 4992involve a call to a @code{noreturn} function. 4993 4994The default version of this hook invokes a function called 4995@samp{__stack_chk_fail}, taking no arguments. This function is 4996normally defined in @file{libgcc2.c}. 4997@end deftypefn 4998 4999@deftypefn {Common Target Hook} bool TARGET_SUPPORTS_SPLIT_STACK (bool @var{report}, struct gcc_options *@var{opts}) 5000Whether this target supports splitting the stack when the options described in @var{opts} have been passed. This is called after options have been parsed, so the target may reject splitting the stack in some configurations. The default version of this hook returns false. If @var{report} is true, this function may issue a warning or error; if @var{report} is false, it must simply return a value 5001@end deftypefn 5002 5003@node Varargs 5004@section Implementing the Varargs Macros 5005@cindex varargs implementation 5006 5007GCC comes with an implementation of @code{<varargs.h>} and 5008@code{<stdarg.h>} that work without change on machines that pass arguments 5009on the stack. Other machines require their own implementations of 5010varargs, and the two machine independent header files must have 5011conditionals to include it. 5012 5013ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 5014the calling convention for @code{va_start}. The traditional 5015implementation takes just one argument, which is the variable in which 5016to store the argument pointer. The ISO implementation of 5017@code{va_start} takes an additional second argument. The user is 5018supposed to write the last named argument of the function here. 5019 5020However, @code{va_start} should not use this argument. The way to find 5021the end of the named arguments is with the built-in functions described 5022below. 5023 5024@defmac __builtin_saveregs () 5025Use this built-in function to save the argument registers in memory so 5026that the varargs mechanism can access them. Both ISO and traditional 5027versions of @code{va_start} must use @code{__builtin_saveregs}, unless 5028you use @code{TARGET_SETUP_INCOMING_VARARGS} (see below) instead. 5029 5030On some machines, @code{__builtin_saveregs} is open-coded under the 5031control of the target hook @code{TARGET_EXPAND_BUILTIN_SAVEREGS}. On 5032other machines, it calls a routine written in assembler language, 5033found in @file{libgcc2.c}. 5034 5035Code generated for the call to @code{__builtin_saveregs} appears at the 5036beginning of the function, as opposed to where the call to 5037@code{__builtin_saveregs} is written, regardless of what the code is. 5038This is because the registers must be saved before the function starts 5039to use them for its own purposes. 5040@c i rewrote the first sentence above to fix an overfull hbox. --mew 5041@c 10feb93 5042@end defmac 5043 5044@defmac __builtin_next_arg (@var{lastarg}) 5045This builtin returns the address of the first anonymous stack 5046argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 5047returns the address of the location above the first anonymous stack 5048argument. Use it in @code{va_start} to initialize the pointer for 5049fetching arguments from the stack. Also use it in @code{va_start} to 5050verify that the second parameter @var{lastarg} is the last named argument 5051of the current function. 5052@end defmac 5053 5054@defmac __builtin_classify_type (@var{object}) 5055Since each machine has its own conventions for which data types are 5056passed in which kind of register, your implementation of @code{va_arg} 5057has to embody these conventions. The easiest way to categorize the 5058specified data type is to use @code{__builtin_classify_type} together 5059with @code{sizeof} and @code{__alignof__}. 5060 5061@code{__builtin_classify_type} ignores the value of @var{object}, 5062considering only its data type. It returns an integer describing what 5063kind of type that is---integer, floating, pointer, structure, and so on. 5064 5065The file @file{typeclass.h} defines an enumeration that you can use to 5066interpret the values of @code{__builtin_classify_type}. 5067@end defmac 5068 5069These machine description macros help implement varargs: 5070 5071@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN_SAVEREGS (void) 5072If defined, this hook produces the machine-specific code for a call to 5073@code{__builtin_saveregs}. This code will be moved to the very 5074beginning of the function, before any parameter access are made. The 5075return value of this function should be an RTX that contains the value 5076to use as the return of @code{__builtin_saveregs}. 5077@end deftypefn 5078 5079@deftypefn {Target Hook} void TARGET_SETUP_INCOMING_VARARGS (cumulative_args_t @var{args_so_far}, enum machine_mode @var{mode}, tree @var{type}, int *@var{pretend_args_size}, int @var{second_time}) 5080This target hook offers an alternative to using 5081@code{__builtin_saveregs} and defining the hook 5082@code{TARGET_EXPAND_BUILTIN_SAVEREGS}. Use it to store the anonymous 5083register arguments into the stack so that all the arguments appear to 5084have been passed consecutively on the stack. Once this is done, you can 5085use the standard implementation of varargs that works for machines that 5086pass all their arguments on the stack. 5087 5088The argument @var{args_so_far} points to the @code{CUMULATIVE_ARGS} data 5089structure, containing the values that are obtained after processing the 5090named arguments. The arguments @var{mode} and @var{type} describe the 5091last named argument---its machine mode and its data type as a tree node. 5092 5093The target hook should do two things: first, push onto the stack all the 5094argument registers @emph{not} used for the named arguments, and second, 5095store the size of the data thus pushed into the @code{int}-valued 5096variable pointed to by @var{pretend_args_size}. The value that you 5097store here will serve as additional offset for setting up the stack 5098frame. 5099 5100Because you must generate code to push the anonymous arguments at 5101compile time without knowing their data types, 5102@code{TARGET_SETUP_INCOMING_VARARGS} is only useful on machines that 5103have just a single category of argument register and use it uniformly 5104for all data types. 5105 5106If the argument @var{second_time} is nonzero, it means that the 5107arguments of the function are being analyzed for the second time. This 5108happens for an inline function, which is not actually compiled until the 5109end of the source file. The hook @code{TARGET_SETUP_INCOMING_VARARGS} should 5110not generate any instructions in this case. 5111@end deftypefn 5112 5113@deftypefn {Target Hook} bool TARGET_STRICT_ARGUMENT_NAMING (cumulative_args_t @var{ca}) 5114Define this hook to return @code{true} if the location where a function 5115argument is passed depends on whether or not it is a named argument. 5116 5117This hook controls how the @var{named} argument to @code{TARGET_FUNCTION_ARG} 5118is set for varargs and stdarg functions. If this hook returns 5119@code{true}, the @var{named} argument is always true for named 5120arguments, and false for unnamed arguments. If it returns @code{false}, 5121but @code{TARGET_PRETEND_OUTGOING_VARARGS_NAMED} returns @code{true}, 5122then all arguments are treated as named. Otherwise, all named arguments 5123except the last are treated as named. 5124 5125You need not define this hook if it always returns @code{false}. 5126@end deftypefn 5127 5128@deftypefn {Target Hook} bool TARGET_PRETEND_OUTGOING_VARARGS_NAMED (cumulative_args_t @var{ca}) 5129If you need to conditionally change ABIs so that one works with 5130@code{TARGET_SETUP_INCOMING_VARARGS}, but the other works like neither 5131@code{TARGET_SETUP_INCOMING_VARARGS} nor @code{TARGET_STRICT_ARGUMENT_NAMING} was 5132defined, then define this hook to return @code{true} if 5133@code{TARGET_SETUP_INCOMING_VARARGS} is used, @code{false} otherwise. 5134Otherwise, you should not define this hook. 5135@end deftypefn 5136 5137@node Trampolines 5138@section Trampolines for Nested Functions 5139@cindex trampolines for nested functions 5140@cindex nested functions, trampolines for 5141 5142A @dfn{trampoline} is a small piece of code that is created at run time 5143when the address of a nested function is taken. It normally resides on 5144the stack, in the stack frame of the containing function. These macros 5145tell GCC how to generate code to allocate and initialize a 5146trampoline. 5147 5148The instructions in the trampoline must do two things: load a constant 5149address into the static chain register, and jump to the real address of 5150the nested function. On CISC machines such as the m68k, this requires 5151two instructions, a move immediate and a jump. Then the two addresses 5152exist in the trampoline as word-long immediate operands. On RISC 5153machines, it is often necessary to load each address into a register in 5154two parts. Then pieces of each address form separate immediate 5155operands. 5156 5157The code generated to initialize the trampoline must store the variable 5158parts---the static chain value and the function address---into the 5159immediate operands of the instructions. On a CISC machine, this is 5160simply a matter of copying each address to a memory reference at the 5161proper offset from the start of the trampoline. On a RISC machine, it 5162may be necessary to take out pieces of the address and store them 5163separately. 5164 5165@deftypefn {Target Hook} void TARGET_ASM_TRAMPOLINE_TEMPLATE (FILE *@var{f}) 5166This hook is called by @code{assemble_trampoline_template} to output, 5167on the stream @var{f}, assembler code for a block of data that contains 5168the constant parts of a trampoline. This code should not include a 5169label---the label is taken care of automatically. 5170 5171If you do not define this hook, it means no template is needed 5172for the target. Do not define this hook on systems where the block move 5173code to copy the trampoline into place would be larger than the code 5174to generate it on the spot. 5175@end deftypefn 5176 5177@defmac TRAMPOLINE_SECTION 5178Return the section into which the trampoline template is to be placed 5179(@pxref{Sections}). The default value is @code{readonly_data_section}. 5180@end defmac 5181 5182@defmac TRAMPOLINE_SIZE 5183A C expression for the size in bytes of the trampoline, as an integer. 5184@end defmac 5185 5186@defmac TRAMPOLINE_ALIGNMENT 5187Alignment required for trampolines, in bits. 5188 5189If you don't define this macro, the value of @code{FUNCTION_ALIGNMENT} 5190is used for aligning trampolines. 5191@end defmac 5192 5193@deftypefn {Target Hook} void TARGET_TRAMPOLINE_INIT (rtx @var{m_tramp}, tree @var{fndecl}, rtx @var{static_chain}) 5194This hook is called to initialize a trampoline. 5195@var{m_tramp} is an RTX for the memory block for the trampoline; @var{fndecl} 5196is the @code{FUNCTION_DECL} for the nested function; @var{static_chain} is an 5197RTX for the static chain value that should be passed to the function 5198when it is called. 5199 5200If the target defines @code{TARGET_ASM_TRAMPOLINE_TEMPLATE}, then the 5201first thing this hook should do is emit a block move into @var{m_tramp} 5202from the memory block returned by @code{assemble_trampoline_template}. 5203Note that the block move need only cover the constant parts of the 5204trampoline. If the target isolates the variable parts of the trampoline 5205to the end, not all @code{TRAMPOLINE_SIZE} bytes need be copied. 5206 5207If the target requires any other actions, such as flushing caches or 5208enabling stack execution, these actions should be performed after 5209initializing the trampoline proper. 5210@end deftypefn 5211 5212@deftypefn {Target Hook} rtx TARGET_TRAMPOLINE_ADJUST_ADDRESS (rtx @var{addr}) 5213This hook should perform any machine-specific adjustment in 5214the address of the trampoline. Its argument contains the address of the 5215memory block that was passed to @code{TARGET_TRAMPOLINE_INIT}. In case 5216the address to be used for a function call should be different from the 5217address at which the template was stored, the different address should 5218be returned; otherwise @var{addr} should be returned unchanged. 5219If this hook is not defined, @var{addr} will be used for function calls. 5220@end deftypefn 5221 5222Implementing trampolines is difficult on many machines because they have 5223separate instruction and data caches. Writing into a stack location 5224fails to clear the memory in the instruction cache, so when the program 5225jumps to that location, it executes the old contents. 5226 5227Here are two possible solutions. One is to clear the relevant parts of 5228the instruction cache whenever a trampoline is set up. The other is to 5229make all trampolines identical, by having them jump to a standard 5230subroutine. The former technique makes trampoline execution faster; the 5231latter makes initialization faster. 5232 5233To clear the instruction cache when a trampoline is initialized, define 5234the following macro. 5235 5236@defmac CLEAR_INSN_CACHE (@var{beg}, @var{end}) 5237If defined, expands to a C expression clearing the @emph{instruction 5238cache} in the specified interval. The definition of this macro would 5239typically be a series of @code{asm} statements. Both @var{beg} and 5240@var{end} are both pointer expressions. 5241@end defmac 5242 5243To use a standard subroutine, define the following macro. In addition, 5244you must make sure that the instructions in a trampoline fill an entire 5245cache line with identical instructions, or else ensure that the 5246beginning of the trampoline code is always aligned at the same point in 5247its cache line. Look in @file{m68k.h} as a guide. 5248 5249@defmac TRANSFER_FROM_TRAMPOLINE 5250Define this macro if trampolines need a special subroutine to do their 5251work. The macro should expand to a series of @code{asm} statements 5252which will be compiled with GCC@. They go in a library function named 5253@code{__transfer_from_trampoline}. 5254 5255If you need to avoid executing the ordinary prologue code of a compiled 5256C function when you jump to the subroutine, you can do so by placing a 5257special label of your own in the assembler code. Use one @code{asm} 5258statement to generate an assembler label, and another to make the label 5259global. Then trampolines can use that label to jump directly to your 5260special assembler code. 5261@end defmac 5262 5263@node Library Calls 5264@section Implicit Calls to Library Routines 5265@cindex library subroutine names 5266@cindex @file{libgcc.a} 5267 5268@c prevent bad page break with this line 5269Here is an explanation of implicit calls to library routines. 5270 5271@defmac DECLARE_LIBRARY_RENAMES 5272This macro, if defined, should expand to a piece of C code that will get 5273expanded when compiling functions for libgcc.a. It can be used to 5274provide alternate names for GCC's internal library functions if there 5275are ABI-mandated names that the compiler should provide. 5276@end defmac 5277 5278@findex set_optab_libfunc 5279@findex init_one_libfunc 5280@deftypefn {Target Hook} void TARGET_INIT_LIBFUNCS (void) 5281This hook should declare additional library routines or rename 5282existing ones, using the functions @code{set_optab_libfunc} and 5283@code{init_one_libfunc} defined in @file{optabs.c}. 5284@code{init_optabs} calls this macro after initializing all the normal 5285library routines. 5286 5287The default is to do nothing. Most ports don't need to define this hook. 5288@end deftypefn 5289 5290@deftypevr {Target Hook} bool TARGET_LIBFUNC_GNU_PREFIX 5291If false (the default), internal library routines start with two 5292underscores. If set to true, these routines start with @code{__gnu_} 5293instead. E.g., @code{__muldi3} changes to @code{__gnu_muldi3}. This 5294currently only affects functions defined in @file{libgcc2.c}. If this 5295is set to true, the @file{tm.h} file must also 5296@code{#define LIBGCC2_GNU_PREFIX}. 5297@end deftypevr 5298 5299@defmac FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 5300This macro should return @code{true} if the library routine that 5301implements the floating point comparison operator @var{comparison} in 5302mode @var{mode} will return a boolean, and @var{false} if it will 5303return a tristate. 5304 5305GCC's own floating point libraries return tristates from the 5306comparison operators, so the default returns false always. Most ports 5307don't need to define this macro. 5308@end defmac 5309 5310@defmac TARGET_LIB_INT_CMP_BIASED 5311This macro should evaluate to @code{true} if the integer comparison 5312functions (like @code{__cmpdi2}) return 0 to indicate that the first 5313operand is smaller than the second, 1 to indicate that they are equal, 5314and 2 to indicate that the first operand is greater than the second. 5315If this macro evaluates to @code{false} the comparison functions return 5316@minus{}1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines 5317in @file{libgcc.a}, you do not need to define this macro. 5318@end defmac 5319 5320@cindex @code{EDOM}, implicit usage 5321@findex matherr 5322@defmac TARGET_EDOM 5323The value of @code{EDOM} on the target machine, as a C integer constant 5324expression. If you don't define this macro, GCC does not attempt to 5325deposit the value of @code{EDOM} into @code{errno} directly. Look in 5326@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 5327system. 5328 5329If you do not define @code{TARGET_EDOM}, then compiled code reports 5330domain errors by calling the library function and letting it report the 5331error. If mathematical functions on your system use @code{matherr} when 5332there is an error, then you should leave @code{TARGET_EDOM} undefined so 5333that @code{matherr} is used normally. 5334@end defmac 5335 5336@cindex @code{errno}, implicit usage 5337@defmac GEN_ERRNO_RTX 5338Define this macro as a C expression to create an rtl expression that 5339refers to the global ``variable'' @code{errno}. (On certain systems, 5340@code{errno} may not actually be a variable.) If you don't define this 5341macro, a reasonable default is used. 5342@end defmac 5343 5344@cindex C99 math functions, implicit usage 5345@defmac TARGET_C99_FUNCTIONS 5346When this macro is nonzero, GCC will implicitly optimize @code{sin} calls into 5347@code{sinf} and similarly for other functions defined by C99 standard. The 5348default is zero because a number of existing systems lack support for these 5349functions in their runtime so this macro needs to be redefined to one on 5350systems that do support the C99 runtime. 5351@end defmac 5352 5353@cindex sincos math function, implicit usage 5354@defmac TARGET_HAS_SINCOS 5355When this macro is nonzero, GCC will implicitly optimize calls to @code{sin} 5356and @code{cos} with the same argument to a call to @code{sincos}. The 5357default is zero. The target has to provide the following functions: 5358@smallexample 5359void sincos(double x, double *sin, double *cos); 5360void sincosf(float x, float *sin, float *cos); 5361void sincosl(long double x, long double *sin, long double *cos); 5362@end smallexample 5363@end defmac 5364 5365@defmac NEXT_OBJC_RUNTIME 5366Set this macro to 1 to use the "NeXT" Objective-C message sending conventions 5367by default. This calling convention involves passing the object, the selector 5368and the method arguments all at once to the method-lookup library function. 5369This is the usual setting when targeting Darwin/Mac OS X systems, which have 5370the NeXT runtime installed. 5371 5372If the macro is set to 0, the "GNU" Objective-C message sending convention 5373will be used by default. This convention passes just the object and the 5374selector to the method-lookup function, which returns a pointer to the method. 5375 5376In either case, it remains possible to select code-generation for the alternate 5377scheme, by means of compiler command line switches. 5378@end defmac 5379 5380@node Addressing Modes 5381@section Addressing Modes 5382@cindex addressing modes 5383 5384@c prevent bad page break with this line 5385This is about addressing modes. 5386 5387@defmac HAVE_PRE_INCREMENT 5388@defmacx HAVE_PRE_DECREMENT 5389@defmacx HAVE_POST_INCREMENT 5390@defmacx HAVE_POST_DECREMENT 5391A C expression that is nonzero if the machine supports pre-increment, 5392pre-decrement, post-increment, or post-decrement addressing respectively. 5393@end defmac 5394 5395@defmac HAVE_PRE_MODIFY_DISP 5396@defmacx HAVE_POST_MODIFY_DISP 5397A C expression that is nonzero if the machine supports pre- or 5398post-address side-effect generation involving constants other than 5399the size of the memory operand. 5400@end defmac 5401 5402@defmac HAVE_PRE_MODIFY_REG 5403@defmacx HAVE_POST_MODIFY_REG 5404A C expression that is nonzero if the machine supports pre- or 5405post-address side-effect generation involving a register displacement. 5406@end defmac 5407 5408@defmac CONSTANT_ADDRESS_P (@var{x}) 5409A C expression that is 1 if the RTX @var{x} is a constant which 5410is a valid address. On most machines the default definition of 5411@code{(CONSTANT_P (@var{x}) && GET_CODE (@var{x}) != CONST_DOUBLE)} 5412is acceptable, but a few machines are more restrictive as to which 5413constant addresses are supported. 5414@end defmac 5415 5416@defmac CONSTANT_P (@var{x}) 5417@code{CONSTANT_P}, which is defined by target-independent code, 5418accepts integer-values expressions whose values are not explicitly 5419known, such as @code{symbol_ref}, @code{label_ref}, and @code{high} 5420expressions and @code{const} arithmetic expressions, in addition to 5421@code{const_int} and @code{const_double} expressions. 5422@end defmac 5423 5424@defmac MAX_REGS_PER_ADDRESS 5425A number, the maximum number of registers that can appear in a valid 5426memory address. Note that it is up to you to specify a value equal to 5427the maximum number that @code{TARGET_LEGITIMATE_ADDRESS_P} would ever 5428accept. 5429@end defmac 5430 5431@deftypefn {Target Hook} bool TARGET_LEGITIMATE_ADDRESS_P (enum machine_mode @var{mode}, rtx @var{x}, bool @var{strict}) 5432A function that returns whether @var{x} (an RTX) is a legitimate memory 5433address on the target machine for a memory operand of mode @var{mode}. 5434 5435Legitimate addresses are defined in two variants: a strict variant and a 5436non-strict one. The @var{strict} parameter chooses which variant is 5437desired by the caller. 5438 5439The strict variant is used in the reload pass. It must be defined so 5440that any pseudo-register that has not been allocated a hard register is 5441considered a memory reference. This is because in contexts where some 5442kind of register is required, a pseudo-register with no hard register 5443must be rejected. For non-hard registers, the strict variant should look 5444up the @code{reg_renumber} array; it should then proceed using the hard 5445register number in the array, or treat the pseudo as a memory reference 5446if the array holds @code{-1}. 5447 5448The non-strict variant is used in other passes. It must be defined to 5449accept all pseudo-registers in every context where some kind of 5450register is required. 5451 5452Normally, constant addresses which are the sum of a @code{symbol_ref} 5453and an integer are stored inside a @code{const} RTX to mark them as 5454constant. Therefore, there is no need to recognize such sums 5455specifically as legitimate addresses. Normally you would simply 5456recognize any @code{const} as legitimate. 5457 5458Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 5459sums that are not marked with @code{const}. It assumes that a naked 5460@code{plus} indicates indexing. If so, then you @emph{must} reject such 5461naked constant sums as illegitimate addresses, so that none of them will 5462be given to @code{PRINT_OPERAND_ADDRESS}. 5463 5464@cindex @code{TARGET_ENCODE_SECTION_INFO} and address validation 5465On some machines, whether a symbolic address is legitimate depends on 5466the section that the address refers to. On these machines, define the 5467target hook @code{TARGET_ENCODE_SECTION_INFO} to store the information 5468into the @code{symbol_ref}, and then check for it here. When you see a 5469@code{const}, you will have to look inside it to find the 5470@code{symbol_ref} in order to determine the section. @xref{Assembler 5471Format}. 5472 5473@cindex @code{GO_IF_LEGITIMATE_ADDRESS} 5474Some ports are still using a deprecated legacy substitute for 5475this hook, the @code{GO_IF_LEGITIMATE_ADDRESS} macro. This macro 5476has this syntax: 5477 5478@example 5479#define GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 5480@end example 5481 5482@noindent 5483and should @code{goto @var{label}} if the address @var{x} is a valid 5484address on the target machine for a memory operand of mode @var{mode}. 5485 5486@findex REG_OK_STRICT 5487Compiler source files that want to use the strict variant of this 5488macro define the macro @code{REG_OK_STRICT}. You should use an 5489@code{#ifdef REG_OK_STRICT} conditional to define the strict variant in 5490that case and the non-strict variant otherwise. 5491 5492Using the hook is usually simpler because it limits the number of 5493files that are recompiled when changes are made. 5494@end deftypefn 5495 5496@defmac TARGET_MEM_CONSTRAINT 5497A single character to be used instead of the default @code{'m'} 5498character for general memory addresses. This defines the constraint 5499letter which matches the memory addresses accepted by 5500@code{TARGET_LEGITIMATE_ADDRESS_P}. Define this macro if you want to 5501support new address formats in your back end without changing the 5502semantics of the @code{'m'} constraint. This is necessary in order to 5503preserve functionality of inline assembly constructs using the 5504@code{'m'} constraint. 5505@end defmac 5506 5507@defmac FIND_BASE_TERM (@var{x}) 5508A C expression to determine the base term of address @var{x}, 5509or to provide a simplified version of @var{x} from which @file{alias.c} 5510can easily find the base term. This macro is used in only two places: 5511@code{find_base_value} and @code{find_base_term} in @file{alias.c}. 5512 5513It is always safe for this macro to not be defined. It exists so 5514that alias analysis can understand machine-dependent addresses. 5515 5516The typical use of this macro is to handle addresses containing 5517a label_ref or symbol_ref within an UNSPEC@. 5518@end defmac 5519 5520@deftypefn {Target Hook} rtx TARGET_LEGITIMIZE_ADDRESS (rtx @var{x}, rtx @var{oldx}, enum machine_mode @var{mode}) 5521This hook is given an invalid memory address @var{x} for an 5522operand of mode @var{mode} and should try to return a valid memory 5523address. 5524 5525@findex break_out_memory_refs 5526@var{x} will always be the result of a call to @code{break_out_memory_refs}, 5527and @var{oldx} will be the operand that was given to that function to produce 5528@var{x}. 5529 5530The code of the hook should not alter the substructure of 5531@var{x}. If it transforms @var{x} into a more legitimate form, it 5532should return the new @var{x}. 5533 5534It is not necessary for this hook to come up with a legitimate address. 5535The compiler has standard ways of doing so in all cases. In fact, it 5536is safe to omit this hook or make it return @var{x} if it cannot find 5537a valid way to legitimize the address. But often a machine-dependent 5538strategy can generate better code. 5539@end deftypefn 5540 5541@defmac LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 5542A C compound statement that attempts to replace @var{x}, which is an address 5543that needs reloading, with a valid memory address for an operand of mode 5544@var{mode}. @var{win} will be a C statement label elsewhere in the code. 5545It is not necessary to define this macro, but it might be useful for 5546performance reasons. 5547 5548For example, on the i386, it is sometimes possible to use a single 5549reload register instead of two by reloading a sum of two pseudo 5550registers into a register. On the other hand, for number of RISC 5551processors offsets are limited so that often an intermediate address 5552needs to be generated in order to address a stack slot. By defining 5553@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 5554generated for adjacent some stack slots can be made identical, and thus 5555be shared. 5556 5557@emph{Note}: This macro should be used with caution. It is necessary 5558to know something of how reload works in order to effectively use this, 5559and it is quite easy to produce macros that build in too much knowledge 5560of reload internals. 5561 5562@emph{Note}: This macro must be able to reload an address created by a 5563previous invocation of this macro. If it fails to handle such addresses 5564then the compiler may generate incorrect code or abort. 5565 5566@findex push_reload 5567The macro definition should use @code{push_reload} to indicate parts that 5568need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 5569suitable to be passed unaltered to @code{push_reload}. 5570 5571The code generated by this macro must not alter the substructure of 5572@var{x}. If it transforms @var{x} into a more legitimate form, it 5573should assign @var{x} (which will always be a C variable) a new value. 5574This also applies to parts that you change indirectly by calling 5575@code{push_reload}. 5576 5577@findex strict_memory_address_p 5578The macro definition may use @code{strict_memory_address_p} to test if 5579the address has become legitimate. 5580 5581@findex copy_rtx 5582If you want to change only a part of @var{x}, one standard way of doing 5583this is to use @code{copy_rtx}. Note, however, that it unshares only a 5584single level of rtl. Thus, if the part to be changed is not at the 5585top level, you'll need to replace first the top level. 5586It is not necessary for this macro to come up with a legitimate 5587address; but often a machine-dependent strategy can generate better code. 5588@end defmac 5589 5590@deftypefn {Target Hook} bool TARGET_MODE_DEPENDENT_ADDRESS_P (const_rtx @var{addr}) 5591This hook returns @code{true} if memory address @var{addr} can have 5592different meanings depending on the machine mode of the memory 5593reference it is used for or if the address is valid for some modes 5594but not others. 5595 5596Autoincrement and autodecrement addresses typically have mode-dependent 5597effects because the amount of the increment or decrement is the size 5598of the operand being addressed. Some machines have other mode-dependent 5599addresses. Many RISC machines have no mode-dependent addresses. 5600 5601You may assume that @var{addr} is a valid address for the machine. 5602 5603The default version of this hook returns @code{false}. 5604@end deftypefn 5605 5606@defmac GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 5607A C statement or compound statement with a conditional @code{goto 5608@var{label};} executed if memory address @var{x} (an RTX) can have 5609different meanings depending on the machine mode of the memory 5610reference it is used for or if the address is valid for some modes 5611but not others. 5612 5613Autoincrement and autodecrement addresses typically have mode-dependent 5614effects because the amount of the increment or decrement is the size 5615of the operand being addressed. Some machines have other mode-dependent 5616addresses. Many RISC machines have no mode-dependent addresses. 5617 5618You may assume that @var{addr} is a valid address for the machine. 5619 5620These are obsolete macros, replaced by the 5621@code{TARGET_MODE_DEPENDENT_ADDRESS_P} target hook. 5622@end defmac 5623 5624@deftypefn {Target Hook} bool TARGET_LEGITIMATE_CONSTANT_P (enum machine_mode @var{mode}, rtx @var{x}) 5625This hook returns true if @var{x} is a legitimate constant for a 5626@var{mode}-mode immediate operand on the target machine. You can assume that 5627@var{x} satisfies @code{CONSTANT_P}, so you need not check this. 5628 5629The default definition returns true. 5630@end deftypefn 5631 5632@deftypefn {Target Hook} rtx TARGET_DELEGITIMIZE_ADDRESS (rtx @var{x}) 5633This hook is used to undo the possibly obfuscating effects of the 5634@code{LEGITIMIZE_ADDRESS} and @code{LEGITIMIZE_RELOAD_ADDRESS} target 5635macros. Some backend implementations of these macros wrap symbol 5636references inside an @code{UNSPEC} rtx to represent PIC or similar 5637addressing modes. This target hook allows GCC's optimizers to understand 5638the semantics of these opaque @code{UNSPEC}s by converting them back 5639into their original form. 5640@end deftypefn 5641 5642@deftypefn {Target Hook} bool TARGET_CONST_NOT_OK_FOR_DEBUG_P (rtx @var{x}) 5643This hook should return true if @var{x} should not be emitted into 5644debug sections. 5645@end deftypefn 5646 5647@deftypefn {Target Hook} bool TARGET_CANNOT_FORCE_CONST_MEM (enum machine_mode @var{mode}, rtx @var{x}) 5648This hook should return true if @var{x} is of a form that cannot (or 5649should not) be spilled to the constant pool. @var{mode} is the mode 5650of @var{x}. 5651 5652The default version of this hook returns false. 5653 5654The primary reason to define this hook is to prevent reload from 5655deciding that a non-legitimate constant would be better reloaded 5656from the constant pool instead of spilling and reloading a register 5657holding the constant. This restriction is often true of addresses 5658of TLS symbols for various targets. 5659@end deftypefn 5660 5661@deftypefn {Target Hook} bool TARGET_USE_BLOCKS_FOR_CONSTANT_P (enum machine_mode @var{mode}, const_rtx @var{x}) 5662This hook should return true if pool entries for constant @var{x} can 5663be placed in an @code{object_block} structure. @var{mode} is the mode 5664of @var{x}. 5665 5666The default version returns false for all constants. 5667@end deftypefn 5668 5669@deftypefn {Target Hook} tree TARGET_BUILTIN_RECIPROCAL (unsigned @var{fn}, bool @var{md_fn}, bool @var{sqrt}) 5670This hook should return the DECL of a function that implements reciprocal of 5671the builtin function with builtin function code @var{fn}, or 5672@code{NULL_TREE} if such a function is not available. @var{md_fn} is true 5673when @var{fn} is a code of a machine-dependent builtin function. When 5674@var{sqrt} is true, additional optimizations that apply only to the reciprocal 5675of a square root function are performed, and only reciprocals of @code{sqrt} 5676function are valid. 5677@end deftypefn 5678 5679@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD (void) 5680This hook should return the DECL of a function @var{f} that given an 5681address @var{addr} as an argument returns a mask @var{m} that can be 5682used to extract from two vectors the relevant data that resides in 5683@var{addr} in case @var{addr} is not properly aligned. 5684 5685The autovectorizer, when vectorizing a load operation from an address 5686@var{addr} that may be unaligned, will generate two vector loads from 5687the two aligned addresses around @var{addr}. It then generates a 5688@code{REALIGN_LOAD} operation to extract the relevant data from the 5689two loaded vectors. The first two arguments to @code{REALIGN_LOAD}, 5690@var{v1} and @var{v2}, are the two vectors, each of size @var{VS}, and 5691the third argument, @var{OFF}, defines how the data will be extracted 5692from these two vectors: if @var{OFF} is 0, then the returned vector is 5693@var{v2}; otherwise, the returned vector is composed from the last 5694@var{VS}-@var{OFF} elements of @var{v1} concatenated to the first 5695@var{OFF} elements of @var{v2}. 5696 5697If this hook is defined, the autovectorizer will generate a call 5698to @var{f} (using the DECL tree that this hook returns) and will 5699use the return value of @var{f} as the argument @var{OFF} to 5700@code{REALIGN_LOAD}. Therefore, the mask @var{m} returned by @var{f} 5701should comply with the semantics expected by @code{REALIGN_LOAD} 5702described above. 5703If this hook is not defined, then @var{addr} will be used as 5704the argument @var{OFF} to @code{REALIGN_LOAD}, in which case the low 5705log2(@var{VS}) @minus{} 1 bits of @var{addr} will be considered. 5706@end deftypefn 5707 5708@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_EVEN (tree @var{x}) 5709This hook should return the DECL of a function @var{f} that implements 5710widening multiplication of the even elements of two input vectors of type @var{x}. 5711 5712If this hook is defined, the autovectorizer will use it along with the 5713@code{TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_ODD} target hook when vectorizing 5714widening multiplication in cases that the order of the results does not have to be 5715preserved (e.g.@: used only by a reduction computation). Otherwise, the 5716@code{widen_mult_hi/lo} idioms will be used. 5717@end deftypefn 5718 5719@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_ODD (tree @var{x}) 5720This hook should return the DECL of a function @var{f} that implements 5721widening multiplication of the odd elements of two input vectors of type @var{x}. 5722 5723If this hook is defined, the autovectorizer will use it along with the 5724@code{TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_EVEN} target hook when vectorizing 5725widening multiplication in cases that the order of the results does not have to be 5726preserved (e.g.@: used only by a reduction computation). Otherwise, the 5727@code{widen_mult_hi/lo} idioms will be used. 5728@end deftypefn 5729 5730@deftypefn {Target Hook} int TARGET_VECTORIZE_BUILTIN_VECTORIZATION_COST (enum vect_cost_for_stmt @var{type_of_cost}, tree @var{vectype}, int @var{misalign}) 5731Returns cost of different scalar or vector statements for vectorization cost model. 5732For vector memory operations the cost may depend on type (@var{vectype}) and 5733misalignment value (@var{misalign}). 5734@end deftypefn 5735 5736@deftypefn {Target Hook} bool TARGET_VECTORIZE_VECTOR_ALIGNMENT_REACHABLE (const_tree @var{type}, bool @var{is_packed}) 5737Return true if vector alignment is reachable (by peeling N iterations) for the given type. 5738@end deftypefn 5739 5740@deftypefn {Target Hook} bool TARGET_VECTORIZE_VEC_PERM_CONST_OK (enum @var{machine_mode}, const unsigned char *@var{sel}) 5741Return true if a vector created for @code{vec_perm_const} is valid. 5742@end deftypefn 5743 5744@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_CONVERSION (unsigned @var{code}, tree @var{dest_type}, tree @var{src_type}) 5745This hook should return the DECL of a function that implements conversion of the 5746input vector of type @var{src_type} to type @var{dest_type}. 5747The value of @var{code} is one of the enumerators in @code{enum tree_code} and 5748specifies how the conversion is to be applied 5749(truncation, rounding, etc.). 5750 5751If this hook is defined, the autovectorizer will use the 5752@code{TARGET_VECTORIZE_BUILTIN_CONVERSION} target hook when vectorizing 5753conversion. Otherwise, it will return @code{NULL_TREE}. 5754@end deftypefn 5755 5756@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_VECTORIZED_FUNCTION (tree @var{fndecl}, tree @var{vec_type_out}, tree @var{vec_type_in}) 5757This hook should return the decl of a function that implements the 5758vectorized variant of the builtin function with builtin function code 5759@var{code} or @code{NULL_TREE} if such a function is not available. 5760The value of @var{fndecl} is the builtin function declaration. The 5761return type of the vectorized function shall be of vector type 5762@var{vec_type_out} and the argument types should be @var{vec_type_in}. 5763@end deftypefn 5764 5765@deftypefn {Target Hook} bool TARGET_VECTORIZE_SUPPORT_VECTOR_MISALIGNMENT (enum machine_mode @var{mode}, const_tree @var{type}, int @var{misalignment}, bool @var{is_packed}) 5766This hook should return true if the target supports misaligned vector 5767store/load of a specific factor denoted in the @var{misalignment} 5768parameter. The vector store/load should be of machine mode @var{mode} and 5769the elements in the vectors should be of type @var{type}. @var{is_packed} 5770parameter is true if the memory access is defined in a packed struct. 5771@end deftypefn 5772 5773@deftypefn {Target Hook} {enum machine_mode} TARGET_VECTORIZE_PREFERRED_SIMD_MODE (enum machine_mode @var{mode}) 5774This hook should return the preferred mode for vectorizing scalar 5775mode @var{mode}. The default is 5776equal to @code{word_mode}, because the vectorizer can do some 5777transformations even in absence of specialized @acronym{SIMD} hardware. 5778@end deftypefn 5779 5780@deftypefn {Target Hook} {unsigned int} TARGET_VECTORIZE_AUTOVECTORIZE_VECTOR_SIZES (void) 5781This hook should return a mask of sizes that should be iterated over 5782after trying to autovectorize using the vector size derived from the 5783mode returned by @code{TARGET_VECTORIZE_PREFERRED_SIMD_MODE}. 5784The default is zero which means to not iterate over other vector sizes. 5785@end deftypefn 5786 5787@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_TM_LOAD (tree) 5788This hook should return the built-in decl needed to load a vector of the given type within a transaction. 5789@end deftypefn 5790 5791@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_TM_STORE (tree) 5792This hook should return the built-in decl needed to store a vector of the given type within a transaction. 5793@end deftypefn 5794 5795@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_GATHER (const_tree @var{mem_vectype}, const_tree @var{index_type}, int @var{scale}) 5796Target builtin that implements vector gather operation. @var{mem_vectype} 5797is the vector type of the load and @var{index_type} is scalar type of 5798the index, scaled by @var{scale}. 5799The default is @code{NULL_TREE} which means to not vectorize gather 5800loads. 5801@end deftypefn 5802 5803@node Anchored Addresses 5804@section Anchored Addresses 5805@cindex anchored addresses 5806@cindex @option{-fsection-anchors} 5807 5808GCC usually addresses every static object as a separate entity. 5809For example, if we have: 5810 5811@smallexample 5812static int a, b, c; 5813int foo (void) @{ return a + b + c; @} 5814@end smallexample 5815 5816the code for @code{foo} will usually calculate three separate symbolic 5817addresses: those of @code{a}, @code{b} and @code{c}. On some targets, 5818it would be better to calculate just one symbolic address and access 5819the three variables relative to it. The equivalent pseudocode would 5820be something like: 5821 5822@smallexample 5823int foo (void) 5824@{ 5825 register int *xr = &x; 5826 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; 5827@} 5828@end smallexample 5829 5830(which isn't valid C). We refer to shared addresses like @code{x} as 5831``section anchors''. Their use is controlled by @option{-fsection-anchors}. 5832 5833The hooks below describe the target properties that GCC needs to know 5834in order to make effective use of section anchors. It won't use 5835section anchors at all unless either @code{TARGET_MIN_ANCHOR_OFFSET} 5836or @code{TARGET_MAX_ANCHOR_OFFSET} is set to a nonzero value. 5837 5838@deftypevr {Target Hook} HOST_WIDE_INT TARGET_MIN_ANCHOR_OFFSET 5839The minimum offset that should be applied to a section anchor. 5840On most targets, it should be the smallest offset that can be 5841applied to a base register while still giving a legitimate address 5842for every mode. The default value is 0. 5843@end deftypevr 5844 5845@deftypevr {Target Hook} HOST_WIDE_INT TARGET_MAX_ANCHOR_OFFSET 5846Like @code{TARGET_MIN_ANCHOR_OFFSET}, but the maximum (inclusive) 5847offset that should be applied to section anchors. The default 5848value is 0. 5849@end deftypevr 5850 5851@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_ANCHOR (rtx @var{x}) 5852Write the assembly code to define section anchor @var{x}, which is a 5853@code{SYMBOL_REF} for which @samp{SYMBOL_REF_ANCHOR_P (@var{x})} is true. 5854The hook is called with the assembly output position set to the beginning 5855of @code{SYMBOL_REF_BLOCK (@var{x})}. 5856 5857If @code{ASM_OUTPUT_DEF} is available, the hook's default definition uses 5858it to define the symbol as @samp{. + SYMBOL_REF_BLOCK_OFFSET (@var{x})}. 5859If @code{ASM_OUTPUT_DEF} is not available, the hook's default definition 5860is @code{NULL}, which disables the use of section anchors altogether. 5861@end deftypefn 5862 5863@deftypefn {Target Hook} bool TARGET_USE_ANCHORS_FOR_SYMBOL_P (const_rtx @var{x}) 5864Return true if GCC should attempt to use anchors to access @code{SYMBOL_REF} 5865@var{x}. You can assume @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})} and 5866@samp{!SYMBOL_REF_ANCHOR_P (@var{x})}. 5867 5868The default version is correct for most targets, but you might need to 5869intercept this hook to handle things like target-specific attributes 5870or target-specific sections. 5871@end deftypefn 5872 5873@node Condition Code 5874@section Condition Code Status 5875@cindex condition code status 5876 5877The macros in this section can be split in two families, according to the 5878two ways of representing condition codes in GCC. 5879 5880The first representation is the so called @code{(cc0)} representation 5881(@pxref{Jump Patterns}), where all instructions can have an implicit 5882clobber of the condition codes. The second is the condition code 5883register representation, which provides better schedulability for 5884architectures that do have a condition code register, but on which 5885most instructions do not affect it. The latter category includes 5886most RISC machines. 5887 5888The implicit clobbering poses a strong restriction on the placement of 5889the definition and use of the condition code, which need to be in adjacent 5890insns for machines using @code{(cc0)}. This can prevent important 5891optimizations on some machines. For example, on the IBM RS/6000, there 5892is a delay for taken branches unless the condition code register is set 5893three instructions earlier than the conditional branch. The instruction 5894scheduler cannot perform this optimization if it is not permitted to 5895separate the definition and use of the condition code register. 5896 5897For this reason, it is possible and suggested to use a register to 5898represent the condition code for new ports. If there is a specific 5899condition code register in the machine, use a hard register. If the 5900condition code or comparison result can be placed in any general register, 5901or if there are multiple condition registers, use a pseudo register. 5902Registers used to store the condition code value will usually have a mode 5903that is in class @code{MODE_CC}. 5904 5905Alternatively, you can use @code{BImode} if the comparison operator is 5906specified already in the compare instruction. In this case, you are not 5907interested in most macros in this section. 5908 5909@menu 5910* CC0 Condition Codes:: Old style representation of condition codes. 5911* MODE_CC Condition Codes:: Modern representation of condition codes. 5912* Cond Exec Macros:: Macros to control conditional execution. 5913@end menu 5914 5915@node CC0 Condition Codes 5916@subsection Representation of condition codes using @code{(cc0)} 5917@findex cc0 5918 5919@findex cc_status 5920The file @file{conditions.h} defines a variable @code{cc_status} to 5921describe how the condition code was computed (in case the interpretation of 5922the condition code depends on the instruction that it was set by). This 5923variable contains the RTL expressions on which the condition code is 5924currently based, and several standard flags. 5925 5926Sometimes additional machine-specific flags must be defined in the machine 5927description header file. It can also add additional machine-specific 5928information by defining @code{CC_STATUS_MDEP}. 5929 5930@defmac CC_STATUS_MDEP 5931C code for a data type which is used for declaring the @code{mdep} 5932component of @code{cc_status}. It defaults to @code{int}. 5933 5934This macro is not used on machines that do not use @code{cc0}. 5935@end defmac 5936 5937@defmac CC_STATUS_MDEP_INIT 5938A C expression to initialize the @code{mdep} field to ``empty''. 5939The default definition does nothing, since most machines don't use 5940the field anyway. If you want to use the field, you should probably 5941define this macro to initialize it. 5942 5943This macro is not used on machines that do not use @code{cc0}. 5944@end defmac 5945 5946@defmac NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 5947A C compound statement to set the components of @code{cc_status} 5948appropriately for an insn @var{insn} whose body is @var{exp}. It is 5949this macro's responsibility to recognize insns that set the condition 5950code as a byproduct of other activity as well as those that explicitly 5951set @code{(cc0)}. 5952 5953This macro is not used on machines that do not use @code{cc0}. 5954 5955If there are insns that do not set the condition code but do alter 5956other machine registers, this macro must check to see whether they 5957invalidate the expressions that the condition code is recorded as 5958reflecting. For example, on the 68000, insns that store in address 5959registers do not set the condition code, which means that usually 5960@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 5961insns. But suppose that the previous insn set the condition code 5962based on location @samp{a4@@(102)} and the current insn stores a new 5963value in @samp{a4}. Although the condition code is not changed by 5964this, it will no longer be true that it reflects the contents of 5965@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 5966@code{cc_status} in this case to say that nothing is known about the 5967condition code value. 5968 5969The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 5970with the results of peephole optimization: insns whose patterns are 5971@code{parallel} RTXs containing various @code{reg}, @code{mem} or 5972constants which are just the operands. The RTL structure of these 5973insns is not sufficient to indicate what the insns actually do. What 5974@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 5975@code{CC_STATUS_INIT}. 5976 5977A possible definition of @code{NOTICE_UPDATE_CC} is to call a function 5978that looks at an attribute (@pxref{Insn Attributes}) named, for example, 5979@samp{cc}. This avoids having detailed information about patterns in 5980two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 5981@end defmac 5982 5983@node MODE_CC Condition Codes 5984@subsection Representation of condition codes using registers 5985@findex CCmode 5986@findex MODE_CC 5987 5988@defmac SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 5989On many machines, the condition code may be produced by other instructions 5990than compares, for example the branch can use directly the condition 5991code set by a subtract instruction. However, on some machines 5992when the condition code is set this way some bits (such as the overflow 5993bit) are not set in the same way as a test instruction, so that a different 5994branch instruction must be used for some conditional branches. When 5995this happens, use the machine mode of the condition code register to 5996record different formats of the condition code register. Modes can 5997also be used to record which compare instruction (e.g. a signed or an 5998unsigned comparison) produced the condition codes. 5999 6000If other modes than @code{CCmode} are required, add them to 6001@file{@var{machine}-modes.def} and define @code{SELECT_CC_MODE} to choose 6002a mode given an operand of a compare. This is needed because the modes 6003have to be chosen not only during RTL generation but also, for example, 6004by instruction combination. The result of @code{SELECT_CC_MODE} should 6005be consistent with the mode used in the patterns; for example to support 6006the case of the add on the SPARC discussed above, we have the pattern 6007 6008@smallexample 6009(define_insn "" 6010 [(set (reg:CC_NOOV 0) 6011 (compare:CC_NOOV 6012 (plus:SI (match_operand:SI 0 "register_operand" "%r") 6013 (match_operand:SI 1 "arith_operand" "rI")) 6014 (const_int 0)))] 6015 "" 6016 "@dots{}") 6017@end smallexample 6018 6019@noindent 6020together with a @code{SELECT_CC_MODE} that returns @code{CC_NOOVmode} 6021for comparisons whose argument is a @code{plus}: 6022 6023@smallexample 6024#define SELECT_CC_MODE(OP,X,Y) \ 6025 (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 6026 ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 6027 : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 6028 || GET_CODE (X) == NEG) \ 6029 ? CC_NOOVmode : CCmode)) 6030@end smallexample 6031 6032Another reason to use modes is to retain information on which operands 6033were used by the comparison; see @code{REVERSIBLE_CC_MODE} later in 6034this section. 6035 6036You should define this macro if and only if you define extra CC modes 6037in @file{@var{machine}-modes.def}. 6038@end defmac 6039 6040@defmac CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 6041On some machines not all possible comparisons are defined, but you can 6042convert an invalid comparison into a valid one. For example, the Alpha 6043does not have a @code{GT} comparison, but you can use an @code{LT} 6044comparison instead and swap the order of the operands. 6045 6046On such machines, define this macro to be a C statement to do any 6047required conversions. @var{code} is the initial comparison code 6048and @var{op0} and @var{op1} are the left and right operands of the 6049comparison, respectively. You should modify @var{code}, @var{op0}, and 6050@var{op1} as required. 6051 6052GCC will not assume that the comparison resulting from this macro is 6053valid but will see if the resulting insn matches a pattern in the 6054@file{md} file. 6055 6056You need not define this macro if it would never change the comparison 6057code or operands. 6058@end defmac 6059 6060@defmac REVERSIBLE_CC_MODE (@var{mode}) 6061A C expression whose value is one if it is always safe to reverse a 6062comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 6063can ever return @var{mode} for a floating-point inequality comparison, 6064then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 6065 6066You need not define this macro if it would always returns zero or if the 6067floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 6068For example, here is the definition used on the SPARC, where floating-point 6069inequality comparisons are always given @code{CCFPEmode}: 6070 6071@smallexample 6072#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 6073@end smallexample 6074@end defmac 6075 6076@defmac REVERSE_CONDITION (@var{code}, @var{mode}) 6077A C expression whose value is reversed condition code of the @var{code} for 6078comparison done in CC_MODE @var{mode}. The macro is used only in case 6079@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 6080machine has some non-standard way how to reverse certain conditionals. For 6081instance in case all floating point conditions are non-trapping, compiler may 6082freely convert unordered compares to ordered one. Then definition may look 6083like: 6084 6085@smallexample 6086#define REVERSE_CONDITION(CODE, MODE) \ 6087 ((MODE) != CCFPmode ? reverse_condition (CODE) \ 6088 : reverse_condition_maybe_unordered (CODE)) 6089@end smallexample 6090@end defmac 6091 6092@deftypefn {Target Hook} bool TARGET_FIXED_CONDITION_CODE_REGS (unsigned int *@var{p1}, unsigned int *@var{p2}) 6093On targets which do not use @code{(cc0)}, and which use a hard 6094register rather than a pseudo-register to hold condition codes, the 6095regular CSE passes are often not able to identify cases in which the 6096hard register is set to a common value. Use this hook to enable a 6097small pass which optimizes such cases. This hook should return true 6098to enable this pass, and it should set the integers to which its 6099arguments point to the hard register numbers used for condition codes. 6100When there is only one such register, as is true on most systems, the 6101integer pointed to by @var{p2} should be set to 6102@code{INVALID_REGNUM}. 6103 6104The default version of this hook returns false. 6105@end deftypefn 6106 6107@deftypefn {Target Hook} {enum machine_mode} TARGET_CC_MODES_COMPATIBLE (enum machine_mode @var{m1}, enum machine_mode @var{m2}) 6108On targets which use multiple condition code modes in class 6109@code{MODE_CC}, it is sometimes the case that a comparison can be 6110validly done in more than one mode. On such a system, define this 6111target hook to take two mode arguments and to return a mode in which 6112both comparisons may be validly done. If there is no such mode, 6113return @code{VOIDmode}. 6114 6115The default version of this hook checks whether the modes are the 6116same. If they are, it returns that mode. If they are different, it 6117returns @code{VOIDmode}. 6118@end deftypefn 6119 6120@node Cond Exec Macros 6121@subsection Macros to control conditional execution 6122@findex conditional execution 6123@findex predication 6124 6125There is one macro that may need to be defined for targets 6126supporting conditional execution, independent of how they 6127represent conditional branches. 6128 6129@defmac REVERSE_CONDEXEC_PREDICATES_P (@var{op1}, @var{op2}) 6130A C expression that returns true if the conditional execution predicate 6131@var{op1}, a comparison operation, is the inverse of @var{op2} and vice 6132versa. Define this to return 0 if the target has conditional execution 6133predicates that cannot be reversed safely. There is no need to validate 6134that the arguments of op1 and op2 are the same, this is done separately. 6135If no expansion is specified, this macro is defined as follows: 6136 6137@smallexample 6138#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 6139 (GET_CODE ((x)) == reversed_comparison_code ((y), NULL)) 6140@end smallexample 6141@end defmac 6142 6143@node Costs 6144@section Describing Relative Costs of Operations 6145@cindex costs of instructions 6146@cindex relative costs 6147@cindex speed of instructions 6148 6149These macros let you describe the relative speed of various operations 6150on the target machine. 6151 6152@defmac REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 6153A C expression for the cost of moving data of mode @var{mode} from a 6154register in class @var{from} to one in class @var{to}. The classes are 6155expressed using the enumeration values such as @code{GENERAL_REGS}. A 6156value of 2 is the default; other values are interpreted relative to 6157that. 6158 6159It is not required that the cost always equal 2 when @var{from} is the 6160same as @var{to}; on some machines it is expensive to move between 6161registers if they are not general registers. 6162 6163If reload sees an insn consisting of a single @code{set} between two 6164hard registers, and if @code{REGISTER_MOVE_COST} applied to their 6165classes returns a value of 2, reload does not check to ensure that the 6166constraints of the insn are met. Setting a cost of other than 2 will 6167allow reload to verify that the constraints are met. You should do this 6168if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 6169 6170These macros are obsolete, new ports should use the target hook 6171@code{TARGET_REGISTER_MOVE_COST} instead. 6172@end defmac 6173 6174@deftypefn {Target Hook} int TARGET_REGISTER_MOVE_COST (enum machine_mode @var{mode}, reg_class_t @var{from}, reg_class_t @var{to}) 6175This target hook should return the cost of moving data of mode @var{mode} 6176from a register in class @var{from} to one in class @var{to}. The classes 6177are expressed using the enumeration values such as @code{GENERAL_REGS}. 6178A value of 2 is the default; other values are interpreted relative to 6179that. 6180 6181It is not required that the cost always equal 2 when @var{from} is the 6182same as @var{to}; on some machines it is expensive to move between 6183registers if they are not general registers. 6184 6185If reload sees an insn consisting of a single @code{set} between two 6186hard registers, and if @code{TARGET_REGISTER_MOVE_COST} applied to their 6187classes returns a value of 2, reload does not check to ensure that the 6188constraints of the insn are met. Setting a cost of other than 2 will 6189allow reload to verify that the constraints are met. You should do this 6190if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 6191 6192The default version of this function returns 2. 6193@end deftypefn 6194 6195@defmac MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 6196A C expression for the cost of moving data of mode @var{mode} between a 6197register of class @var{class} and memory; @var{in} is zero if the value 6198is to be written to memory, nonzero if it is to be read in. This cost 6199is relative to those in @code{REGISTER_MOVE_COST}. If moving between 6200registers and memory is more expensive than between two registers, you 6201should define this macro to express the relative cost. 6202 6203If you do not define this macro, GCC uses a default cost of 4 plus 6204the cost of copying via a secondary reload register, if one is 6205needed. If your machine requires a secondary reload register to copy 6206between memory and a register of @var{class} but the reload mechanism is 6207more complex than copying via an intermediate, define this macro to 6208reflect the actual cost of the move. 6209 6210GCC defines the function @code{memory_move_secondary_cost} if 6211secondary reloads are needed. It computes the costs due to copying via 6212a secondary register. If your machine copies from memory using a 6213secondary register in the conventional way but the default base value of 62144 is not correct for your machine, define this macro to add some other 6215value to the result of that function. The arguments to that function 6216are the same as to this macro. 6217 6218These macros are obsolete, new ports should use the target hook 6219@code{TARGET_MEMORY_MOVE_COST} instead. 6220@end defmac 6221 6222@deftypefn {Target Hook} int TARGET_MEMORY_MOVE_COST (enum machine_mode @var{mode}, reg_class_t @var{rclass}, bool @var{in}) 6223This target hook should return the cost of moving data of mode @var{mode} 6224between a register of class @var{rclass} and memory; @var{in} is @code{false} 6225if the value is to be written to memory, @code{true} if it is to be read in. 6226This cost is relative to those in @code{TARGET_REGISTER_MOVE_COST}. 6227If moving between registers and memory is more expensive than between two 6228registers, you should add this target hook to express the relative cost. 6229 6230If you do not add this target hook, GCC uses a default cost of 4 plus 6231the cost of copying via a secondary reload register, if one is 6232needed. If your machine requires a secondary reload register to copy 6233between memory and a register of @var{rclass} but the reload mechanism is 6234more complex than copying via an intermediate, use this target hook to 6235reflect the actual cost of the move. 6236 6237GCC defines the function @code{memory_move_secondary_cost} if 6238secondary reloads are needed. It computes the costs due to copying via 6239a secondary register. If your machine copies from memory using a 6240secondary register in the conventional way but the default base value of 62414 is not correct for your machine, use this target hook to add some other 6242value to the result of that function. The arguments to that function 6243are the same as to this target hook. 6244@end deftypefn 6245 6246@defmac BRANCH_COST (@var{speed_p}, @var{predictable_p}) 6247A C expression for the cost of a branch instruction. A value of 1 is 6248the default; other values are interpreted relative to that. Parameter 6249@var{speed_p} is true when the branch in question should be optimized 6250for speed. When it is false, @code{BRANCH_COST} should return a value 6251optimal for code size rather than performance. @var{predictable_p} is 6252true for well-predicted branches. On many architectures the 6253@code{BRANCH_COST} can be reduced then. 6254@end defmac 6255 6256Here are additional macros which do not specify precise relative costs, 6257but only that certain actions are more expensive than GCC would 6258ordinarily expect. 6259 6260@defmac SLOW_BYTE_ACCESS 6261Define this macro as a C expression which is nonzero if accessing less 6262than a word of memory (i.e.@: a @code{char} or a @code{short}) is no 6263faster than accessing a word of memory, i.e., if such access 6264require more than one instruction or if there is no difference in cost 6265between byte and (aligned) word loads. 6266 6267When this macro is not defined, the compiler will access a field by 6268finding the smallest containing object; when it is defined, a fullword 6269load will be used if alignment permits. Unless bytes accesses are 6270faster than word accesses, using word accesses is preferable since it 6271may eliminate subsequent memory access if subsequent accesses occur to 6272other fields in the same word of the structure, but to different bytes. 6273@end defmac 6274 6275@defmac SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 6276Define this macro to be the value 1 if memory accesses described by the 6277@var{mode} and @var{alignment} parameters have a cost many times greater 6278than aligned accesses, for example if they are emulated in a trap 6279handler. 6280 6281When this macro is nonzero, the compiler will act as if 6282@code{STRICT_ALIGNMENT} were nonzero when generating code for block 6283moves. This can cause significantly more instructions to be produced. 6284Therefore, do not set this macro nonzero if unaligned accesses only add a 6285cycle or two to the time for a memory access. 6286 6287If the value of this macro is always zero, it need not be defined. If 6288this macro is defined, it should produce a nonzero value when 6289@code{STRICT_ALIGNMENT} is nonzero. 6290@end defmac 6291 6292@defmac MOVE_RATIO (@var{speed}) 6293The threshold of number of scalar memory-to-memory move insns, @emph{below} 6294which a sequence of insns should be generated instead of a 6295string move insn or a library call. Increasing the value will always 6296make code faster, but eventually incurs high cost in increased code size. 6297 6298Note that on machines where the corresponding move insn is a 6299@code{define_expand} that emits a sequence of insns, this macro counts 6300the number of such sequences. 6301 6302The parameter @var{speed} is true if the code is currently being 6303optimized for speed rather than size. 6304 6305If you don't define this, a reasonable default is used. 6306@end defmac 6307 6308@defmac MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 6309A C expression used to determine whether @code{move_by_pieces} will be used to 6310copy a chunk of memory, or whether some other block move mechanism 6311will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6312than @code{MOVE_RATIO}. 6313@end defmac 6314 6315@defmac MOVE_MAX_PIECES 6316A C expression used by @code{move_by_pieces} to determine the largest unit 6317a load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 6318@end defmac 6319 6320@defmac CLEAR_RATIO (@var{speed}) 6321The threshold of number of scalar move insns, @emph{below} which a sequence 6322of insns should be generated to clear memory instead of a string clear insn 6323or a library call. Increasing the value will always make code faster, but 6324eventually incurs high cost in increased code size. 6325 6326The parameter @var{speed} is true if the code is currently being 6327optimized for speed rather than size. 6328 6329If you don't define this, a reasonable default is used. 6330@end defmac 6331 6332@defmac CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) 6333A C expression used to determine whether @code{clear_by_pieces} will be used 6334to clear a chunk of memory, or whether some other block clear mechanism 6335will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6336than @code{CLEAR_RATIO}. 6337@end defmac 6338 6339@defmac SET_RATIO (@var{speed}) 6340The threshold of number of scalar move insns, @emph{below} which a sequence 6341of insns should be generated to set memory to a constant value, instead of 6342a block set insn or a library call. 6343Increasing the value will always make code faster, but 6344eventually incurs high cost in increased code size. 6345 6346The parameter @var{speed} is true if the code is currently being 6347optimized for speed rather than size. 6348 6349If you don't define this, it defaults to the value of @code{MOVE_RATIO}. 6350@end defmac 6351 6352@defmac SET_BY_PIECES_P (@var{size}, @var{alignment}) 6353A C expression used to determine whether @code{store_by_pieces} will be 6354used to set a chunk of memory to a constant value, or whether some 6355other mechanism will be used. Used by @code{__builtin_memset} when 6356storing values other than constant zero. 6357Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6358than @code{SET_RATIO}. 6359@end defmac 6360 6361@defmac STORE_BY_PIECES_P (@var{size}, @var{alignment}) 6362A C expression used to determine whether @code{store_by_pieces} will be 6363used to set a chunk of memory to a constant string value, or whether some 6364other mechanism will be used. Used by @code{__builtin_strcpy} when 6365called with a constant source string. 6366Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6367than @code{MOVE_RATIO}. 6368@end defmac 6369 6370@defmac USE_LOAD_POST_INCREMENT (@var{mode}) 6371A C expression used to determine whether a load postincrement is a good 6372thing to use for a given mode. Defaults to the value of 6373@code{HAVE_POST_INCREMENT}. 6374@end defmac 6375 6376@defmac USE_LOAD_POST_DECREMENT (@var{mode}) 6377A C expression used to determine whether a load postdecrement is a good 6378thing to use for a given mode. Defaults to the value of 6379@code{HAVE_POST_DECREMENT}. 6380@end defmac 6381 6382@defmac USE_LOAD_PRE_INCREMENT (@var{mode}) 6383A C expression used to determine whether a load preincrement is a good 6384thing to use for a given mode. Defaults to the value of 6385@code{HAVE_PRE_INCREMENT}. 6386@end defmac 6387 6388@defmac USE_LOAD_PRE_DECREMENT (@var{mode}) 6389A C expression used to determine whether a load predecrement is a good 6390thing to use for a given mode. Defaults to the value of 6391@code{HAVE_PRE_DECREMENT}. 6392@end defmac 6393 6394@defmac USE_STORE_POST_INCREMENT (@var{mode}) 6395A C expression used to determine whether a store postincrement is a good 6396thing to use for a given mode. Defaults to the value of 6397@code{HAVE_POST_INCREMENT}. 6398@end defmac 6399 6400@defmac USE_STORE_POST_DECREMENT (@var{mode}) 6401A C expression used to determine whether a store postdecrement is a good 6402thing to use for a given mode. Defaults to the value of 6403@code{HAVE_POST_DECREMENT}. 6404@end defmac 6405 6406@defmac USE_STORE_PRE_INCREMENT (@var{mode}) 6407This macro is used to determine whether a store preincrement is a good 6408thing to use for a given mode. Defaults to the value of 6409@code{HAVE_PRE_INCREMENT}. 6410@end defmac 6411 6412@defmac USE_STORE_PRE_DECREMENT (@var{mode}) 6413This macro is used to determine whether a store predecrement is a good 6414thing to use for a given mode. Defaults to the value of 6415@code{HAVE_PRE_DECREMENT}. 6416@end defmac 6417 6418@defmac NO_FUNCTION_CSE 6419Define this macro if it is as good or better to call a constant 6420function address than to call an address kept in a register. 6421@end defmac 6422 6423@defmac RANGE_TEST_NON_SHORT_CIRCUIT 6424Define this macro if a non-short-circuit operation produced by 6425@samp{fold_range_test ()} is optimal. This macro defaults to true if 6426@code{BRANCH_COST} is greater than or equal to the value 2. 6427@end defmac 6428 6429@deftypefn {Target Hook} bool TARGET_RTX_COSTS (rtx @var{x}, int @var{code}, int @var{outer_code}, int @var{opno}, int *@var{total}, bool @var{speed}) 6430This target hook describes the relative costs of RTL expressions. 6431 6432The cost may depend on the precise form of the expression, which is 6433available for examination in @var{x}, and the fact that @var{x} appears 6434as operand @var{opno} of an expression with rtx code @var{outer_code}. 6435That is, the hook can assume that there is some rtx @var{y} such 6436that @samp{GET_CODE (@var{y}) == @var{outer_code}} and such that 6437either (a) @samp{XEXP (@var{y}, @var{opno}) == @var{x}} or 6438(b) @samp{XVEC (@var{y}, @var{opno})} contains @var{x}. 6439 6440@var{code} is @var{x}'s expression code---redundant, since it can be 6441obtained with @code{GET_CODE (@var{x})}. 6442 6443In implementing this hook, you can use the construct 6444@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 6445instructions. 6446 6447On entry to the hook, @code{*@var{total}} contains a default estimate 6448for the cost of the expression. The hook should modify this value as 6449necessary. Traditionally, the default costs are @code{COSTS_N_INSNS (5)} 6450for multiplications, @code{COSTS_N_INSNS (7)} for division and modulus 6451operations, and @code{COSTS_N_INSNS (1)} for all other operations. 6452 6453When optimizing for code size, i.e.@: when @code{speed} is 6454false, this target hook should be used to estimate the relative 6455size cost of an expression, again relative to @code{COSTS_N_INSNS}. 6456 6457The hook returns true when all subexpressions of @var{x} have been 6458processed, and false when @code{rtx_cost} should recurse. 6459@end deftypefn 6460 6461@deftypefn {Target Hook} int TARGET_ADDRESS_COST (rtx @var{address}, bool @var{speed}) 6462This hook computes the cost of an addressing mode that contains 6463@var{address}. If not defined, the cost is computed from 6464the @var{address} expression and the @code{TARGET_RTX_COST} hook. 6465 6466For most CISC machines, the default cost is a good approximation of the 6467true cost of the addressing mode. However, on RISC machines, all 6468instructions normally have the same length and execution time. Hence 6469all addresses will have equal costs. 6470 6471In cases where more than one form of an address is known, the form with 6472the lowest cost will be used. If multiple forms have the same, lowest, 6473cost, the one that is the most complex will be used. 6474 6475For example, suppose an address that is equal to the sum of a register 6476and a constant is used twice in the same basic block. When this macro 6477is not defined, the address will be computed in a register and memory 6478references will be indirect through that register. On machines where 6479the cost of the addressing mode containing the sum is no higher than 6480that of a simple indirect reference, this will produce an additional 6481instruction and possibly require an additional register. Proper 6482specification of this macro eliminates this overhead for such machines. 6483 6484This hook is never called with an invalid address. 6485 6486On machines where an address involving more than one register is as 6487cheap as an address computation involving only one register, defining 6488@code{TARGET_ADDRESS_COST} to reflect this can cause two registers to 6489be live over a region of code where only one would have been if 6490@code{TARGET_ADDRESS_COST} were not defined in that manner. This effect 6491should be considered in the definition of this macro. Equivalent costs 6492should probably only be given to addresses with different numbers of 6493registers on machines with lots of registers. 6494@end deftypefn 6495 6496@node Scheduling 6497@section Adjusting the Instruction Scheduler 6498 6499The instruction scheduler may need a fair amount of machine-specific 6500adjustment in order to produce good code. GCC provides several target 6501hooks for this purpose. It is usually enough to define just a few of 6502them: try the first ones in this list first. 6503 6504@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 6505This hook returns the maximum number of instructions that can ever 6506issue at the same time on the target machine. The default is one. 6507Although the insn scheduler can define itself the possibility of issue 6508an insn on the same cycle, the value can serve as an additional 6509constraint to issue insns on the same simulated processor cycle (see 6510hooks @samp{TARGET_SCHED_REORDER} and @samp{TARGET_SCHED_REORDER2}). 6511This value must be constant over the entire compilation. If you need 6512it to vary depending on what the instructions are, you must use 6513@samp{TARGET_SCHED_VARIABLE_ISSUE}. 6514@end deftypefn 6515 6516@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 6517This hook is executed by the scheduler after it has scheduled an insn 6518from the ready list. It should return the number of insns which can 6519still be issued in the current cycle. The default is 6520@samp{@w{@var{more} - 1}} for insns other than @code{CLOBBER} and 6521@code{USE}, which normally are not counted against the issue rate. 6522You should define this hook if some insns take more machine resources 6523than others, so that fewer insns can follow them in the same cycle. 6524@var{file} is either a null pointer, or a stdio stream to write any 6525debug output to. @var{verbose} is the verbose level provided by 6526@option{-fsched-verbose-@var{n}}. @var{insn} is the instruction that 6527was scheduled. 6528@end deftypefn 6529 6530@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 6531This function corrects the value of @var{cost} based on the 6532relationship between @var{insn} and @var{dep_insn} through the 6533dependence @var{link}. It should return the new value. The default 6534is to make no adjustment to @var{cost}. This can be used for example 6535to specify to the scheduler using the traditional pipeline description 6536that an output- or anti-dependence does not incur the same cost as a 6537data-dependence. If the scheduler using the automaton based pipeline 6538description, the cost of anti-dependence is zero and the cost of 6539output-dependence is maximum of one and the difference of latency 6540times of the first and the second insns. If these values are not 6541acceptable, you could use the hook to modify them too. See also 6542@pxref{Processor pipeline description}. 6543@end deftypefn 6544 6545@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 6546This hook adjusts the integer scheduling priority @var{priority} of 6547@var{insn}. It should return the new priority. Increase the priority to 6548execute @var{insn} earlier, reduce the priority to execute @var{insn} 6549later. Do not define this hook if you do not need to adjust the 6550scheduling priorities of insns. 6551@end deftypefn 6552 6553@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 6554This hook is executed by the scheduler after it has scheduled the ready 6555list, to allow the machine description to reorder it (for example to 6556combine two small instructions together on @samp{VLIW} machines). 6557@var{file} is either a null pointer, or a stdio stream to write any 6558debug output to. @var{verbose} is the verbose level provided by 6559@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 6560list of instructions that are ready to be scheduled. @var{n_readyp} is 6561a pointer to the number of elements in the ready list. The scheduler 6562reads the ready list in reverse order, starting with 6563@var{ready}[@var{*n_readyp} @minus{} 1] and going to @var{ready}[0]. @var{clock} 6564is the timer tick of the scheduler. You may modify the ready list and 6565the number of ready insns. The return value is the number of insns that 6566can issue this cycle; normally this is just @code{issue_rate}. See also 6567@samp{TARGET_SCHED_REORDER2}. 6568@end deftypefn 6569 6570@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 6571Like @samp{TARGET_SCHED_REORDER}, but called at a different time. That 6572function is called whenever the scheduler starts a new cycle. This one 6573is called once per iteration over a cycle, immediately after 6574@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 6575return the number of insns to be scheduled in the same cycle. Defining 6576this hook can be useful if there are frequent situations where 6577scheduling one insn causes other insns to become ready in the same 6578cycle. These other insns can then be taken into account properly. 6579@end deftypefn 6580 6581@deftypefn {Target Hook} void TARGET_SCHED_DEPENDENCIES_EVALUATION_HOOK (rtx @var{head}, rtx @var{tail}) 6582This hook is called after evaluation forward dependencies of insns in 6583chain given by two parameter values (@var{head} and @var{tail} 6584correspondingly) but before insns scheduling of the insn chain. For 6585example, it can be used for better insn classification if it requires 6586analysis of dependencies. This hook can use backward and forward 6587dependencies of the insn scheduler because they are already 6588calculated. 6589@end deftypefn 6590 6591@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 6592This hook is executed by the scheduler at the beginning of each block of 6593instructions that are to be scheduled. @var{file} is either a null 6594pointer, or a stdio stream to write any debug output to. @var{verbose} 6595is the verbose level provided by @option{-fsched-verbose-@var{n}}. 6596@var{max_ready} is the maximum number of insns in the current scheduling 6597region that can be live at the same time. This can be used to allocate 6598scratch space if it is needed, e.g.@: by @samp{TARGET_SCHED_REORDER}. 6599@end deftypefn 6600 6601@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 6602This hook is executed by the scheduler at the end of each block of 6603instructions that are to be scheduled. It can be used to perform 6604cleanup of any actions done by the other scheduling hooks. @var{file} 6605is either a null pointer, or a stdio stream to write any debug output 6606to. @var{verbose} is the verbose level provided by 6607@option{-fsched-verbose-@var{n}}. 6608@end deftypefn 6609 6610@deftypefn {Target Hook} void TARGET_SCHED_INIT_GLOBAL (FILE *@var{file}, int @var{verbose}, int @var{old_max_uid}) 6611This hook is executed by the scheduler after function level initializations. 6612@var{file} is either a null pointer, or a stdio stream to write any debug output to. 6613@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 6614@var{old_max_uid} is the maximum insn uid when scheduling begins. 6615@end deftypefn 6616 6617@deftypefn {Target Hook} void TARGET_SCHED_FINISH_GLOBAL (FILE *@var{file}, int @var{verbose}) 6618This is the cleanup hook corresponding to @code{TARGET_SCHED_INIT_GLOBAL}. 6619@var{file} is either a null pointer, or a stdio stream to write any debug output to. 6620@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 6621@end deftypefn 6622 6623@deftypefn {Target Hook} rtx TARGET_SCHED_DFA_PRE_CYCLE_INSN (void) 6624The hook returns an RTL insn. The automaton state used in the 6625pipeline hazard recognizer is changed as if the insn were scheduled 6626when the new simulated processor cycle starts. Usage of the hook may 6627simplify the automaton pipeline description for some @acronym{VLIW} 6628processors. If the hook is defined, it is used only for the automaton 6629based pipeline description. The default is not to change the state 6630when the new simulated processor cycle starts. 6631@end deftypefn 6632 6633@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN (void) 6634The hook can be used to initialize data used by the previous hook. 6635@end deftypefn 6636 6637@deftypefn {Target Hook} rtx TARGET_SCHED_DFA_POST_CYCLE_INSN (void) 6638The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used 6639to changed the state as if the insn were scheduled when the new 6640simulated processor cycle finishes. 6641@end deftypefn 6642 6643@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN (void) 6644The hook is analogous to @samp{TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN} but 6645used to initialize data used by the previous hook. 6646@end deftypefn 6647 6648@deftypefn {Target Hook} void TARGET_SCHED_DFA_PRE_ADVANCE_CYCLE (void) 6649The hook to notify target that the current simulated cycle is about to finish. 6650The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used 6651to change the state in more complicated situations - e.g., when advancing 6652state on a single insn is not enough. 6653@end deftypefn 6654 6655@deftypefn {Target Hook} void TARGET_SCHED_DFA_POST_ADVANCE_CYCLE (void) 6656The hook to notify target that new simulated cycle has just started. 6657The hook is analogous to @samp{TARGET_SCHED_DFA_POST_CYCLE_INSN} but used 6658to change the state in more complicated situations - e.g., when advancing 6659state on a single insn is not enough. 6660@end deftypefn 6661 6662@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD (void) 6663This hook controls better choosing an insn from the ready insn queue 6664for the @acronym{DFA}-based insn scheduler. Usually the scheduler 6665chooses the first insn from the queue. If the hook returns a positive 6666value, an additional scheduler code tries all permutations of 6667@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD ()} 6668subsequent ready insns to choose an insn whose issue will result in 6669maximal number of issued insns on the same cycle. For the 6670@acronym{VLIW} processor, the code could actually solve the problem of 6671packing simple insns into the @acronym{VLIW} insn. Of course, if the 6672rules of @acronym{VLIW} packing are described in the automaton. 6673 6674This code also could be used for superscalar @acronym{RISC} 6675processors. Let us consider a superscalar @acronym{RISC} processor 6676with 3 pipelines. Some insns can be executed in pipelines @var{A} or 6677@var{B}, some insns can be executed only in pipelines @var{B} or 6678@var{C}, and one insn can be executed in pipeline @var{B}. The 6679processor may issue the 1st insn into @var{A} and the 2nd one into 6680@var{B}. In this case, the 3rd insn will wait for freeing @var{B} 6681until the next cycle. If the scheduler issues the 3rd insn the first, 6682the processor could issue all 3 insns per cycle. 6683 6684Actually this code demonstrates advantages of the automaton based 6685pipeline hazard recognizer. We try quickly and easy many insn 6686schedules to choose the best one. 6687 6688The default is no multipass scheduling. 6689@end deftypefn 6690 6691@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD (rtx @var{insn}) 6692 6693This hook controls what insns from the ready insn queue will be 6694considered for the multipass insn scheduling. If the hook returns 6695zero for @var{insn}, the insn will be not chosen to 6696be issued. 6697 6698The default is that any ready insns can be chosen to be issued. 6699@end deftypefn 6700 6701@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_BEGIN (void *@var{data}, char *@var{ready_try}, int @var{n_ready}, bool @var{first_cycle_insn_p}) 6702This hook prepares the target backend for a new round of multipass 6703scheduling. 6704@end deftypefn 6705 6706@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_ISSUE (void *@var{data}, char *@var{ready_try}, int @var{n_ready}, rtx @var{insn}, const void *@var{prev_data}) 6707This hook is called when multipass scheduling evaluates instruction INSN. 6708@end deftypefn 6709 6710@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_BACKTRACK (const void *@var{data}, char *@var{ready_try}, int @var{n_ready}) 6711This is called when multipass scheduling backtracks from evaluation of 6712an instruction. 6713@end deftypefn 6714 6715@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_END (const void *@var{data}) 6716This hook notifies the target about the result of the concluded current 6717round of multipass scheduling. 6718@end deftypefn 6719 6720@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_INIT (void *@var{data}) 6721This hook initializes target-specific data used in multipass scheduling. 6722@end deftypefn 6723 6724@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_FINI (void *@var{data}) 6725This hook finalizes target-specific data used in multipass scheduling. 6726@end deftypefn 6727 6728@deftypefn {Target Hook} int TARGET_SCHED_DFA_NEW_CYCLE (FILE *@var{dump}, int @var{verbose}, rtx @var{insn}, int @var{last_clock}, int @var{clock}, int *@var{sort_p}) 6729This hook is called by the insn scheduler before issuing @var{insn} 6730on cycle @var{clock}. If the hook returns nonzero, 6731@var{insn} is not issued on this processor cycle. Instead, 6732the processor cycle is advanced. If *@var{sort_p} 6733is zero, the insn ready queue is not sorted on the new cycle 6734start as usually. @var{dump} and @var{verbose} specify the file and 6735verbosity level to use for debugging output. 6736@var{last_clock} and @var{clock} are, respectively, the 6737processor cycle on which the previous insn has been issued, 6738and the current processor cycle. 6739@end deftypefn 6740 6741@deftypefn {Target Hook} bool TARGET_SCHED_IS_COSTLY_DEPENDENCE (struct _dep *@var{_dep}, int @var{cost}, int @var{distance}) 6742This hook is used to define which dependences are considered costly by 6743the target, so costly that it is not advisable to schedule the insns that 6744are involved in the dependence too close to one another. The parameters 6745to this hook are as follows: The first parameter @var{_dep} is the dependence 6746being evaluated. The second parameter @var{cost} is the cost of the 6747dependence as estimated by the scheduler, and the third 6748parameter @var{distance} is the distance in cycles between the two insns. 6749The hook returns @code{true} if considering the distance between the two 6750insns the dependence between them is considered costly by the target, 6751and @code{false} otherwise. 6752 6753Defining this hook can be useful in multiple-issue out-of-order machines, 6754where (a) it's practically hopeless to predict the actual data/resource 6755delays, however: (b) there's a better chance to predict the actual grouping 6756that will be formed, and (c) correctly emulating the grouping can be very 6757important. In such targets one may want to allow issuing dependent insns 6758closer to one another---i.e., closer than the dependence distance; however, 6759not in cases of ``costly dependences'', which this hooks allows to define. 6760@end deftypefn 6761 6762@deftypefn {Target Hook} void TARGET_SCHED_H_I_D_EXTENDED (void) 6763This hook is called by the insn scheduler after emitting a new instruction to 6764the instruction stream. The hook notifies a target backend to extend its 6765per instruction data structures. 6766@end deftypefn 6767 6768@deftypefn {Target Hook} {void *} TARGET_SCHED_ALLOC_SCHED_CONTEXT (void) 6769Return a pointer to a store large enough to hold target scheduling context. 6770@end deftypefn 6771 6772@deftypefn {Target Hook} void TARGET_SCHED_INIT_SCHED_CONTEXT (void *@var{tc}, bool @var{clean_p}) 6773Initialize store pointed to by @var{tc} to hold target scheduling context. 6774It @var{clean_p} is true then initialize @var{tc} as if scheduler is at the 6775beginning of the block. Otherwise, copy the current context into @var{tc}. 6776@end deftypefn 6777 6778@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_CONTEXT (void *@var{tc}) 6779Copy target scheduling context pointed to by @var{tc} to the current context. 6780@end deftypefn 6781 6782@deftypefn {Target Hook} void TARGET_SCHED_CLEAR_SCHED_CONTEXT (void *@var{tc}) 6783Deallocate internal data in target scheduling context pointed to by @var{tc}. 6784@end deftypefn 6785 6786@deftypefn {Target Hook} void TARGET_SCHED_FREE_SCHED_CONTEXT (void *@var{tc}) 6787Deallocate a store for target scheduling context pointed to by @var{tc}. 6788@end deftypefn 6789 6790@deftypefn {Target Hook} int TARGET_SCHED_SPECULATE_INSN (rtx @var{insn}, int @var{request}, rtx *@var{new_pat}) 6791This hook is called by the insn scheduler when @var{insn} has only 6792speculative dependencies and therefore can be scheduled speculatively. 6793The hook is used to check if the pattern of @var{insn} has a speculative 6794version and, in case of successful check, to generate that speculative 6795pattern. The hook should return 1, if the instruction has a speculative form, 6796or @minus{}1, if it doesn't. @var{request} describes the type of requested 6797speculation. If the return value equals 1 then @var{new_pat} is assigned 6798the generated speculative pattern. 6799@end deftypefn 6800 6801@deftypefn {Target Hook} bool TARGET_SCHED_NEEDS_BLOCK_P (int @var{dep_status}) 6802This hook is called by the insn scheduler during generation of recovery code 6803for @var{insn}. It should return @code{true}, if the corresponding check 6804instruction should branch to recovery code, or @code{false} otherwise. 6805@end deftypefn 6806 6807@deftypefn {Target Hook} rtx TARGET_SCHED_GEN_SPEC_CHECK (rtx @var{insn}, rtx @var{label}, int @var{mutate_p}) 6808This hook is called by the insn scheduler to generate a pattern for recovery 6809check instruction. If @var{mutate_p} is zero, then @var{insn} is a 6810speculative instruction for which the check should be generated. 6811@var{label} is either a label of a basic block, where recovery code should 6812be emitted, or a null pointer, when requested check doesn't branch to 6813recovery code (a simple check). If @var{mutate_p} is nonzero, then 6814a pattern for a branchy check corresponding to a simple check denoted by 6815@var{insn} should be generated. In this case @var{label} can't be null. 6816@end deftypefn 6817 6818@deftypefn {Target Hook} bool TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD_SPEC (const_rtx @var{insn}) 6819This hook is used as a workaround for 6820@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD} not being 6821called on the first instruction of the ready list. The hook is used to 6822discard speculative instructions that stand first in the ready list from 6823being scheduled on the current cycle. If the hook returns @code{false}, 6824@var{insn} will not be chosen to be issued. 6825For non-speculative instructions, 6826the hook should always return @code{true}. For example, in the ia64 backend 6827the hook is used to cancel data speculative insns when the ALAT table 6828is nearly full. 6829@end deftypefn 6830 6831@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_FLAGS (struct spec_info_def *@var{spec_info}) 6832This hook is used by the insn scheduler to find out what features should be 6833enabled/used. 6834The structure *@var{spec_info} should be filled in by the target. 6835The structure describes speculation types that can be used in the scheduler. 6836@end deftypefn 6837 6838@deftypefn {Target Hook} int TARGET_SCHED_SMS_RES_MII (struct ddg *@var{g}) 6839This hook is called by the swing modulo scheduler to calculate a 6840resource-based lower bound which is based on the resources available in 6841the machine and the resources required by each instruction. The target 6842backend can use @var{g} to calculate such bound. A very simple lower 6843bound will be used in case this hook is not implemented: the total number 6844of instructions divided by the issue rate. 6845@end deftypefn 6846 6847@deftypefn {Target Hook} bool TARGET_SCHED_DISPATCH (rtx @var{insn}, int @var{x}) 6848This hook is called by Haifa Scheduler. It returns true if dispatch scheduling 6849is supported in hardware and the condition specified in the parameter is true. 6850@end deftypefn 6851 6852@deftypefn {Target Hook} void TARGET_SCHED_DISPATCH_DO (rtx @var{insn}, int @var{x}) 6853This hook is called by Haifa Scheduler. It performs the operation specified 6854in its second parameter. 6855@end deftypefn 6856 6857@deftypevr {Target Hook} bool TARGET_SCHED_EXPOSED_PIPELINE 6858True if the processor has an exposed pipeline, which means that not just 6859the order of instructions is important for correctness when scheduling, but 6860also the latencies of operations. 6861@end deftypevr 6862 6863@deftypefn {Target Hook} int TARGET_SCHED_REASSOCIATION_WIDTH (unsigned int @var{opc}, enum machine_mode @var{mode}) 6864This hook is called by tree reassociator to determine a level of 6865parallelism required in output calculations chain. 6866@end deftypefn 6867 6868@node Sections 6869@section Dividing the Output into Sections (Texts, Data, @dots{}) 6870@c the above section title is WAY too long. maybe cut the part between 6871@c the (...)? --mew 10feb93 6872 6873An object file is divided into sections containing different types of 6874data. In the most common case, there are three sections: the @dfn{text 6875section}, which holds instructions and read-only data; the @dfn{data 6876section}, which holds initialized writable data; and the @dfn{bss 6877section}, which holds uninitialized data. Some systems have other kinds 6878of sections. 6879 6880@file{varasm.c} provides several well-known sections, such as 6881@code{text_section}, @code{data_section} and @code{bss_section}. 6882The normal way of controlling a @code{@var{foo}_section} variable 6883is to define the associated @code{@var{FOO}_SECTION_ASM_OP} macro, 6884as described below. The macros are only read once, when @file{varasm.c} 6885initializes itself, so their values must be run-time constants. 6886They may however depend on command-line flags. 6887 6888@emph{Note:} Some run-time files, such @file{crtstuff.c}, also make 6889use of the @code{@var{FOO}_SECTION_ASM_OP} macros, and expect them 6890to be string literals. 6891 6892Some assemblers require a different string to be written every time a 6893section is selected. If your assembler falls into this category, you 6894should define the @code{TARGET_ASM_INIT_SECTIONS} hook and use 6895@code{get_unnamed_section} to set up the sections. 6896 6897You must always create a @code{text_section}, either by defining 6898@code{TEXT_SECTION_ASM_OP} or by initializing @code{text_section} 6899in @code{TARGET_ASM_INIT_SECTIONS}. The same is true of 6900@code{data_section} and @code{DATA_SECTION_ASM_OP}. If you do not 6901create a distinct @code{readonly_data_section}, the default is to 6902reuse @code{text_section}. 6903 6904All the other @file{varasm.c} sections are optional, and are null 6905if the target does not provide them. 6906 6907@defmac TEXT_SECTION_ASM_OP 6908A C expression whose value is a string, including spacing, containing the 6909assembler operation that should precede instructions and read-only data. 6910Normally @code{"\t.text"} is right. 6911@end defmac 6912 6913@defmac HOT_TEXT_SECTION_NAME 6914If defined, a C string constant for the name of the section containing most 6915frequently executed functions of the program. If not defined, GCC will provide 6916a default definition if the target supports named sections. 6917@end defmac 6918 6919@defmac UNLIKELY_EXECUTED_TEXT_SECTION_NAME 6920If defined, a C string constant for the name of the section containing unlikely 6921executed functions in the program. 6922@end defmac 6923 6924@defmac DATA_SECTION_ASM_OP 6925A C expression whose value is a string, including spacing, containing the 6926assembler operation to identify the following data as writable initialized 6927data. Normally @code{"\t.data"} is right. 6928@end defmac 6929 6930@defmac SDATA_SECTION_ASM_OP 6931If defined, a C expression whose value is a string, including spacing, 6932containing the assembler operation to identify the following data as 6933initialized, writable small data. 6934@end defmac 6935 6936@defmac READONLY_DATA_SECTION_ASM_OP 6937A C expression whose value is a string, including spacing, containing the 6938assembler operation to identify the following data as read-only initialized 6939data. 6940@end defmac 6941 6942@defmac BSS_SECTION_ASM_OP 6943If defined, a C expression whose value is a string, including spacing, 6944containing the assembler operation to identify the following data as 6945uninitialized global data. If not defined, and 6946@code{ASM_OUTPUT_ALIGNED_BSS} not defined, 6947uninitialized global data will be output in the data section if 6948@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 6949used. 6950@end defmac 6951 6952@defmac SBSS_SECTION_ASM_OP 6953If defined, a C expression whose value is a string, including spacing, 6954containing the assembler operation to identify the following data as 6955uninitialized, writable small data. 6956@end defmac 6957 6958@defmac TLS_COMMON_ASM_OP 6959If defined, a C expression whose value is a string containing the 6960assembler operation to identify the following data as thread-local 6961common data. The default is @code{".tls_common"}. 6962@end defmac 6963 6964@defmac TLS_SECTION_ASM_FLAG 6965If defined, a C expression whose value is a character constant 6966containing the flag used to mark a section as a TLS section. The 6967default is @code{'T'}. 6968@end defmac 6969 6970@defmac INIT_SECTION_ASM_OP 6971If defined, a C expression whose value is a string, including spacing, 6972containing the assembler operation to identify the following data as 6973initialization code. If not defined, GCC will assume such a section does 6974not exist. This section has no corresponding @code{init_section} 6975variable; it is used entirely in runtime code. 6976@end defmac 6977 6978@defmac FINI_SECTION_ASM_OP 6979If defined, a C expression whose value is a string, including spacing, 6980containing the assembler operation to identify the following data as 6981finalization code. If not defined, GCC will assume such a section does 6982not exist. This section has no corresponding @code{fini_section} 6983variable; it is used entirely in runtime code. 6984@end defmac 6985 6986@defmac INIT_ARRAY_SECTION_ASM_OP 6987If defined, a C expression whose value is a string, including spacing, 6988containing the assembler operation to identify the following data as 6989part of the @code{.init_array} (or equivalent) section. If not 6990defined, GCC will assume such a section does not exist. Do not define 6991both this macro and @code{INIT_SECTION_ASM_OP}. 6992@end defmac 6993 6994@defmac FINI_ARRAY_SECTION_ASM_OP 6995If defined, a C expression whose value is a string, including spacing, 6996containing the assembler operation to identify the following data as 6997part of the @code{.fini_array} (or equivalent) section. If not 6998defined, GCC will assume such a section does not exist. Do not define 6999both this macro and @code{FINI_SECTION_ASM_OP}. 7000@end defmac 7001 7002@defmac CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 7003If defined, an ASM statement that switches to a different section 7004via @var{section_op}, calls @var{function}, and switches back to 7005the text section. This is used in @file{crtstuff.c} if 7006@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 7007to initialization and finalization functions from the init and fini 7008sections. By default, this macro uses a simple function call. Some 7009ports need hand-crafted assembly code to avoid dependencies on 7010registers initialized in the function prologue or to ensure that 7011constant pools don't end up too far way in the text section. 7012@end defmac 7013 7014@defmac TARGET_LIBGCC_SDATA_SECTION 7015If defined, a string which names the section into which small 7016variables defined in crtstuff and libgcc should go. This is useful 7017when the target has options for optimizing access to small data, and 7018you want the crtstuff and libgcc routines to be conservative in what 7019they expect of your application yet liberal in what your application 7020expects. For example, for targets with a @code{.sdata} section (like 7021MIPS), you could compile crtstuff with @code{-G 0} so that it doesn't 7022require small data support from your application, but use this macro 7023to put small data into @code{.sdata} so that your application can 7024access these variables whether it uses small data or not. 7025@end defmac 7026 7027@defmac FORCE_CODE_SECTION_ALIGN 7028If defined, an ASM statement that aligns a code section to some 7029arbitrary boundary. This is used to force all fragments of the 7030@code{.init} and @code{.fini} sections to have to same alignment 7031and thus prevent the linker from having to add any padding. 7032@end defmac 7033 7034@defmac JUMP_TABLES_IN_TEXT_SECTION 7035Define this macro to be an expression with a nonzero value if jump 7036tables (for @code{tablejump} insns) should be output in the text 7037section, along with the assembler instructions. Otherwise, the 7038readonly data section is used. 7039 7040This macro is irrelevant if there is no separate readonly data section. 7041@end defmac 7042 7043@deftypefn {Target Hook} void TARGET_ASM_INIT_SECTIONS (void) 7044Define this hook if you need to do something special to set up the 7045@file{varasm.c} sections, or if your target has some special sections 7046of its own that you need to create. 7047 7048GCC calls this hook after processing the command line, but before writing 7049any assembly code, and before calling any of the section-returning hooks 7050described below. 7051@end deftypefn 7052 7053@deftypefn {Target Hook} int TARGET_ASM_RELOC_RW_MASK (void) 7054Return a mask describing how relocations should be treated when 7055selecting sections. Bit 1 should be set if global relocations 7056should be placed in a read-write section; bit 0 should be set if 7057local relocations should be placed in a read-write section. 7058 7059The default version of this function returns 3 when @option{-fpic} 7060is in effect, and 0 otherwise. The hook is typically redefined 7061when the target cannot support (some kinds of) dynamic relocations 7062in read-only sections even in executables. 7063@end deftypefn 7064 7065@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align}) 7066Return the section into which @var{exp} should be placed. You can 7067assume that @var{exp} is either a @code{VAR_DECL} node or a constant of 7068some sort. @var{reloc} indicates whether the initial value of @var{exp} 7069requires link-time relocations. Bit 0 is set when variable contains 7070local relocations only, while bit 1 is set for global relocations. 7071@var{align} is the constant alignment in bits. 7072 7073The default version of this function takes care of putting read-only 7074variables in @code{readonly_data_section}. 7075 7076See also @var{USE_SELECT_SECTION_FOR_FUNCTIONS}. 7077@end deftypefn 7078 7079@defmac USE_SELECT_SECTION_FOR_FUNCTIONS 7080Define this macro if you wish TARGET_ASM_SELECT_SECTION to be called 7081for @code{FUNCTION_DECL}s as well as for variables and constants. 7082 7083In the case of a @code{FUNCTION_DECL}, @var{reloc} will be zero if the 7084function has been determined to be likely to be called, and nonzero if 7085it is unlikely to be called. 7086@end defmac 7087 7088@deftypefn {Target Hook} void TARGET_ASM_UNIQUE_SECTION (tree @var{decl}, int @var{reloc}) 7089Build up a unique section name, expressed as a @code{STRING_CST} node, 7090and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 7091As with @code{TARGET_ASM_SELECT_SECTION}, @var{reloc} indicates whether 7092the initial value of @var{exp} requires link-time relocations. 7093 7094The default version of this function appends the symbol name to the 7095ELF section name that would normally be used for the symbol. For 7096example, the function @code{foo} would be placed in @code{.text.foo}. 7097Whatever the actual target object format, this is often good enough. 7098@end deftypefn 7099 7100@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_RODATA_SECTION (tree @var{decl}) 7101Return the readonly data section associated with 7102@samp{DECL_SECTION_NAME (@var{decl})}. 7103The default version of this function selects @code{.gnu.linkonce.r.name} if 7104the function's section is @code{.gnu.linkonce.t.name}, @code{.rodata.name} 7105if function is in @code{.text.name}, and the normal readonly-data section 7106otherwise. 7107@end deftypefn 7108 7109@deftypevr {Target Hook} {const char *} TARGET_ASM_MERGEABLE_RODATA_PREFIX 7110Usually, the compiler uses the prefix @code{".rodata"} to construct 7111section names for mergeable constant data. Define this macro to override 7112the string if a different section name should be used. 7113@end deftypevr 7114 7115@deftypefn {Target Hook} {section *} TARGET_ASM_TM_CLONE_TABLE_SECTION (void) 7116Return the section that should be used for transactional memory clone tables. 7117@end deftypefn 7118 7119@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_RTX_SECTION (enum machine_mode @var{mode}, rtx @var{x}, unsigned HOST_WIDE_INT @var{align}) 7120Return the section into which a constant @var{x}, of mode @var{mode}, 7121should be placed. You can assume that @var{x} is some kind of 7122constant in RTL@. The argument @var{mode} is redundant except in the 7123case of a @code{const_int} rtx. @var{align} is the constant alignment 7124in bits. 7125 7126The default version of this function takes care of putting symbolic 7127constants in @code{flag_pic} mode in @code{data_section} and everything 7128else in @code{readonly_data_section}. 7129@end deftypefn 7130 7131@deftypefn {Target Hook} tree TARGET_MANGLE_DECL_ASSEMBLER_NAME (tree @var{decl}, tree @var{id}) 7132Define this hook if you need to postprocess the assembler name generated 7133by target-independent code. The @var{id} provided to this hook will be 7134the computed name (e.g., the macro @code{DECL_NAME} of the @var{decl} in C, 7135or the mangled name of the @var{decl} in C++). The return value of the 7136hook is an @code{IDENTIFIER_NODE} for the appropriate mangled name on 7137your target system. The default implementation of this hook just 7138returns the @var{id} provided. 7139@end deftypefn 7140 7141@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, rtx @var{rtl}, int @var{new_decl_p}) 7142Define this hook if references to a symbol or a constant must be 7143treated differently depending on something about the variable or 7144function named by the symbol (such as what section it is in). 7145 7146The hook is executed immediately after rtl has been created for 7147@var{decl}, which may be a variable or function declaration or 7148an entry in the constant pool. In either case, @var{rtl} is the 7149rtl in question. Do @emph{not} use @code{DECL_RTL (@var{decl})} 7150in this hook; that field may not have been initialized yet. 7151 7152In the case of a constant, it is safe to assume that the rtl is 7153a @code{mem} whose address is a @code{symbol_ref}. Most decls 7154will also have this form, but that is not guaranteed. Global 7155register variables, for instance, will have a @code{reg} for their 7156rtl. (Normally the right thing to do with such unusual rtl is 7157leave it alone.) 7158 7159The @var{new_decl_p} argument will be true if this is the first time 7160that @code{TARGET_ENCODE_SECTION_INFO} has been invoked on this decl. It will 7161be false for subsequent invocations, which will happen for duplicate 7162declarations. Whether or not anything must be done for the duplicate 7163declaration depends on whether the hook examines @code{DECL_ATTRIBUTES}. 7164@var{new_decl_p} is always true when the hook is called for a constant. 7165 7166@cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO} 7167The usual thing for this hook to do is to record flags in the 7168@code{symbol_ref}, using @code{SYMBOL_REF_FLAG} or @code{SYMBOL_REF_FLAGS}. 7169Historically, the name string was modified if it was necessary to 7170encode more than one bit of information, but this practice is now 7171discouraged; use @code{SYMBOL_REF_FLAGS}. 7172 7173The default definition of this hook, @code{default_encode_section_info} 7174in @file{varasm.c}, sets a number of commonly-useful bits in 7175@code{SYMBOL_REF_FLAGS}. Check whether the default does what you need 7176before overriding it. 7177@end deftypefn 7178 7179@deftypefn {Target Hook} {const char *} TARGET_STRIP_NAME_ENCODING (const char *@var{name}) 7180Decode @var{name} and return the real name part, sans 7181the characters that @code{TARGET_ENCODE_SECTION_INFO} 7182may have added. 7183@end deftypefn 7184 7185@deftypefn {Target Hook} bool TARGET_IN_SMALL_DATA_P (const_tree @var{exp}) 7186Returns true if @var{exp} should be placed into a ``small data'' section. 7187The default version of this hook always returns false. 7188@end deftypefn 7189 7190@deftypevr {Target Hook} bool TARGET_HAVE_SRODATA_SECTION 7191Contains the value true if the target places read-only 7192``small data'' into a separate section. The default value is false. 7193@end deftypevr 7194 7195@deftypefn {Target Hook} bool TARGET_PROFILE_BEFORE_PROLOGUE (void) 7196It returns true if target wants profile code emitted before prologue. 7197 7198The default version of this hook use the target macro 7199@code{PROFILE_BEFORE_PROLOGUE}. 7200@end deftypefn 7201 7202@deftypefn {Target Hook} bool TARGET_BINDS_LOCAL_P (const_tree @var{exp}) 7203Returns true if @var{exp} names an object for which name resolution 7204rules must resolve to the current ``module'' (dynamic shared library 7205or executable image). 7206 7207The default version of this hook implements the name resolution rules 7208for ELF, which has a looser model of global name binding than other 7209currently supported object file formats. 7210@end deftypefn 7211 7212@deftypevr {Target Hook} bool TARGET_HAVE_TLS 7213Contains the value true if the target supports thread-local storage. 7214The default value is false. 7215@end deftypevr 7216 7217 7218@node PIC 7219@section Position Independent Code 7220@cindex position independent code 7221@cindex PIC 7222 7223This section describes macros that help implement generation of position 7224independent code. Simply defining these macros is not enough to 7225generate valid PIC; you must also add support to the hook 7226@code{TARGET_LEGITIMATE_ADDRESS_P} and to the macro 7227@code{PRINT_OPERAND_ADDRESS}, as well as @code{LEGITIMIZE_ADDRESS}. You 7228must modify the definition of @samp{movsi} to do something appropriate 7229when the source operand contains a symbolic address. You may also 7230need to alter the handling of switch statements so that they use 7231relative addresses. 7232@c i rearranged the order of the macros above to try to force one of 7233@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 7234 7235@defmac PIC_OFFSET_TABLE_REGNUM 7236The register number of the register used to address a table of static 7237data addresses in memory. In some cases this register is defined by a 7238processor's ``application binary interface'' (ABI)@. When this macro 7239is defined, RTL is generated for this register once, as with the stack 7240pointer and frame pointer registers. If this macro is not defined, it 7241is up to the machine-dependent files to allocate such a register (if 7242necessary). Note that this register must be fixed when in use (e.g.@: 7243when @code{flag_pic} is true). 7244@end defmac 7245 7246@defmac PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 7247A C expression that is nonzero if the register defined by 7248@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. If not defined, 7249the default is zero. Do not define 7250this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 7251@end defmac 7252 7253@defmac LEGITIMATE_PIC_OPERAND_P (@var{x}) 7254A C expression that is nonzero if @var{x} is a legitimate immediate 7255operand on the target machine when generating position independent code. 7256You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 7257check this. You can also assume @var{flag_pic} is true, so you need not 7258check it either. You need not define this macro if all constants 7259(including @code{SYMBOL_REF}) can be immediate operands when generating 7260position independent code. 7261@end defmac 7262 7263@node Assembler Format 7264@section Defining the Output Assembler Language 7265 7266This section describes macros whose principal purpose is to describe how 7267to write instructions in assembler language---rather than what the 7268instructions do. 7269 7270@menu 7271* File Framework:: Structural information for the assembler file. 7272* Data Output:: Output of constants (numbers, strings, addresses). 7273* Uninitialized Data:: Output of uninitialized variables. 7274* Label Output:: Output and generation of labels. 7275* Initialization:: General principles of initialization 7276 and termination routines. 7277* Macros for Initialization:: 7278 Specific macros that control the handling of 7279 initialization and termination routines. 7280* Instruction Output:: Output of actual instructions. 7281* Dispatch Tables:: Output of jump tables. 7282* Exception Region Output:: Output of exception region code. 7283* Alignment Output:: Pseudo ops for alignment and skipping data. 7284@end menu 7285 7286@node File Framework 7287@subsection The Overall Framework of an Assembler File 7288@cindex assembler format 7289@cindex output of assembler code 7290 7291@c prevent bad page break with this line 7292This describes the overall framework of an assembly file. 7293 7294@findex default_file_start 7295@deftypefn {Target Hook} void TARGET_ASM_FILE_START (void) 7296Output to @code{asm_out_file} any text which the assembler expects to 7297find at the beginning of a file. The default behavior is controlled 7298by two flags, documented below. Unless your target's assembler is 7299quite unusual, if you override the default, you should call 7300@code{default_file_start} at some point in your target hook. This 7301lets other target files rely on these variables. 7302@end deftypefn 7303 7304@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_APP_OFF 7305If this flag is true, the text of the macro @code{ASM_APP_OFF} will be 7306printed as the very first line in the assembly file, unless 7307@option{-fverbose-asm} is in effect. (If that macro has been defined 7308to the empty string, this variable has no effect.) With the normal 7309definition of @code{ASM_APP_OFF}, the effect is to notify the GNU 7310assembler that it need not bother stripping comments or extra 7311whitespace from its input. This allows it to work a bit faster. 7312 7313The default is false. You should not set it to true unless you have 7314verified that your port does not generate any extra whitespace or 7315comments that will cause GAS to issue errors in NO_APP mode. 7316@end deftypevr 7317 7318@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_FILE_DIRECTIVE 7319If this flag is true, @code{output_file_directive} will be called 7320for the primary source file, immediately after printing 7321@code{ASM_APP_OFF} (if that is enabled). Most ELF assemblers expect 7322this to be done. The default is false. 7323@end deftypevr 7324 7325@deftypefn {Target Hook} void TARGET_ASM_FILE_END (void) 7326Output to @code{asm_out_file} any text which the assembler expects 7327to find at the end of a file. The default is to output nothing. 7328@end deftypefn 7329 7330@deftypefun void file_end_indicate_exec_stack () 7331Some systems use a common convention, the @samp{.note.GNU-stack} 7332special section, to indicate whether or not an object file relies on 7333the stack being executable. If your system uses this convention, you 7334should define @code{TARGET_ASM_FILE_END} to this function. If you 7335need to do other things in that hook, have your hook function call 7336this function. 7337@end deftypefun 7338 7339@deftypefn {Target Hook} void TARGET_ASM_LTO_START (void) 7340Output to @code{asm_out_file} any text which the assembler expects 7341to find at the start of an LTO section. The default is to output 7342nothing. 7343@end deftypefn 7344 7345@deftypefn {Target Hook} void TARGET_ASM_LTO_END (void) 7346Output to @code{asm_out_file} any text which the assembler expects 7347to find at the end of an LTO section. The default is to output 7348nothing. 7349@end deftypefn 7350 7351@deftypefn {Target Hook} void TARGET_ASM_CODE_END (void) 7352Output to @code{asm_out_file} any text which is needed before emitting 7353unwind info and debug info at the end of a file. Some targets emit 7354here PIC setup thunks that cannot be emitted at the end of file, 7355because they couldn't have unwind info then. The default is to output 7356nothing. 7357@end deftypefn 7358 7359@defmac ASM_COMMENT_START 7360A C string constant describing how to begin a comment in the target 7361assembler language. The compiler assumes that the comment will end at 7362the end of the line. 7363@end defmac 7364 7365@defmac ASM_APP_ON 7366A C string constant for text to be output before each @code{asm} 7367statement or group of consecutive ones. Normally this is 7368@code{"#APP"}, which is a comment that has no effect on most 7369assemblers but tells the GNU assembler that it must check the lines 7370that follow for all valid assembler constructs. 7371@end defmac 7372 7373@defmac ASM_APP_OFF 7374A C string constant for text to be output after each @code{asm} 7375statement or group of consecutive ones. Normally this is 7376@code{"#NO_APP"}, which tells the GNU assembler to resume making the 7377time-saving assumptions that are valid for ordinary compiler output. 7378@end defmac 7379 7380@defmac ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 7381A C statement to output COFF information or DWARF debugging information 7382which indicates that filename @var{name} is the current source file to 7383the stdio stream @var{stream}. 7384 7385This macro need not be defined if the standard form of output 7386for the file format in use is appropriate. 7387@end defmac 7388 7389@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_SOURCE_FILENAME (FILE *@var{file}, const char *@var{name}) 7390Output COFF information or DWARF debugging information which indicates that filename @var{name} is the current source file to the stdio stream @var{file}. 7391 7392 This target hook need not be defined if the standard form of output for the file format in use is appropriate. 7393@end deftypefn 7394 7395@defmac OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 7396A C statement to output the string @var{string} to the stdio stream 7397@var{stream}. If you do not call the function @code{output_quoted_string} 7398in your config files, GCC will only call it to output filenames to 7399the assembler source. So you can use it to canonicalize the format 7400of the filename using this macro. 7401@end defmac 7402 7403@defmac ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 7404A C statement to output something to the assembler file to handle a 7405@samp{#ident} directive containing the text @var{string}. If this 7406macro is not defined, nothing is output for a @samp{#ident} directive. 7407@end defmac 7408 7409@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, tree @var{decl}) 7410Output assembly directives to switch to section @var{name}. The section 7411should have attributes as specified by @var{flags}, which is a bit mask 7412of the @code{SECTION_*} flags defined in @file{output.h}. If @var{decl} 7413is non-NULL, it is the @code{VAR_DECL} or @code{FUNCTION_DECL} with which 7414this section is associated. 7415@end deftypefn 7416 7417@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_SECTION (tree @var{decl}, enum node_frequency @var{freq}, bool @var{startup}, bool @var{exit}) 7418Return preferred text (sub)section for function @var{decl}. 7419Main purpose of this function is to separate cold, normal and hot 7420functions. @var{startup} is true when function is known to be used only 7421at startup (from static constructors or it is @code{main()}). 7422@var{exit} is true when function is known to be used only at exit 7423(from static destructors). 7424Return NULL if function should go to default text section. 7425@end deftypefn 7426 7427@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_SWITCHED_TEXT_SECTIONS (FILE *@var{file}, tree @var{decl}, bool @var{new_is_cold}) 7428Used by the target to emit any assembler directives or additional labels needed when a function is partitioned between different sections. Output should be written to @var{file}. The function decl is available as @var{decl} and the new section is `cold' if @var{new_is_cold} is @code{true}. 7429@end deftypefn 7430 7431@deftypevr {Common Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 7432This flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 7433It must not be modified by command-line option processing. 7434@end deftypevr 7435 7436@anchor{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS} 7437@deftypevr {Target Hook} bool TARGET_HAVE_SWITCHABLE_BSS_SECTIONS 7438This flag is true if we can create zeroed data by switching to a BSS 7439section and then using @code{ASM_OUTPUT_SKIP} to allocate the space. 7440This is true on most ELF targets. 7441@end deftypevr 7442 7443@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 7444Choose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 7445based on a variable or function decl, a section name, and whether or not the 7446declaration's initializer may contain runtime relocations. @var{decl} may be 7447null, in which case read-write data should be assumed. 7448 7449The default version of this function handles choosing code vs data, 7450read-only vs read-write data, and @code{flag_pic}. You should only 7451need to override this if your target has special flags that might be 7452set via @code{__attribute__}. 7453@end deftypefn 7454 7455@deftypefn {Target Hook} int TARGET_ASM_RECORD_GCC_SWITCHES (print_switch_type @var{type}, const char *@var{text}) 7456Provides the target with the ability to record the gcc command line 7457switches that have been passed to the compiler, and options that are 7458enabled. The @var{type} argument specifies what is being recorded. 7459It can take the following values: 7460 7461@table @gcctabopt 7462@item SWITCH_TYPE_PASSED 7463@var{text} is a command line switch that has been set by the user. 7464 7465@item SWITCH_TYPE_ENABLED 7466@var{text} is an option which has been enabled. This might be as a 7467direct result of a command line switch, or because it is enabled by 7468default or because it has been enabled as a side effect of a different 7469command line switch. For example, the @option{-O2} switch enables 7470various different individual optimization passes. 7471 7472@item SWITCH_TYPE_DESCRIPTIVE 7473@var{text} is either NULL or some descriptive text which should be 7474ignored. If @var{text} is NULL then it is being used to warn the 7475target hook that either recording is starting or ending. The first 7476time @var{type} is SWITCH_TYPE_DESCRIPTIVE and @var{text} is NULL, the 7477warning is for start up and the second time the warning is for 7478wind down. This feature is to allow the target hook to make any 7479necessary preparations before it starts to record switches and to 7480perform any necessary tidying up after it has finished recording 7481switches. 7482 7483@item SWITCH_TYPE_LINE_START 7484This option can be ignored by this target hook. 7485 7486@item SWITCH_TYPE_LINE_END 7487This option can be ignored by this target hook. 7488@end table 7489 7490The hook's return value must be zero. Other return values may be 7491supported in the future. 7492 7493By default this hook is set to NULL, but an example implementation is 7494provided for ELF based targets. Called @var{elf_record_gcc_switches}, 7495it records the switches as ASCII text inside a new, string mergeable 7496section in the assembler output file. The name of the new section is 7497provided by the @code{TARGET_ASM_RECORD_GCC_SWITCHES_SECTION} target 7498hook. 7499@end deftypefn 7500 7501@deftypevr {Target Hook} {const char *} TARGET_ASM_RECORD_GCC_SWITCHES_SECTION 7502This is the name of the section that will be created by the example 7503ELF implementation of the @code{TARGET_ASM_RECORD_GCC_SWITCHES} target 7504hook. 7505@end deftypevr 7506 7507@need 2000 7508@node Data Output 7509@subsection Output of Data 7510 7511 7512@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 7513@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 7514@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 7515@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 7516@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 7517@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 7518@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 7519@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 7520@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 7521These hooks specify assembly directives for creating certain kinds 7522of integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 7523byte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 7524aligned two-byte object, and so on. Any of the hooks may be 7525@code{NULL}, indicating that no suitable directive is available. 7526 7527The compiler will print these strings at the start of a new line, 7528followed immediately by the object's initial value. In most cases, 7529the string should contain a tab, a pseudo-op, and then another tab. 7530@end deftypevr 7531 7532@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 7533The @code{assemble_integer} function uses this hook to output an 7534integer object. @var{x} is the object's value, @var{size} is its size 7535in bytes and @var{aligned_p} indicates whether it is aligned. The 7536function should return @code{true} if it was able to output the 7537object. If it returns false, @code{assemble_integer} will try to 7538split the object into smaller parts. 7539 7540The default implementation of this hook will use the 7541@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 7542when the relevant string is @code{NULL}. 7543@end deftypefn 7544 7545@deftypefn {Target Hook} bool TARGET_ASM_OUTPUT_ADDR_CONST_EXTRA (FILE *@var{file}, rtx @var{x}) 7546A target hook to recognize @var{rtx} patterns that @code{output_addr_const} 7547can't deal with, and output assembly code to @var{file} corresponding to 7548the pattern @var{x}. This may be used to allow machine-dependent 7549@code{UNSPEC}s to appear within constants. 7550 7551If target hook fails to recognize a pattern, it must return @code{false}, 7552so that a standard error message is printed. If it prints an error message 7553itself, by calling, for example, @code{output_operand_lossage}, it may just 7554return @code{true}. 7555@end deftypefn 7556 7557@defmac ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 7558A C statement to output to the stdio stream @var{stream} an assembler 7559instruction to assemble a string constant containing the @var{len} 7560bytes at @var{ptr}. @var{ptr} will be a C expression of type 7561@code{char *} and @var{len} a C expression of type @code{int}. 7562 7563If the assembler has a @code{.ascii} pseudo-op as found in the 7564Berkeley Unix assembler, do not define the macro 7565@code{ASM_OUTPUT_ASCII}. 7566@end defmac 7567 7568@defmac ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 7569A C statement to output word @var{n} of a function descriptor for 7570@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 7571is defined, and is otherwise unused. 7572@end defmac 7573 7574@defmac CONSTANT_POOL_BEFORE_FUNCTION 7575You may define this macro as a C expression. You should define the 7576expression to have a nonzero value if GCC should output the constant 7577pool for a function before the code for the function, or a zero value if 7578GCC should output the constant pool after the function. If you do 7579not define this macro, the usual case, GCC will output the constant 7580pool before the function. 7581@end defmac 7582 7583@defmac ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 7584A C statement to output assembler commands to define the start of the 7585constant pool for a function. @var{funname} is a string giving 7586the name of the function. Should the return type of the function 7587be required, it can be obtained via @var{fundecl}. @var{size} 7588is the size, in bytes, of the constant pool that will be written 7589immediately after this call. 7590 7591If no constant-pool prefix is required, the usual case, this macro need 7592not be defined. 7593@end defmac 7594 7595@defmac ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 7596A C statement (with or without semicolon) to output a constant in the 7597constant pool, if it needs special treatment. (This macro need not do 7598anything for RTL expressions that can be output normally.) 7599 7600The argument @var{file} is the standard I/O stream to output the 7601assembler code on. @var{x} is the RTL expression for the constant to 7602output, and @var{mode} is the machine mode (in case @var{x} is a 7603@samp{const_int}). @var{align} is the required alignment for the value 7604@var{x}; you should output an assembler directive to force this much 7605alignment. 7606 7607The argument @var{labelno} is a number to use in an internal label for 7608the address of this pool entry. The definition of this macro is 7609responsible for outputting the label definition at the proper place. 7610Here is how to do this: 7611 7612@smallexample 7613@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno}); 7614@end smallexample 7615 7616When you output a pool entry specially, you should end with a 7617@code{goto} to the label @var{jumpto}. This will prevent the same pool 7618entry from being output a second time in the usual manner. 7619 7620You need not define this macro if it would do nothing. 7621@end defmac 7622 7623@defmac ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 7624A C statement to output assembler commands to at the end of the constant 7625pool for a function. @var{funname} is a string giving the name of the 7626function. Should the return type of the function be required, you can 7627obtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 7628constant pool that GCC wrote immediately before this call. 7629 7630If no constant-pool epilogue is required, the usual case, you need not 7631define this macro. 7632@end defmac 7633 7634@defmac IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}, @var{STR}) 7635Define this macro as a C expression which is nonzero if @var{C} is 7636used as a logical line separator by the assembler. @var{STR} points 7637to the position in the string where @var{C} was found; this can be used if 7638a line separator uses multiple characters. 7639 7640If you do not define this macro, the default is that only 7641the character @samp{;} is treated as a logical line separator. 7642@end defmac 7643 7644@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 7645@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 7646These target hooks are C string constants, describing the syntax in the 7647assembler for grouping arithmetic expressions. If not overridden, they 7648default to normal parentheses, which is correct for most assemblers. 7649@end deftypevr 7650 7651These macros are provided by @file{real.h} for writing the definitions 7652of @code{ASM_OUTPUT_DOUBLE} and the like: 7653 7654@defmac REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 7655@defmacx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 7656@defmacx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 7657@defmacx REAL_VALUE_TO_TARGET_DECIMAL32 (@var{x}, @var{l}) 7658@defmacx REAL_VALUE_TO_TARGET_DECIMAL64 (@var{x}, @var{l}) 7659@defmacx REAL_VALUE_TO_TARGET_DECIMAL128 (@var{x}, @var{l}) 7660These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the 7661target's floating point representation, and store its bit pattern in 7662the variable @var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE} and 7663@code{REAL_VALUE_TO_TARGET_DECIMAL32}, this variable should be a 7664simple @code{long int}. For the others, it should be an array of 7665@code{long int}. The number of elements in this array is determined 7666by the size of the desired target floating point data type: 32 bits of 7667it go in each @code{long int} array element. Each array element holds 766832 bits of the result, even if @code{long int} is wider than 32 bits 7669on the host machine. 7670 7671The array element values are designed so that you can print them out 7672using @code{fprintf} in the order they should appear in the target 7673machine's memory. 7674@end defmac 7675 7676@node Uninitialized Data 7677@subsection Output of Uninitialized Variables 7678 7679Each of the macros in this section is used to do the whole job of 7680outputting a single uninitialized variable. 7681 7682@defmac ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 7683A C statement (sans semicolon) to output to the stdio stream 7684@var{stream} the assembler definition of a common-label named 7685@var{name} whose size is @var{size} bytes. The variable @var{rounded} 7686is the size rounded up to whatever alignment the caller wants. It is 7687possible that @var{size} may be zero, for instance if a struct with no 7688other member than a zero-length array is defined. In this case, the 7689backend must output a symbol definition that allocates at least one 7690byte, both so that the address of the resulting object does not compare 7691equal to any other, and because some object formats cannot even express 7692the concept of a zero-sized common symbol, as that is how they represent 7693an ordinary undefined external. 7694 7695Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7696output the name itself; before and after that, output the additional 7697assembler syntax for defining the name, and a newline. 7698 7699This macro controls how the assembler definitions of uninitialized 7700common global variables are output. 7701@end defmac 7702 7703@defmac ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 7704Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 7705separate, explicit argument. If you define this macro, it is used in 7706place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 7707handling the required alignment of the variable. The alignment is specified 7708as the number of bits. 7709@end defmac 7710 7711@defmac ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 7712Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 7713variable to be output, if there is one, or @code{NULL_TREE} if there 7714is no corresponding variable. If you define this macro, GCC will use it 7715in place of both @code{ASM_OUTPUT_COMMON} and 7716@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 7717the variable's decl in order to chose what to output. 7718@end defmac 7719 7720@defmac ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 7721A C statement (sans semicolon) to output to the stdio stream 7722@var{stream} the assembler definition of uninitialized global @var{decl} named 7723@var{name} whose size is @var{size} bytes. The variable @var{alignment} 7724is the alignment specified as the number of bits. 7725 7726Try to use function @code{asm_output_aligned_bss} defined in file 7727@file{varasm.c} when defining this macro. If unable, use the expression 7728@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 7729before and after that, output the additional assembler syntax for defining 7730the name, and a newline. 7731 7732There are two ways of handling global BSS@. One is to define this macro. 7733The other is to have @code{TARGET_ASM_SELECT_SECTION} return a 7734switchable BSS section (@pxref{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}). 7735You do not need to do both. 7736 7737Some languages do not have @code{common} data, and require a 7738non-common form of global BSS in order to handle uninitialized globals 7739efficiently. C++ is one example of this. However, if the target does 7740not support global BSS, the front end may choose to make globals 7741common in order to save space in the object file. 7742@end defmac 7743 7744@defmac ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 7745A C statement (sans semicolon) to output to the stdio stream 7746@var{stream} the assembler definition of a local-common-label named 7747@var{name} whose size is @var{size} bytes. The variable @var{rounded} 7748is the size rounded up to whatever alignment the caller wants. 7749 7750Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7751output the name itself; before and after that, output the additional 7752assembler syntax for defining the name, and a newline. 7753 7754This macro controls how the assembler definitions of uninitialized 7755static variables are output. 7756@end defmac 7757 7758@defmac ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 7759Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 7760separate, explicit argument. If you define this macro, it is used in 7761place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 7762handling the required alignment of the variable. The alignment is specified 7763as the number of bits. 7764@end defmac 7765 7766@defmac ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 7767Like @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 7768variable to be output, if there is one, or @code{NULL_TREE} if there 7769is no corresponding variable. If you define this macro, GCC will use it 7770in place of both @code{ASM_OUTPUT_DECL} and 7771@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 7772the variable's decl in order to chose what to output. 7773@end defmac 7774 7775@node Label Output 7776@subsection Output and Generation of Labels 7777 7778@c prevent bad page break with this line 7779This is about outputting labels. 7780 7781@findex assemble_name 7782@defmac ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 7783A C statement (sans semicolon) to output to the stdio stream 7784@var{stream} the assembler definition of a label named @var{name}. 7785Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7786output the name itself; before and after that, output the additional 7787assembler syntax for defining the name, and a newline. A default 7788definition of this macro is provided which is correct for most systems. 7789@end defmac 7790 7791@defmac ASM_OUTPUT_FUNCTION_LABEL (@var{stream}, @var{name}, @var{decl}) 7792A C statement (sans semicolon) to output to the stdio stream 7793@var{stream} the assembler definition of a label named @var{name} of 7794a function. 7795Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7796output the name itself; before and after that, output the additional 7797assembler syntax for defining the name, and a newline. A default 7798definition of this macro is provided which is correct for most systems. 7799 7800If this macro is not defined, then the function name is defined in the 7801usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 7802@end defmac 7803 7804@findex assemble_name_raw 7805@defmac ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{name}) 7806Identical to @code{ASM_OUTPUT_LABEL}, except that @var{name} is known 7807to refer to a compiler-generated label. The default definition uses 7808@code{assemble_name_raw}, which is like @code{assemble_name} except 7809that it is more efficient. 7810@end defmac 7811 7812@defmac SIZE_ASM_OP 7813A C string containing the appropriate assembler directive to specify the 7814size of a symbol, without any arguments. On systems that use ELF, the 7815default (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other 7816systems, the default is not to define this macro. 7817 7818Define this macro only if it is correct to use the default definitions 7819of @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE} 7820for your system. If you need your own custom definitions of those 7821macros, or if you do not need explicit symbol sizes at all, do not 7822define this macro. 7823@end defmac 7824 7825@defmac ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) 7826A C statement (sans semicolon) to output to the stdio stream 7827@var{stream} a directive telling the assembler that the size of the 7828symbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}. 7829If you define @code{SIZE_ASM_OP}, a default definition of this macro is 7830provided. 7831@end defmac 7832 7833@defmac ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) 7834A C statement (sans semicolon) to output to the stdio stream 7835@var{stream} a directive telling the assembler to calculate the size of 7836the symbol @var{name} by subtracting its address from the current 7837address. 7838 7839If you define @code{SIZE_ASM_OP}, a default definition of this macro is 7840provided. The default assumes that the assembler recognizes a special 7841@samp{.} symbol as referring to the current address, and can calculate 7842the difference between this and another symbol. If your assembler does 7843not recognize @samp{.} or cannot do calculations with it, you will need 7844to redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique. 7845@end defmac 7846 7847@defmac TYPE_ASM_OP 7848A C string containing the appropriate assembler directive to specify the 7849type of a symbol, without any arguments. On systems that use ELF, the 7850default (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other 7851systems, the default is not to define this macro. 7852 7853Define this macro only if it is correct to use the default definition of 7854@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 7855custom definition of this macro, or if you do not need explicit symbol 7856types at all, do not define this macro. 7857@end defmac 7858 7859@defmac TYPE_OPERAND_FMT 7860A C string which specifies (using @code{printf} syntax) the format of 7861the second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the 7862default (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems, 7863the default is not to define this macro. 7864 7865Define this macro only if it is correct to use the default definition of 7866@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 7867custom definition of this macro, or if you do not need explicit symbol 7868types at all, do not define this macro. 7869@end defmac 7870 7871@defmac ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) 7872A C statement (sans semicolon) to output to the stdio stream 7873@var{stream} a directive telling the assembler that the type of the 7874symbol @var{name} is @var{type}. @var{type} is a C string; currently, 7875that string is always either @samp{"function"} or @samp{"object"}, but 7876you should not count on this. 7877 7878If you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default 7879definition of this macro is provided. 7880@end defmac 7881 7882@defmac ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 7883A C statement (sans semicolon) to output to the stdio stream 7884@var{stream} any text necessary for declaring the name @var{name} of a 7885function which is being defined. This macro is responsible for 7886outputting the label definition (perhaps using 7887@code{ASM_OUTPUT_FUNCTION_LABEL}). The argument @var{decl} is the 7888@code{FUNCTION_DECL} tree node representing the function. 7889 7890If this macro is not defined, then the function name is defined in the 7891usual manner as a label (by means of @code{ASM_OUTPUT_FUNCTION_LABEL}). 7892 7893You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 7894of this macro. 7895@end defmac 7896 7897@defmac ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 7898A C statement (sans semicolon) to output to the stdio stream 7899@var{stream} any text necessary for declaring the size of a function 7900which is being defined. The argument @var{name} is the name of the 7901function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 7902representing the function. 7903 7904If this macro is not defined, then the function size is not defined. 7905 7906You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition 7907of this macro. 7908@end defmac 7909 7910@defmac ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 7911A C statement (sans semicolon) to output to the stdio stream 7912@var{stream} any text necessary for declaring the name @var{name} of an 7913initialized variable which is being defined. This macro must output the 7914label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 7915@var{decl} is the @code{VAR_DECL} tree node representing the variable. 7916 7917If this macro is not defined, then the variable name is defined in the 7918usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 7919 7920You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or 7921@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro. 7922@end defmac 7923 7924@deftypefn {Target Hook} void TARGET_ASM_DECLARE_CONSTANT_NAME (FILE *@var{file}, const char *@var{name}, const_tree @var{expr}, HOST_WIDE_INT @var{size}) 7925A target hook to output to the stdio stream @var{file} any text necessary 7926for declaring the name @var{name} of a constant which is being defined. This 7927target hook is responsible for outputting the label definition (perhaps using 7928@code{assemble_label}). The argument @var{exp} is the value of the constant, 7929and @var{size} is the size of the constant in bytes. The @var{name} 7930will be an internal label. 7931 7932The default version of this target hook, define the @var{name} in the 7933usual manner as a label (by means of @code{assemble_label}). 7934 7935You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in this target hook. 7936@end deftypefn 7937 7938@defmac ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 7939A C statement (sans semicolon) to output to the stdio stream 7940@var{stream} any text necessary for claiming a register @var{regno} 7941for a global variable @var{decl} with name @var{name}. 7942 7943If you don't define this macro, that is equivalent to defining it to do 7944nothing. 7945@end defmac 7946 7947@defmac ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 7948A C statement (sans semicolon) to finish up declaring a variable name 7949once the compiler has processed its initializer fully and thus has had a 7950chance to determine the size of an array when controlled by an 7951initializer. This is used on systems where it's necessary to declare 7952something about the size of the object. 7953 7954If you don't define this macro, that is equivalent to defining it to do 7955nothing. 7956 7957You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or 7958@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. 7959@end defmac 7960 7961@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) 7962This target hook is a function to output to the stdio stream 7963@var{stream} some commands that will make the label @var{name} global; 7964that is, available for reference from other files. 7965 7966The default implementation relies on a proper definition of 7967@code{GLOBAL_ASM_OP}. 7968@end deftypefn 7969 7970@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_DECL_NAME (FILE *@var{stream}, tree @var{decl}) 7971This target hook is a function to output to the stdio stream 7972@var{stream} some commands that will make the name associated with @var{decl} 7973global; that is, available for reference from other files. 7974 7975The default implementation uses the TARGET_ASM_GLOBALIZE_LABEL target hook. 7976@end deftypefn 7977 7978@defmac ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 7979A C statement (sans semicolon) to output to the stdio stream 7980@var{stream} some commands that will make the label @var{name} weak; 7981that is, available for reference from other files but only used if 7982no other definition is available. Use the expression 7983@code{assemble_name (@var{stream}, @var{name})} to output the name 7984itself; before and after that, output the additional assembler syntax 7985for making that name weak, and a newline. 7986 7987If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 7988support weak symbols and you should not define the @code{SUPPORTS_WEAK} 7989macro. 7990@end defmac 7991 7992@defmac ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 7993Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 7994@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 7995or variable decl. If @var{value} is not @code{NULL}, this C statement 7996should output to the stdio stream @var{stream} assembler code which 7997defines (equates) the weak symbol @var{name} to have the value 7998@var{value}. If @var{value} is @code{NULL}, it should output commands 7999to make @var{name} weak. 8000@end defmac 8001 8002@defmac ASM_OUTPUT_WEAKREF (@var{stream}, @var{decl}, @var{name}, @var{value}) 8003Outputs a directive that enables @var{name} to be used to refer to 8004symbol @var{value} with weak-symbol semantics. @code{decl} is the 8005declaration of @code{name}. 8006@end defmac 8007 8008@defmac SUPPORTS_WEAK 8009A preprocessor constant expression which evaluates to true if the target 8010supports weak symbols. 8011 8012If you don't define this macro, @file{defaults.h} provides a default 8013definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 8014is defined, the default definition is @samp{1}; otherwise, it is @samp{0}. 8015@end defmac 8016 8017@defmac TARGET_SUPPORTS_WEAK 8018A C expression which evaluates to true if the target supports weak symbols. 8019 8020If you don't define this macro, @file{defaults.h} provides a default 8021definition. The default definition is @samp{(SUPPORTS_WEAK)}. Define 8022this macro if you want to control weak symbol support with a compiler 8023flag such as @option{-melf}. 8024@end defmac 8025 8026@defmac MAKE_DECL_ONE_ONLY (@var{decl}) 8027A C statement (sans semicolon) to mark @var{decl} to be emitted as a 8028public symbol such that extra copies in multiple translation units will 8029be discarded by the linker. Define this macro if your object file 8030format provides support for this concept, such as the @samp{COMDAT} 8031section flags in the Microsoft Windows PE/COFF format, and this support 8032requires changes to @var{decl}, such as putting it in a separate section. 8033@end defmac 8034 8035@defmac SUPPORTS_ONE_ONLY 8036A C expression which evaluates to true if the target supports one-only 8037semantics. 8038 8039If you don't define this macro, @file{varasm.c} provides a default 8040definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 8041definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 8042you want to control one-only symbol support with a compiler flag, or if 8043setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 8044be emitted as one-only. 8045@end defmac 8046 8047@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, int @var{visibility}) 8048This target hook is a function to output to @var{asm_out_file} some 8049commands that will make the symbol(s) associated with @var{decl} have 8050hidden, protected or internal visibility as specified by @var{visibility}. 8051@end deftypefn 8052 8053@defmac TARGET_WEAK_NOT_IN_ARCHIVE_TOC 8054A C expression that evaluates to true if the target's linker expects 8055that weak symbols do not appear in a static archive's table of contents. 8056The default is @code{0}. 8057 8058Leaving weak symbols out of an archive's table of contents means that, 8059if a symbol will only have a definition in one translation unit and 8060will have undefined references from other translation units, that 8061symbol should not be weak. Defining this macro to be nonzero will 8062thus have the effect that certain symbols that would normally be weak 8063(explicit template instantiations, and vtables for polymorphic classes 8064with noninline key methods) will instead be nonweak. 8065 8066The C++ ABI requires this macro to be zero. Define this macro for 8067targets where full C++ ABI compliance is impossible and where linker 8068restrictions require weak symbols to be left out of a static archive's 8069table of contents. 8070@end defmac 8071 8072@defmac ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 8073A C statement (sans semicolon) to output to the stdio stream 8074@var{stream} any text necessary for declaring the name of an external 8075symbol named @var{name} which is referenced in this compilation but 8076not defined. The value of @var{decl} is the tree node for the 8077declaration. 8078 8079This macro need not be defined if it does not need to output anything. 8080The GNU assembler and most Unix assemblers don't require anything. 8081@end defmac 8082 8083@deftypefn {Target Hook} void TARGET_ASM_EXTERNAL_LIBCALL (rtx @var{symref}) 8084This target hook is a function to output to @var{asm_out_file} an assembler 8085pseudo-op to declare a library function name external. The name of the 8086library function is given by @var{symref}, which is a @code{symbol_ref}. 8087@end deftypefn 8088 8089@deftypefn {Target Hook} void TARGET_ASM_MARK_DECL_PRESERVED (const char *@var{symbol}) 8090This target hook is a function to output to @var{asm_out_file} an assembler 8091directive to annotate @var{symbol} as used. The Darwin target uses the 8092.no_dead_code_strip directive. 8093@end deftypefn 8094 8095@defmac ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 8096A C statement (sans semicolon) to output to the stdio stream 8097@var{stream} a reference in assembler syntax to a label named 8098@var{name}. This should add @samp{_} to the front of the name, if that 8099is customary on your operating system, as it is in most Berkeley Unix 8100systems. This macro is used in @code{assemble_name}. 8101@end defmac 8102 8103@deftypefn {Target Hook} tree TARGET_MANGLE_ASSEMBLER_NAME (const char *@var{name}) 8104Given a symbol @var{name}, perform same mangling as @code{varasm.c}'s @code{assemble_name}, but in memory rather than to a file stream, returning result as an @code{IDENTIFIER_NODE}. Required for correct LTO symtabs. The default implementation calls the @code{TARGET_STRIP_NAME_ENCODING} hook and then prepends the @code{USER_LABEL_PREFIX}, if any. 8105@end deftypefn 8106 8107@defmac ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 8108A C statement (sans semicolon) to output a reference to 8109@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 8110will be used to output the name of the symbol. This macro may be used 8111to modify the way a symbol is referenced depending on information 8112encoded by @code{TARGET_ENCODE_SECTION_INFO}. 8113@end defmac 8114 8115@defmac ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 8116A C statement (sans semicolon) to output a reference to @var{buf}, the 8117result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, 8118@code{assemble_name} will be used to output the name of the symbol. 8119This macro is not used by @code{output_asm_label}, or the @code{%l} 8120specifier that calls it; the intention is that this macro should be set 8121when it is necessary to output a label differently when its address is 8122being taken. 8123@end defmac 8124 8125@deftypefn {Target Hook} void TARGET_ASM_INTERNAL_LABEL (FILE *@var{stream}, const char *@var{prefix}, unsigned long @var{labelno}) 8126A function to output to the stdio stream @var{stream} a label whose 8127name is made from the string @var{prefix} and the number @var{labelno}. 8128 8129It is absolutely essential that these labels be distinct from the labels 8130used for user-level functions and variables. Otherwise, certain programs 8131will have name conflicts with internal labels. 8132 8133It is desirable to exclude internal labels from the symbol table of the 8134object file. Most assemblers have a naming convention for labels that 8135should be excluded; on many systems, the letter @samp{L} at the 8136beginning of a label has this effect. You should find out what 8137convention your system uses, and follow it. 8138 8139The default version of this function utilizes @code{ASM_GENERATE_INTERNAL_LABEL}. 8140@end deftypefn 8141 8142@defmac ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 8143A C statement to output to the stdio stream @var{stream} a debug info 8144label whose name is made from the string @var{prefix} and the number 8145@var{num}. This is useful for VLIW targets, where debug info labels 8146may need to be treated differently than branch target labels. On some 8147systems, branch target labels must be at the beginning of instruction 8148bundles, but debug info labels can occur in the middle of instruction 8149bundles. 8150 8151If this macro is not defined, then @code{(*targetm.asm_out.internal_label)} will be 8152used. 8153@end defmac 8154 8155@defmac ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 8156A C statement to store into the string @var{string} a label whose name 8157is made from the string @var{prefix} and the number @var{num}. 8158 8159This string, when output subsequently by @code{assemble_name}, should 8160produce the output that @code{(*targetm.asm_out.internal_label)} would produce 8161with the same @var{prefix} and @var{num}. 8162 8163If the string begins with @samp{*}, then @code{assemble_name} will 8164output the rest of the string unchanged. It is often convenient for 8165@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 8166string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 8167to output the string, and may change it. (Of course, 8168@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 8169you should know what it does on your machine.) 8170@end defmac 8171 8172@defmac ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 8173A C expression to assign to @var{outvar} (which is a variable of type 8174@code{char *}) a newly allocated string made from the string 8175@var{name} and the number @var{number}, with some suitable punctuation 8176added. Use @code{alloca} to get space for the string. 8177 8178The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 8179produce an assembler label for an internal static variable whose name is 8180@var{name}. Therefore, the string must be such as to result in valid 8181assembler code. The argument @var{number} is different each time this 8182macro is executed; it prevents conflicts between similarly-named 8183internal static variables in different scopes. 8184 8185Ideally this string should not be a valid C identifier, to prevent any 8186conflict with the user's own symbols. Most assemblers allow periods 8187or percent signs in assembler symbols; putting at least one of these 8188between the name and the number will suffice. 8189 8190If this macro is not defined, a default definition will be provided 8191which is correct for most systems. 8192@end defmac 8193 8194@defmac ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 8195A C statement to output to the stdio stream @var{stream} assembler code 8196which defines (equates) the symbol @var{name} to have the value @var{value}. 8197 8198@findex SET_ASM_OP 8199If @code{SET_ASM_OP} is defined, a default definition is provided which is 8200correct for most systems. 8201@end defmac 8202 8203@defmac ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 8204A C statement to output to the stdio stream @var{stream} assembler code 8205which defines (equates) the symbol whose tree node is @var{decl_of_name} 8206to have the value of the tree node @var{decl_of_value}. This macro will 8207be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 8208the tree nodes are available. 8209 8210@findex SET_ASM_OP 8211If @code{SET_ASM_OP} is defined, a default definition is provided which is 8212correct for most systems. 8213@end defmac 8214 8215@defmac TARGET_DEFERRED_OUTPUT_DEFS (@var{decl_of_name}, @var{decl_of_value}) 8216A C statement that evaluates to true if the assembler code which defines 8217(equates) the symbol whose tree node is @var{decl_of_name} to have the value 8218of the tree node @var{decl_of_value} should be emitted near the end of the 8219current compilation unit. The default is to not defer output of defines. 8220This macro affects defines output by @samp{ASM_OUTPUT_DEF} and 8221@samp{ASM_OUTPUT_DEF_FROM_DECLS}. 8222@end defmac 8223 8224@defmac ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 8225A C statement to output to the stdio stream @var{stream} assembler code 8226which defines (equates) the weak symbol @var{name} to have the value 8227@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 8228an undefined weak symbol. 8229 8230Define this macro if the target only supports weak aliases; define 8231@code{ASM_OUTPUT_DEF} instead if possible. 8232@end defmac 8233 8234@defmac OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 8235Define this macro to override the default assembler names used for 8236Objective-C methods. 8237 8238The default name is a unique method number followed by the name of the 8239class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 8240the category is also included in the assembler name (e.g.@: 8241@samp{_1_Foo_Bar}). 8242 8243These names are safe on most systems, but make debugging difficult since 8244the method's selector is not present in the name. Therefore, particular 8245systems define other ways of computing names. 8246 8247@var{buf} is an expression of type @code{char *} which gives you a 8248buffer in which to store the name; its length is as long as 8249@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 825050 characters extra. 8251 8252The argument @var{is_inst} specifies whether the method is an instance 8253method or a class method; @var{class_name} is the name of the class; 8254@var{cat_name} is the name of the category (or @code{NULL} if the method is not 8255in a category); and @var{sel_name} is the name of the selector. 8256 8257On systems where the assembler can handle quoted names, you can use this 8258macro to provide more human-readable names. 8259@end defmac 8260 8261@defmac ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) 8262A C statement (sans semicolon) to output to the stdio stream 8263@var{stream} commands to declare that the label @var{name} is an 8264Objective-C class reference. This is only needed for targets whose 8265linkers have special support for NeXT-style runtimes. 8266@end defmac 8267 8268@defmac ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) 8269A C statement (sans semicolon) to output to the stdio stream 8270@var{stream} commands to declare that the label @var{name} is an 8271unresolved Objective-C class reference. This is only needed for targets 8272whose linkers have special support for NeXT-style runtimes. 8273@end defmac 8274 8275@node Initialization 8276@subsection How Initialization Functions Are Handled 8277@cindex initialization routines 8278@cindex termination routines 8279@cindex constructors, output of 8280@cindex destructors, output of 8281 8282The compiled code for certain languages includes @dfn{constructors} 8283(also called @dfn{initialization routines})---functions to initialize 8284data in the program when the program is started. These functions need 8285to be called before the program is ``started''---that is to say, before 8286@code{main} is called. 8287 8288Compiling some languages generates @dfn{destructors} (also called 8289@dfn{termination routines}) that should be called when the program 8290terminates. 8291 8292To make the initialization and termination functions work, the compiler 8293must output something in the assembler code to cause those functions to 8294be called at the appropriate time. When you port the compiler to a new 8295system, you need to specify how to do this. 8296 8297There are two major ways that GCC currently supports the execution of 8298initialization and termination functions. Each way has two variants. 8299Much of the structure is common to all four variations. 8300 8301@findex __CTOR_LIST__ 8302@findex __DTOR_LIST__ 8303The linker must build two lists of these functions---a list of 8304initialization functions, called @code{__CTOR_LIST__}, and a list of 8305termination functions, called @code{__DTOR_LIST__}. 8306 8307Each list always begins with an ignored function pointer (which may hold 83080, @minus{}1, or a count of the function pointers after it, depending on 8309the environment). This is followed by a series of zero or more function 8310pointers to constructors (or destructors), followed by a function 8311pointer containing zero. 8312 8313Depending on the operating system and its executable file format, either 8314@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 8315time and exit time. Constructors are called in reverse order of the 8316list; destructors in forward order. 8317 8318The best way to handle static constructors works only for object file 8319formats which provide arbitrarily-named sections. A section is set 8320aside for a list of constructors, and another for a list of destructors. 8321Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each 8322object file that defines an initialization function also puts a word in 8323the constructor section to point to that function. The linker 8324accumulates all these words into one contiguous @samp{.ctors} section. 8325Termination functions are handled similarly. 8326 8327This method will be chosen as the default by @file{target-def.h} if 8328@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 8329support arbitrary sections, but does support special designated 8330constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 8331and @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 8332 8333When arbitrary sections are available, there are two variants, depending 8334upon how the code in @file{crtstuff.c} is called. On systems that 8335support a @dfn{.init} section which is executed at program startup, 8336parts of @file{crtstuff.c} are compiled into that section. The 8337program is linked by the @command{gcc} driver like this: 8338 8339@smallexample 8340ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 8341@end smallexample 8342 8343The prologue of a function (@code{__init}) appears in the @code{.init} 8344section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 8345for the function @code{__fini} in the @dfn{.fini} section. Normally these 8346files are provided by the operating system or by the GNU C library, but 8347are provided by GCC for a few targets. 8348 8349The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 8350compiled from @file{crtstuff.c}. They contain, among other things, code 8351fragments within the @code{.init} and @code{.fini} sections that branch 8352to routines in the @code{.text} section. The linker will pull all parts 8353of a section together, which results in a complete @code{__init} function 8354that invokes the routines we need at startup. 8355 8356To use this variant, you must define the @code{INIT_SECTION_ASM_OP} 8357macro properly. 8358 8359If no init section is available, when GCC compiles any function called 8360@code{main} (or more accurately, any function designated as a program 8361entry point by the language front end calling @code{expand_main_function}), 8362it inserts a procedure call to @code{__main} as the first executable code 8363after the function prologue. The @code{__main} function is defined 8364in @file{libgcc2.c} and runs the global constructors. 8365 8366In file formats that don't support arbitrary sections, there are again 8367two variants. In the simplest variant, the GNU linker (GNU @code{ld}) 8368and an `a.out' format must be used. In this case, 8369@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 8370entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 8371and with the address of the void function containing the initialization 8372code as its value. The GNU linker recognizes this as a request to add 8373the value to a @dfn{set}; the values are accumulated, and are eventually 8374placed in the executable as a vector in the format described above, with 8375a leading (ignored) count and a trailing zero element. 8376@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 8377section is available, the absence of @code{INIT_SECTION_ASM_OP} causes 8378the compilation of @code{main} to call @code{__main} as above, starting 8379the initialization process. 8380 8381The last variant uses neither arbitrary sections nor the GNU linker. 8382This is preferable when you want to do dynamic linking and when using 8383file formats which the GNU linker does not support, such as `ECOFF'@. In 8384this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 8385termination functions are recognized simply by their names. This requires 8386an extra program in the linkage step, called @command{collect2}. This program 8387pretends to be the linker, for use with GCC; it does its job by running 8388the ordinary linker, but also arranges to include the vectors of 8389initialization and termination functions. These functions are called 8390via @code{__main} as described above. In order to use this method, 8391@code{use_collect2} must be defined in the target in @file{config.gcc}. 8392 8393@ifinfo 8394The following section describes the specific macros that control and 8395customize the handling of initialization and termination functions. 8396@end ifinfo 8397 8398@node Macros for Initialization 8399@subsection Macros Controlling Initialization Routines 8400 8401Here are the macros that control how the compiler handles initialization 8402and termination functions: 8403 8404@defmac INIT_SECTION_ASM_OP 8405If defined, a C string constant, including spacing, for the assembler 8406operation to identify the following data as initialization code. If not 8407defined, GCC will assume such a section does not exist. When you are 8408using special sections for initialization and termination functions, this 8409macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 8410run the initialization functions. 8411@end defmac 8412 8413@defmac HAS_INIT_SECTION 8414If defined, @code{main} will not call @code{__main} as described above. 8415This macro should be defined for systems that control start-up code 8416on a symbol-by-symbol basis, such as OSF/1, and should not 8417be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 8418@end defmac 8419 8420@defmac LD_INIT_SWITCH 8421If defined, a C string constant for a switch that tells the linker that 8422the following symbol is an initialization routine. 8423@end defmac 8424 8425@defmac LD_FINI_SWITCH 8426If defined, a C string constant for a switch that tells the linker that 8427the following symbol is a finalization routine. 8428@end defmac 8429 8430@defmac COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 8431If defined, a C statement that will write a function that can be 8432automatically called when a shared library is loaded. The function 8433should call @var{func}, which takes no arguments. If not defined, and 8434the object format requires an explicit initialization function, then a 8435function called @code{_GLOBAL__DI} will be generated. 8436 8437This function and the following one are used by collect2 when linking a 8438shared library that needs constructors or destructors, or has DWARF2 8439exception tables embedded in the code. 8440@end defmac 8441 8442@defmac COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 8443If defined, a C statement that will write a function that can be 8444automatically called when a shared library is unloaded. The function 8445should call @var{func}, which takes no arguments. If not defined, and 8446the object format requires an explicit finalization function, then a 8447function called @code{_GLOBAL__DD} will be generated. 8448@end defmac 8449 8450@defmac INVOKE__main 8451If defined, @code{main} will call @code{__main} despite the presence of 8452@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 8453where the init section is not actually run automatically, but is still 8454useful for collecting the lists of constructors and destructors. 8455@end defmac 8456 8457@defmac SUPPORTS_INIT_PRIORITY 8458If nonzero, the C++ @code{init_priority} attribute is supported and the 8459compiler should emit instructions to control the order of initialization 8460of objects. If zero, the compiler will issue an error message upon 8461encountering an @code{init_priority} attribute. 8462@end defmac 8463 8464@deftypevr {Target Hook} bool TARGET_HAVE_CTORS_DTORS 8465This value is true if the target supports some ``native'' method of 8466collecting constructors and destructors to be run at startup and exit. 8467It is false if we must use @command{collect2}. 8468@end deftypevr 8469 8470@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 8471If defined, a function that outputs assembler code to arrange to call 8472the function referenced by @var{symbol} at initialization time. 8473 8474Assume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 8475no arguments and with no return value. If the target supports initialization 8476priorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 8477otherwise it must be @code{DEFAULT_INIT_PRIORITY}. 8478 8479If this macro is not defined by the target, a suitable default will 8480be chosen if (1) the target supports arbitrary section names, (2) the 8481target defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 8482is not defined. 8483@end deftypefn 8484 8485@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 8486This is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 8487functions rather than initialization functions. 8488@end deftypefn 8489 8490If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 8491generated for the generated object file will have static linkage. 8492 8493If your system uses @command{collect2} as the means of processing 8494constructors, then that program normally uses @command{nm} to scan 8495an object file for constructor functions to be called. 8496 8497On certain kinds of systems, you can define this macro to make 8498@command{collect2} work faster (and, in some cases, make it work at all): 8499 8500@defmac OBJECT_FORMAT_COFF 8501Define this macro if the system uses COFF (Common Object File Format) 8502object files, so that @command{collect2} can assume this format and scan 8503object files directly for dynamic constructor/destructor functions. 8504 8505This macro is effective only in a native compiler; @command{collect2} as 8506part of a cross compiler always uses @command{nm} for the target machine. 8507@end defmac 8508 8509@defmac REAL_NM_FILE_NAME 8510Define this macro as a C string constant containing the file name to use 8511to execute @command{nm}. The default is to search the path normally for 8512@command{nm}. 8513@end defmac 8514 8515@defmac NM_FLAGS 8516@command{collect2} calls @command{nm} to scan object files for static 8517constructors and destructors and LTO info. By default, @option{-n} is 8518passed. Define @code{NM_FLAGS} to a C string constant if other options 8519are needed to get the same output format as GNU @command{nm -n} 8520produces. 8521@end defmac 8522 8523If your system supports shared libraries and has a program to list the 8524dynamic dependencies of a given library or executable, you can define 8525these macros to enable support for running initialization and 8526termination functions in shared libraries: 8527 8528@defmac LDD_SUFFIX 8529Define this macro to a C string constant containing the name of the program 8530which lists dynamic dependencies, like @command{ldd} under SunOS 4. 8531@end defmac 8532 8533@defmac PARSE_LDD_OUTPUT (@var{ptr}) 8534Define this macro to be C code that extracts filenames from the output 8535of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 8536of type @code{char *} that points to the beginning of a line of output 8537from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 8538code must advance @var{ptr} to the beginning of the filename on that 8539line. Otherwise, it must set @var{ptr} to @code{NULL}. 8540@end defmac 8541 8542@defmac SHLIB_SUFFIX 8543Define this macro to a C string constant containing the default shared 8544library extension of the target (e.g., @samp{".so"}). @command{collect2} 8545strips version information after this suffix when generating global 8546constructor and destructor names. This define is only needed on targets 8547that use @command{collect2} to process constructors and destructors. 8548@end defmac 8549 8550@node Instruction Output 8551@subsection Output of Assembler Instructions 8552 8553@c prevent bad page break with this line 8554This describes assembler instruction output. 8555 8556@defmac REGISTER_NAMES 8557A C initializer containing the assembler's names for the machine 8558registers, each one as a C string constant. This is what translates 8559register numbers in the compiler into assembler language. 8560@end defmac 8561 8562@defmac ADDITIONAL_REGISTER_NAMES 8563If defined, a C initializer for an array of structures containing a name 8564and a register number. This macro defines additional names for hard 8565registers, thus allowing the @code{asm} option in declarations to refer 8566to registers using alternate names. 8567@end defmac 8568 8569@defmac OVERLAPPING_REGISTER_NAMES 8570If defined, a C initializer for an array of structures containing a 8571name, a register number and a count of the number of consecutive 8572machine registers the name overlaps. This macro defines additional 8573names for hard registers, thus allowing the @code{asm} option in 8574declarations to refer to registers using alternate names. Unlike 8575@code{ADDITIONAL_REGISTER_NAMES}, this macro should be used when the 8576register name implies multiple underlying registers. 8577 8578This macro should be used when it is important that a clobber in an 8579@code{asm} statement clobbers all the underlying values implied by the 8580register name. For example, on ARM, clobbering the double-precision 8581VFP register ``d0'' implies clobbering both single-precision registers 8582``s0'' and ``s1''. 8583@end defmac 8584 8585@defmac ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 8586Define this macro if you are using an unusual assembler that 8587requires different names for the machine instructions. 8588 8589The definition is a C statement or statements which output an 8590assembler instruction opcode to the stdio stream @var{stream}. The 8591macro-operand @var{ptr} is a variable of type @code{char *} which 8592points to the opcode name in its ``internal'' form---the form that is 8593written in the machine description. The definition should output the 8594opcode name to @var{stream}, performing any translation you desire, and 8595increment the variable @var{ptr} to point at the end of the opcode 8596so that it will not be output twice. 8597 8598In fact, your macro definition may process less than the entire opcode 8599name, or more than the opcode name; but if you want to process text 8600that includes @samp{%}-sequences to substitute operands, you must take 8601care of the substitution yourself. Just be sure to increment 8602@var{ptr} over whatever text should not be output normally. 8603 8604@findex recog_data.operand 8605If you need to look at the operand values, they can be found as the 8606elements of @code{recog_data.operand}. 8607 8608If the macro definition does nothing, the instruction is output 8609in the usual way. 8610@end defmac 8611 8612@defmac FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 8613If defined, a C statement to be executed just prior to the output of 8614assembler code for @var{insn}, to modify the extracted operands so 8615they will be output differently. 8616 8617Here the argument @var{opvec} is the vector containing the operands 8618extracted from @var{insn}, and @var{noperands} is the number of 8619elements of the vector which contain meaningful data for this insn. 8620The contents of this vector are what will be used to convert the insn 8621template into assembler code, so you can change the assembler output 8622by changing the contents of the vector. 8623 8624This macro is useful when various assembler syntaxes share a single 8625file of instruction patterns; by defining this macro differently, you 8626can cause a large class of instructions to be output differently (such 8627as with rearranged operands). Naturally, variations in assembler 8628syntax affecting individual insn patterns ought to be handled by 8629writing conditional output routines in those patterns. 8630 8631If this macro is not defined, it is equivalent to a null statement. 8632@end defmac 8633 8634@deftypefn {Target Hook} void TARGET_ASM_FINAL_POSTSCAN_INSN (FILE *@var{file}, rtx @var{insn}, rtx *@var{opvec}, int @var{noperands}) 8635If defined, this target hook is a function which is executed just after the 8636output of assembler code for @var{insn}, to change the mode of the assembler 8637if necessary. 8638 8639Here the argument @var{opvec} is the vector containing the operands 8640extracted from @var{insn}, and @var{noperands} is the number of 8641elements of the vector which contain meaningful data for this insn. 8642The contents of this vector are what was used to convert the insn 8643template into assembler code, so you can change the assembler mode 8644by checking the contents of the vector. 8645@end deftypefn 8646 8647@defmac PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 8648A C compound statement to output to stdio stream @var{stream} the 8649assembler syntax for an instruction operand @var{x}. @var{x} is an 8650RTL expression. 8651 8652@var{code} is a value that can be used to specify one of several ways 8653of printing the operand. It is used when identical operands must be 8654printed differently depending on the context. @var{code} comes from 8655the @samp{%} specification that was used to request printing of the 8656operand. If the specification was just @samp{%@var{digit}} then 8657@var{code} is 0; if the specification was @samp{%@var{ltr} 8658@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 8659 8660@findex reg_names 8661If @var{x} is a register, this macro should print the register's name. 8662The names can be found in an array @code{reg_names} whose type is 8663@code{char *[]}. @code{reg_names} is initialized from 8664@code{REGISTER_NAMES}. 8665 8666When the machine description has a specification @samp{%@var{punct}} 8667(a @samp{%} followed by a punctuation character), this macro is called 8668with a null pointer for @var{x} and the punctuation character for 8669@var{code}. 8670@end defmac 8671 8672@defmac PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 8673A C expression which evaluates to true if @var{code} is a valid 8674punctuation character for use in the @code{PRINT_OPERAND} macro. If 8675@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 8676punctuation characters (except for the standard one, @samp{%}) are used 8677in this way. 8678@end defmac 8679 8680@defmac PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 8681A C compound statement to output to stdio stream @var{stream} the 8682assembler syntax for an instruction operand that is a memory reference 8683whose address is @var{x}. @var{x} is an RTL expression. 8684 8685@cindex @code{TARGET_ENCODE_SECTION_INFO} usage 8686On some machines, the syntax for a symbolic address depends on the 8687section that the address refers to. On these machines, define the hook 8688@code{TARGET_ENCODE_SECTION_INFO} to store the information into the 8689@code{symbol_ref}, and then check for it here. @xref{Assembler 8690Format}. 8691@end defmac 8692 8693@findex dbr_sequence_length 8694@defmac DBR_OUTPUT_SEQEND (@var{file}) 8695A C statement, to be executed after all slot-filler instructions have 8696been output. If necessary, call @code{dbr_sequence_length} to 8697determine the number of slots filled in a sequence (zero if not 8698currently outputting a sequence), to decide how many no-ops to output, 8699or whatever. 8700 8701Don't define this macro if it has nothing to do, but it is helpful in 8702reading assembly output if the extent of the delay sequence is made 8703explicit (e.g.@: with white space). 8704@end defmac 8705 8706@findex final_sequence 8707Note that output routines for instructions with delay slots must be 8708prepared to deal with not being output as part of a sequence 8709(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 8710found.) The variable @code{final_sequence} is null when not 8711processing a sequence, otherwise it contains the @code{sequence} rtx 8712being output. 8713 8714@findex asm_fprintf 8715@defmac REGISTER_PREFIX 8716@defmacx LOCAL_LABEL_PREFIX 8717@defmacx USER_LABEL_PREFIX 8718@defmacx IMMEDIATE_PREFIX 8719If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 8720@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 8721@file{final.c}). These are useful when a single @file{md} file must 8722support multiple assembler formats. In that case, the various @file{tm.h} 8723files can define these macros differently. 8724@end defmac 8725 8726@defmac ASM_FPRINTF_EXTENSIONS (@var{file}, @var{argptr}, @var{format}) 8727If defined this macro should expand to a series of @code{case} 8728statements which will be parsed inside the @code{switch} statement of 8729the @code{asm_fprintf} function. This allows targets to define extra 8730printf formats which may useful when generating their assembler 8731statements. Note that uppercase letters are reserved for future 8732generic extensions to asm_fprintf, and so are not available to target 8733specific code. The output file is given by the parameter @var{file}. 8734The varargs input pointer is @var{argptr} and the rest of the format 8735string, starting the character after the one that is being switched 8736upon, is pointed to by @var{format}. 8737@end defmac 8738 8739@defmac ASSEMBLER_DIALECT 8740If your target supports multiple dialects of assembler language (such as 8741different opcodes), define this macro as a C expression that gives the 8742numeric index of the assembler language dialect to use, with zero as the 8743first variant. 8744 8745If this macro is defined, you may use constructs of the form 8746@smallexample 8747@samp{@{option0|option1|option2@dots{}@}} 8748@end smallexample 8749@noindent 8750in the output templates of patterns (@pxref{Output Template}) or in the 8751first argument of @code{asm_fprintf}. This construct outputs 8752@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 8753@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 8754within these strings retain their usual meaning. If there are fewer 8755alternatives within the braces than the value of 8756@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 8757 8758If you do not define this macro, the characters @samp{@{}, @samp{|} and 8759@samp{@}} do not have any special meaning when used in templates or 8760operands to @code{asm_fprintf}. 8761 8762Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 8763@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 8764the variations in assembler language syntax with that mechanism. Define 8765@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 8766if the syntax variant are larger and involve such things as different 8767opcodes or operand order. 8768@end defmac 8769 8770@defmac ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 8771A C expression to output to @var{stream} some assembler code 8772which will push hard register number @var{regno} onto the stack. 8773The code need not be optimal, since this macro is used only when 8774profiling. 8775@end defmac 8776 8777@defmac ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 8778A C expression to output to @var{stream} some assembler code 8779which will pop hard register number @var{regno} off of the stack. 8780The code need not be optimal, since this macro is used only when 8781profiling. 8782@end defmac 8783 8784@node Dispatch Tables 8785@subsection Output of Dispatch Tables 8786 8787@c prevent bad page break with this line 8788This concerns dispatch tables. 8789 8790@cindex dispatch table 8791@defmac ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 8792A C statement to output to the stdio stream @var{stream} an assembler 8793pseudo-instruction to generate a difference between two labels. 8794@var{value} and @var{rel} are the numbers of two internal labels. The 8795definitions of these labels are output using 8796@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same 8797way here. For example, 8798 8799@smallexample 8800fprintf (@var{stream}, "\t.word L%d-L%d\n", 8801 @var{value}, @var{rel}) 8802@end smallexample 8803 8804You must provide this macro on machines where the addresses in a 8805dispatch table are relative to the table's own address. If defined, GCC 8806will also use this macro on all machines when producing PIC@. 8807@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 8808mode and flags can be read. 8809@end defmac 8810 8811@defmac ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 8812This macro should be provided on machines where the addresses 8813in a dispatch table are absolute. 8814 8815The definition should be a C statement to output to the stdio stream 8816@var{stream} an assembler pseudo-instruction to generate a reference to 8817a label. @var{value} is the number of an internal label whose 8818definition is output using @code{(*targetm.asm_out.internal_label)}. 8819For example, 8820 8821@smallexample 8822fprintf (@var{stream}, "\t.word L%d\n", @var{value}) 8823@end smallexample 8824@end defmac 8825 8826@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 8827Define this if the label before a jump-table needs to be output 8828specially. The first three arguments are the same as for 8829@code{(*targetm.asm_out.internal_label)}; the fourth argument is the 8830jump-table which follows (a @code{jump_insn} containing an 8831@code{addr_vec} or @code{addr_diff_vec}). 8832 8833This feature is used on system V to output a @code{swbeg} statement 8834for the table. 8835 8836If this macro is not defined, these labels are output with 8837@code{(*targetm.asm_out.internal_label)}. 8838@end defmac 8839 8840@defmac ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 8841Define this if something special must be output at the end of a 8842jump-table. The definition should be a C statement to be executed 8843after the assembler code for the table is written. It should write 8844the appropriate code to stdio stream @var{stream}. The argument 8845@var{table} is the jump-table insn, and @var{num} is the label-number 8846of the preceding label. 8847 8848If this macro is not defined, nothing special is output at the end of 8849the jump-table. 8850@end defmac 8851 8852@deftypefn {Target Hook} void TARGET_ASM_EMIT_UNWIND_LABEL (FILE *@var{stream}, tree @var{decl}, int @var{for_eh}, int @var{empty}) 8853This target hook emits a label at the beginning of each FDE@. It 8854should be defined on targets where FDEs need special labels, and it 8855should write the appropriate label, for the FDE associated with the 8856function declaration @var{decl}, to the stdio stream @var{stream}. 8857The third argument, @var{for_eh}, is a boolean: true if this is for an 8858exception table. The fourth argument, @var{empty}, is a boolean: 8859true if this is a placeholder label for an omitted FDE@. 8860 8861The default is that FDEs are not given nonlocal labels. 8862@end deftypefn 8863 8864@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL (FILE *@var{stream}) 8865This target hook emits a label at the beginning of the exception table. 8866It should be defined on targets where it is desirable for the table 8867to be broken up according to function. 8868 8869The default is that no label is emitted. 8870@end deftypefn 8871 8872@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_PERSONALITY (rtx @var{personality}) 8873If the target implements @code{TARGET_ASM_UNWIND_EMIT}, this hook may be used to emit a directive to install a personality hook into the unwind info. This hook should not be used if dwarf2 unwind info is used. 8874@end deftypefn 8875 8876@deftypefn {Target Hook} void TARGET_ASM_UNWIND_EMIT (FILE *@var{stream}, rtx @var{insn}) 8877This target hook emits assembly directives required to unwind the 8878given instruction. This is only used when @code{TARGET_EXCEPT_UNWIND_INFO} 8879returns @code{UI_TARGET}. 8880@end deftypefn 8881 8882@deftypevr {Target Hook} bool TARGET_ASM_UNWIND_EMIT_BEFORE_INSN 8883True if the @code{TARGET_ASM_UNWIND_EMIT} hook should be called before the assembly for @var{insn} has been emitted, false if the hook should be called afterward. 8884@end deftypevr 8885 8886@node Exception Region Output 8887@subsection Assembler Commands for Exception Regions 8888 8889@c prevent bad page break with this line 8890 8891This describes commands marking the start and the end of an exception 8892region. 8893 8894@defmac EH_FRAME_SECTION_NAME 8895If defined, a C string constant for the name of the section containing 8896exception handling frame unwind information. If not defined, GCC will 8897provide a default definition if the target supports named sections. 8898@file{crtstuff.c} uses this macro to switch to the appropriate section. 8899 8900You should define this symbol if your target supports DWARF 2 frame 8901unwind information and the default definition does not work. 8902@end defmac 8903 8904@defmac EH_FRAME_IN_DATA_SECTION 8905If defined, DWARF 2 frame unwind information will be placed in the 8906data section even though the target supports named sections. This 8907might be necessary, for instance, if the system linker does garbage 8908collection and sections cannot be marked as not to be collected. 8909 8910Do not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 8911also defined. 8912@end defmac 8913 8914@defmac EH_TABLES_CAN_BE_READ_ONLY 8915Define this macro to 1 if your target is such that no frame unwind 8916information encoding used with non-PIC code will ever require a 8917runtime relocation, but the linker may not support merging read-only 8918and read-write sections into a single read-write section. 8919@end defmac 8920 8921@defmac MASK_RETURN_ADDR 8922An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 8923that it does not contain any extraneous set bits in it. 8924@end defmac 8925 8926@defmac DWARF2_UNWIND_INFO 8927Define this macro to 0 if your target supports DWARF 2 frame unwind 8928information, but it does not yet work with exception handling. 8929Otherwise, if your target supports this information (if it defines 8930@code{INCOMING_RETURN_ADDR_RTX} and either @code{UNALIGNED_INT_ASM_OP} 8931or @code{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 1. 8932@end defmac 8933 8934@deftypefn {Common Target Hook} {enum unwind_info_type} TARGET_EXCEPT_UNWIND_INFO (struct gcc_options *@var{opts}) 8935This hook defines the mechanism that will be used for exception handling 8936by the target. If the target has ABI specified unwind tables, the hook 8937should return @code{UI_TARGET}. If the target is to use the 8938@code{setjmp}/@code{longjmp}-based exception handling scheme, the hook 8939should return @code{UI_SJLJ}. If the target supports DWARF 2 frame unwind 8940information, the hook should return @code{UI_DWARF2}. 8941 8942A target may, if exceptions are disabled, choose to return @code{UI_NONE}. 8943This may end up simplifying other parts of target-specific code. The 8944default implementation of this hook never returns @code{UI_NONE}. 8945 8946Note that the value returned by this hook should be constant. It should 8947not depend on anything except the command-line switches described by 8948@var{opts}. In particular, the 8949setting @code{UI_SJLJ} must be fixed at compiler start-up as C pre-processor 8950macros and builtin functions related to exception handling are set up 8951depending on this setting. 8952 8953The default implementation of the hook first honors the 8954@option{--enable-sjlj-exceptions} configure option, then 8955@code{DWARF2_UNWIND_INFO}, and finally defaults to @code{UI_SJLJ}. If 8956@code{DWARF2_UNWIND_INFO} depends on command-line options, the target 8957must define this hook so that @var{opts} is used correctly. 8958@end deftypefn 8959 8960@deftypevr {Common Target Hook} bool TARGET_UNWIND_TABLES_DEFAULT 8961This variable should be set to @code{true} if the target ABI requires unwinding 8962tables even when exceptions are not used. It must not be modified by 8963command-line option processing. 8964@end deftypevr 8965 8966@defmac DONT_USE_BUILTIN_SETJMP 8967Define this macro to 1 if the @code{setjmp}/@code{longjmp}-based scheme 8968should use the @code{setjmp}/@code{longjmp} functions from the C library 8969instead of the @code{__builtin_setjmp}/@code{__builtin_longjmp} machinery. 8970@end defmac 8971 8972@defmac DWARF_CIE_DATA_ALIGNMENT 8973This macro need only be defined if the target might save registers in the 8974function prologue at an offset to the stack pointer that is not aligned to 8975@code{UNITS_PER_WORD}. The definition should be the negative minimum 8976alignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 8977minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 8978the target supports DWARF 2 frame unwind information. 8979@end defmac 8980 8981@deftypevr {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO 8982Contains the value true if the target should add a zero word onto the 8983end of a Dwarf-2 frame info section when used for exception handling. 8984Default value is false if @code{EH_FRAME_SECTION_NAME} is defined, and 8985true otherwise. 8986@end deftypevr 8987 8988@deftypefn {Target Hook} rtx TARGET_DWARF_REGISTER_SPAN (rtx @var{reg}) 8989Given a register, this hook should return a parallel of registers to 8990represent where to find the register pieces. Define this hook if the 8991register and its mode are represented in Dwarf in non-contiguous 8992locations, or if the register should be represented in more than one 8993register in Dwarf. Otherwise, this hook should return @code{NULL_RTX}. 8994If not defined, the default is to return @code{NULL_RTX}. 8995@end deftypefn 8996 8997@deftypefn {Target Hook} void TARGET_INIT_DWARF_REG_SIZES_EXTRA (tree @var{address}) 8998If some registers are represented in Dwarf-2 unwind information in 8999multiple pieces, define this hook to fill in information about the 9000sizes of those pieces in the table used by the unwinder at runtime. 9001It will be called by @code{expand_builtin_init_dwarf_reg_sizes} after 9002filling in a single size corresponding to each hard register; 9003@var{address} is the address of the table. 9004@end deftypefn 9005 9006@deftypefn {Target Hook} bool TARGET_ASM_TTYPE (rtx @var{sym}) 9007This hook is used to output a reference from a frame unwinding table to 9008the type_info object identified by @var{sym}. It should return @code{true} 9009if the reference was output. Returning @code{false} will cause the 9010reference to be output using the normal Dwarf2 routines. 9011@end deftypefn 9012 9013@deftypevr {Target Hook} bool TARGET_ARM_EABI_UNWINDER 9014This flag should be set to @code{true} on targets that use an ARM EABI 9015based unwinding library, and @code{false} on other targets. This effects 9016the format of unwinding tables, and how the unwinder in entered after 9017running a cleanup. The default is @code{false}. 9018@end deftypevr 9019 9020@node Alignment Output 9021@subsection Assembler Commands for Alignment 9022 9023@c prevent bad page break with this line 9024This describes commands for alignment. 9025 9026@defmac JUMP_ALIGN (@var{label}) 9027The alignment (log base 2) to put in front of @var{label}, which is 9028a common destination of jumps and has no fallthru incoming edge. 9029 9030This macro need not be defined if you don't want any special alignment 9031to be done at such a time. Most machine descriptions do not currently 9032define the macro. 9033 9034Unless it's necessary to inspect the @var{label} parameter, it is better 9035to set the variable @var{align_jumps} in the target's 9036@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's 9037selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 9038@end defmac 9039 9040@deftypefn {Target Hook} int TARGET_ASM_JUMP_ALIGN_MAX_SKIP (rtx @var{label}) 9041The maximum number of bytes to skip before @var{label} when applying 9042@code{JUMP_ALIGN}. This works only if 9043@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 9044@end deftypefn 9045 9046@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label}) 9047The alignment (log base 2) to put in front of @var{label}, which follows 9048a @code{BARRIER}. 9049 9050This macro need not be defined if you don't want any special alignment 9051to be done at such a time. Most machine descriptions do not currently 9052define the macro. 9053@end defmac 9054 9055@deftypefn {Target Hook} int TARGET_ASM_LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP (rtx @var{label}) 9056The maximum number of bytes to skip before @var{label} when applying 9057@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 9058@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 9059@end deftypefn 9060 9061@defmac LOOP_ALIGN (@var{label}) 9062The alignment (log base 2) to put in front of @var{label}, which follows 9063a @code{NOTE_INSN_LOOP_BEG} note. 9064 9065This macro need not be defined if you don't want any special alignment 9066to be done at such a time. Most machine descriptions do not currently 9067define the macro. 9068 9069Unless it's necessary to inspect the @var{label} parameter, it is better 9070to set the variable @code{align_loops} in the target's 9071@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's 9072selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 9073@end defmac 9074 9075@deftypefn {Target Hook} int TARGET_ASM_LOOP_ALIGN_MAX_SKIP (rtx @var{label}) 9076The maximum number of bytes to skip when applying @code{LOOP_ALIGN} to 9077@var{label}. This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is 9078defined. 9079@end deftypefn 9080 9081@defmac LABEL_ALIGN (@var{label}) 9082The alignment (log base 2) to put in front of @var{label}. 9083If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 9084the maximum of the specified values is used. 9085 9086Unless it's necessary to inspect the @var{label} parameter, it is better 9087to set the variable @code{align_labels} in the target's 9088@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's 9089selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 9090@end defmac 9091 9092@deftypefn {Target Hook} int TARGET_ASM_LABEL_ALIGN_MAX_SKIP (rtx @var{label}) 9093The maximum number of bytes to skip when applying @code{LABEL_ALIGN} 9094to @var{label}. This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} 9095is defined. 9096@end deftypefn 9097 9098@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 9099A C statement to output to the stdio stream @var{stream} an assembler 9100instruction to advance the location counter by @var{nbytes} bytes. 9101Those bytes should be zero when loaded. @var{nbytes} will be a C 9102expression of type @code{unsigned HOST_WIDE_INT}. 9103@end defmac 9104 9105@defmac ASM_NO_SKIP_IN_TEXT 9106Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 9107text section because it fails to put zeros in the bytes that are skipped. 9108This is true on many Unix systems, where the pseudo--op to skip bytes 9109produces no-op instructions rather than zeros when used in the text 9110section. 9111@end defmac 9112 9113@defmac ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 9114A C statement to output to the stdio stream @var{stream} an assembler 9115command to advance the location counter to a multiple of 2 to the 9116@var{power} bytes. @var{power} will be a C expression of type @code{int}. 9117@end defmac 9118 9119@defmac ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) 9120Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used 9121for padding, if necessary. 9122@end defmac 9123 9124@defmac ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 9125A C statement to output to the stdio stream @var{stream} an assembler 9126command to advance the location counter to a multiple of 2 to the 9127@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 9128satisfy the alignment request. @var{power} and @var{max_skip} will be 9129a C expression of type @code{int}. 9130@end defmac 9131 9132@need 3000 9133@node Debugging Info 9134@section Controlling Debugging Information Format 9135 9136@c prevent bad page break with this line 9137This describes how to specify debugging information. 9138 9139@menu 9140* All Debuggers:: Macros that affect all debugging formats uniformly. 9141* DBX Options:: Macros enabling specific options in DBX format. 9142* DBX Hooks:: Hook macros for varying DBX format. 9143* File Names and DBX:: Macros controlling output of file names in DBX format. 9144* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 9145* VMS Debug:: Macros for VMS debug format. 9146@end menu 9147 9148@node All Debuggers 9149@subsection Macros Affecting All Debugging Formats 9150 9151@c prevent bad page break with this line 9152These macros affect all debugging formats. 9153 9154@defmac DBX_REGISTER_NUMBER (@var{regno}) 9155A C expression that returns the DBX register number for the compiler 9156register number @var{regno}. In the default macro provided, the value 9157of this expression will be @var{regno} itself. But sometimes there are 9158some registers that the compiler knows about and DBX does not, or vice 9159versa. In such cases, some register may need to have one number in the 9160compiler and another for DBX@. 9161 9162If two registers have consecutive numbers inside GCC, and they can be 9163used as a pair to hold a multiword value, then they @emph{must} have 9164consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 9165Otherwise, debuggers will be unable to access such a pair, because they 9166expect register pairs to be consecutive in their own numbering scheme. 9167 9168If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 9169does not preserve register pairs, then what you must do instead is 9170redefine the actual register numbering scheme. 9171@end defmac 9172 9173@defmac DEBUGGER_AUTO_OFFSET (@var{x}) 9174A C expression that returns the integer offset value for an automatic 9175variable having address @var{x} (an RTL expression). The default 9176computation assumes that @var{x} is based on the frame-pointer and 9177gives the offset from the frame-pointer. This is required for targets 9178that produce debugging output for DBX or COFF-style debugging output 9179for SDB and allow the frame-pointer to be eliminated when the 9180@option{-g} options is used. 9181@end defmac 9182 9183@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 9184A C expression that returns the integer offset value for an argument 9185having address @var{x} (an RTL expression). The nominal offset is 9186@var{offset}. 9187@end defmac 9188 9189@defmac PREFERRED_DEBUGGING_TYPE 9190A C expression that returns the type of debugging output GCC should 9191produce when the user specifies just @option{-g}. Define 9192this if you have arranged for GCC to support more than one format of 9193debugging output. Currently, the allowable values are @code{DBX_DEBUG}, 9194@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 9195@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 9196 9197When the user specifies @option{-ggdb}, GCC normally also uses the 9198value of this macro to select the debugging output format, but with two 9199exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined, GCC uses the 9200value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 9201defined, GCC uses @code{DBX_DEBUG}. 9202 9203The value of this macro only affects the default debugging output; the 9204user can always get a specific type of output by using @option{-gstabs}, 9205@option{-gcoff}, @option{-gdwarf-2}, @option{-gxcoff}, or @option{-gvms}. 9206@end defmac 9207 9208@node DBX Options 9209@subsection Specific Options for DBX Output 9210 9211@c prevent bad page break with this line 9212These are specific options for DBX output. 9213 9214@defmac DBX_DEBUGGING_INFO 9215Define this macro if GCC should produce debugging output for DBX 9216in response to the @option{-g} option. 9217@end defmac 9218 9219@defmac XCOFF_DEBUGGING_INFO 9220Define this macro if GCC should produce XCOFF format debugging output 9221in response to the @option{-g} option. This is a variant of DBX format. 9222@end defmac 9223 9224@defmac DEFAULT_GDB_EXTENSIONS 9225Define this macro to control whether GCC should by default generate 9226GDB's extended version of DBX debugging information (assuming DBX-format 9227debugging information is enabled at all). If you don't define the 9228macro, the default is 1: always generate the extended information 9229if there is any occasion to. 9230@end defmac 9231 9232@defmac DEBUG_SYMS_TEXT 9233Define this macro if all @code{.stabs} commands should be output while 9234in the text section. 9235@end defmac 9236 9237@defmac ASM_STABS_OP 9238A C string constant, including spacing, naming the assembler pseudo op to 9239use instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 9240If you don't define this macro, @code{"\t.stabs\t"} is used. This macro 9241applies only to DBX debugging information format. 9242@end defmac 9243 9244@defmac ASM_STABD_OP 9245A C string constant, including spacing, naming the assembler pseudo op to 9246use instead of @code{"\t.stabd\t"} to define a debugging symbol whose 9247value is the current location. If you don't define this macro, 9248@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 9249information format. 9250@end defmac 9251 9252@defmac ASM_STABN_OP 9253A C string constant, including spacing, naming the assembler pseudo op to 9254use instead of @code{"\t.stabn\t"} to define a debugging symbol with no 9255name. If you don't define this macro, @code{"\t.stabn\t"} is used. This 9256macro applies only to DBX debugging information format. 9257@end defmac 9258 9259@defmac DBX_NO_XREFS 9260Define this macro if DBX on your system does not support the construct 9261@samp{xs@var{tagname}}. On some systems, this construct is used to 9262describe a forward reference to a structure named @var{tagname}. 9263On other systems, this construct is not supported at all. 9264@end defmac 9265 9266@defmac DBX_CONTIN_LENGTH 9267A symbol name in DBX-format debugging information is normally 9268continued (split into two separate @code{.stabs} directives) when it 9269exceeds a certain length (by default, 80 characters). On some 9270operating systems, DBX requires this splitting; on others, splitting 9271must not be done. You can inhibit splitting by defining this macro 9272with the value zero. You can override the default splitting-length by 9273defining this macro as an expression for the length you desire. 9274@end defmac 9275 9276@defmac DBX_CONTIN_CHAR 9277Normally continuation is indicated by adding a @samp{\} character to 9278the end of a @code{.stabs} string when a continuation follows. To use 9279a different character instead, define this macro as a character 9280constant for the character you want to use. Do not define this macro 9281if backslash is correct for your system. 9282@end defmac 9283 9284@defmac DBX_STATIC_STAB_DATA_SECTION 9285Define this macro if it is necessary to go to the data section before 9286outputting the @samp{.stabs} pseudo-op for a non-global static 9287variable. 9288@end defmac 9289 9290@defmac DBX_TYPE_DECL_STABS_CODE 9291The value to use in the ``code'' field of the @code{.stabs} directive 9292for a typedef. The default is @code{N_LSYM}. 9293@end defmac 9294 9295@defmac DBX_STATIC_CONST_VAR_CODE 9296The value to use in the ``code'' field of the @code{.stabs} directive 9297for a static variable located in the text section. DBX format does not 9298provide any ``right'' way to do this. The default is @code{N_FUN}. 9299@end defmac 9300 9301@defmac DBX_REGPARM_STABS_CODE 9302The value to use in the ``code'' field of the @code{.stabs} directive 9303for a parameter passed in registers. DBX format does not provide any 9304``right'' way to do this. The default is @code{N_RSYM}. 9305@end defmac 9306 9307@defmac DBX_REGPARM_STABS_LETTER 9308The letter to use in DBX symbol data to identify a symbol as a parameter 9309passed in registers. DBX format does not customarily provide any way to 9310do this. The default is @code{'P'}. 9311@end defmac 9312 9313@defmac DBX_FUNCTION_FIRST 9314Define this macro if the DBX information for a function and its 9315arguments should precede the assembler code for the function. Normally, 9316in DBX format, the debugging information entirely follows the assembler 9317code. 9318@end defmac 9319 9320@defmac DBX_BLOCKS_FUNCTION_RELATIVE 9321Define this macro, with value 1, if the value of a symbol describing 9322the scope of a block (@code{N_LBRAC} or @code{N_RBRAC}) should be 9323relative to the start of the enclosing function. Normally, GCC uses 9324an absolute address. 9325@end defmac 9326 9327@defmac DBX_LINES_FUNCTION_RELATIVE 9328Define this macro, with value 1, if the value of a symbol indicating 9329the current line number (@code{N_SLINE}) should be relative to the 9330start of the enclosing function. Normally, GCC uses an absolute address. 9331@end defmac 9332 9333@defmac DBX_USE_BINCL 9334Define this macro if GCC should generate @code{N_BINCL} and 9335@code{N_EINCL} stabs for included header files, as on Sun systems. This 9336macro also directs GCC to output a type number as a pair of a file 9337number and a type number within the file. Normally, GCC does not 9338generate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 9339number for a type number. 9340@end defmac 9341 9342@node DBX Hooks 9343@subsection Open-Ended Hooks for DBX Format 9344 9345@c prevent bad page break with this line 9346These are hooks for DBX format. 9347 9348@defmac DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 9349Define this macro to say how to output to @var{stream} the debugging 9350information for the start of a scope level for variable names. The 9351argument @var{name} is the name of an assembler symbol (for use with 9352@code{assemble_name}) whose value is the address where the scope begins. 9353@end defmac 9354 9355@defmac DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 9356Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 9357@end defmac 9358 9359@defmac DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 9360Define this macro if the target machine requires special handling to 9361output an @code{N_FUN} entry for the function @var{decl}. 9362@end defmac 9363 9364@defmac DBX_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}, @var{counter}) 9365A C statement to output DBX debugging information before code for line 9366number @var{line} of the current source file to the stdio stream 9367@var{stream}. @var{counter} is the number of time the macro was 9368invoked, including the current invocation; it is intended to generate 9369unique labels in the assembly output. 9370 9371This macro should not be defined if the default output is correct, or 9372if it can be made correct by defining @code{DBX_LINES_FUNCTION_RELATIVE}. 9373@end defmac 9374 9375@defmac NO_DBX_FUNCTION_END 9376Some stabs encapsulation formats (in particular ECOFF), cannot handle the 9377@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 9378On those machines, define this macro to turn this feature off without 9379disturbing the rest of the gdb extensions. 9380@end defmac 9381 9382@defmac NO_DBX_BNSYM_ENSYM 9383Some assemblers cannot handle the @code{.stabd BNSYM/ENSYM,0,0} gdb dbx 9384extension construct. On those machines, define this macro to turn this 9385feature off without disturbing the rest of the gdb extensions. 9386@end defmac 9387 9388@node File Names and DBX 9389@subsection File Names in DBX Format 9390 9391@c prevent bad page break with this line 9392This describes file names in DBX format. 9393 9394@defmac DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 9395A C statement to output DBX debugging information to the stdio stream 9396@var{stream}, which indicates that file @var{name} is the main source 9397file---the file specified as the input file for compilation. 9398This macro is called only once, at the beginning of compilation. 9399 9400This macro need not be defined if the standard form of output 9401for DBX debugging information is appropriate. 9402 9403It may be necessary to refer to a label equal to the beginning of the 9404text section. You can use @samp{assemble_name (stream, ltext_label_name)} 9405to do so. If you do this, you must also set the variable 9406@var{used_ltext_label_name} to @code{true}. 9407@end defmac 9408 9409@defmac NO_DBX_MAIN_SOURCE_DIRECTORY 9410Define this macro, with value 1, if GCC should not emit an indication 9411of the current directory for compilation and current source language at 9412the beginning of the file. 9413@end defmac 9414 9415@defmac NO_DBX_GCC_MARKER 9416Define this macro, with value 1, if GCC should not emit an indication 9417that this object file was compiled by GCC@. The default is to emit 9418an @code{N_OPT} stab at the beginning of every source file, with 9419@samp{gcc2_compiled.} for the string and value 0. 9420@end defmac 9421 9422@defmac DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 9423A C statement to output DBX debugging information at the end of 9424compilation of the main source file @var{name}. Output should be 9425written to the stdio stream @var{stream}. 9426 9427If you don't define this macro, nothing special is output at the end 9428of compilation, which is correct for most machines. 9429@end defmac 9430 9431@defmac DBX_OUTPUT_NULL_N_SO_AT_MAIN_SOURCE_FILE_END 9432Define this macro @emph{instead of} defining 9433@code{DBX_OUTPUT_MAIN_SOURCE_FILE_END}, if what needs to be output at 9434the end of compilation is an @code{N_SO} stab with an empty string, 9435whose value is the highest absolute text address in the file. 9436@end defmac 9437 9438@need 2000 9439@node SDB and DWARF 9440@subsection Macros for SDB and DWARF Output 9441 9442@c prevent bad page break with this line 9443Here are macros for SDB and DWARF output. 9444 9445@defmac SDB_DEBUGGING_INFO 9446Define this macro if GCC should produce COFF-style debugging output 9447for SDB in response to the @option{-g} option. 9448@end defmac 9449 9450@defmac DWARF2_DEBUGGING_INFO 9451Define this macro if GCC should produce dwarf version 2 format 9452debugging output in response to the @option{-g} option. 9453 9454@deftypefn {Target Hook} int TARGET_DWARF_CALLING_CONVENTION (const_tree @var{function}) 9455Define this to enable the dwarf attribute @code{DW_AT_calling_convention} to 9456be emitted for each function. Instead of an integer return the enum 9457value for the @code{DW_CC_} tag. 9458@end deftypefn 9459 9460To support optional call frame debugging information, you must also 9461define @code{INCOMING_RETURN_ADDR_RTX} and either set 9462@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 9463prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 9464as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 9465@end defmac 9466 9467@defmac DWARF2_FRAME_INFO 9468Define this macro to a nonzero value if GCC should always output 9469Dwarf 2 frame information. If @code{TARGET_EXCEPT_UNWIND_INFO} 9470(@pxref{Exception Region Output}) returns @code{UI_DWARF2}, and 9471exceptions are enabled, GCC will output this information not matter 9472how you define @code{DWARF2_FRAME_INFO}. 9473@end defmac 9474 9475@deftypefn {Target Hook} {enum unwind_info_type} TARGET_DEBUG_UNWIND_INFO (void) 9476This hook defines the mechanism that will be used for describing frame 9477unwind information to the debugger. Normally the hook will return 9478@code{UI_DWARF2} if DWARF 2 debug information is enabled, and 9479return @code{UI_NONE} otherwise. 9480 9481A target may return @code{UI_DWARF2} even when DWARF 2 debug information 9482is disabled in order to always output DWARF 2 frame information. 9483 9484A target may return @code{UI_TARGET} if it has ABI specified unwind tables. 9485This will suppress generation of the normal debug frame unwind information. 9486@end deftypefn 9487 9488@defmac DWARF2_ASM_LINE_DEBUG_INFO 9489Define this macro to be a nonzero value if the assembler can generate Dwarf 2 9490line debug info sections. This will result in much more compact line number 9491tables, and hence is desirable if it works. 9492@end defmac 9493 9494@deftypevr {Target Hook} bool TARGET_WANT_DEBUG_PUB_SECTIONS 9495True if the @code{.debug_pubtypes} and @code{.debug_pubnames} sections should be emitted. These sections are not used on most platforms, and in particular GDB does not use them. 9496@end deftypevr 9497 9498@deftypevr {Target Hook} bool TARGET_DELAY_SCHED2 9499True if sched2 is not to be run at its normal place. This usually means it will be run as part of machine-specific reorg. 9500@end deftypevr 9501 9502@deftypevr {Target Hook} bool TARGET_DELAY_VARTRACK 9503True if vartrack is not to be run at its normal place. This usually means it will be run as part of machine-specific reorg. 9504@end deftypevr 9505 9506@defmac ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 9507A C statement to issue assembly directives that create a difference 9508@var{lab1} minus @var{lab2}, using an integer of the given @var{size}. 9509@end defmac 9510 9511@defmac ASM_OUTPUT_DWARF_VMS_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 9512A C statement to issue assembly directives that create a difference 9513between the two given labels in system defined units, e.g. instruction 9514slots on IA64 VMS, using an integer of the given size. 9515@end defmac 9516 9517@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{section}) 9518A C statement to issue assembly directives that create a 9519section-relative reference to the given @var{label}, using an integer of the 9520given @var{size}. The label is known to be defined in the given @var{section}. 9521@end defmac 9522 9523@defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) 9524A C statement to issue assembly directives that create a self-relative 9525reference to the given @var{label}, using an integer of the given @var{size}. 9526@end defmac 9527 9528@defmac ASM_OUTPUT_DWARF_TABLE_REF (@var{label}) 9529A C statement to issue assembly directives that create a reference to 9530the DWARF table identifier @var{label} from the current section. This 9531is used on some systems to avoid garbage collecting a DWARF table which 9532is referenced by a function. 9533@end defmac 9534 9535@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_DWARF_DTPREL (FILE *@var{file}, int @var{size}, rtx @var{x}) 9536If defined, this target hook is a function which outputs a DTP-relative 9537reference to the given TLS symbol of the specified size. 9538@end deftypefn 9539 9540@defmac PUT_SDB_@dots{} 9541Define these macros to override the assembler syntax for the special 9542SDB assembler directives. See @file{sdbout.c} for a list of these 9543macros and their arguments. If the standard syntax is used, you need 9544not define them yourself. 9545@end defmac 9546 9547@defmac SDB_DELIM 9548Some assemblers do not support a semicolon as a delimiter, even between 9549SDB assembler directives. In that case, define this macro to be the 9550delimiter to use (usually @samp{\n}). It is not necessary to define 9551a new set of @code{PUT_SDB_@var{op}} macros if this is the only change 9552required. 9553@end defmac 9554 9555@defmac SDB_ALLOW_UNKNOWN_REFERENCES 9556Define this macro to allow references to unknown structure, 9557union, or enumeration tags to be emitted. Standard COFF does not 9558allow handling of unknown references, MIPS ECOFF has support for 9559it. 9560@end defmac 9561 9562@defmac SDB_ALLOW_FORWARD_REFERENCES 9563Define this macro to allow references to structure, union, or 9564enumeration tags that have not yet been seen to be handled. Some 9565assemblers choke if forward tags are used, while some require it. 9566@end defmac 9567 9568@defmac SDB_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 9569A C statement to output SDB debugging information before code for line 9570number @var{line} of the current source file to the stdio stream 9571@var{stream}. The default is to emit an @code{.ln} directive. 9572@end defmac 9573 9574@need 2000 9575@node VMS Debug 9576@subsection Macros for VMS Debug Format 9577 9578@c prevent bad page break with this line 9579Here are macros for VMS debug format. 9580 9581@defmac VMS_DEBUGGING_INFO 9582Define this macro if GCC should produce debugging output for VMS 9583in response to the @option{-g} option. The default behavior for VMS 9584is to generate minimal debug info for a traceback in the absence of 9585@option{-g} unless explicitly overridden with @option{-g0}. This 9586behavior is controlled by @code{TARGET_OPTION_OPTIMIZATION} and 9587@code{TARGET_OPTION_OVERRIDE}. 9588@end defmac 9589 9590@node Floating Point 9591@section Cross Compilation and Floating Point 9592@cindex cross compilation and floating point 9593@cindex floating point and cross compilation 9594 9595While all modern machines use twos-complement representation for integers, 9596there are a variety of representations for floating point numbers. This 9597means that in a cross-compiler the representation of floating point numbers 9598in the compiled program may be different from that used in the machine 9599doing the compilation. 9600 9601Because different representation systems may offer different amounts of 9602range and precision, all floating point constants must be represented in 9603the target machine's format. Therefore, the cross compiler cannot 9604safely use the host machine's floating point arithmetic; it must emulate 9605the target's arithmetic. To ensure consistency, GCC always uses 9606emulation to work with floating point values, even when the host and 9607target floating point formats are identical. 9608 9609The following macros are provided by @file{real.h} for the compiler to 9610use. All parts of the compiler which generate or optimize 9611floating-point calculations must use these macros. They may evaluate 9612their operands more than once, so operands must not have side effects. 9613 9614@defmac REAL_VALUE_TYPE 9615The C data type to be used to hold a floating point value in the target 9616machine's format. Typically this is a @code{struct} containing an 9617array of @code{HOST_WIDE_INT}, but all code should treat it as an opaque 9618quantity. 9619@end defmac 9620 9621@deftypefn Macro int REAL_VALUES_EQUAL (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 9622Compares for equality the two values, @var{x} and @var{y}. If the target 9623floating point format supports negative zeroes and/or NaNs, 9624@samp{REAL_VALUES_EQUAL (-0.0, 0.0)} is true, and 9625@samp{REAL_VALUES_EQUAL (NaN, NaN)} is false. 9626@end deftypefn 9627 9628@deftypefn Macro int REAL_VALUES_LESS (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 9629Tests whether @var{x} is less than @var{y}. 9630@end deftypefn 9631 9632@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x}) 9633Truncates @var{x} to a signed integer, rounding toward zero. 9634@end deftypefn 9635 9636@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x}) 9637Truncates @var{x} to an unsigned integer, rounding toward zero. If 9638@var{x} is negative, returns zero. 9639@end deftypefn 9640 9641@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, enum machine_mode @var{mode}) 9642Converts @var{string} into a floating point number in the target machine's 9643representation for mode @var{mode}. This routine can handle both 9644decimal and hexadecimal floating point constants, using the syntax 9645defined by the C language for both. 9646@end deftypefn 9647 9648@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x}) 9649Returns 1 if @var{x} is negative (including negative zero), 0 otherwise. 9650@end deftypefn 9651 9652@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x}) 9653Determines whether @var{x} represents infinity (positive or negative). 9654@end deftypefn 9655 9656@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x}) 9657Determines whether @var{x} represents a ``NaN'' (not-a-number). 9658@end deftypefn 9659 9660@deftypefn Macro void REAL_ARITHMETIC (REAL_VALUE_TYPE @var{output}, enum tree_code @var{code}, REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 9661Calculates an arithmetic operation on the two floating point values 9662@var{x} and @var{y}, storing the result in @var{output} (which must be a 9663variable). 9664 9665The operation to be performed is specified by @var{code}. Only the 9666following codes are supported: @code{PLUS_EXPR}, @code{MINUS_EXPR}, 9667@code{MULT_EXPR}, @code{RDIV_EXPR}, @code{MAX_EXPR}, @code{MIN_EXPR}. 9668 9669If @code{REAL_ARITHMETIC} is asked to evaluate division by zero and the 9670target's floating point format cannot represent infinity, it will call 9671@code{abort}. Callers should check for this situation first, using 9672@code{MODE_HAS_INFINITIES}. @xref{Storage Layout}. 9673@end deftypefn 9674 9675@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x}) 9676Returns the negative of the floating point value @var{x}. 9677@end deftypefn 9678 9679@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x}) 9680Returns the absolute value of @var{x}. 9681@end deftypefn 9682 9683@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_TRUNCATE (REAL_VALUE_TYPE @var{mode}, enum machine_mode @var{x}) 9684Truncates the floating point value @var{x} to fit in @var{mode}. The 9685return value is still a full-size @code{REAL_VALUE_TYPE}, but it has an 9686appropriate bit pattern to be output as a floating constant whose 9687precision accords with mode @var{mode}. 9688@end deftypefn 9689 9690@deftypefn Macro void REAL_VALUE_TO_INT (HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, REAL_VALUE_TYPE @var{x}) 9691Converts a floating point value @var{x} into a double-precision integer 9692which is then stored into @var{low} and @var{high}. If the value is not 9693integral, it is truncated. 9694@end deftypefn 9695 9696@deftypefn Macro void REAL_VALUE_FROM_INT (REAL_VALUE_TYPE @var{x}, HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, enum machine_mode @var{mode}) 9697Converts a double-precision integer found in @var{low} and @var{high}, 9698into a floating point value which is then stored into @var{x}. The 9699value is truncated to fit in mode @var{mode}. 9700@end deftypefn 9701 9702@node Mode Switching 9703@section Mode Switching Instructions 9704@cindex mode switching 9705The following macros control mode switching optimizations: 9706 9707@defmac OPTIMIZE_MODE_SWITCHING (@var{entity}) 9708Define this macro if the port needs extra instructions inserted for mode 9709switching in an optimizing compilation. 9710 9711For an example, the SH4 can perform both single and double precision 9712floating point operations, but to perform a single precision operation, 9713the FPSCR PR bit has to be cleared, while for a double precision 9714operation, this bit has to be set. Changing the PR bit requires a general 9715purpose register as a scratch register, hence these FPSCR sets have to 9716be inserted before reload, i.e.@: you can't put this into instruction emitting 9717or @code{TARGET_MACHINE_DEPENDENT_REORG}. 9718 9719You can have multiple entities that are mode-switched, and select at run time 9720which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 9721return nonzero for any @var{entity} that needs mode-switching. 9722If you define this macro, you also have to define 9723@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 9724@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 9725@code{MODE_AFTER}, @code{MODE_ENTRY}, and @code{MODE_EXIT} 9726are optional. 9727@end defmac 9728 9729@defmac NUM_MODES_FOR_MODE_SWITCHING 9730If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 9731initializer for an array of integers. Each initializer element 9732N refers to an entity that needs mode switching, and specifies the number 9733of different modes that might need to be set for this entity. 9734The position of the initializer in the initializer---starting counting at 9735zero---determines the integer that is used to refer to the mode-switched 9736entity in question. 9737In macros that take mode arguments / yield a mode result, modes are 9738represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 9739switch is needed / supplied. 9740@end defmac 9741 9742@defmac MODE_NEEDED (@var{entity}, @var{insn}) 9743@var{entity} is an integer specifying a mode-switched entity. If 9744@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 9745return an integer value not larger than the corresponding element in 9746@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 9747be switched into prior to the execution of @var{insn}. 9748@end defmac 9749 9750@defmac MODE_AFTER (@var{mode}, @var{insn}) 9751If this macro is defined, it is evaluated for every @var{insn} during 9752mode switching. It determines the mode that an insn results in (if 9753different from the incoming mode). 9754@end defmac 9755 9756@defmac MODE_ENTRY (@var{entity}) 9757If this macro is defined, it is evaluated for every @var{entity} that needs 9758mode switching. It should evaluate to an integer, which is a mode that 9759@var{entity} is assumed to be switched to at function entry. If @code{MODE_ENTRY} 9760is defined then @code{MODE_EXIT} must be defined. 9761@end defmac 9762 9763@defmac MODE_EXIT (@var{entity}) 9764If this macro is defined, it is evaluated for every @var{entity} that needs 9765mode switching. It should evaluate to an integer, which is a mode that 9766@var{entity} is assumed to be switched to at function exit. If @code{MODE_EXIT} 9767is defined then @code{MODE_ENTRY} must be defined. 9768@end defmac 9769 9770@defmac MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 9771This macro specifies the order in which modes for @var{entity} are processed. 97720 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 9773lowest. The value of the macro should be an integer designating a mode 9774for @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 9775(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 9776@code{num_modes_for_mode_switching[@var{entity}] - 1}. 9777@end defmac 9778 9779@defmac EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 9780Generate one or more insns to set @var{entity} to @var{mode}. 9781@var{hard_reg_live} is the set of hard registers live at the point where 9782the insn(s) are to be inserted. 9783@end defmac 9784 9785@node Target Attributes 9786@section Defining target-specific uses of @code{__attribute__} 9787@cindex target attributes 9788@cindex machine attributes 9789@cindex attributes, target-specific 9790 9791Target-specific attributes may be defined for functions, data and types. 9792These are described using the following target hooks; they also need to 9793be documented in @file{extend.texi}. 9794 9795@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 9796If defined, this target hook points to an array of @samp{struct 9797attribute_spec} (defined in @file{tree.h}) specifying the machine 9798specific attributes for this target and some of the restrictions on the 9799entities to which these attributes are applied and the arguments they 9800take. 9801@end deftypevr 9802 9803@deftypefn {Target Hook} bool TARGET_ATTRIBUTE_TAKES_IDENTIFIER_P (const_tree @var{name}) 9804If defined, this target hook is a function which returns true if the 9805machine-specific attribute named @var{name} expects an identifier 9806given as its first argument to be passed on as a plain identifier, not 9807subjected to name lookup. If this is not defined, the default is 9808false for all machine-specific attributes. 9809@end deftypefn 9810 9811@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (const_tree @var{type1}, const_tree @var{type2}) 9812If defined, this target hook is a function which returns zero if the attributes on 9813@var{type1} and @var{type2} are incompatible, one if they are compatible, 9814and two if they are nearly compatible (which causes a warning to be 9815generated). If this is not defined, machine-specific attributes are 9816supposed always to be compatible. 9817@end deftypefn 9818 9819@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 9820If defined, this target hook is a function which assigns default attributes to 9821the newly defined @var{type}. 9822@end deftypefn 9823 9824@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 9825Define this target hook if the merging of type attributes needs special 9826handling. If defined, the result is a list of the combined 9827@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 9828that @code{comptypes} has already been called and returned 1. This 9829function may call @code{merge_attributes} to handle machine-independent 9830merging. 9831@end deftypefn 9832 9833@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 9834Define this target hook if the merging of decl attributes needs special 9835handling. If defined, the result is a list of the combined 9836@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 9837@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 9838when this is needed are when one attribute overrides another, or when an 9839attribute is nullified by a subsequent definition. This function may 9840call @code{merge_attributes} to handle machine-independent merging. 9841 9842@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 9843If the only target-specific handling you require is @samp{dllimport} 9844for Microsoft Windows targets, you should define the macro 9845@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES} to @code{1}. The compiler 9846will then define a function called 9847@code{merge_dllimport_decl_attributes} which can then be defined as 9848the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. You can also 9849add @code{handle_dll_attribute} in the attribute table for your port 9850to perform initial processing of the @samp{dllimport} and 9851@samp{dllexport} attributes. This is done in @file{i386/cygwin.h} and 9852@file{i386/i386.c}, for example. 9853@end deftypefn 9854 9855@deftypefn {Target Hook} bool TARGET_VALID_DLLIMPORT_ATTRIBUTE_P (const_tree @var{decl}) 9856@var{decl} is a variable or function with @code{__attribute__((dllimport))} specified. Use this hook if the target needs to add extra validation checks to @code{handle_dll_attribute}. 9857@end deftypefn 9858 9859@defmac TARGET_DECLSPEC 9860Define this macro to a nonzero value if you want to treat 9861@code{__declspec(X)} as equivalent to @code{__attribute((X))}. By 9862default, this behavior is enabled only for targets that define 9863@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. The current implementation 9864of @code{__declspec} is via a built-in macro, but you should not rely 9865on this implementation detail. 9866@end defmac 9867 9868@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 9869Define this target hook if you want to be able to add attributes to a decl 9870when it is being created. This is normally useful for back ends which 9871wish to implement a pragma by using the attributes which correspond to 9872the pragma's effect. The @var{node} argument is the decl which is being 9873created. The @var{attr_ptr} argument is a pointer to the attribute list 9874for this decl. The list itself should not be modified, since it may be 9875shared with other decls, but attributes may be chained on the head of 9876the list and @code{*@var{attr_ptr}} modified to point to the new 9877attributes, or a copy of the list may be made if further changes are 9878needed. 9879@end deftypefn 9880 9881@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (const_tree @var{fndecl}) 9882@cindex inlining 9883This target hook returns @code{true} if it is ok to inline @var{fndecl} 9884into the current function, despite its having target-specific 9885attributes, @code{false} otherwise. By default, if a function has a 9886target specific attribute attached to it, it will not be inlined. 9887@end deftypefn 9888 9889@deftypefn {Target Hook} bool TARGET_OPTION_VALID_ATTRIBUTE_P (tree @var{fndecl}, tree @var{name}, tree @var{args}, int @var{flags}) 9890This hook is called to parse the @code{attribute(option("..."))}, and 9891it allows the function to set different target machine compile time 9892options for the current function that might be different than the 9893options specified on the command line. The hook should return 9894@code{true} if the options are valid. 9895 9896The hook should set the @var{DECL_FUNCTION_SPECIFIC_TARGET} field in 9897the function declaration to hold a pointer to a target specific 9898@var{struct cl_target_option} structure. 9899@end deftypefn 9900 9901@deftypefn {Target Hook} void TARGET_OPTION_SAVE (struct cl_target_option *@var{ptr}) 9902This hook is called to save any additional target specific information 9903in the @var{struct cl_target_option} structure for function specific 9904options. 9905@xref{Option file format}. 9906@end deftypefn 9907 9908@deftypefn {Target Hook} void TARGET_OPTION_RESTORE (struct cl_target_option *@var{ptr}) 9909This hook is called to restore any additional target specific 9910information in the @var{struct cl_target_option} structure for 9911function specific options. 9912@end deftypefn 9913 9914@deftypefn {Target Hook} void TARGET_OPTION_PRINT (FILE *@var{file}, int @var{indent}, struct cl_target_option *@var{ptr}) 9915This hook is called to print any additional target specific 9916information in the @var{struct cl_target_option} structure for 9917function specific options. 9918@end deftypefn 9919 9920@deftypefn {Target Hook} bool TARGET_OPTION_PRAGMA_PARSE (tree @var{args}, tree @var{pop_target}) 9921This target hook parses the options for @code{#pragma GCC option} to 9922set the machine specific options for functions that occur later in the 9923input stream. The options should be the same as handled by the 9924@code{TARGET_OPTION_VALID_ATTRIBUTE_P} hook. 9925@end deftypefn 9926 9927@deftypefn {Target Hook} void TARGET_OPTION_OVERRIDE (void) 9928Sometimes certain combinations of command options do not make sense on 9929a particular target machine. You can override the hook 9930@code{TARGET_OPTION_OVERRIDE} to take account of this. This hooks is called 9931once just after all the command options have been parsed. 9932 9933Don't use this hook to turn on various extra optimizations for 9934@option{-O}. That is what @code{TARGET_OPTION_OPTIMIZATION} is for. 9935 9936If you need to do something whenever the optimization level is 9937changed via the optimize attribute or pragma, see 9938@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE} 9939@end deftypefn 9940 9941@deftypefn {Target Hook} bool TARGET_CAN_INLINE_P (tree @var{caller}, tree @var{callee}) 9942This target hook returns @code{false} if the @var{caller} function 9943cannot inline @var{callee}, based on target specific information. By 9944default, inlining is not allowed if the callee function has function 9945specific target options and the caller does not use the same options. 9946@end deftypefn 9947 9948@node Emulated TLS 9949@section Emulating TLS 9950@cindex Emulated TLS 9951 9952For targets whose psABI does not provide Thread Local Storage via 9953specific relocations and instruction sequences, an emulation layer is 9954used. A set of target hooks allows this emulation layer to be 9955configured for the requirements of a particular target. For instance 9956the psABI may in fact specify TLS support in terms of an emulation 9957layer. 9958 9959The emulation layer works by creating a control object for every TLS 9960object. To access the TLS object, a lookup function is provided 9961which, when given the address of the control object, will return the 9962address of the current thread's instance of the TLS object. 9963 9964@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_GET_ADDRESS 9965Contains the name of the helper function that uses a TLS control 9966object to locate a TLS instance. The default causes libgcc's 9967emulated TLS helper function to be used. 9968@end deftypevr 9969 9970@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_REGISTER_COMMON 9971Contains the name of the helper function that should be used at 9972program startup to register TLS objects that are implicitly 9973initialized to zero. If this is @code{NULL}, all TLS objects will 9974have explicit initializers. The default causes libgcc's emulated TLS 9975registration function to be used. 9976@end deftypevr 9977 9978@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_VAR_SECTION 9979Contains the name of the section in which TLS control variables should 9980be placed. The default of @code{NULL} allows these to be placed in 9981any section. 9982@end deftypevr 9983 9984@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_TMPL_SECTION 9985Contains the name of the section in which TLS initializers should be 9986placed. The default of @code{NULL} allows these to be placed in any 9987section. 9988@end deftypevr 9989 9990@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_VAR_PREFIX 9991Contains the prefix to be prepended to TLS control variable names. 9992The default of @code{NULL} uses a target-specific prefix. 9993@end deftypevr 9994 9995@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_TMPL_PREFIX 9996Contains the prefix to be prepended to TLS initializer objects. The 9997default of @code{NULL} uses a target-specific prefix. 9998@end deftypevr 9999 10000@deftypefn {Target Hook} tree TARGET_EMUTLS_VAR_FIELDS (tree @var{type}, tree *@var{name}) 10001Specifies a function that generates the FIELD_DECLs for a TLS control 10002object type. @var{type} is the RECORD_TYPE the fields are for and 10003@var{name} should be filled with the structure tag, if the default of 10004@code{__emutls_object} is unsuitable. The default creates a type suitable 10005for libgcc's emulated TLS function. 10006@end deftypefn 10007 10008@deftypefn {Target Hook} tree TARGET_EMUTLS_VAR_INIT (tree @var{var}, tree @var{decl}, tree @var{tmpl_addr}) 10009Specifies a function that generates the CONSTRUCTOR to initialize a 10010TLS control object. @var{var} is the TLS control object, @var{decl} 10011is the TLS object and @var{tmpl_addr} is the address of the 10012initializer. The default initializes libgcc's emulated TLS control object. 10013@end deftypefn 10014 10015@deftypevr {Target Hook} bool TARGET_EMUTLS_VAR_ALIGN_FIXED 10016Specifies whether the alignment of TLS control variable objects is 10017fixed and should not be increased as some backends may do to optimize 10018single objects. The default is false. 10019@end deftypevr 10020 10021@deftypevr {Target Hook} bool TARGET_EMUTLS_DEBUG_FORM_TLS_ADDRESS 10022Specifies whether a DWARF @code{DW_OP_form_tls_address} location descriptor 10023may be used to describe emulated TLS control objects. 10024@end deftypevr 10025 10026@node MIPS Coprocessors 10027@section Defining coprocessor specifics for MIPS targets. 10028@cindex MIPS coprocessor-definition macros 10029 10030The MIPS specification allows MIPS implementations to have as many as 4 10031coprocessors, each with as many as 32 private registers. GCC supports 10032accessing these registers and transferring values between the registers 10033and memory using asm-ized variables. For example: 10034 10035@smallexample 10036 register unsigned int cp0count asm ("c0r1"); 10037 unsigned int d; 10038 10039 d = cp0count + 3; 10040@end smallexample 10041 10042(``c0r1'' is the default name of register 1 in coprocessor 0; alternate 10043names may be added as described below, or the default names may be 10044overridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.) 10045 10046Coprocessor registers are assumed to be epilogue-used; sets to them will 10047be preserved even if it does not appear that the register is used again 10048later in the function. 10049 10050Another note: according to the MIPS spec, coprocessor 1 (if present) is 10051the FPU@. One accesses COP1 registers through standard mips 10052floating-point support; they are not included in this mechanism. 10053 10054There is one macro used in defining the MIPS coprocessor interface which 10055you may want to override in subtargets; it is described below. 10056 10057@defmac ALL_COP_ADDITIONAL_REGISTER_NAMES 10058A comma-separated list (with leading comma) of pairs describing the 10059alternate names of coprocessor registers. The format of each entry should be 10060@smallexample 10061@{ @var{alternatename}, @var{register_number}@} 10062@end smallexample 10063Default: empty. 10064@end defmac 10065 10066@node PCH Target 10067@section Parameters for Precompiled Header Validity Checking 10068@cindex parameters, precompiled headers 10069 10070@deftypefn {Target Hook} {void *} TARGET_GET_PCH_VALIDITY (size_t *@var{sz}) 10071This hook returns a pointer to the data needed by 10072@code{TARGET_PCH_VALID_P} and sets 10073@samp{*@var{sz}} to the size of the data in bytes. 10074@end deftypefn 10075 10076@deftypefn {Target Hook} {const char *} TARGET_PCH_VALID_P (const void *@var{data}, size_t @var{sz}) 10077This hook checks whether the options used to create a PCH file are 10078compatible with the current settings. It returns @code{NULL} 10079if so and a suitable error message if not. Error messages will 10080be presented to the user and must be localized using @samp{_(@var{msg})}. 10081 10082@var{data} is the data that was returned by @code{TARGET_GET_PCH_VALIDITY} 10083when the PCH file was created and @var{sz} is the size of that data in bytes. 10084It's safe to assume that the data was created by the same version of the 10085compiler, so no format checking is needed. 10086 10087The default definition of @code{default_pch_valid_p} should be 10088suitable for most targets. 10089@end deftypefn 10090 10091@deftypefn {Target Hook} {const char *} TARGET_CHECK_PCH_TARGET_FLAGS (int @var{pch_flags}) 10092If this hook is nonnull, the default implementation of 10093@code{TARGET_PCH_VALID_P} will use it to check for compatible values 10094of @code{target_flags}. @var{pch_flags} specifies the value that 10095@code{target_flags} had when the PCH file was created. The return 10096value is the same as for @code{TARGET_PCH_VALID_P}. 10097@end deftypefn 10098 10099@deftypefn {Target Hook} void TARGET_PREPARE_PCH_SAVE (void) 10100Called before writing out a PCH file. If the target has some 10101garbage-collected data that needs to be in a particular state on PCH loads, 10102it can use this hook to enforce that state. Very few targets need 10103to do anything here. 10104@end deftypefn 10105 10106@node C++ ABI 10107@section C++ ABI parameters 10108@cindex parameters, c++ abi 10109 10110@deftypefn {Target Hook} tree TARGET_CXX_GUARD_TYPE (void) 10111Define this hook to override the integer type used for guard variables. 10112These are used to implement one-time construction of static objects. The 10113default is long_long_integer_type_node. 10114@end deftypefn 10115 10116@deftypefn {Target Hook} bool TARGET_CXX_GUARD_MASK_BIT (void) 10117This hook determines how guard variables are used. It should return 10118@code{false} (the default) if the first byte should be used. A return value of 10119@code{true} indicates that only the least significant bit should be used. 10120@end deftypefn 10121 10122@deftypefn {Target Hook} tree TARGET_CXX_GET_COOKIE_SIZE (tree @var{type}) 10123This hook returns the size of the cookie to use when allocating an array 10124whose elements have the indicated @var{type}. Assumes that it is already 10125known that a cookie is needed. The default is 10126@code{max(sizeof (size_t), alignof(type))}, as defined in section 2.7 of the 10127IA64/Generic C++ ABI@. 10128@end deftypefn 10129 10130@deftypefn {Target Hook} bool TARGET_CXX_COOKIE_HAS_SIZE (void) 10131This hook should return @code{true} if the element size should be stored in 10132array cookies. The default is to return @code{false}. 10133@end deftypefn 10134 10135@deftypefn {Target Hook} int TARGET_CXX_IMPORT_EXPORT_CLASS (tree @var{type}, int @var{import_export}) 10136If defined by a backend this hook allows the decision made to export 10137class @var{type} to be overruled. Upon entry @var{import_export} 10138will contain 1 if the class is going to be exported, @minus{}1 if it is going 10139to be imported and 0 otherwise. This function should return the 10140modified value and perform any other actions necessary to support the 10141backend's targeted operating system. 10142@end deftypefn 10143 10144@deftypefn {Target Hook} bool TARGET_CXX_CDTOR_RETURNS_THIS (void) 10145This hook should return @code{true} if constructors and destructors return 10146the address of the object created/destroyed. The default is to return 10147@code{false}. 10148@end deftypefn 10149 10150@deftypefn {Target Hook} bool TARGET_CXX_KEY_METHOD_MAY_BE_INLINE (void) 10151This hook returns true if the key method for a class (i.e., the method 10152which, if defined in the current translation unit, causes the virtual 10153table to be emitted) may be an inline function. Under the standard 10154Itanium C++ ABI the key method may be an inline function so long as 10155the function is not declared inline in the class definition. Under 10156some variants of the ABI, an inline function can never be the key 10157method. The default is to return @code{true}. 10158@end deftypefn 10159 10160@deftypefn {Target Hook} void TARGET_CXX_DETERMINE_CLASS_DATA_VISIBILITY (tree @var{decl}) 10161@var{decl} is a virtual table, virtual table table, typeinfo object, or other similar implicit class data object that will be emitted with external linkage in this translation unit. No ELF visibility has been explicitly specified. If the target needs to specify a visibility other than that of the containing class, use this hook to set @code{DECL_VISIBILITY} and @code{DECL_VISIBILITY_SPECIFIED}. 10162@end deftypefn 10163 10164@deftypefn {Target Hook} bool TARGET_CXX_CLASS_DATA_ALWAYS_COMDAT (void) 10165This hook returns true (the default) if virtual tables and other 10166similar implicit class data objects are always COMDAT if they have 10167external linkage. If this hook returns false, then class data for 10168classes whose virtual table will be emitted in only one translation 10169unit will not be COMDAT. 10170@end deftypefn 10171 10172@deftypefn {Target Hook} bool TARGET_CXX_LIBRARY_RTTI_COMDAT (void) 10173This hook returns true (the default) if the RTTI information for 10174the basic types which is defined in the C++ runtime should always 10175be COMDAT, false if it should not be COMDAT. 10176@end deftypefn 10177 10178@deftypefn {Target Hook} bool TARGET_CXX_USE_AEABI_ATEXIT (void) 10179This hook returns true if @code{__aeabi_atexit} (as defined by the ARM EABI) 10180should be used to register static destructors when @option{-fuse-cxa-atexit} 10181is in effect. The default is to return false to use @code{__cxa_atexit}. 10182@end deftypefn 10183 10184@deftypefn {Target Hook} bool TARGET_CXX_USE_ATEXIT_FOR_CXA_ATEXIT (void) 10185This hook returns true if the target @code{atexit} function can be used 10186in the same manner as @code{__cxa_atexit} to register C++ static 10187destructors. This requires that @code{atexit}-registered functions in 10188shared libraries are run in the correct order when the libraries are 10189unloaded. The default is to return false. 10190@end deftypefn 10191 10192@deftypefn {Target Hook} void TARGET_CXX_ADJUST_CLASS_AT_DEFINITION (tree @var{type}) 10193@var{type} is a C++ class (i.e., RECORD_TYPE or UNION_TYPE) that has just been defined. Use this hook to make adjustments to the class (eg, tweak visibility or perform any other required target modifications). 10194@end deftypefn 10195 10196@deftypefn {Target Hook} tree TARGET_CXX_DECL_MANGLING_CONTEXT (const_tree @var{decl}) 10197Return target-specific mangling context of @var{decl} or @code{NULL_TREE}. 10198@end deftypefn 10199 10200@node Named Address Spaces 10201@section Adding support for named address spaces 10202@cindex named address spaces 10203 10204The draft technical report of the ISO/IEC JTC1 S22 WG14 N1275 10205standards committee, @cite{Programming Languages - C - Extensions to 10206support embedded processors}, specifies a syntax for embedded 10207processors to specify alternate address spaces. You can configure a 10208GCC port to support section 5.1 of the draft report to add support for 10209address spaces other than the default address space. These address 10210spaces are new keywords that are similar to the @code{volatile} and 10211@code{const} type attributes. 10212 10213Pointers to named address spaces can have a different size than 10214pointers to the generic address space. 10215 10216For example, the SPU port uses the @code{__ea} address space to refer 10217to memory in the host processor, rather than memory local to the SPU 10218processor. Access to memory in the @code{__ea} address space involves 10219issuing DMA operations to move data between the host processor and the 10220local processor memory address space. Pointers in the @code{__ea} 10221address space are either 32 bits or 64 bits based on the 10222@option{-mea32} or @option{-mea64} switches (native SPU pointers are 10223always 32 bits). 10224 10225Internally, address spaces are represented as a small integer in the 10226range 0 to 15 with address space 0 being reserved for the generic 10227address space. 10228 10229To register a named address space qualifier keyword with the C front end, 10230the target may call the @code{c_register_addr_space} routine. For example, 10231the SPU port uses the following to declare @code{__ea} as the keyword for 10232named address space #1: 10233@smallexample 10234#define ADDR_SPACE_EA 1 10235c_register_addr_space ("__ea", ADDR_SPACE_EA); 10236@end smallexample 10237 10238@deftypefn {Target Hook} {enum machine_mode} TARGET_ADDR_SPACE_POINTER_MODE (addr_space_t @var{address_space}) 10239Define this to return the machine mode to use for pointers to 10240@var{address_space} if the target supports named address spaces. 10241The default version of this hook returns @code{ptr_mode} for the 10242generic address space only. 10243@end deftypefn 10244 10245@deftypefn {Target Hook} {enum machine_mode} TARGET_ADDR_SPACE_ADDRESS_MODE (addr_space_t @var{address_space}) 10246Define this to return the machine mode to use for addresses in 10247@var{address_space} if the target supports named address spaces. 10248The default version of this hook returns @code{Pmode} for the 10249generic address space only. 10250@end deftypefn 10251 10252@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_VALID_POINTER_MODE (enum machine_mode @var{mode}, addr_space_t @var{as}) 10253Define this to return nonzero if the port can handle pointers 10254with machine mode @var{mode} to address space @var{as}. This target 10255hook is the same as the @code{TARGET_VALID_POINTER_MODE} target hook, 10256except that it includes explicit named address space support. The default 10257version of this hook returns true for the modes returned by either the 10258@code{TARGET_ADDR_SPACE_POINTER_MODE} or @code{TARGET_ADDR_SPACE_ADDRESS_MODE} 10259target hooks for the given address space. 10260@end deftypefn 10261 10262@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_LEGITIMATE_ADDRESS_P (enum machine_mode @var{mode}, rtx @var{exp}, bool @var{strict}, addr_space_t @var{as}) 10263Define this to return true if @var{exp} is a valid address for mode 10264@var{mode} in the named address space @var{as}. The @var{strict} 10265parameter says whether strict addressing is in effect after reload has 10266finished. This target hook is the same as the 10267@code{TARGET_LEGITIMATE_ADDRESS_P} target hook, except that it includes 10268explicit named address space support. 10269@end deftypefn 10270 10271@deftypefn {Target Hook} rtx TARGET_ADDR_SPACE_LEGITIMIZE_ADDRESS (rtx @var{x}, rtx @var{oldx}, enum machine_mode @var{mode}, addr_space_t @var{as}) 10272Define this to modify an invalid address @var{x} to be a valid address 10273with mode @var{mode} in the named address space @var{as}. This target 10274hook is the same as the @code{TARGET_LEGITIMIZE_ADDRESS} target hook, 10275except that it includes explicit named address space support. 10276@end deftypefn 10277 10278@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_SUBSET_P (addr_space_t @var{subset}, addr_space_t @var{superset}) 10279Define this to return whether the @var{subset} named address space is 10280contained within the @var{superset} named address space. Pointers to 10281a named address space that is a subset of another named address space 10282will be converted automatically without a cast if used together in 10283arithmetic operations. Pointers to a superset address space can be 10284converted to pointers to a subset address space via explicit casts. 10285@end deftypefn 10286 10287@deftypefn {Target Hook} rtx TARGET_ADDR_SPACE_CONVERT (rtx @var{op}, tree @var{from_type}, tree @var{to_type}) 10288Define this to convert the pointer expression represented by the RTL 10289@var{op} with type @var{from_type} that points to a named address 10290space to a new pointer expression with type @var{to_type} that points 10291to a different named address space. When this hook it called, it is 10292guaranteed that one of the two address spaces is a subset of the other, 10293as determined by the @code{TARGET_ADDR_SPACE_SUBSET_P} target hook. 10294@end deftypefn 10295 10296@node Misc 10297@section Miscellaneous Parameters 10298@cindex parameters, miscellaneous 10299 10300@c prevent bad page break with this line 10301Here are several miscellaneous parameters. 10302 10303@defmac HAS_LONG_COND_BRANCH 10304Define this boolean macro to indicate whether or not your architecture 10305has conditional branches that can span all of memory. It is used in 10306conjunction with an optimization that partitions hot and cold basic 10307blocks into separate sections of the executable. If this macro is 10308set to false, gcc will convert any conditional branches that attempt 10309to cross between sections into unconditional branches or indirect jumps. 10310@end defmac 10311 10312@defmac HAS_LONG_UNCOND_BRANCH 10313Define this boolean macro to indicate whether or not your architecture 10314has unconditional branches that can span all of memory. It is used in 10315conjunction with an optimization that partitions hot and cold basic 10316blocks into separate sections of the executable. If this macro is 10317set to false, gcc will convert any unconditional branches that attempt 10318to cross between sections into indirect jumps. 10319@end defmac 10320 10321@defmac CASE_VECTOR_MODE 10322An alias for a machine mode name. This is the machine mode that 10323elements of a jump-table should have. 10324@end defmac 10325 10326@defmac CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 10327Optional: return the preferred mode for an @code{addr_diff_vec} 10328when the minimum and maximum offset are known. If you define this, 10329it enables extra code in branch shortening to deal with @code{addr_diff_vec}. 10330To make this work, you also have to define @code{INSN_ALIGN} and 10331make the alignment for @code{addr_diff_vec} explicit. 10332The @var{body} argument is provided so that the offset_unsigned and scale 10333flags can be updated. 10334@end defmac 10335 10336@defmac CASE_VECTOR_PC_RELATIVE 10337Define this macro to be a C expression to indicate when jump-tables 10338should contain relative addresses. You need not define this macro if 10339jump-tables never contain relative addresses, or jump-tables should 10340contain relative addresses only when @option{-fPIC} or @option{-fPIC} 10341is in effect. 10342@end defmac 10343 10344@deftypefn {Target Hook} {unsigned int} TARGET_CASE_VALUES_THRESHOLD (void) 10345This function return the smallest number of different values for which it 10346is best to use a jump-table instead of a tree of conditional branches. 10347The default is four for machines with a @code{casesi} instruction and 10348five otherwise. This is best for most machines. 10349@end deftypefn 10350 10351@defmac CASE_USE_BIT_TESTS 10352Define this macro to be a C expression to indicate whether C switch 10353statements may be implemented by a sequence of bit tests. This is 10354advantageous on processors that can efficiently implement left shift 10355of 1 by the number of bits held in a register, but inappropriate on 10356targets that would require a loop. By default, this macro returns 10357@code{true} if the target defines an @code{ashlsi3} pattern, and 10358@code{false} otherwise. 10359@end defmac 10360 10361@defmac WORD_REGISTER_OPERATIONS 10362Define this macro if operations between registers with integral mode 10363smaller than a word are always performed on the entire register. 10364Most RISC machines have this property and most CISC machines do not. 10365@end defmac 10366 10367@defmac LOAD_EXTEND_OP (@var{mem_mode}) 10368Define this macro to be a C expression indicating when insns that read 10369memory in @var{mem_mode}, an integral mode narrower than a word, set the 10370bits outside of @var{mem_mode} to be either the sign-extension or the 10371zero-extension of the data read. Return @code{SIGN_EXTEND} for values 10372of @var{mem_mode} for which the 10373insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 10374@code{UNKNOWN} for other modes. 10375 10376This macro is not called with @var{mem_mode} non-integral or with a width 10377greater than or equal to @code{BITS_PER_WORD}, so you may return any 10378value in this case. Do not define this macro if it would always return 10379@code{UNKNOWN}. On machines where this macro is defined, you will normally 10380define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 10381 10382You may return a non-@code{UNKNOWN} value even if for some hard registers 10383the sign extension is not performed, if for the @code{REGNO_REG_CLASS} 10384of these hard registers @code{CANNOT_CHANGE_MODE_CLASS} returns nonzero 10385when the @var{from} mode is @var{mem_mode} and the @var{to} mode is any 10386integral mode larger than this but not larger than @code{word_mode}. 10387 10388You must return @code{UNKNOWN} if for some hard registers that allow this 10389mode, @code{CANNOT_CHANGE_MODE_CLASS} says that they cannot change to 10390@code{word_mode}, but that they can change to another integral mode that 10391is larger then @var{mem_mode} but still smaller than @code{word_mode}. 10392@end defmac 10393 10394@defmac SHORT_IMMEDIATES_SIGN_EXTEND 10395Define this macro if loading short immediate values into registers sign 10396extends. 10397@end defmac 10398 10399@defmac FIXUNS_TRUNC_LIKE_FIX_TRUNC 10400Define this macro if the same instructions that convert a floating 10401point number to a signed fixed point number also convert validly to an 10402unsigned one. 10403@end defmac 10404 10405@deftypefn {Target Hook} {unsigned int} TARGET_MIN_DIVISIONS_FOR_RECIP_MUL (enum machine_mode @var{mode}) 10406When @option{-ffast-math} is in effect, GCC tries to optimize 10407divisions by the same divisor, by turning them into multiplications by 10408the reciprocal. This target hook specifies the minimum number of divisions 10409that should be there for GCC to perform the optimization for a variable 10410of mode @var{mode}. The default implementation returns 3 if the machine 10411has an instruction for the division, and 2 if it does not. 10412@end deftypefn 10413 10414@defmac MOVE_MAX 10415The maximum number of bytes that a single instruction can move quickly 10416between memory and registers or between two memory locations. 10417@end defmac 10418 10419@defmac MAX_MOVE_MAX 10420The maximum number of bytes that a single instruction can move quickly 10421between memory and registers or between two memory locations. If this 10422is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 10423constant value that is the largest value that @code{MOVE_MAX} can have 10424at run-time. 10425@end defmac 10426 10427@defmac SHIFT_COUNT_TRUNCATED 10428A C expression that is nonzero if on this machine the number of bits 10429actually used for the count of a shift operation is equal to the number 10430of bits needed to represent the size of the object being shifted. When 10431this macro is nonzero, the compiler will assume that it is safe to omit 10432a sign-extend, zero-extend, and certain bitwise `and' instructions that 10433truncates the count of a shift operation. On machines that have 10434instructions that act on bit-fields at variable positions, which may 10435include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 10436also enables deletion of truncations of the values that serve as 10437arguments to bit-field instructions. 10438 10439If both types of instructions truncate the count (for shifts) and 10440position (for bit-field operations), or if no variable-position bit-field 10441instructions exist, you should define this macro. 10442 10443However, on some machines, such as the 80386 and the 680x0, truncation 10444only applies to shift operations and not the (real or pretended) 10445bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 10446such machines. Instead, add patterns to the @file{md} file that include 10447the implied truncation of the shift instructions. 10448 10449You need not define this macro if it would always have the value of zero. 10450@end defmac 10451 10452@anchor{TARGET_SHIFT_TRUNCATION_MASK} 10453@deftypefn {Target Hook} {unsigned HOST_WIDE_INT} TARGET_SHIFT_TRUNCATION_MASK (enum machine_mode @var{mode}) 10454This function describes how the standard shift patterns for @var{mode} 10455deal with shifts by negative amounts or by more than the width of the mode. 10456@xref{shift patterns}. 10457 10458On many machines, the shift patterns will apply a mask @var{m} to the 10459shift count, meaning that a fixed-width shift of @var{x} by @var{y} is 10460equivalent to an arbitrary-width shift of @var{x} by @var{y & m}. If 10461this is true for mode @var{mode}, the function should return @var{m}, 10462otherwise it should return 0. A return value of 0 indicates that no 10463particular behavior is guaranteed. 10464 10465Note that, unlike @code{SHIFT_COUNT_TRUNCATED}, this function does 10466@emph{not} apply to general shift rtxes; it applies only to instructions 10467that are generated by the named shift patterns. 10468 10469The default implementation of this function returns 10470@code{GET_MODE_BITSIZE (@var{mode}) - 1} if @code{SHIFT_COUNT_TRUNCATED} 10471and 0 otherwise. This definition is always safe, but if 10472@code{SHIFT_COUNT_TRUNCATED} is false, and some shift patterns 10473nevertheless truncate the shift count, you may get better code 10474by overriding it. 10475@end deftypefn 10476 10477@defmac TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 10478A C expression which is nonzero if on this machine it is safe to 10479``convert'' an integer of @var{inprec} bits to one of @var{outprec} 10480bits (where @var{outprec} is smaller than @var{inprec}) by merely 10481operating on it as if it had only @var{outprec} bits. 10482 10483On many machines, this expression can be 1. 10484 10485@c rearranged this, removed the phrase "it is reported that". this was 10486@c to fix an overfull hbox. --mew 10feb93 10487When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 10488modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 10489If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 10490such cases may improve things. 10491@end defmac 10492 10493@deftypefn {Target Hook} int TARGET_MODE_REP_EXTENDED (enum machine_mode @var{mode}, enum machine_mode @var{rep_mode}) 10494The representation of an integral mode can be such that the values 10495are always extended to a wider integral mode. Return 10496@code{SIGN_EXTEND} if values of @var{mode} are represented in 10497sign-extended form to @var{rep_mode}. Return @code{UNKNOWN} 10498otherwise. (Currently, none of the targets use zero-extended 10499representation this way so unlike @code{LOAD_EXTEND_OP}, 10500@code{TARGET_MODE_REP_EXTENDED} is expected to return either 10501@code{SIGN_EXTEND} or @code{UNKNOWN}. Also no target extends 10502@var{mode} to @var{rep_mode} so that @var{rep_mode} is not the next 10503widest integral mode and currently we take advantage of this fact.) 10504 10505Similarly to @code{LOAD_EXTEND_OP} you may return a non-@code{UNKNOWN} 10506value even if the extension is not performed on certain hard registers 10507as long as for the @code{REGNO_REG_CLASS} of these hard registers 10508@code{CANNOT_CHANGE_MODE_CLASS} returns nonzero. 10509 10510Note that @code{TARGET_MODE_REP_EXTENDED} and @code{LOAD_EXTEND_OP} 10511describe two related properties. If you define 10512@code{TARGET_MODE_REP_EXTENDED (mode, word_mode)} you probably also want 10513to define @code{LOAD_EXTEND_OP (mode)} to return the same type of 10514extension. 10515 10516In order to enforce the representation of @code{mode}, 10517@code{TRULY_NOOP_TRUNCATION} should return false when truncating to 10518@code{mode}. 10519@end deftypefn 10520 10521@defmac STORE_FLAG_VALUE 10522A C expression describing the value returned by a comparison operator 10523with an integral mode and stored by a store-flag instruction 10524(@samp{cstore@var{mode}4}) when the condition is true. This description must 10525apply to @emph{all} the @samp{cstore@var{mode}4} patterns and all the 10526comparison operators whose results have a @code{MODE_INT} mode. 10527 10528A value of 1 or @minus{}1 means that the instruction implementing the 10529comparison operator returns exactly 1 or @minus{}1 when the comparison is true 10530and 0 when the comparison is false. Otherwise, the value indicates 10531which bits of the result are guaranteed to be 1 when the comparison is 10532true. This value is interpreted in the mode of the comparison 10533operation, which is given by the mode of the first operand in the 10534@samp{cstore@var{mode}4} pattern. Either the low bit or the sign bit of 10535@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 10536the compiler. 10537 10538If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 10539generate code that depends only on the specified bits. It can also 10540replace comparison operators with equivalent operations if they cause 10541the required bits to be set, even if the remaining bits are undefined. 10542For example, on a machine whose comparison operators return an 10543@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 10544@samp{0x80000000}, saying that just the sign bit is relevant, the 10545expression 10546 10547@smallexample 10548(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 10549@end smallexample 10550 10551@noindent 10552can be converted to 10553 10554@smallexample 10555(ashift:SI @var{x} (const_int @var{n})) 10556@end smallexample 10557 10558@noindent 10559where @var{n} is the appropriate shift count to move the bit being 10560tested into the sign bit. 10561 10562There is no way to describe a machine that always sets the low-order bit 10563for a true value, but does not guarantee the value of any other bits, 10564but we do not know of any machine that has such an instruction. If you 10565are trying to port GCC to such a machine, include an instruction to 10566perform a logical-and of the result with 1 in the pattern for the 10567comparison operators and let us know at @email{gcc@@gcc.gnu.org}. 10568 10569Often, a machine will have multiple instructions that obtain a value 10570from a comparison (or the condition codes). Here are rules to guide the 10571choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 10572to be used: 10573 10574@itemize @bullet 10575@item 10576Use the shortest sequence that yields a valid definition for 10577@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 10578``normalize'' the value (convert it to, e.g., 1 or 0) than for the 10579comparison operators to do so because there may be opportunities to 10580combine the normalization with other operations. 10581 10582@item 10583For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 10584slightly preferred on machines with expensive jumps and 1 preferred on 10585other machines. 10586 10587@item 10588As a second choice, choose a value of @samp{0x80000001} if instructions 10589exist that set both the sign and low-order bits but do not define the 10590others. 10591 10592@item 10593Otherwise, use a value of @samp{0x80000000}. 10594@end itemize 10595 10596Many machines can produce both the value chosen for 10597@code{STORE_FLAG_VALUE} and its negation in the same number of 10598instructions. On those machines, you should also define a pattern for 10599those cases, e.g., one matching 10600 10601@smallexample 10602(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 10603@end smallexample 10604 10605Some machines can also perform @code{and} or @code{plus} operations on 10606condition code values with less instructions than the corresponding 10607@samp{cstore@var{mode}4} insn followed by @code{and} or @code{plus}. On those 10608machines, define the appropriate patterns. Use the names @code{incscc} 10609and @code{decscc}, respectively, for the patterns which perform 10610@code{plus} or @code{minus} operations on condition code values. See 10611@file{rs6000.md} for some examples. The GNU Superoptimizer can be used to 10612find such instruction sequences on other machines. 10613 10614If this macro is not defined, the default value, 1, is used. You need 10615not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 10616instructions, or if the value generated by these instructions is 1. 10617@end defmac 10618 10619@defmac FLOAT_STORE_FLAG_VALUE (@var{mode}) 10620A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 10621returned when comparison operators with floating-point results are true. 10622Define this macro on machines that have comparison operations that return 10623floating-point values. If there are no such operations, do not define 10624this macro. 10625@end defmac 10626 10627@defmac VECTOR_STORE_FLAG_VALUE (@var{mode}) 10628A C expression that gives a rtx representing the nonzero true element 10629for vector comparisons. The returned rtx should be valid for the inner 10630mode of @var{mode} which is guaranteed to be a vector mode. Define 10631this macro on machines that have vector comparison operations that 10632return a vector result. If there are no such operations, do not define 10633this macro. Typically, this macro is defined as @code{const1_rtx} or 10634@code{constm1_rtx}. This macro may return @code{NULL_RTX} to prevent 10635the compiler optimizing such vector comparison operations for the 10636given mode. 10637@end defmac 10638 10639@defmac CLZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 10640@defmacx CTZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 10641A C expression that indicates whether the architecture defines a value 10642for @code{clz} or @code{ctz} with a zero operand. 10643A result of @code{0} indicates the value is undefined. 10644If the value is defined for only the RTL expression, the macro should 10645evaluate to @code{1}; if the value applies also to the corresponding optab 10646entry (which is normally the case if it expands directly into 10647the corresponding RTL), then the macro should evaluate to @code{2}. 10648In the cases where the value is defined, @var{value} should be set to 10649this value. 10650 10651If this macro is not defined, the value of @code{clz} or 10652@code{ctz} at zero is assumed to be undefined. 10653 10654This macro must be defined if the target's expansion for @code{ffs} 10655relies on a particular value to get correct results. Otherwise it 10656is not necessary, though it may be used to optimize some corner cases, and 10657to provide a default expansion for the @code{ffs} optab. 10658 10659Note that regardless of this macro the ``definedness'' of @code{clz} 10660and @code{ctz} at zero do @emph{not} extend to the builtin functions 10661visible to the user. Thus one may be free to adjust the value at will 10662to match the target expansion of these operations without fear of 10663breaking the API@. 10664@end defmac 10665 10666@defmac Pmode 10667An alias for the machine mode for pointers. On most machines, define 10668this to be the integer mode corresponding to the width of a hardware 10669pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 10670On some machines you must define this to be one of the partial integer 10671modes, such as @code{PSImode}. 10672 10673The width of @code{Pmode} must be at least as large as the value of 10674@code{POINTER_SIZE}. If it is not equal, you must define the macro 10675@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 10676to @code{Pmode}. 10677@end defmac 10678 10679@defmac FUNCTION_MODE 10680An alias for the machine mode used for memory references to functions 10681being called, in @code{call} RTL expressions. On most CISC machines, 10682where an instruction can begin at any byte address, this should be 10683@code{QImode}. On most RISC machines, where all instructions have fixed 10684size and alignment, this should be a mode with the same size and alignment 10685as the machine instruction words - typically @code{SImode} or @code{HImode}. 10686@end defmac 10687 10688@defmac STDC_0_IN_SYSTEM_HEADERS 10689In normal operation, the preprocessor expands @code{__STDC__} to the 10690constant 1, to signify that GCC conforms to ISO Standard C@. On some 10691hosts, like Solaris, the system compiler uses a different convention, 10692where @code{__STDC__} is normally 0, but is 1 if the user specifies 10693strict conformance to the C Standard. 10694 10695Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 10696convention when processing system header files, but when processing user 10697files @code{__STDC__} will always expand to 1. 10698@end defmac 10699 10700@defmac NO_IMPLICIT_EXTERN_C 10701Define this macro if the system header files support C++ as well as C@. 10702This macro inhibits the usual method of using system header files in 10703C++, which is to pretend that the file's contents are enclosed in 10704@samp{extern "C" @{@dots{}@}}. 10705@end defmac 10706 10707@findex #pragma 10708@findex pragma 10709@defmac REGISTER_TARGET_PRAGMAS () 10710Define this macro if you want to implement any target-specific pragmas. 10711If defined, it is a C expression which makes a series of calls to 10712@code{c_register_pragma} or @code{c_register_pragma_with_expansion} 10713for each pragma. The macro may also do any 10714setup required for the pragmas. 10715 10716The primary reason to define this macro is to provide compatibility with 10717other compilers for the same target. In general, we discourage 10718definition of target-specific pragmas for GCC@. 10719 10720If the pragma can be implemented by attributes then you should consider 10721defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 10722 10723Preprocessor macros that appear on pragma lines are not expanded. All 10724@samp{#pragma} directives that do not match any registered pragma are 10725silently ignored, unless the user specifies @option{-Wunknown-pragmas}. 10726@end defmac 10727 10728@deftypefun void c_register_pragma (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 10729@deftypefunx void c_register_pragma_with_expansion (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 10730 10731Each call to @code{c_register_pragma} or 10732@code{c_register_pragma_with_expansion} establishes one pragma. The 10733@var{callback} routine will be called when the preprocessor encounters a 10734pragma of the form 10735 10736@smallexample 10737#pragma [@var{space}] @var{name} @dots{} 10738@end smallexample 10739 10740@var{space} is the case-sensitive namespace of the pragma, or 10741@code{NULL} to put the pragma in the global namespace. The callback 10742routine receives @var{pfile} as its first argument, which can be passed 10743on to cpplib's functions if necessary. You can lex tokens after the 10744@var{name} by calling @code{pragma_lex}. Tokens that are not read by the 10745callback will be silently ignored. The end of the line is indicated by 10746a token of type @code{CPP_EOF}. Macro expansion occurs on the 10747arguments of pragmas registered with 10748@code{c_register_pragma_with_expansion} but not on the arguments of 10749pragmas registered with @code{c_register_pragma}. 10750 10751Note that the use of @code{pragma_lex} is specific to the C and C++ 10752compilers. It will not work in the Java or Fortran compilers, or any 10753other language compilers for that matter. Thus if @code{pragma_lex} is going 10754to be called from target-specific code, it must only be done so when 10755building the C and C++ compilers. This can be done by defining the 10756variables @code{c_target_objs} and @code{cxx_target_objs} in the 10757target entry in the @file{config.gcc} file. These variables should name 10758the target-specific, language-specific object file which contains the 10759code that uses @code{pragma_lex}. Note it will also be necessary to add a 10760rule to the makefile fragment pointed to by @code{tmake_file} that shows 10761how to build this object file. 10762@end deftypefun 10763 10764@defmac HANDLE_PRAGMA_PACK_WITH_EXPANSION 10765Define this macro if macros should be expanded in the 10766arguments of @samp{#pragma pack}. 10767@end defmac 10768 10769@deftypevr {Target Hook} bool TARGET_HANDLE_PRAGMA_EXTERN_PREFIX 10770True if @code{#pragma extern_prefix} is to be supported. 10771@end deftypevr 10772 10773@defmac TARGET_DEFAULT_PACK_STRUCT 10774If your target requires a structure packing default other than 0 (meaning 10775the machine default), define this macro to the necessary value (in bytes). 10776This must be a value that would also be valid to use with 10777@samp{#pragma pack()} (that is, a small power of two). 10778@end defmac 10779 10780@defmac DOLLARS_IN_IDENTIFIERS 10781Define this macro to control use of the character @samp{$} in 10782identifier names for the C family of languages. 0 means @samp{$} is 10783not allowed by default; 1 means it is allowed. 1 is the default; 10784there is no need to define this macro in that case. 10785@end defmac 10786 10787@defmac NO_DOLLAR_IN_LABEL 10788Define this macro if the assembler does not accept the character 10789@samp{$} in label names. By default constructors and destructors in 10790G++ have @samp{$} in the identifiers. If this macro is defined, 10791@samp{.} is used instead. 10792@end defmac 10793 10794@defmac NO_DOT_IN_LABEL 10795Define this macro if the assembler does not accept the character 10796@samp{.} in label names. By default constructors and destructors in G++ 10797have names that use @samp{.}. If this macro is defined, these names 10798are rewritten to avoid @samp{.}. 10799@end defmac 10800 10801@defmac INSN_SETS_ARE_DELAYED (@var{insn}) 10802Define this macro as a C expression that is nonzero if it is safe for the 10803delay slot scheduler to place instructions in the delay slot of @var{insn}, 10804even if they appear to use a resource set or clobbered in @var{insn}. 10805@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 10806every @code{call_insn} has this behavior. On machines where some @code{insn} 10807or @code{jump_insn} is really a function call and hence has this behavior, 10808you should define this macro. 10809 10810You need not define this macro if it would always return zero. 10811@end defmac 10812 10813@defmac INSN_REFERENCES_ARE_DELAYED (@var{insn}) 10814Define this macro as a C expression that is nonzero if it is safe for the 10815delay slot scheduler to place instructions in the delay slot of @var{insn}, 10816even if they appear to set or clobber a resource referenced in @var{insn}. 10817@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 10818some @code{insn} or @code{jump_insn} is really a function call and its operands 10819are registers whose use is actually in the subroutine it calls, you should 10820define this macro. Doing so allows the delay slot scheduler to move 10821instructions which copy arguments into the argument registers into the delay 10822slot of @var{insn}. 10823 10824You need not define this macro if it would always return zero. 10825@end defmac 10826 10827@defmac MULTIPLE_SYMBOL_SPACES 10828Define this macro as a C expression that is nonzero if, in some cases, 10829global symbols from one translation unit may not be bound to undefined 10830symbols in another translation unit without user intervention. For 10831instance, under Microsoft Windows symbols must be explicitly imported 10832from shared libraries (DLLs). 10833 10834You need not define this macro if it would always evaluate to zero. 10835@end defmac 10836 10837@deftypefn {Target Hook} tree TARGET_MD_ASM_CLOBBERS (tree @var{outputs}, tree @var{inputs}, tree @var{clobbers}) 10838This target hook should add to @var{clobbers} @code{STRING_CST} trees for 10839any hard regs the port wishes to automatically clobber for an asm. 10840It should return the result of the last @code{tree_cons} used to add a 10841clobber. The @var{outputs}, @var{inputs} and @var{clobber} lists are the 10842corresponding parameters to the asm and may be inspected to avoid 10843clobbering a register that is an input or output of the asm. You can use 10844@code{tree_overlaps_hard_reg_set}, declared in @file{tree.h}, to test 10845for overlap with regards to asm-declared registers. 10846@end deftypefn 10847 10848@defmac MATH_LIBRARY 10849Define this macro as a C string constant for the linker argument to link 10850in the system math library, minus the initial @samp{"-l"}, or 10851@samp{""} if the target does not have a 10852separate math library. 10853 10854You need only define this macro if the default of @samp{"m"} is wrong. 10855@end defmac 10856 10857@defmac LIBRARY_PATH_ENV 10858Define this macro as a C string constant for the environment variable that 10859specifies where the linker should look for libraries. 10860 10861You need only define this macro if the default of @samp{"LIBRARY_PATH"} 10862is wrong. 10863@end defmac 10864 10865@defmac TARGET_POSIX_IO 10866Define this macro if the target supports the following POSIX@ file 10867functions, access, mkdir and file locking with fcntl / F_SETLKW@. 10868Defining @code{TARGET_POSIX_IO} will enable the test coverage code 10869to use file locking when exiting a program, which avoids race conditions 10870if the program has forked. It will also create directories at run-time 10871for cross-profiling. 10872@end defmac 10873 10874@defmac MAX_CONDITIONAL_EXECUTE 10875 10876A C expression for the maximum number of instructions to execute via 10877conditional execution instructions instead of a branch. A value of 10878@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 108791 if it does use cc0. 10880@end defmac 10881 10882@defmac IFCVT_MODIFY_TESTS (@var{ce_info}, @var{true_expr}, @var{false_expr}) 10883Used if the target needs to perform machine-dependent modifications on the 10884conditionals used for turning basic blocks into conditionally executed code. 10885@var{ce_info} points to a data structure, @code{struct ce_if_block}, which 10886contains information about the currently processed blocks. @var{true_expr} 10887and @var{false_expr} are the tests that are used for converting the 10888then-block and the else-block, respectively. Set either @var{true_expr} or 10889@var{false_expr} to a null pointer if the tests cannot be converted. 10890@end defmac 10891 10892@defmac IFCVT_MODIFY_MULTIPLE_TESTS (@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) 10893Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated 10894if-statements into conditions combined by @code{and} and @code{or} operations. 10895@var{bb} contains the basic block that contains the test that is currently 10896being processed and about to be turned into a condition. 10897@end defmac 10898 10899@defmac IFCVT_MODIFY_INSN (@var{ce_info}, @var{pattern}, @var{insn}) 10900A C expression to modify the @var{PATTERN} of an @var{INSN} that is to 10901be converted to conditional execution format. @var{ce_info} points to 10902a data structure, @code{struct ce_if_block}, which contains information 10903about the currently processed blocks. 10904@end defmac 10905 10906@defmac IFCVT_MODIFY_FINAL (@var{ce_info}) 10907A C expression to perform any final machine dependent modifications in 10908converting code to conditional execution. The involved basic blocks 10909can be found in the @code{struct ce_if_block} structure that is pointed 10910to by @var{ce_info}. 10911@end defmac 10912 10913@defmac IFCVT_MODIFY_CANCEL (@var{ce_info}) 10914A C expression to cancel any machine dependent modifications in 10915converting code to conditional execution. The involved basic blocks 10916can be found in the @code{struct ce_if_block} structure that is pointed 10917to by @var{ce_info}. 10918@end defmac 10919 10920@defmac IFCVT_INIT_EXTRA_FIELDS (@var{ce_info}) 10921A C expression to initialize any extra fields in a @code{struct ce_if_block} 10922structure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. 10923@end defmac 10924 10925@defmac IFCVT_EXTRA_FIELDS 10926If defined, it should expand to a set of field declarations that will be 10927added to the @code{struct ce_if_block} structure. These should be initialized 10928by the @code{IFCVT_INIT_EXTRA_FIELDS} macro. 10929@end defmac 10930 10931@deftypefn {Target Hook} void TARGET_MACHINE_DEPENDENT_REORG (void) 10932If non-null, this hook performs a target-specific pass over the 10933instruction stream. The compiler will run it at all optimization levels, 10934just before the point at which it normally does delayed-branch scheduling. 10935 10936The exact purpose of the hook varies from target to target. Some use 10937it to do transformations that are necessary for correctness, such as 10938laying out in-function constant pools or avoiding hardware hazards. 10939Others use it as an opportunity to do some machine-dependent optimizations. 10940 10941You need not implement the hook if it has nothing to do. The default 10942definition is null. 10943@end deftypefn 10944 10945@deftypefn {Target Hook} void TARGET_INIT_BUILTINS (void) 10946Define this hook if you have any machine-specific built-in functions 10947that need to be defined. It should be a function that performs the 10948necessary setup. 10949 10950Machine specific built-in functions can be useful to expand special machine 10951instructions that would otherwise not normally be generated because 10952they have no equivalent in the source language (for example, SIMD vector 10953instructions or prefetch instructions). 10954 10955To create a built-in function, call the function 10956@code{lang_hooks.builtin_function} 10957which is defined by the language front end. You can use any type nodes set 10958up by @code{build_common_tree_nodes}; 10959only language front ends that use those two functions will call 10960@samp{TARGET_INIT_BUILTINS}. 10961@end deftypefn 10962 10963@deftypefn {Target Hook} tree TARGET_BUILTIN_DECL (unsigned @var{code}, bool @var{initialize_p}) 10964Define this hook if you have any machine-specific built-in functions 10965that need to be defined. It should be a function that returns the 10966builtin function declaration for the builtin function code @var{code}. 10967If there is no such builtin and it cannot be initialized at this time 10968if @var{initialize_p} is true the function should return @code{NULL_TREE}. 10969If @var{code} is out of range the function should return 10970@code{error_mark_node}. 10971@end deftypefn 10972 10973@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 10974 10975Expand a call to a machine specific built-in function that was set up by 10976@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 10977function call; the result should go to @var{target} if that is 10978convenient, and have mode @var{mode} if that is convenient. 10979@var{subtarget} may be used as the target for computing one of 10980@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 10981ignored. This function should return the result of the call to the 10982built-in function. 10983@end deftypefn 10984 10985@deftypefn {Target Hook} tree TARGET_RESOLVE_OVERLOADED_BUILTIN (unsigned int @var{loc}, tree @var{fndecl}, void *@var{arglist}) 10986Select a replacement for a machine specific built-in function that 10987was set up by @samp{TARGET_INIT_BUILTINS}. This is done 10988@emph{before} regular type checking, and so allows the target to 10989implement a crude form of function overloading. @var{fndecl} is the 10990declaration of the built-in function. @var{arglist} is the list of 10991arguments passed to the built-in function. The result is a 10992complete expression that implements the operation, usually 10993another @code{CALL_EXPR}. 10994@var{arglist} really has type @samp{VEC(tree,gc)*} 10995@end deftypefn 10996 10997@deftypefn {Target Hook} tree TARGET_FOLD_BUILTIN (tree @var{fndecl}, int @var{n_args}, tree *@var{argp}, bool @var{ignore}) 10998Fold a call to a machine specific built-in function that was set up by 10999@samp{TARGET_INIT_BUILTINS}. @var{fndecl} is the declaration of the 11000built-in function. @var{n_args} is the number of arguments passed to 11001the function; the arguments themselves are pointed to by @var{argp}. 11002The result is another tree containing a simplified expression for the 11003call's result. If @var{ignore} is true the value will be ignored. 11004@end deftypefn 11005 11006@deftypefn {Target Hook} {const char *} TARGET_INVALID_WITHIN_DOLOOP (const_rtx @var{insn}) 11007 11008Take an instruction in @var{insn} and return NULL if it is valid within a 11009low-overhead loop, otherwise return a string explaining why doloop 11010could not be applied. 11011 11012Many targets use special registers for low-overhead looping. For any 11013instruction that clobbers these this function should return a string indicating 11014the reason why the doloop could not be applied. 11015By default, the RTL loop optimizer does not use a present doloop pattern for 11016loops containing function calls or branch on table instructions. 11017@end deftypefn 11018 11019@defmac MD_CAN_REDIRECT_BRANCH (@var{branch1}, @var{branch2}) 11020 11021Take a branch insn in @var{branch1} and another in @var{branch2}. 11022Return true if redirecting @var{branch1} to the destination of 11023@var{branch2} is possible. 11024 11025On some targets, branches may have a limited range. Optimizing the 11026filling of delay slots can result in branches being redirected, and this 11027may in turn cause a branch offset to overflow. 11028@end defmac 11029 11030@deftypefn {Target Hook} bool TARGET_COMMUTATIVE_P (const_rtx @var{x}, int @var{outer_code}) 11031This target hook returns @code{true} if @var{x} is considered to be commutative. 11032Usually, this is just COMMUTATIVE_P (@var{x}), but the HP PA doesn't consider 11033PLUS to be commutative inside a MEM@. @var{outer_code} is the rtx code 11034of the enclosing rtl, if known, otherwise it is UNKNOWN. 11035@end deftypefn 11036 11037@deftypefn {Target Hook} rtx TARGET_ALLOCATE_INITIAL_VALUE (rtx @var{hard_reg}) 11038 11039When the initial value of a hard register has been copied in a pseudo 11040register, it is often not necessary to actually allocate another register 11041to this pseudo register, because the original hard register or a stack slot 11042it has been saved into can be used. @code{TARGET_ALLOCATE_INITIAL_VALUE} 11043is called at the start of register allocation once for each hard register 11044that had its initial value copied by using 11045@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 11046Possible values are @code{NULL_RTX}, if you don't want 11047to do any special allocation, a @code{REG} rtx---that would typically be 11048the hard register itself, if it is known not to be clobbered---or a 11049@code{MEM}. 11050If you are returning a @code{MEM}, this is only a hint for the allocator; 11051it might decide to use another register anyways. 11052You may use @code{current_function_leaf_function} in the hook, functions 11053that use @code{REG_N_SETS}, to determine if the hard 11054register in question will not be clobbered. 11055The default value of this hook is @code{NULL}, which disables any special 11056allocation. 11057@end deftypefn 11058 11059@deftypefn {Target Hook} int TARGET_UNSPEC_MAY_TRAP_P (const_rtx @var{x}, unsigned @var{flags}) 11060This target hook returns nonzero if @var{x}, an @code{unspec} or 11061@code{unspec_volatile} operation, might cause a trap. Targets can use 11062this hook to enhance precision of analysis for @code{unspec} and 11063@code{unspec_volatile} operations. You may call @code{may_trap_p_1} 11064to analyze inner elements of @var{x} in which case @var{flags} should be 11065passed along. 11066@end deftypefn 11067 11068@deftypefn {Target Hook} void TARGET_SET_CURRENT_FUNCTION (tree @var{decl}) 11069The compiler invokes this hook whenever it changes its current function 11070context (@code{cfun}). You can define this function if 11071the back end needs to perform any initialization or reset actions on a 11072per-function basis. For example, it may be used to implement function 11073attributes that affect register usage or code generation patterns. 11074The argument @var{decl} is the declaration for the new function context, 11075and may be null to indicate that the compiler has left a function context 11076and is returning to processing at the top level. 11077The default hook function does nothing. 11078 11079GCC sets @code{cfun} to a dummy function context during initialization of 11080some parts of the back end. The hook function is not invoked in this 11081situation; you need not worry about the hook being invoked recursively, 11082or when the back end is in a partially-initialized state. 11083@code{cfun} might be @code{NULL} to indicate processing at top level, 11084outside of any function scope. 11085@end deftypefn 11086 11087@defmac TARGET_OBJECT_SUFFIX 11088Define this macro to be a C string representing the suffix for object 11089files on your target machine. If you do not define this macro, GCC will 11090use @samp{.o} as the suffix for object files. 11091@end defmac 11092 11093@defmac TARGET_EXECUTABLE_SUFFIX 11094Define this macro to be a C string representing the suffix to be 11095automatically added to executable files on your target machine. If you 11096do not define this macro, GCC will use the null string as the suffix for 11097executable files. 11098@end defmac 11099 11100@defmac COLLECT_EXPORT_LIST 11101If defined, @code{collect2} will scan the individual object files 11102specified on its command line and create an export list for the linker. 11103Define this macro for systems like AIX, where the linker discards 11104object files that are not referenced from @code{main} and uses export 11105lists. 11106@end defmac 11107 11108@defmac MODIFY_JNI_METHOD_CALL (@var{mdecl}) 11109Define this macro to a C expression representing a variant of the 11110method call @var{mdecl}, if Java Native Interface (JNI) methods 11111must be invoked differently from other methods on your target. 11112For example, on 32-bit Microsoft Windows, JNI methods must be invoked using 11113the @code{stdcall} calling convention and this macro is then 11114defined as this expression: 11115 11116@smallexample 11117build_type_attribute_variant (@var{mdecl}, 11118 build_tree_list 11119 (get_identifier ("stdcall"), 11120 NULL)) 11121@end smallexample 11122@end defmac 11123 11124@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 11125This target hook returns @code{true} past the point in which new jump 11126instructions could be created. On machines that require a register for 11127every jump such as the SHmedia ISA of SH5, this point would typically be 11128reload, so this target hook should be defined to a function such as: 11129 11130@smallexample 11131static bool 11132cannot_modify_jumps_past_reload_p () 11133@{ 11134 return (reload_completed || reload_in_progress); 11135@} 11136@end smallexample 11137@end deftypefn 11138 11139@deftypefn {Target Hook} reg_class_t TARGET_BRANCH_TARGET_REGISTER_CLASS (void) 11140This target hook returns a register class for which branch target register 11141optimizations should be applied. All registers in this class should be 11142usable interchangeably. After reload, registers in this class will be 11143re-allocated and loads will be hoisted out of loops and be subjected 11144to inter-block scheduling. 11145@end deftypefn 11146 11147@deftypefn {Target Hook} bool TARGET_BRANCH_TARGET_REGISTER_CALLEE_SAVED (bool @var{after_prologue_epilogue_gen}) 11148Branch target register optimization will by default exclude callee-saved 11149registers 11150that are not already live during the current function; if this target hook 11151returns true, they will be included. The target code must than make sure 11152that all target registers in the class returned by 11153@samp{TARGET_BRANCH_TARGET_REGISTER_CLASS} that might need saving are 11154saved. @var{after_prologue_epilogue_gen} indicates if prologues and 11155epilogues have already been generated. Note, even if you only return 11156true when @var{after_prologue_epilogue_gen} is false, you still are likely 11157to have to make special provisions in @code{INITIAL_ELIMINATION_OFFSET} 11158to reserve space for caller-saved target registers. 11159@end deftypefn 11160 11161@deftypefn {Target Hook} bool TARGET_HAVE_CONDITIONAL_EXECUTION (void) 11162This target hook returns true if the target supports conditional execution. 11163This target hook is required only when the target has several different 11164modes and they have different conditional execution capability, such as ARM. 11165@end deftypefn 11166 11167@deftypefn {Target Hook} unsigned TARGET_LOOP_UNROLL_ADJUST (unsigned @var{nunroll}, struct loop *@var{loop}) 11168This target hook returns a new value for the number of times @var{loop} 11169should be unrolled. The parameter @var{nunroll} is the number of times 11170the loop is to be unrolled. The parameter @var{loop} is a pointer to 11171the loop, which is going to be checked for unrolling. This target hook 11172is required only when the target has special constraints like maximum 11173number of memory accesses. 11174@end deftypefn 11175 11176@defmac POWI_MAX_MULTS 11177If defined, this macro is interpreted as a signed integer C expression 11178that specifies the maximum number of floating point multiplications 11179that should be emitted when expanding exponentiation by an integer 11180constant inline. When this value is defined, exponentiation requiring 11181more than this number of multiplications is implemented by calling the 11182system library's @code{pow}, @code{powf} or @code{powl} routines. 11183The default value places no upper bound on the multiplication count. 11184@end defmac 11185 11186@deftypefn Macro void TARGET_EXTRA_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 11187This target hook should register any extra include files for the 11188target. The parameter @var{stdinc} indicates if normal include files 11189are present. The parameter @var{sysroot} is the system root directory. 11190The parameter @var{iprefix} is the prefix for the gcc directory. 11191@end deftypefn 11192 11193@deftypefn Macro void TARGET_EXTRA_PRE_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 11194This target hook should register any extra include files for the 11195target before any standard headers. The parameter @var{stdinc} 11196indicates if normal include files are present. The parameter 11197@var{sysroot} is the system root directory. The parameter 11198@var{iprefix} is the prefix for the gcc directory. 11199@end deftypefn 11200 11201@deftypefn Macro void TARGET_OPTF (char *@var{path}) 11202This target hook should register special include paths for the target. 11203The parameter @var{path} is the include to register. On Darwin 11204systems, this is used for Framework includes, which have semantics 11205that are different from @option{-I}. 11206@end deftypefn 11207 11208@defmac bool TARGET_USE_LOCAL_THUNK_ALIAS_P (tree @var{fndecl}) 11209This target macro returns @code{true} if it is safe to use a local alias 11210for a virtual function @var{fndecl} when constructing thunks, 11211@code{false} otherwise. By default, the macro returns @code{true} for all 11212functions, if a target supports aliases (i.e.@: defines 11213@code{ASM_OUTPUT_DEF}), @code{false} otherwise, 11214@end defmac 11215 11216@defmac TARGET_FORMAT_TYPES 11217If defined, this macro is the name of a global variable containing 11218target-specific format checking information for the @option{-Wformat} 11219option. The default is to have no target-specific format checks. 11220@end defmac 11221 11222@defmac TARGET_N_FORMAT_TYPES 11223If defined, this macro is the number of entries in 11224@code{TARGET_FORMAT_TYPES}. 11225@end defmac 11226 11227@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES 11228If defined, this macro is the name of a global variable containing 11229target-specific format overrides for the @option{-Wformat} option. The 11230default is to have no target-specific format overrides. If defined, 11231@code{TARGET_FORMAT_TYPES} must be defined, too. 11232@end defmac 11233 11234@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT 11235If defined, this macro specifies the number of entries in 11236@code{TARGET_OVERRIDES_FORMAT_ATTRIBUTES}. 11237@end defmac 11238 11239@defmac TARGET_OVERRIDES_FORMAT_INIT 11240If defined, this macro specifies the optional initialization 11241routine for target specific customizations of the system printf 11242and scanf formatter settings. 11243@end defmac 11244 11245@deftypevr {Target Hook} bool TARGET_RELAXED_ORDERING 11246If set to @code{true}, means that the target's memory model does not 11247guarantee that loads which do not depend on one another will access 11248main memory in the order of the instruction stream; if ordering is 11249important, an explicit memory barrier must be used. This is true of 11250many recent processors which implement a policy of ``relaxed,'' 11251``weak,'' or ``release'' memory consistency, such as Alpha, PowerPC, 11252and ia64. The default is @code{false}. 11253@end deftypevr 11254 11255@deftypefn {Target Hook} {const char *} TARGET_INVALID_ARG_FOR_UNPROTOTYPED_FN (const_tree @var{typelist}, const_tree @var{funcdecl}, const_tree @var{val}) 11256If defined, this macro returns the diagnostic message when it is 11257illegal to pass argument @var{val} to function @var{funcdecl} 11258with prototype @var{typelist}. 11259@end deftypefn 11260 11261@deftypefn {Target Hook} {const char *} TARGET_INVALID_CONVERSION (const_tree @var{fromtype}, const_tree @var{totype}) 11262If defined, this macro returns the diagnostic message when it is 11263invalid to convert from @var{fromtype} to @var{totype}, or @code{NULL} 11264if validity should be determined by the front end. 11265@end deftypefn 11266 11267@deftypefn {Target Hook} {const char *} TARGET_INVALID_UNARY_OP (int @var{op}, const_tree @var{type}) 11268If defined, this macro returns the diagnostic message when it is 11269invalid to apply operation @var{op} (where unary plus is denoted by 11270@code{CONVERT_EXPR}) to an operand of type @var{type}, or @code{NULL} 11271if validity should be determined by the front end. 11272@end deftypefn 11273 11274@deftypefn {Target Hook} {const char *} TARGET_INVALID_BINARY_OP (int @var{op}, const_tree @var{type1}, const_tree @var{type2}) 11275If defined, this macro returns the diagnostic message when it is 11276invalid to apply operation @var{op} to operands of types @var{type1} 11277and @var{type2}, or @code{NULL} if validity should be determined by 11278the front end. 11279@end deftypefn 11280 11281@deftypefn {Target Hook} {const char *} TARGET_INVALID_PARAMETER_TYPE (const_tree @var{type}) 11282If defined, this macro returns the diagnostic message when it is 11283invalid for functions to include parameters of type @var{type}, 11284or @code{NULL} if validity should be determined by 11285the front end. This is currently used only by the C and C++ front ends. 11286@end deftypefn 11287 11288@deftypefn {Target Hook} {const char *} TARGET_INVALID_RETURN_TYPE (const_tree @var{type}) 11289If defined, this macro returns the diagnostic message when it is 11290invalid for functions to have return type @var{type}, 11291or @code{NULL} if validity should be determined by 11292the front end. This is currently used only by the C and C++ front ends. 11293@end deftypefn 11294 11295@deftypefn {Target Hook} tree TARGET_PROMOTED_TYPE (const_tree @var{type}) 11296If defined, this target hook returns the type to which values of 11297@var{type} should be promoted when they appear in expressions, 11298analogous to the integer promotions, or @code{NULL_TREE} to use the 11299front end's normal promotion rules. This hook is useful when there are 11300target-specific types with special promotion rules. 11301This is currently used only by the C and C++ front ends. 11302@end deftypefn 11303 11304@deftypefn {Target Hook} tree TARGET_CONVERT_TO_TYPE (tree @var{type}, tree @var{expr}) 11305If defined, this hook returns the result of converting @var{expr} to 11306@var{type}. It should return the converted expression, 11307or @code{NULL_TREE} to apply the front end's normal conversion rules. 11308This hook is useful when there are target-specific types with special 11309conversion rules. 11310This is currently used only by the C and C++ front ends. 11311@end deftypefn 11312 11313@defmac TARGET_USE_JCR_SECTION 11314This macro determines whether to use the JCR section to register Java 11315classes. By default, TARGET_USE_JCR_SECTION is defined to 1 if both 11316SUPPORTS_WEAK and TARGET_HAVE_NAMED_SECTIONS are true, else 0. 11317@end defmac 11318 11319@defmac OBJC_JBLEN 11320This macro determines the size of the objective C jump buffer for the 11321NeXT runtime. By default, OBJC_JBLEN is defined to an innocuous value. 11322@end defmac 11323 11324@defmac LIBGCC2_UNWIND_ATTRIBUTE 11325Define this macro if any target-specific attributes need to be attached 11326to the functions in @file{libgcc} that provide low-level support for 11327call stack unwinding. It is used in declarations in @file{unwind-generic.h} 11328and the associated definitions of those functions. 11329@end defmac 11330 11331@deftypefn {Target Hook} void TARGET_UPDATE_STACK_BOUNDARY (void) 11332Define this macro to update the current function stack boundary if 11333necessary. 11334@end deftypefn 11335 11336@deftypefn {Target Hook} rtx TARGET_GET_DRAP_RTX (void) 11337This hook should return an rtx for Dynamic Realign Argument Pointer (DRAP) if a 11338different argument pointer register is needed to access the function's 11339argument list due to stack realignment. Return @code{NULL} if no DRAP 11340is needed. 11341@end deftypefn 11342 11343@deftypefn {Target Hook} bool TARGET_ALLOCATE_STACK_SLOTS_FOR_ARGS (void) 11344When optimization is disabled, this hook indicates whether or not 11345arguments should be allocated to stack slots. Normally, GCC allocates 11346stacks slots for arguments when not optimizing in order to make 11347debugging easier. However, when a function is declared with 11348@code{__attribute__((naked))}, there is no stack frame, and the compiler 11349cannot safely move arguments from the registers in which they are passed 11350to the stack. Therefore, this hook should return true in general, but 11351false for naked functions. The default implementation always returns true. 11352@end deftypefn 11353 11354@deftypevr {Target Hook} {unsigned HOST_WIDE_INT} TARGET_CONST_ANCHOR 11355On some architectures it can take multiple instructions to synthesize 11356a constant. If there is another constant already in a register that 11357is close enough in value then it is preferable that the new constant 11358is computed from this register using immediate addition or 11359subtraction. We accomplish this through CSE. Besides the value of 11360the constant we also add a lower and an upper constant anchor to the 11361available expressions. These are then queried when encountering new 11362constants. The anchors are computed by rounding the constant up and 11363down to a multiple of the value of @code{TARGET_CONST_ANCHOR}. 11364@code{TARGET_CONST_ANCHOR} should be the maximum positive value 11365accepted by immediate-add plus one. We currently assume that the 11366value of @code{TARGET_CONST_ANCHOR} is a power of 2. For example, on 11367MIPS, where add-immediate takes a 16-bit signed value, 11368@code{TARGET_CONST_ANCHOR} is set to @samp{0x8000}. The default value 11369is zero, which disables this optimization. @end deftypevr 11370 11371@deftypevr {Target Hook} {unsigned char} TARGET_ATOMIC_TEST_AND_SET_TRUEVAL 11372This value should be set if the result written by @code{atomic_test_and_set} is not exactly 1, i.e. the @code{bool} @code{true}. 11373@end deftypevr 11374