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} void TARGET_OBJC_DECLARE_UNRESOLVED_CLASS_REFERENCE (const char *@var{classname}) 704Declare that Objective C class @var{classname} is referenced by the current TU. 705@end deftypefn 706 707@deftypefn {C Target Hook} void TARGET_OBJC_DECLARE_CLASS_DEFINITION (const char *@var{classname}) 708Declare that Objective C class @var{classname} is defined by the current TU. 709@end deftypefn 710 711@deftypefn {C Target Hook} bool TARGET_STRING_OBJECT_REF_TYPE_P (const_tree @var{stringref}) 712If a target implements string objects then this hook should return @code{true} if @var{stringref} is a valid reference to such an object. 713@end deftypefn 714 715@deftypefn {C Target Hook} void TARGET_CHECK_STRING_OBJECT_FORMAT_ARG (tree @var{format_arg}, tree @var{args_list}) 716If 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. 717@end deftypefn 718 719@deftypefn {Target Hook} void TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE (void) 720This target function is similar to the hook @code{TARGET_OPTION_OVERRIDE} 721but is called when the optimize level is changed via an attribute or 722pragma or when it is reset at the end of the code affected by the 723attribute or pragma. It is not called at the beginning of compilation 724when @code{TARGET_OPTION_OVERRIDE} is called so if you want to perform these 725actions then, you should have @code{TARGET_OPTION_OVERRIDE} call 726@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}. 727@end deftypefn 728 729@defmac C_COMMON_OVERRIDE_OPTIONS 730This is similar to the @code{TARGET_OPTION_OVERRIDE} hook 731but is only used in the C 732language frontends (C, Objective-C, C++, Objective-C++) and so can be 733used to alter option flag variables which only exist in those 734frontends. 735@end defmac 736 737@deftypevr {Common Target Hook} {const struct default_options *} TARGET_OPTION_OPTIMIZATION_TABLE 738Some machines may desire to change what optimizations are performed for 739various optimization levels. This variable, if defined, describes 740options to enable at particular sets of optimization levels. These 741options are processed once 742just after the optimization level is determined and before the remainder 743of the command options have been parsed, so may be overridden by other 744options passed explicitly. 745 746This processing is run once at program startup and when the optimization 747options are changed via @code{#pragma GCC optimize} or by using the 748@code{optimize} attribute. 749@end deftypevr 750 751@deftypefn {Common Target Hook} void TARGET_OPTION_INIT_STRUCT (struct gcc_options *@var{opts}) 752Set target-dependent initial values of fields in @var{opts}. 753@end deftypefn 754 755@deftypefn {Common Target Hook} void TARGET_OPTION_DEFAULT_PARAMS (void) 756Set target-dependent default values for @option{--param} settings, using calls to @code{set_default_param_value}. 757@end deftypefn 758 759@defmac SWITCHABLE_TARGET 760Some targets need to switch between substantially different subtargets 761during compilation. For example, the MIPS target has one subtarget for 762the traditional MIPS architecture and another for MIPS16. Source code 763can switch between these two subarchitectures using the @code{mips16} 764and @code{nomips16} attributes. 765 766Such subtargets can differ in things like the set of available 767registers, the set of available instructions, the costs of various 768operations, and so on. GCC caches a lot of this type of information 769in global variables, and recomputing them for each subtarget takes a 770significant amount of time. The compiler therefore provides a facility 771for maintaining several versions of the global variables and quickly 772switching between them; see @file{target-globals.h} for details. 773 774Define this macro to 1 if your target needs this facility. The default 775is 0. 776@end defmac 777 778@node Per-Function Data 779@section Defining data structures for per-function information. 780@cindex per-function data 781@cindex data structures 782 783If the target needs to store information on a per-function basis, GCC 784provides a macro and a couple of variables to allow this. Note, just 785using statics to store the information is a bad idea, since GCC supports 786nested functions, so you can be halfway through encoding one function 787when another one comes along. 788 789GCC defines a data structure called @code{struct function} which 790contains all of the data specific to an individual function. This 791structure contains a field called @code{machine} whose type is 792@code{struct machine_function *}, which can be used by targets to point 793to their own specific data. 794 795If a target needs per-function specific data it should define the type 796@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. 797This macro should be used to initialize the function pointer 798@code{init_machine_status}. This pointer is explained below. 799 800One typical use of per-function, target specific data is to create an 801RTX to hold the register containing the function's return address. This 802RTX can then be used to implement the @code{__builtin_return_address} 803function, for level 0. 804 805Note---earlier implementations of GCC used a single data area to hold 806all of the per-function information. Thus when processing of a nested 807function began the old per-function data had to be pushed onto a 808stack, and when the processing was finished, it had to be popped off the 809stack. GCC used to provide function pointers called 810@code{save_machine_status} and @code{restore_machine_status} to handle 811the saving and restoring of the target specific information. Since the 812single data area approach is no longer used, these pointers are no 813longer supported. 814 815@defmac INIT_EXPANDERS 816Macro called to initialize any target specific information. This macro 817is called once per function, before generation of any RTL has begun. 818The intention of this macro is to allow the initialization of the 819function pointer @code{init_machine_status}. 820@end defmac 821 822@deftypevar {void (*)(struct function *)} init_machine_status 823If this function pointer is non-@code{NULL} it will be called once per 824function, before function compilation starts, in order to allow the 825target to perform any target specific initialization of the 826@code{struct function} structure. It is intended that this would be 827used to initialize the @code{machine} of that structure. 828 829@code{struct machine_function} structures are expected to be freed by GC@. 830Generally, any memory that they reference must be allocated by using 831GC allocation, including the structure itself. 832@end deftypevar 833 834@node Storage Layout 835@section Storage Layout 836@cindex storage layout 837 838Note that the definitions of the macros in this table which are sizes or 839alignments measured in bits do not need to be constant. They can be C 840expressions that refer to static variables, such as the @code{target_flags}. 841@xref{Run-time Target}. 842 843@defmac BITS_BIG_ENDIAN 844Define this macro to have the value 1 if the most significant bit in a 845byte has the lowest number; otherwise define it to have the value zero. 846This means that bit-field instructions count from the most significant 847bit. If the machine has no bit-field instructions, then this must still 848be defined, but it doesn't matter which value it is defined to. This 849macro need not be a constant. 850 851This macro does not affect the way structure fields are packed into 852bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 853@end defmac 854 855@defmac BYTES_BIG_ENDIAN 856Define this macro to have the value 1 if the most significant byte in a 857word has the lowest number. This macro need not be a constant. 858@end defmac 859 860@defmac WORDS_BIG_ENDIAN 861Define this macro to have the value 1 if, in a multiword object, the 862most significant word has the lowest number. This applies to both 863memory locations and registers; see @code{REG_WORDS_BIG_ENDIAN} if the 864order of words in memory is not the same as the order in registers. This 865macro need not be a constant. 866@end defmac 867 868@defmac REG_WORDS_BIG_ENDIAN 869On some machines, the order of words in a multiword object differs between 870registers in memory. In such a situation, define this macro to describe 871the order of words in a register. The macro @code{WORDS_BIG_ENDIAN} controls 872the order of words in memory. 873@end defmac 874 875@defmac FLOAT_WORDS_BIG_ENDIAN 876Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 877@code{TFmode} floating point numbers are stored in memory with the word 878containing the sign bit at the lowest address; otherwise define it to 879have the value 0. This macro need not be a constant. 880 881You need not define this macro if the ordering is the same as for 882multi-word integers. 883@end defmac 884 885@defmac BITS_PER_UNIT 886Define this macro to be the number of bits in an addressable storage 887unit (byte). If you do not define this macro the default is 8. 888@end defmac 889 890@defmac BITS_PER_WORD 891Number of bits in a word. If you do not define this macro, the default 892is @code{BITS_PER_UNIT * UNITS_PER_WORD}. 893@end defmac 894 895@defmac MAX_BITS_PER_WORD 896Maximum number of bits in a word. If this is undefined, the default is 897@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 898largest value that @code{BITS_PER_WORD} can have at run-time. 899@end defmac 900 901@defmac UNITS_PER_WORD 902Number of storage units in a word; normally the size of a general-purpose 903register, a power of two from 1 or 8. 904@end defmac 905 906@defmac MIN_UNITS_PER_WORD 907Minimum number of units in a word. If this is undefined, the default is 908@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 909smallest value that @code{UNITS_PER_WORD} can have at run-time. 910@end defmac 911 912@defmac POINTER_SIZE 913Width of a pointer, in bits. You must specify a value no wider than the 914width of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 915you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify 916a value the default is @code{BITS_PER_WORD}. 917@end defmac 918 919@defmac POINTERS_EXTEND_UNSIGNED 920A C expression that determines how pointers should be extended from 921@code{ptr_mode} to either @code{Pmode} or @code{word_mode}. It is 922greater than zero if pointers should be zero-extended, zero if they 923should be sign-extended, and negative if some other sort of conversion 924is needed. In the last case, the extension is done by the target's 925@code{ptr_extend} instruction. 926 927You need not define this macro if the @code{ptr_mode}, @code{Pmode} 928and @code{word_mode} are all the same width. 929@end defmac 930 931@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 932A macro to update @var{m} and @var{unsignedp} when an object whose type 933is @var{type} and which has the specified mode and signedness is to be 934stored in a register. This macro is only called when @var{type} is a 935scalar type. 936 937On most RISC machines, which only have operations that operate on a full 938register, define this macro to set @var{m} to @code{word_mode} if 939@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 940cases, only integer modes should be widened because wider-precision 941floating-point operations are usually more expensive than their narrower 942counterparts. 943 944For most machines, the macro definition does not change @var{unsignedp}. 945However, some machines, have instructions that preferentially handle 946either signed or unsigned quantities of certain modes. For example, on 947the DEC Alpha, 32-bit loads from memory and 32-bit add instructions 948sign-extend the result to 64 bits. On such machines, set 949@var{unsignedp} according to which kind of extension is more efficient. 950 951Do not define this macro if it would never modify @var{m}. 952@end defmac 953 954@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}) 955Like @code{PROMOTE_MODE}, but it is applied to outgoing function arguments or 956function return values. The target hook should return the new mode 957and possibly change @code{*@var{punsignedp}} if the promotion should 958change signedness. This function is called only for scalar @emph{or 959pointer} types. 960 961@var{for_return} allows to distinguish the promotion of arguments and 962return values. If it is @code{1}, a return value is being promoted and 963@code{TARGET_FUNCTION_VALUE} must perform the same promotions done here. 964If it is @code{2}, the returned mode should be that of the register in 965which an incoming parameter is copied, or the outgoing result is computed; 966then the hook should return the same mode as @code{promote_mode}, though 967the signedness may be different. 968 969@var{type} can be NULL when promoting function arguments of libcalls. 970 971The default is to not promote arguments and return values. You can 972also define the hook to @code{default_promote_function_mode_always_promote} 973if you would like to apply the same rules given by @code{PROMOTE_MODE}. 974@end deftypefn 975 976@defmac PARM_BOUNDARY 977Normal alignment required for function parameters on the stack, in 978bits. All stack parameters receive at least this much alignment 979regardless of data type. On most machines, this is the same as the 980size of an integer. 981@end defmac 982 983@defmac STACK_BOUNDARY 984Define this macro to the minimum alignment enforced by hardware for the 985stack pointer on this machine. The definition is a C expression for the 986desired alignment (measured in bits). This value is used as a default 987if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 988this should be the same as @code{PARM_BOUNDARY}. 989@end defmac 990 991@defmac PREFERRED_STACK_BOUNDARY 992Define this macro if you wish to preserve a certain alignment for the 993stack pointer, greater than what the hardware enforces. The definition 994is a C expression for the desired alignment (measured in bits). This 995macro must evaluate to a value equal to or larger than 996@code{STACK_BOUNDARY}. 997@end defmac 998 999@defmac INCOMING_STACK_BOUNDARY 1000Define this macro if the incoming stack boundary may be different 1001from @code{PREFERRED_STACK_BOUNDARY}. This macro must evaluate 1002to a value equal to or larger than @code{STACK_BOUNDARY}. 1003@end defmac 1004 1005@defmac FUNCTION_BOUNDARY 1006Alignment required for a function entry point, in bits. 1007@end defmac 1008 1009@defmac BIGGEST_ALIGNMENT 1010Biggest alignment that any data type can require on this machine, in 1011bits. Note that this is not the biggest alignment that is supported, 1012just the biggest alignment that, when violated, may cause a fault. 1013@end defmac 1014 1015@defmac MALLOC_ABI_ALIGNMENT 1016Alignment, in bits, a C conformant malloc implementation has to 1017provide. If not defined, the default value is @code{BITS_PER_WORD}. 1018@end defmac 1019 1020@defmac ATTRIBUTE_ALIGNED_VALUE 1021Alignment used by the @code{__attribute__ ((aligned))} construct. If 1022not defined, the default value is @code{BIGGEST_ALIGNMENT}. 1023@end defmac 1024 1025@defmac MINIMUM_ATOMIC_ALIGNMENT 1026If defined, the smallest alignment, in bits, that can be given to an 1027object that can be referenced in one operation, without disturbing any 1028nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 1029on machines that don't have byte or half-word store operations. 1030@end defmac 1031 1032@defmac BIGGEST_FIELD_ALIGNMENT 1033Biggest alignment that any structure or union field can require on this 1034machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 1035structure and union fields only, unless the field alignment has been set 1036by the @code{__attribute__ ((aligned (@var{n})))} construct. 1037@end defmac 1038 1039@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 1040An expression for the alignment of a structure field @var{field} if the 1041alignment computed in the usual way (including applying of 1042@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the 1043alignment) is @var{computed}. It overrides alignment only if the 1044field alignment has not been set by the 1045@code{__attribute__ ((aligned (@var{n})))} construct. 1046@end defmac 1047 1048@defmac MAX_STACK_ALIGNMENT 1049Biggest stack alignment guaranteed by the backend. Use this macro 1050to specify the maximum alignment of a variable on stack. 1051 1052If not defined, the default value is @code{STACK_BOUNDARY}. 1053 1054@c FIXME: The default should be @code{PREFERRED_STACK_BOUNDARY}. 1055@c But the fix for PR 32893 indicates that we can only guarantee 1056@c maximum stack alignment on stack up to @code{STACK_BOUNDARY}, not 1057@c @code{PREFERRED_STACK_BOUNDARY}, if stack alignment isn't supported. 1058@end defmac 1059 1060@defmac MAX_OFILE_ALIGNMENT 1061Biggest alignment supported by the object file format of this machine. 1062Use this macro to limit the alignment which can be specified using the 1063@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 1064the default value is @code{BIGGEST_ALIGNMENT}. 1065 1066On systems that use ELF, the default (in @file{config/elfos.h}) is 1067the largest supported 32-bit ELF section alignment representable on 1068a 32-bit host e.g. @samp{(((unsigned HOST_WIDEST_INT) 1 << 28) * 8)}. 1069On 32-bit ELF the largest supported section alignment in bits is 1070@samp{(0x80000000 * 8)}, but this is not representable on 32-bit hosts. 1071@end defmac 1072 1073@defmac DATA_ALIGNMENT (@var{type}, @var{basic-align}) 1074If defined, a C expression to compute the alignment for a variable in 1075the static store. @var{type} is the data type, and @var{basic-align} is 1076the alignment that the object would ordinarily have. The value of this 1077macro is used instead of that alignment to align the object. 1078 1079If this macro is not defined, then @var{basic-align} is used. 1080 1081@findex strcpy 1082One use of this macro is to increase alignment of medium-size data to 1083make it all fit in fewer cache lines. Another is to cause character 1084arrays to be word-aligned so that @code{strcpy} calls that copy 1085constants to character arrays can be done inline. 1086@end defmac 1087 1088@defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 1089If defined, a C expression to compute the alignment given to a constant 1090that is being placed in memory. @var{constant} is the constant and 1091@var{basic-align} is the alignment that the object would ordinarily 1092have. The value of this macro is used instead of that alignment to 1093align the object. 1094 1095If this macro is not defined, then @var{basic-align} is used. 1096 1097The typical use of this macro is to increase alignment for string 1098constants to be word aligned so that @code{strcpy} calls that copy 1099constants can be done inline. 1100@end defmac 1101 1102@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 1103If defined, a C expression to compute the alignment for a variable in 1104the local store. @var{type} is the data type, and @var{basic-align} is 1105the alignment that the object would ordinarily have. The value of this 1106macro is used instead of that alignment to align the object. 1107 1108If this macro is not defined, then @var{basic-align} is used. 1109 1110One use of this macro is to increase alignment of medium-size data to 1111make it all fit in fewer cache lines. 1112 1113If the value of this macro has a type, it should be an unsigned type. 1114@end defmac 1115 1116@deftypefn {Target Hook} HOST_WIDE_INT TARGET_VECTOR_ALIGNMENT (const_tree @var{type}) 1117This hook can be used to define the alignment for a vector of type 1118@var{type}, in order to comply with a platform ABI. The default is to 1119require natural alignment for vector types. The alignment returned by 1120this hook must be a power-of-two multiple of the default alignment of 1121the vector element type. 1122@end deftypefn 1123 1124@defmac STACK_SLOT_ALIGNMENT (@var{type}, @var{mode}, @var{basic-align}) 1125If defined, a C expression to compute the alignment for stack slot. 1126@var{type} is the data type, @var{mode} is the widest mode available, 1127and @var{basic-align} is the alignment that the slot would ordinarily 1128have. The value of this macro is used instead of that alignment to 1129align the slot. 1130 1131If this macro is not defined, then @var{basic-align} is used when 1132@var{type} is @code{NULL}. Otherwise, @code{LOCAL_ALIGNMENT} will 1133be used. 1134 1135This macro is to set alignment of stack slot to the maximum alignment 1136of all possible modes which the slot may have. 1137 1138If the value of this macro has a type, it should be an unsigned type. 1139@end defmac 1140 1141@defmac LOCAL_DECL_ALIGNMENT (@var{decl}) 1142If defined, a C expression to compute the alignment for a local 1143variable @var{decl}. 1144 1145If this macro is not defined, then 1146@code{LOCAL_ALIGNMENT (TREE_TYPE (@var{decl}), DECL_ALIGN (@var{decl}))} 1147is used. 1148 1149One use of this macro is to increase alignment of medium-size data to 1150make it all fit in fewer cache lines. 1151 1152If the value of this macro has a type, it should be an unsigned type. 1153@end defmac 1154 1155@defmac MINIMUM_ALIGNMENT (@var{exp}, @var{mode}, @var{align}) 1156If defined, a C expression to compute the minimum required alignment 1157for dynamic stack realignment purposes for @var{exp} (a type or decl), 1158@var{mode}, assuming normal alignment @var{align}. 1159 1160If this macro is not defined, then @var{align} will be used. 1161@end defmac 1162 1163@defmac EMPTY_FIELD_BOUNDARY 1164Alignment in bits to be given to a structure bit-field that follows an 1165empty field such as @code{int : 0;}. 1166 1167If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro. 1168@end defmac 1169 1170@defmac STRUCTURE_SIZE_BOUNDARY 1171Number of bits which any structure or union's size must be a multiple of. 1172Each structure or union's size is rounded up to a multiple of this. 1173 1174If you do not define this macro, the default is the same as 1175@code{BITS_PER_UNIT}. 1176@end defmac 1177 1178@defmac STRICT_ALIGNMENT 1179Define this macro to be the value 1 if instructions will fail to work 1180if given data not on the nominal alignment. If instructions will merely 1181go slower in that case, define this macro as 0. 1182@end defmac 1183 1184@defmac PCC_BITFIELD_TYPE_MATTERS 1185Define this if you wish to imitate the way many other C compilers handle 1186alignment of bit-fields and the structures that contain them. 1187 1188The behavior is that the type written for a named bit-field (@code{int}, 1189@code{short}, or other integer type) imposes an alignment for the entire 1190structure, as if the structure really did contain an ordinary field of 1191that type. In addition, the bit-field is placed within the structure so 1192that it would fit within such a field, not crossing a boundary for it. 1193 1194Thus, on most machines, a named bit-field whose type is written as 1195@code{int} would not cross a four-byte boundary, and would force 1196four-byte alignment for the whole structure. (The alignment used may 1197not be four bytes; it is controlled by the other alignment parameters.) 1198 1199An unnamed bit-field will not affect the alignment of the containing 1200structure. 1201 1202If the macro is defined, its definition should be a C expression; 1203a nonzero value for the expression enables this behavior. 1204 1205Note that if this macro is not defined, or its value is zero, some 1206bit-fields may cross more than one alignment boundary. The compiler can 1207support such references if there are @samp{insv}, @samp{extv}, and 1208@samp{extzv} insns that can directly reference memory. 1209 1210The other known way of making bit-fields work is to define 1211@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 1212Then every structure can be accessed with fullwords. 1213 1214Unless the machine has bit-field instructions or you define 1215@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 1216@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 1217 1218If your aim is to make GCC use the same conventions for laying out 1219bit-fields as are used by another compiler, here is how to investigate 1220what the other compiler does. Compile and run this program: 1221 1222@smallexample 1223struct foo1 1224@{ 1225 char x; 1226 char :0; 1227 char y; 1228@}; 1229 1230struct foo2 1231@{ 1232 char x; 1233 int :0; 1234 char y; 1235@}; 1236 1237main () 1238@{ 1239 printf ("Size of foo1 is %d\n", 1240 sizeof (struct foo1)); 1241 printf ("Size of foo2 is %d\n", 1242 sizeof (struct foo2)); 1243 exit (0); 1244@} 1245@end smallexample 1246 1247If this prints 2 and 5, then the compiler's behavior is what you would 1248get from @code{PCC_BITFIELD_TYPE_MATTERS}. 1249@end defmac 1250 1251@defmac BITFIELD_NBYTES_LIMITED 1252Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 1253to aligning a bit-field within the structure. 1254@end defmac 1255 1256@deftypefn {Target Hook} bool TARGET_ALIGN_ANON_BITFIELD (void) 1257When @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine 1258whether unnamed bitfields affect the alignment of the containing 1259structure. The hook should return true if the structure should inherit 1260the alignment requirements of an unnamed bitfield's type. 1261@end deftypefn 1262 1263@deftypefn {Target Hook} bool TARGET_NARROW_VOLATILE_BITFIELD (void) 1264This target hook should return @code{true} if accesses to volatile bitfields 1265should use the narrowest mode possible. It should return @code{false} if 1266these accesses should use the bitfield container type. 1267 1268The default is @code{!TARGET_STRICT_ALIGN}. 1269@end deftypefn 1270 1271@defmac MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) 1272Return 1 if a structure or array containing @var{field} should be accessed using 1273@code{BLKMODE}. 1274 1275If @var{field} is the only field in the structure, @var{mode} is its 1276mode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the 1277case where structures of one field would require the structure's mode to 1278retain the field's mode. 1279 1280Normally, this is not needed. 1281@end defmac 1282 1283@defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 1284Define this macro as an expression for the alignment of a type (given 1285by @var{type} as a tree node) if the alignment computed in the usual 1286way is @var{computed} and the alignment explicitly specified was 1287@var{specified}. 1288 1289The default is to use @var{specified} if it is larger; otherwise, use 1290the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 1291@end defmac 1292 1293@defmac MAX_FIXED_MODE_SIZE 1294An integer expression for the size in bits of the largest integer 1295machine mode that should actually be used. All integer machine modes of 1296this size or smaller can be used for structures and unions with the 1297appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 1298(DImode)} is assumed. 1299@end defmac 1300 1301@defmac STACK_SAVEAREA_MODE (@var{save_level}) 1302If defined, an expression of type @code{enum machine_mode} that 1303specifies the mode of the save area operand of a 1304@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 1305@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 1306@code{SAVE_NONLOCAL} and selects which of the three named patterns is 1307having its mode specified. 1308 1309You need not define this macro if it always returns @code{Pmode}. You 1310would most commonly define this macro if the 1311@code{save_stack_@var{level}} patterns need to support both a 32- and a 131264-bit mode. 1313@end defmac 1314 1315@defmac STACK_SIZE_MODE 1316If defined, an expression of type @code{enum machine_mode} that 1317specifies the mode of the size increment operand of an 1318@code{allocate_stack} named pattern (@pxref{Standard Names}). 1319 1320You need not define this macro if it always returns @code{word_mode}. 1321You would most commonly define this macro if the @code{allocate_stack} 1322pattern needs to support both a 32- and a 64-bit mode. 1323@end defmac 1324 1325@deftypefn {Target Hook} {enum machine_mode} TARGET_LIBGCC_CMP_RETURN_MODE (void) 1326This target hook should return the mode to be used for the return value 1327of compare instructions expanded to libgcc calls. If not defined 1328@code{word_mode} is returned which is the right choice for a majority of 1329targets. 1330@end deftypefn 1331 1332@deftypefn {Target Hook} {enum machine_mode} TARGET_LIBGCC_SHIFT_COUNT_MODE (void) 1333This target hook should return the mode to be used for the shift count operand 1334of shift instructions expanded to libgcc calls. If not defined 1335@code{word_mode} is returned which is the right choice for a majority of 1336targets. 1337@end deftypefn 1338 1339@deftypefn {Target Hook} {enum machine_mode} TARGET_UNWIND_WORD_MODE (void) 1340Return machine mode to be used for @code{_Unwind_Word} type. 1341The default is to use @code{word_mode}. 1342@end deftypefn 1343 1344@defmac ROUND_TOWARDS_ZERO 1345If defined, this macro should be true if the prevailing rounding 1346mode is towards zero. 1347 1348Defining this macro only affects the way @file{libgcc.a} emulates 1349floating-point arithmetic. 1350 1351Not defining this macro is equivalent to returning zero. 1352@end defmac 1353 1354@defmac LARGEST_EXPONENT_IS_NORMAL (@var{size}) 1355This macro should return true if floats with @var{size} 1356bits do not have a NaN or infinity representation, but use the largest 1357exponent for normal numbers instead. 1358 1359Defining this macro only affects the way @file{libgcc.a} emulates 1360floating-point arithmetic. 1361 1362The default definition of this macro returns false for all sizes. 1363@end defmac 1364 1365@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (const_tree @var{record_type}) 1366This target hook returns @code{true} if bit-fields in the given 1367@var{record_type} are to be laid out following the rules of Microsoft 1368Visual C/C++, namely: (i) a bit-field won't share the same storage 1369unit with the previous bit-field if their underlying types have 1370different sizes, and the bit-field will be aligned to the highest 1371alignment of the underlying types of itself and of the previous 1372bit-field; (ii) a zero-sized bit-field will affect the alignment of 1373the whole enclosing structure, even if it is unnamed; except that 1374(iii) a zero-sized bit-field will be disregarded unless it follows 1375another bit-field of nonzero size. If this hook returns @code{true}, 1376other macros that control bit-field layout are ignored. 1377 1378When a bit-field is inserted into a packed record, the whole size 1379of the underlying type is used by one or more same-size adjacent 1380bit-fields (that is, if its long:3, 32 bits is used in the record, 1381and any additional adjacent long bit-fields are packed into the same 1382chunk of 32 bits. However, if the size changes, a new field of that 1383size is allocated). In an unpacked record, this is the same as using 1384alignment, but not equivalent when packing. 1385 1386If both MS bit-fields and @samp{__attribute__((packed))} are used, 1387the latter will take precedence. If @samp{__attribute__((packed))} is 1388used on a single field when MS bit-fields are in use, it will take 1389precedence for that field, but the alignment of the rest of the structure 1390may affect its placement. 1391@end deftypefn 1392 1393@deftypefn {Target Hook} bool TARGET_DECIMAL_FLOAT_SUPPORTED_P (void) 1394Returns true if the target supports decimal floating point. 1395@end deftypefn 1396 1397@deftypefn {Target Hook} bool TARGET_FIXED_POINT_SUPPORTED_P (void) 1398Returns true if the target supports fixed-point arithmetic. 1399@end deftypefn 1400 1401@deftypefn {Target Hook} void TARGET_EXPAND_TO_RTL_HOOK (void) 1402This hook is called just before expansion into rtl, allowing the target 1403to perform additional initializations or analysis before the expansion. 1404For example, the rs6000 port uses it to allocate a scratch stack slot 1405for use in copying SDmode values between memory and floating point 1406registers whenever the function being expanded has any SDmode 1407usage. 1408@end deftypefn 1409 1410@deftypefn {Target Hook} void TARGET_INSTANTIATE_DECLS (void) 1411This hook allows the backend to perform additional instantiations on rtl 1412that are not actually in any insns yet, but will be later. 1413@end deftypefn 1414 1415@deftypefn {Target Hook} {const char *} TARGET_MANGLE_TYPE (const_tree @var{type}) 1416If your target defines any fundamental types, or any types your target 1417uses should be mangled differently from the default, define this hook 1418to return the appropriate encoding for these types as part of a C++ 1419mangled name. The @var{type} argument is the tree structure representing 1420the type to be mangled. The hook may be applied to trees which are 1421not target-specific fundamental types; it should return @code{NULL} 1422for all such types, as well as arguments it does not recognize. If the 1423return value is not @code{NULL}, it must point to a statically-allocated 1424string constant. 1425 1426Target-specific fundamental types might be new fundamental types or 1427qualified versions of ordinary fundamental types. Encode new 1428fundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name} 1429is the name used for the type in source code, and @var{n} is the 1430length of @var{name} in decimal. Encode qualified versions of 1431ordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where 1432@var{name} is the name used for the type qualifier in source code, 1433@var{n} is the length of @var{name} as above, and @var{code} is the 1434code used to represent the unqualified version of this type. (See 1435@code{write_builtin_type} in @file{cp/mangle.c} for the list of 1436codes.) In both cases the spaces are for clarity; do not include any 1437spaces in your string. 1438 1439This hook is applied to types prior to typedef resolution. If the mangled 1440name for a particular type depends only on that type's main variant, you 1441can perform typedef resolution yourself using @code{TYPE_MAIN_VARIANT} 1442before mangling. 1443 1444The default version of this hook always returns @code{NULL}, which is 1445appropriate for a target that does not define any new fundamental 1446types. 1447@end deftypefn 1448 1449@node Type Layout 1450@section Layout of Source Language Data Types 1451 1452These macros define the sizes and other characteristics of the standard 1453basic data types used in programs being compiled. Unlike the macros in 1454the previous section, these apply to specific features of C and related 1455languages, rather than to fundamental aspects of storage layout. 1456 1457@defmac INT_TYPE_SIZE 1458A C expression for the size in bits of the type @code{int} on the 1459target machine. If you don't define this, the default is one word. 1460@end defmac 1461 1462@defmac SHORT_TYPE_SIZE 1463A C expression for the size in bits of the type @code{short} on the 1464target machine. If you don't define this, the default is half a word. 1465(If this would be less than one storage unit, it is rounded up to one 1466unit.) 1467@end defmac 1468 1469@defmac LONG_TYPE_SIZE 1470A C expression for the size in bits of the type @code{long} on the 1471target machine. If you don't define this, the default is one word. 1472@end defmac 1473 1474@defmac ADA_LONG_TYPE_SIZE 1475On some machines, the size used for the Ada equivalent of the type 1476@code{long} by a native Ada compiler differs from that used by C@. In 1477that situation, define this macro to be a C expression to be used for 1478the size of that type. If you don't define this, the default is the 1479value of @code{LONG_TYPE_SIZE}. 1480@end defmac 1481 1482@defmac LONG_LONG_TYPE_SIZE 1483A C expression for the size in bits of the type @code{long long} on the 1484target machine. If you don't define this, the default is two 1485words. If you want to support GNU Ada on your machine, the value of this 1486macro must be at least 64. 1487@end defmac 1488 1489@defmac CHAR_TYPE_SIZE 1490A C expression for the size in bits of the type @code{char} on the 1491target machine. If you don't define this, the default is 1492@code{BITS_PER_UNIT}. 1493@end defmac 1494 1495@defmac BOOL_TYPE_SIZE 1496A C expression for the size in bits of the C++ type @code{bool} and 1497C99 type @code{_Bool} on the target machine. If you don't define 1498this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 1499@end defmac 1500 1501@defmac FLOAT_TYPE_SIZE 1502A C expression for the size in bits of the type @code{float} on the 1503target machine. If you don't define this, the default is one word. 1504@end defmac 1505 1506@defmac DOUBLE_TYPE_SIZE 1507A C expression for the size in bits of the type @code{double} on the 1508target machine. If you don't define this, the default is two 1509words. 1510@end defmac 1511 1512@defmac LONG_DOUBLE_TYPE_SIZE 1513A C expression for the size in bits of the type @code{long double} on 1514the target machine. If you don't define this, the default is two 1515words. 1516@end defmac 1517 1518@defmac SHORT_FRACT_TYPE_SIZE 1519A C expression for the size in bits of the type @code{short _Fract} on 1520the target machine. If you don't define this, the default is 1521@code{BITS_PER_UNIT}. 1522@end defmac 1523 1524@defmac FRACT_TYPE_SIZE 1525A C expression for the size in bits of the type @code{_Fract} on 1526the target machine. If you don't define this, the default is 1527@code{BITS_PER_UNIT * 2}. 1528@end defmac 1529 1530@defmac LONG_FRACT_TYPE_SIZE 1531A C expression for the size in bits of the type @code{long _Fract} on 1532the target machine. If you don't define this, the default is 1533@code{BITS_PER_UNIT * 4}. 1534@end defmac 1535 1536@defmac LONG_LONG_FRACT_TYPE_SIZE 1537A C expression for the size in bits of the type @code{long long _Fract} on 1538the target machine. If you don't define this, the default is 1539@code{BITS_PER_UNIT * 8}. 1540@end defmac 1541 1542@defmac SHORT_ACCUM_TYPE_SIZE 1543A C expression for the size in bits of the type @code{short _Accum} on 1544the target machine. If you don't define this, the default is 1545@code{BITS_PER_UNIT * 2}. 1546@end defmac 1547 1548@defmac ACCUM_TYPE_SIZE 1549A C expression for the size in bits of the type @code{_Accum} on 1550the target machine. If you don't define this, the default is 1551@code{BITS_PER_UNIT * 4}. 1552@end defmac 1553 1554@defmac LONG_ACCUM_TYPE_SIZE 1555A C expression for the size in bits of the type @code{long _Accum} on 1556the target machine. If you don't define this, the default is 1557@code{BITS_PER_UNIT * 8}. 1558@end defmac 1559 1560@defmac LONG_LONG_ACCUM_TYPE_SIZE 1561A C expression for the size in bits of the type @code{long long _Accum} on 1562the target machine. If you don't define this, the default is 1563@code{BITS_PER_UNIT * 16}. 1564@end defmac 1565 1566@defmac LIBGCC2_LONG_DOUBLE_TYPE_SIZE 1567Define this macro if @code{LONG_DOUBLE_TYPE_SIZE} is not constant or 1568if you want routines in @file{libgcc2.a} for a size other than 1569@code{LONG_DOUBLE_TYPE_SIZE}. If you don't define this, the 1570default is @code{LONG_DOUBLE_TYPE_SIZE}. 1571@end defmac 1572 1573@defmac LIBGCC2_HAS_DF_MODE 1574Define this macro if neither @code{DOUBLE_TYPE_SIZE} nor 1575@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 1576@code{DFmode} but you want @code{DFmode} routines in @file{libgcc2.a} 1577anyway. If you don't define this and either @code{DOUBLE_TYPE_SIZE} 1578or @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64 then the default is 1, 1579otherwise it is 0. 1580@end defmac 1581 1582@defmac LIBGCC2_HAS_XF_MODE 1583Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1584@code{XFmode} but you want @code{XFmode} routines in @file{libgcc2.a} 1585anyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1586is 80 then the default is 1, otherwise it is 0. 1587@end defmac 1588 1589@defmac LIBGCC2_HAS_TF_MODE 1590Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1591@code{TFmode} but you want @code{TFmode} routines in @file{libgcc2.a} 1592anyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1593is 128 then the default is 1, otherwise it is 0. 1594@end defmac 1595 1596@defmac LIBGCC2_GNU_PREFIX 1597This macro corresponds to the @code{TARGET_LIBFUNC_GNU_PREFIX} target 1598hook and should be defined if that hook is overriden to be true. It 1599causes function names in libgcc to be changed to use a @code{__gnu_} 1600prefix for their name rather than the default @code{__}. A port which 1601uses this macro should also arrange to use @file{t-gnu-prefix} in 1602the libgcc @file{config.host}. 1603@end defmac 1604 1605@defmac SF_SIZE 1606@defmacx DF_SIZE 1607@defmacx XF_SIZE 1608@defmacx TF_SIZE 1609Define these macros to be the size in bits of the mantissa of 1610@code{SFmode}, @code{DFmode}, @code{XFmode} and @code{TFmode} values, 1611if the defaults in @file{libgcc2.h} are inappropriate. By default, 1612@code{FLT_MANT_DIG} is used for @code{SF_SIZE}, @code{LDBL_MANT_DIG} 1613for @code{XF_SIZE} and @code{TF_SIZE}, and @code{DBL_MANT_DIG} or 1614@code{LDBL_MANT_DIG} for @code{DF_SIZE} according to whether 1615@code{DOUBLE_TYPE_SIZE} or 1616@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64. 1617@end defmac 1618 1619@defmac TARGET_FLT_EVAL_METHOD 1620A C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, 1621assuming, if applicable, that the floating-point control word is in its 1622default state. If you do not define this macro the value of 1623@code{FLT_EVAL_METHOD} will be zero. 1624@end defmac 1625 1626@defmac WIDEST_HARDWARE_FP_SIZE 1627A C expression for the size in bits of the widest floating-point format 1628supported by the hardware. If you define this macro, you must specify a 1629value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 1630If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 1631is the default. 1632@end defmac 1633 1634@defmac DEFAULT_SIGNED_CHAR 1635An expression whose value is 1 or 0, according to whether the type 1636@code{char} should be signed or unsigned by default. The user can 1637always override this default with the options @option{-fsigned-char} 1638and @option{-funsigned-char}. 1639@end defmac 1640 1641@deftypefn {Target Hook} bool TARGET_DEFAULT_SHORT_ENUMS (void) 1642This target hook should return true if the compiler should give an 1643@code{enum} type only as many bytes as it takes to represent the range 1644of possible values of that type. It should return false if all 1645@code{enum} types should be allocated like @code{int}. 1646 1647The default is to return false. 1648@end deftypefn 1649 1650@defmac SIZE_TYPE 1651A C expression for a string describing the name of the data type to use 1652for size values. The typedef name @code{size_t} is defined using the 1653contents of the string. 1654 1655The string can contain more than one keyword. If so, separate them with 1656spaces, and write first any length keyword, then @code{unsigned} if 1657appropriate, and finally @code{int}. The string must exactly match one 1658of the data type names defined in the function 1659@code{init_decl_processing} in the file @file{c-decl.c}. You may not 1660omit @code{int} or change the order---that would cause the compiler to 1661crash on startup. 1662 1663If you don't define this macro, the default is @code{"long unsigned 1664int"}. 1665@end defmac 1666 1667@defmac PTRDIFF_TYPE 1668A C expression for a string describing the name of the data type to use 1669for the result of subtracting two pointers. The typedef name 1670@code{ptrdiff_t} is defined using the contents of the string. See 1671@code{SIZE_TYPE} above for more information. 1672 1673If you don't define this macro, the default is @code{"long int"}. 1674@end defmac 1675 1676@defmac WCHAR_TYPE 1677A C expression for a string describing the name of the data type to use 1678for wide characters. The typedef name @code{wchar_t} is defined using 1679the contents of the string. See @code{SIZE_TYPE} above for more 1680information. 1681 1682If you don't define this macro, the default is @code{"int"}. 1683@end defmac 1684 1685@defmac WCHAR_TYPE_SIZE 1686A C expression for the size in bits of the data type for wide 1687characters. This is used in @code{cpp}, which cannot make use of 1688@code{WCHAR_TYPE}. 1689@end defmac 1690 1691@defmac WINT_TYPE 1692A C expression for a string describing the name of the data type to 1693use for wide characters passed to @code{printf} and returned from 1694@code{getwc}. The typedef name @code{wint_t} is defined using the 1695contents of the string. See @code{SIZE_TYPE} above for more 1696information. 1697 1698If you don't define this macro, the default is @code{"unsigned int"}. 1699@end defmac 1700 1701@defmac INTMAX_TYPE 1702A C expression for a string describing the name of the data type that 1703can represent any value of any standard or extended signed integer type. 1704The typedef name @code{intmax_t} is defined using the contents of the 1705string. See @code{SIZE_TYPE} above for more information. 1706 1707If you don't define this macro, the default is the first of 1708@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 1709much precision as @code{long long int}. 1710@end defmac 1711 1712@defmac UINTMAX_TYPE 1713A C expression for a string describing the name of the data type that 1714can represent any value of any standard or extended unsigned integer 1715type. The typedef name @code{uintmax_t} is defined using the contents 1716of the string. See @code{SIZE_TYPE} above for more information. 1717 1718If you don't define this macro, the default is the first of 1719@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 1720unsigned int"} that has as much precision as @code{long long unsigned 1721int}. 1722@end defmac 1723 1724@defmac SIG_ATOMIC_TYPE 1725@defmacx INT8_TYPE 1726@defmacx INT16_TYPE 1727@defmacx INT32_TYPE 1728@defmacx INT64_TYPE 1729@defmacx UINT8_TYPE 1730@defmacx UINT16_TYPE 1731@defmacx UINT32_TYPE 1732@defmacx UINT64_TYPE 1733@defmacx INT_LEAST8_TYPE 1734@defmacx INT_LEAST16_TYPE 1735@defmacx INT_LEAST32_TYPE 1736@defmacx INT_LEAST64_TYPE 1737@defmacx UINT_LEAST8_TYPE 1738@defmacx UINT_LEAST16_TYPE 1739@defmacx UINT_LEAST32_TYPE 1740@defmacx UINT_LEAST64_TYPE 1741@defmacx INT_FAST8_TYPE 1742@defmacx INT_FAST16_TYPE 1743@defmacx INT_FAST32_TYPE 1744@defmacx INT_FAST64_TYPE 1745@defmacx UINT_FAST8_TYPE 1746@defmacx UINT_FAST16_TYPE 1747@defmacx UINT_FAST32_TYPE 1748@defmacx UINT_FAST64_TYPE 1749@defmacx INTPTR_TYPE 1750@defmacx UINTPTR_TYPE 1751C expressions for the standard types @code{sig_atomic_t}, 1752@code{int8_t}, @code{int16_t}, @code{int32_t}, @code{int64_t}, 1753@code{uint8_t}, @code{uint16_t}, @code{uint32_t}, @code{uint64_t}, 1754@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, 1755@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, 1756@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, 1757@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, 1758@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, 1759@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t}. See 1760@code{SIZE_TYPE} above for more information. 1761 1762If any of these macros evaluates to a null pointer, the corresponding 1763type is not supported; if GCC is configured to provide 1764@code{<stdint.h>} in such a case, the header provided may not conform 1765to C99, depending on the type in question. The defaults for all of 1766these macros are null pointers. 1767@end defmac 1768 1769@defmac TARGET_PTRMEMFUNC_VBIT_LOCATION 1770The C++ compiler represents a pointer-to-member-function with a struct 1771that looks like: 1772 1773@smallexample 1774 struct @{ 1775 union @{ 1776 void (*fn)(); 1777 ptrdiff_t vtable_index; 1778 @}; 1779 ptrdiff_t delta; 1780 @}; 1781@end smallexample 1782 1783@noindent 1784The C++ compiler must use one bit to indicate whether the function that 1785will be called through a pointer-to-member-function is virtual. 1786Normally, we assume that the low-order bit of a function pointer must 1787always be zero. Then, by ensuring that the vtable_index is odd, we can 1788distinguish which variant of the union is in use. But, on some 1789platforms function pointers can be odd, and so this doesn't work. In 1790that case, we use the low-order bit of the @code{delta} field, and shift 1791the remainder of the @code{delta} field to the left. 1792 1793GCC will automatically make the right selection about where to store 1794this bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 1795However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 1796set such that functions always start at even addresses, but the lowest 1797bit of pointers to functions indicate whether the function at that 1798address is in ARM or Thumb mode. If this is the case of your 1799architecture, you should define this macro to 1800@code{ptrmemfunc_vbit_in_delta}. 1801 1802In general, you should not have to define this macro. On architectures 1803in which function addresses are always even, according to 1804@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 1805@code{ptrmemfunc_vbit_in_pfn}. 1806@end defmac 1807 1808@defmac TARGET_VTABLE_USES_DESCRIPTORS 1809Normally, the C++ compiler uses function pointers in vtables. This 1810macro allows the target to change to use ``function descriptors'' 1811instead. Function descriptors are found on targets for whom a 1812function pointer is actually a small data structure. Normally the 1813data structure consists of the actual code address plus a data 1814pointer to which the function's data is relative. 1815 1816If vtables are used, the value of this macro should be the number 1817of words that the function descriptor occupies. 1818@end defmac 1819 1820@defmac TARGET_VTABLE_ENTRY_ALIGN 1821By default, the vtable entries are void pointers, the so the alignment 1822is the same as pointer alignment. The value of this macro specifies 1823the alignment of the vtable entry in bits. It should be defined only 1824when special alignment is necessary. */ 1825@end defmac 1826 1827@defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE 1828There are a few non-descriptor entries in the vtable at offsets below 1829zero. If these entries must be padded (say, to preserve the alignment 1830specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number 1831of words in each data entry. 1832@end defmac 1833 1834@node Registers 1835@section Register Usage 1836@cindex register usage 1837 1838This section explains how to describe what registers the target machine 1839has, and how (in general) they can be used. 1840 1841The description of which registers a specific instruction can use is 1842done with register classes; see @ref{Register Classes}. For information 1843on using registers to access a stack frame, see @ref{Frame Registers}. 1844For passing values in registers, see @ref{Register Arguments}. 1845For returning values in registers, see @ref{Scalar Return}. 1846 1847@menu 1848* Register Basics:: Number and kinds of registers. 1849* Allocation Order:: Order in which registers are allocated. 1850* Values in Registers:: What kinds of values each reg can hold. 1851* Leaf Functions:: Renumbering registers for leaf functions. 1852* Stack Registers:: Handling a register stack such as 80387. 1853@end menu 1854 1855@node Register Basics 1856@subsection Basic Characteristics of Registers 1857 1858@c prevent bad page break with this line 1859Registers have various characteristics. 1860 1861@defmac FIRST_PSEUDO_REGISTER 1862Number of hardware registers known to the compiler. They receive 1863numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 1864pseudo register's number really is assigned the number 1865@code{FIRST_PSEUDO_REGISTER}. 1866@end defmac 1867 1868@defmac FIXED_REGISTERS 1869@cindex fixed register 1870An initializer that says which registers are used for fixed purposes 1871all throughout the compiled code and are therefore not available for 1872general allocation. These would include the stack pointer, the frame 1873pointer (except on machines where that can be used as a general 1874register when no frame pointer is needed), the program counter on 1875machines where that is considered one of the addressable registers, 1876and any other numbered register with a standard use. 1877 1878This information is expressed as a sequence of numbers, separated by 1879commas and surrounded by braces. The @var{n}th number is 1 if 1880register @var{n} is fixed, 0 otherwise. 1881 1882The table initialized from this macro, and the table initialized by 1883the following one, may be overridden at run time either automatically, 1884by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 1885the user with the command options @option{-ffixed-@var{reg}}, 1886@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. 1887@end defmac 1888 1889@defmac CALL_USED_REGISTERS 1890@cindex call-used register 1891@cindex call-clobbered register 1892@cindex call-saved register 1893Like @code{FIXED_REGISTERS} but has 1 for each register that is 1894clobbered (in general) by function calls as well as for fixed 1895registers. This macro therefore identifies the registers that are not 1896available for general allocation of values that must live across 1897function calls. 1898 1899If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 1900automatically saves it on function entry and restores it on function 1901exit, if the register is used within the function. 1902@end defmac 1903 1904@defmac CALL_REALLY_USED_REGISTERS 1905@cindex call-used register 1906@cindex call-clobbered register 1907@cindex call-saved register 1908Like @code{CALL_USED_REGISTERS} except this macro doesn't require 1909that the entire set of @code{FIXED_REGISTERS} be included. 1910(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). 1911This macro is optional. If not specified, it defaults to the value 1912of @code{CALL_USED_REGISTERS}. 1913@end defmac 1914 1915@defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) 1916@cindex call-used register 1917@cindex call-clobbered register 1918@cindex call-saved register 1919A C expression that is nonzero if it is not permissible to store a 1920value of mode @var{mode} in hard register number @var{regno} across a 1921call without some part of it being clobbered. For most machines this 1922macro need not be defined. It is only required for machines that do not 1923preserve the entire contents of a register across a call. 1924@end defmac 1925 1926@findex fixed_regs 1927@findex call_used_regs 1928@findex global_regs 1929@findex reg_names 1930@findex reg_class_contents 1931@deftypefn {Target Hook} void TARGET_CONDITIONAL_REGISTER_USAGE (void) 1932This hook may conditionally modify five variables 1933@code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, 1934@code{reg_names}, and @code{reg_class_contents}, to take into account 1935any dependence of these register sets on target flags. The first three 1936of these are of type @code{char []} (interpreted as Boolean vectors). 1937@code{global_regs} is a @code{const char *[]}, and 1938@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is 1939called, @code{fixed_regs}, @code{call_used_regs}, 1940@code{reg_class_contents}, and @code{reg_names} have been initialized 1941from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, 1942@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. 1943@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, 1944@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} 1945command options have been applied. 1946 1947@cindex disabling certain registers 1948@cindex controlling register usage 1949If the usage of an entire class of registers depends on the target 1950flags, you may indicate this to GCC by using this macro to modify 1951@code{fixed_regs} and @code{call_used_regs} to 1 for each of the 1952registers in the classes which should not be used by GCC@. Also define 1953the macro @code{REG_CLASS_FROM_LETTER} / @code{REG_CLASS_FROM_CONSTRAINT} 1954to return @code{NO_REGS} if it 1955is called with a letter for a class that shouldn't be used. 1956 1957(However, if this class is not included in @code{GENERAL_REGS} and all 1958of the insn patterns whose constraints permit this class are 1959controlled by target switches, then GCC will automatically avoid using 1960these registers when the target switches are opposed to them.) 1961@end deftypefn 1962 1963@defmac INCOMING_REGNO (@var{out}) 1964Define this macro if the target machine has register windows. This C 1965expression returns the register number as seen by the called function 1966corresponding to the register number @var{out} as seen by the calling 1967function. Return @var{out} if register number @var{out} is not an 1968outbound register. 1969@end defmac 1970 1971@defmac OUTGOING_REGNO (@var{in}) 1972Define this macro if the target machine has register windows. This C 1973expression returns the register number as seen by the calling function 1974corresponding to the register number @var{in} as seen by the called 1975function. Return @var{in} if register number @var{in} is not an inbound 1976register. 1977@end defmac 1978 1979@defmac LOCAL_REGNO (@var{regno}) 1980Define this macro if the target machine has register windows. This C 1981expression returns true if the register is call-saved but is in the 1982register window. Unlike most call-saved registers, such registers 1983need not be explicitly restored on function exit or during non-local 1984gotos. 1985@end defmac 1986 1987@defmac PC_REGNUM 1988If the program counter has a register number, define this as that 1989register number. Otherwise, do not define it. 1990@end defmac 1991 1992@node Allocation Order 1993@subsection Order of Allocation of Registers 1994@cindex order of register allocation 1995@cindex register allocation order 1996 1997@c prevent bad page break with this line 1998Registers are allocated in order. 1999 2000@defmac REG_ALLOC_ORDER 2001If defined, an initializer for a vector of integers, containing the 2002numbers of hard registers in the order in which GCC should prefer 2003to use them (from most preferred to least). 2004 2005If this macro is not defined, registers are used lowest numbered first 2006(all else being equal). 2007 2008One use of this macro is on machines where the highest numbered 2009registers must always be saved and the save-multiple-registers 2010instruction supports only sequences of consecutive registers. On such 2011machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 2012the highest numbered allocable register first. 2013@end defmac 2014 2015@defmac ADJUST_REG_ALLOC_ORDER 2016A C statement (sans semicolon) to choose the order in which to allocate 2017hard registers for pseudo-registers local to a basic block. 2018 2019Store the desired register order in the array @code{reg_alloc_order}. 2020Element 0 should be the register to allocate first; element 1, the next 2021register; and so on. 2022 2023The macro body should not assume anything about the contents of 2024@code{reg_alloc_order} before execution of the macro. 2025 2026On most machines, it is not necessary to define this macro. 2027@end defmac 2028 2029@defmac HONOR_REG_ALLOC_ORDER 2030Normally, IRA tries to estimate the costs for saving a register in the 2031prologue and restoring it in the epilogue. This discourages it from 2032using call-saved registers. If a machine wants to ensure that IRA 2033allocates registers in the order given by REG_ALLOC_ORDER even if some 2034call-saved registers appear earlier than call-used ones, this macro 2035should be defined. 2036@end defmac 2037 2038@defmac IRA_HARD_REGNO_ADD_COST_MULTIPLIER (@var{regno}) 2039In some case register allocation order is not enough for the 2040Integrated Register Allocator (@acronym{IRA}) to generate a good code. 2041If this macro is defined, it should return a floating point value 2042based on @var{regno}. The cost of using @var{regno} for a pseudo will 2043be increased by approximately the pseudo's usage frequency times the 2044value returned by this macro. Not defining this macro is equivalent 2045to having it always return @code{0.0}. 2046 2047On most machines, it is not necessary to define this macro. 2048@end defmac 2049 2050@node Values in Registers 2051@subsection How Values Fit in Registers 2052 2053This section discusses the macros that describe which kinds of values 2054(specifically, which machine modes) each register can hold, and how many 2055consecutive registers are needed for a given mode. 2056 2057@defmac HARD_REGNO_NREGS (@var{regno}, @var{mode}) 2058A C expression for the number of consecutive hard registers, starting 2059at register number @var{regno}, required to hold a value of mode 2060@var{mode}. This macro must never return zero, even if a register 2061cannot hold the requested mode - indicate that with HARD_REGNO_MODE_OK 2062and/or CANNOT_CHANGE_MODE_CLASS instead. 2063 2064On a machine where all registers are exactly one word, a suitable 2065definition of this macro is 2066 2067@smallexample 2068#define HARD_REGNO_NREGS(REGNO, MODE) \ 2069 ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 2070 / UNITS_PER_WORD) 2071@end smallexample 2072@end defmac 2073 2074@defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode}) 2075A C expression that is nonzero if a value of mode @var{mode}, stored 2076in memory, ends with padding that causes it to take up more space than 2077in registers starting at register number @var{regno} (as determined by 2078multiplying GCC's notion of the size of the register when containing 2079this mode by the number of registers returned by 2080@code{HARD_REGNO_NREGS}). By default this is zero. 2081 2082For example, if a floating-point value is stored in three 32-bit 2083registers but takes up 128 bits in memory, then this would be 2084nonzero. 2085 2086This macros only needs to be defined if there are cases where 2087@code{subreg_get_info} 2088would otherwise wrongly determine that a @code{subreg} can be 2089represented by an offset to the register number, when in fact such a 2090@code{subreg} would contain some of the padding not stored in 2091registers and so not be representable. 2092@end defmac 2093 2094@defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode}) 2095For values of @var{regno} and @var{mode} for which 2096@code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression 2097returning the greater number of registers required to hold the value 2098including any padding. In the example above, the value would be four. 2099@end defmac 2100 2101@defmac REGMODE_NATURAL_SIZE (@var{mode}) 2102Define this macro if the natural size of registers that hold values 2103of mode @var{mode} is not the word size. It is a C expression that 2104should give the natural size in bytes for the specified mode. It is 2105used by the register allocator to try to optimize its results. This 2106happens for example on SPARC 64-bit where the natural size of 2107floating-point registers is still 32-bit. 2108@end defmac 2109 2110@defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 2111A C expression that is nonzero if it is permissible to store a value 2112of mode @var{mode} in hard register number @var{regno} (or in several 2113registers starting with that one). For a machine where all registers 2114are equivalent, a suitable definition is 2115 2116@smallexample 2117#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 2118@end smallexample 2119 2120You need not include code to check for the numbers of fixed registers, 2121because the allocation mechanism considers them to be always occupied. 2122 2123@cindex register pairs 2124On some machines, double-precision values must be kept in even/odd 2125register pairs. You can implement that by defining this macro to reject 2126odd register numbers for such modes. 2127 2128The minimum requirement for a mode to be OK in a register is that the 2129@samp{mov@var{mode}} instruction pattern support moves between the 2130register and other hard register in the same class and that moving a 2131value into the register and back out not alter it. 2132 2133Since the same instruction used to move @code{word_mode} will work for 2134all narrower integer modes, it is not necessary on any machine for 2135@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 2136you define patterns @samp{movhi}, etc., to take advantage of this. This 2137is useful because of the interaction between @code{HARD_REGNO_MODE_OK} 2138and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 2139to be tieable. 2140 2141Many machines have special registers for floating point arithmetic. 2142Often people assume that floating point machine modes are allowed only 2143in floating point registers. This is not true. Any registers that 2144can hold integers can safely @emph{hold} a floating point machine 2145mode, whether or not floating arithmetic can be done on it in those 2146registers. Integer move instructions can be used to move the values. 2147 2148On some machines, though, the converse is true: fixed-point machine 2149modes may not go in floating registers. This is true if the floating 2150registers normalize any value stored in them, because storing a 2151non-floating value there would garble it. In this case, 2152@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 2153floating registers. But if the floating registers do not automatically 2154normalize, if you can store any bit pattern in one and retrieve it 2155unchanged without a trap, then any machine mode may go in a floating 2156register, so you can define this macro to say so. 2157 2158The primary significance of special floating registers is rather that 2159they are the registers acceptable in floating point arithmetic 2160instructions. However, this is of no concern to 2161@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 2162constraints for those instructions. 2163 2164On some machines, the floating registers are especially slow to access, 2165so that it is better to store a value in a stack frame than in such a 2166register if floating point arithmetic is not being done. As long as the 2167floating registers are not in class @code{GENERAL_REGS}, they will not 2168be used unless some pattern's constraint asks for one. 2169@end defmac 2170 2171@defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to}) 2172A C expression that is nonzero if it is OK to rename a hard register 2173@var{from} to another hard register @var{to}. 2174 2175One common use of this macro is to prevent renaming of a register to 2176another register that is not saved by a prologue in an interrupt 2177handler. 2178 2179The default is always nonzero. 2180@end defmac 2181 2182@defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 2183A C expression that is nonzero if a value of mode 2184@var{mode1} is accessible in mode @var{mode2} without copying. 2185 2186If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 2187@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for 2188any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})} 2189should be nonzero. If they differ for any @var{r}, you should define 2190this macro to return zero unless some other mechanism ensures the 2191accessibility of the value in a narrower mode. 2192 2193You should define this macro to return nonzero in as many cases as 2194possible since doing so will allow GCC to perform better register 2195allocation. 2196@end defmac 2197 2198@deftypefn {Target Hook} bool TARGET_HARD_REGNO_SCRATCH_OK (unsigned int @var{regno}) 2199This target hook should return @code{true} if it is OK to use a hard register 2200@var{regno} as scratch reg in peephole2. 2201 2202One common use of this macro is to prevent using of a register that 2203is not saved by a prologue in an interrupt handler. 2204 2205The default version of this hook always returns @code{true}. 2206@end deftypefn 2207 2208@defmac AVOID_CCMODE_COPIES 2209Define this macro if the compiler should avoid copies to/from @code{CCmode} 2210registers. You should only define this macro if support for copying to/from 2211@code{CCmode} is incomplete. 2212@end defmac 2213 2214@node Leaf Functions 2215@subsection Handling Leaf Functions 2216 2217@cindex leaf functions 2218@cindex functions, leaf 2219On some machines, a leaf function (i.e., one which makes no calls) can run 2220more efficiently if it does not make its own register window. Often this 2221means it is required to receive its arguments in the registers where they 2222are passed by the caller, instead of the registers where they would 2223normally arrive. 2224 2225The special treatment for leaf functions generally applies only when 2226other conditions are met; for example, often they may use only those 2227registers for its own variables and temporaries. We use the term ``leaf 2228function'' to mean a function that is suitable for this special 2229handling, so that functions with no calls are not necessarily ``leaf 2230functions''. 2231 2232GCC assigns register numbers before it knows whether the function is 2233suitable for leaf function treatment. So it needs to renumber the 2234registers in order to output a leaf function. The following macros 2235accomplish this. 2236 2237@defmac LEAF_REGISTERS 2238Name of a char vector, indexed by hard register number, which 2239contains 1 for a register that is allowable in a candidate for leaf 2240function treatment. 2241 2242If leaf function treatment involves renumbering the registers, then the 2243registers marked here should be the ones before renumbering---those that 2244GCC would ordinarily allocate. The registers which will actually be 2245used in the assembler code, after renumbering, should not be marked with 1 2246in this vector. 2247 2248Define this macro only if the target machine offers a way to optimize 2249the treatment of leaf functions. 2250@end defmac 2251 2252@defmac LEAF_REG_REMAP (@var{regno}) 2253A C expression whose value is the register number to which @var{regno} 2254should be renumbered, when a function is treated as a leaf function. 2255 2256If @var{regno} is a register number which should not appear in a leaf 2257function before renumbering, then the expression should yield @minus{}1, which 2258will cause the compiler to abort. 2259 2260Define this macro only if the target machine offers a way to optimize the 2261treatment of leaf functions, and registers need to be renumbered to do 2262this. 2263@end defmac 2264 2265@findex current_function_is_leaf 2266@findex current_function_uses_only_leaf_regs 2267@code{TARGET_ASM_FUNCTION_PROLOGUE} and 2268@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions 2269specially. They can test the C variable @code{current_function_is_leaf} 2270which is nonzero for leaf functions. @code{current_function_is_leaf} is 2271set prior to local register allocation and is valid for the remaining 2272compiler passes. They can also test the C variable 2273@code{current_function_uses_only_leaf_regs} which is nonzero for leaf 2274functions which only use leaf registers. 2275@code{current_function_uses_only_leaf_regs} is valid after all passes 2276that modify the instructions have been run and is only useful if 2277@code{LEAF_REGISTERS} is defined. 2278@c changed this to fix overfull. ALSO: why the "it" at the beginning 2279@c of the next paragraph?! --mew 2feb93 2280 2281@node Stack Registers 2282@subsection Registers That Form a Stack 2283 2284There are special features to handle computers where some of the 2285``registers'' form a stack. Stack registers are normally written by 2286pushing onto the stack, and are numbered relative to the top of the 2287stack. 2288 2289Currently, GCC can only handle one group of stack-like registers, and 2290they must be consecutively numbered. Furthermore, the existing 2291support for stack-like registers is specific to the 80387 floating 2292point coprocessor. If you have a new architecture that uses 2293stack-like registers, you will need to do substantial work on 2294@file{reg-stack.c} and write your machine description to cooperate 2295with it, as well as defining these macros. 2296 2297@defmac STACK_REGS 2298Define this if the machine has any stack-like registers. 2299@end defmac 2300 2301@defmac STACK_REG_COVER_CLASS 2302This is a cover class containing the stack registers. Define this if 2303the machine has any stack-like registers. 2304@end defmac 2305 2306@defmac FIRST_STACK_REG 2307The number of the first stack-like register. This one is the top 2308of the stack. 2309@end defmac 2310 2311@defmac LAST_STACK_REG 2312The number of the last stack-like register. This one is the bottom of 2313the stack. 2314@end defmac 2315 2316@node Register Classes 2317@section Register Classes 2318@cindex register class definitions 2319@cindex class definitions, register 2320 2321On many machines, the numbered registers are not all equivalent. 2322For example, certain registers may not be allowed for indexed addressing; 2323certain registers may not be allowed in some instructions. These machine 2324restrictions are described to the compiler using @dfn{register classes}. 2325 2326You define a number of register classes, giving each one a name and saying 2327which of the registers belong to it. Then you can specify register classes 2328that are allowed as operands to particular instruction patterns. 2329 2330@findex ALL_REGS 2331@findex NO_REGS 2332In general, each register will belong to several classes. In fact, one 2333class must be named @code{ALL_REGS} and contain all the registers. Another 2334class must be named @code{NO_REGS} and contain no registers. Often the 2335union of two classes will be another class; however, this is not required. 2336 2337@findex GENERAL_REGS 2338One of the classes must be named @code{GENERAL_REGS}. There is nothing 2339terribly special about the name, but the operand constraint letters 2340@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 2341the same as @code{ALL_REGS}, just define it as a macro which expands 2342to @code{ALL_REGS}. 2343 2344Order the classes so that if class @var{x} is contained in class @var{y} 2345then @var{x} has a lower class number than @var{y}. 2346 2347The way classes other than @code{GENERAL_REGS} are specified in operand 2348constraints is through machine-dependent operand constraint letters. 2349You can define such letters to correspond to various classes, then use 2350them in operand constraints. 2351 2352You must define the narrowest register classes for allocatable 2353registers, so that each class either has no subclasses, or that for 2354some mode, the move cost between registers within the class is 2355cheaper than moving a register in the class to or from memory 2356(@pxref{Costs}). 2357 2358You should define a class for the union of two classes whenever some 2359instruction allows both classes. For example, if an instruction allows 2360either a floating point (coprocessor) register or a general register for a 2361certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 2362which includes both of them. Otherwise you will get suboptimal code, 2363or even internal compiler errors when reload cannot find a register in the 2364class computed via @code{reg_class_subunion}. 2365 2366You must also specify certain redundant information about the register 2367classes: for each class, which classes contain it and which ones are 2368contained in it; for each pair of classes, the largest class contained 2369in their union. 2370 2371When a value occupying several consecutive registers is expected in a 2372certain class, all the registers used must belong to that class. 2373Therefore, register classes cannot be used to enforce a requirement for 2374a register pair to start with an even-numbered register. The way to 2375specify this requirement is with @code{HARD_REGNO_MODE_OK}. 2376 2377Register classes used for input-operands of bitwise-and or shift 2378instructions have a special requirement: each such class must have, for 2379each fixed-point machine mode, a subclass whose registers can transfer that 2380mode to or from memory. For example, on some machines, the operations for 2381single-byte values (@code{QImode}) are limited to certain registers. When 2382this is so, each register class that is used in a bitwise-and or shift 2383instruction must have a subclass consisting of registers from which 2384single-byte values can be loaded or stored. This is so that 2385@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 2386 2387@deftp {Data type} {enum reg_class} 2388An enumerated type that must be defined with all the register class names 2389as enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS} 2390must be the last register class, followed by one more enumerated value, 2391@code{LIM_REG_CLASSES}, which is not a register class but rather 2392tells how many classes there are. 2393 2394Each register class has a number, which is the value of casting 2395the class name to type @code{int}. The number serves as an index 2396in many of the tables described below. 2397@end deftp 2398 2399@defmac N_REG_CLASSES 2400The number of distinct register classes, defined as follows: 2401 2402@smallexample 2403#define N_REG_CLASSES (int) LIM_REG_CLASSES 2404@end smallexample 2405@end defmac 2406 2407@defmac REG_CLASS_NAMES 2408An initializer containing the names of the register classes as C string 2409constants. These names are used in writing some of the debugging dumps. 2410@end defmac 2411 2412@defmac REG_CLASS_CONTENTS 2413An initializer containing the contents of the register classes, as integers 2414which are bit masks. The @var{n}th integer specifies the contents of class 2415@var{n}. The way the integer @var{mask} is interpreted is that 2416register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 2417 2418When the machine has more than 32 registers, an integer does not suffice. 2419Then the integers are replaced by sub-initializers, braced groupings containing 2420several integers. Each sub-initializer must be suitable as an initializer 2421for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 2422In this situation, the first integer in each sub-initializer corresponds to 2423registers 0 through 31, the second integer to registers 32 through 63, and 2424so on. 2425@end defmac 2426 2427@defmac REGNO_REG_CLASS (@var{regno}) 2428A C expression whose value is a register class containing hard register 2429@var{regno}. In general there is more than one such class; choose a class 2430which is @dfn{minimal}, meaning that no smaller class also contains the 2431register. 2432@end defmac 2433 2434@defmac BASE_REG_CLASS 2435A macro whose definition is the name of the class to which a valid 2436base register must belong. A base register is one used in an address 2437which is the register value plus a displacement. 2438@end defmac 2439 2440@defmac MODE_BASE_REG_CLASS (@var{mode}) 2441This is a variation of the @code{BASE_REG_CLASS} macro which allows 2442the selection of a base register in a mode dependent manner. If 2443@var{mode} is VOIDmode then it should return the same value as 2444@code{BASE_REG_CLASS}. 2445@end defmac 2446 2447@defmac MODE_BASE_REG_REG_CLASS (@var{mode}) 2448A C expression whose value is the register class to which a valid 2449base register must belong in order to be used in a base plus index 2450register address. You should define this macro if base plus index 2451addresses have different requirements than other base register uses. 2452@end defmac 2453 2454@defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{address_space}, @var{outer_code}, @var{index_code}) 2455A C expression whose value is the register class to which a valid 2456base register for a memory reference in mode @var{mode} to address 2457space @var{address_space} must belong. @var{outer_code} and @var{index_code} 2458define the context in which the base register occurs. @var{outer_code} is 2459the code of the immediately enclosing expression (@code{MEM} for the top level 2460of an address, @code{ADDRESS} for something that occurs in an 2461@code{address_operand}). @var{index_code} is the code of the corresponding 2462index expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise. 2463@end defmac 2464 2465@defmac INDEX_REG_CLASS 2466A macro whose definition is the name of the class to which a valid 2467index register must belong. An index register is one used in an 2468address where its value is either multiplied by a scale factor or 2469added to another register (as well as added to a displacement). 2470@end defmac 2471 2472@defmac REGNO_OK_FOR_BASE_P (@var{num}) 2473A C expression which is nonzero if register number @var{num} is 2474suitable for use as a base register in operand addresses. 2475@end defmac 2476 2477@defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) 2478A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that 2479that expression may examine the mode of the memory reference in 2480@var{mode}. You should define this macro if the mode of the memory 2481reference affects whether a register may be used as a base register. If 2482you define this macro, the compiler will use it instead of 2483@code{REGNO_OK_FOR_BASE_P}. The mode may be @code{VOIDmode} for 2484addresses that appear outside a @code{MEM}, i.e., as an 2485@code{address_operand}. 2486@end defmac 2487 2488@defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode}) 2489A C expression which is nonzero if register number @var{num} is suitable for 2490use as a base register in base plus index operand addresses, accessing 2491memory in mode @var{mode}. It may be either a suitable hard register or a 2492pseudo register that has been allocated such a hard register. You should 2493define this macro if base plus index addresses have different requirements 2494than other base register uses. 2495 2496Use of this macro is deprecated; please use the more general 2497@code{REGNO_MODE_CODE_OK_FOR_BASE_P}. 2498@end defmac 2499 2500@defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{address_space}, @var{outer_code}, @var{index_code}) 2501A C expression which is nonzero if register number @var{num} is 2502suitable for use as a base register in operand addresses, accessing 2503memory in mode @var{mode} in address space @var{address_space}. 2504This is similar to @code{REGNO_MODE_OK_FOR_BASE_P}, except 2505that that expression may examine the context in which the register 2506appears in the memory reference. @var{outer_code} is the code of the 2507immediately enclosing expression (@code{MEM} if at the top level of the 2508address, @code{ADDRESS} for something that occurs in an 2509@code{address_operand}). @var{index_code} is the code of the 2510corresponding index expression if @var{outer_code} is @code{PLUS}; 2511@code{SCRATCH} otherwise. The mode may be @code{VOIDmode} for addresses 2512that appear outside a @code{MEM}, i.e., as an @code{address_operand}. 2513@end defmac 2514 2515@defmac REGNO_OK_FOR_INDEX_P (@var{num}) 2516A C expression which is nonzero if register number @var{num} is 2517suitable for use as an index register in operand addresses. It may be 2518either a suitable hard register or a pseudo register that has been 2519allocated such a hard register. 2520 2521The difference between an index register and a base register is that 2522the index register may be scaled. If an address involves the sum of 2523two registers, neither one of them scaled, then either one may be 2524labeled the ``base'' and the other the ``index''; but whichever 2525labeling is used must fit the machine's constraints of which registers 2526may serve in each capacity. The compiler will try both labelings, 2527looking for one that is valid, and will reload one or both registers 2528only if neither labeling works. 2529@end defmac 2530 2531@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RENAME_CLASS (reg_class_t @var{rclass}) 2532A 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. 2533@end deftypefn 2534 2535@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass}) 2536A target hook that places additional restrictions on the register class 2537to use when it is necessary to copy value @var{x} into a register in class 2538@var{rclass}. The value is a register class; perhaps @var{rclass}, or perhaps 2539another, smaller class. 2540 2541The default version of this hook always returns value of @code{rclass} argument. 2542 2543Sometimes returning a more restrictive class makes better code. For 2544example, on the 68000, when @var{x} is an integer constant that is in range 2545for a @samp{moveq} instruction, the value of this macro is always 2546@code{DATA_REGS} as long as @var{rclass} includes the data registers. 2547Requiring a data register guarantees that a @samp{moveq} will be used. 2548 2549One case where @code{TARGET_PREFERRED_RELOAD_CLASS} must not return 2550@var{rclass} is if @var{x} is a legitimate constant which cannot be 2551loaded into some register class. By returning @code{NO_REGS} you can 2552force @var{x} into a memory location. For example, rs6000 can load 2553immediate values into general-purpose registers, but does not have an 2554instruction for loading an immediate value into a floating-point 2555register, so @code{TARGET_PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when 2556@var{x} is a floating-point constant. If the constant can't be loaded 2557into any kind of register, code generation will be better if 2558@code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead 2559of using @code{TARGET_PREFERRED_RELOAD_CLASS}. 2560 2561If an insn has pseudos in it after register allocation, reload will go 2562through the alternatives and call repeatedly @code{TARGET_PREFERRED_RELOAD_CLASS} 2563to find the best one. Returning @code{NO_REGS}, in this case, makes 2564reload add a @code{!} in front of the constraint: the x86 back-end uses 2565this feature to discourage usage of 387 registers when math is done in 2566the SSE registers (and vice versa). 2567@end deftypefn 2568 2569@defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 2570A C expression that places additional restrictions on the register class 2571to use when it is necessary to copy value @var{x} into a register in class 2572@var{class}. The value is a register class; perhaps @var{class}, or perhaps 2573another, smaller class. On many machines, the following definition is 2574safe: 2575 2576@smallexample 2577#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 2578@end smallexample 2579 2580Sometimes returning a more restrictive class makes better code. For 2581example, on the 68000, when @var{x} is an integer constant that is in range 2582for a @samp{moveq} instruction, the value of this macro is always 2583@code{DATA_REGS} as long as @var{class} includes the data registers. 2584Requiring a data register guarantees that a @samp{moveq} will be used. 2585 2586One case where @code{PREFERRED_RELOAD_CLASS} must not return 2587@var{class} is if @var{x} is a legitimate constant which cannot be 2588loaded into some register class. By returning @code{NO_REGS} you can 2589force @var{x} into a memory location. For example, rs6000 can load 2590immediate values into general-purpose registers, but does not have an 2591instruction for loading an immediate value into a floating-point 2592register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when 2593@var{x} is a floating-point constant. If the constant can't be loaded 2594into any kind of register, code generation will be better if 2595@code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead 2596of using @code{TARGET_PREFERRED_RELOAD_CLASS}. 2597 2598If an insn has pseudos in it after register allocation, reload will go 2599through the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS} 2600to find the best one. Returning @code{NO_REGS}, in this case, makes 2601reload add a @code{!} in front of the constraint: the x86 back-end uses 2602this feature to discourage usage of 387 registers when math is done in 2603the SSE registers (and vice versa). 2604@end defmac 2605 2606@deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_OUTPUT_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass}) 2607Like @code{TARGET_PREFERRED_RELOAD_CLASS}, but for output reloads instead of 2608input reloads. 2609 2610The default version of this hook always returns value of @code{rclass} 2611argument. 2612 2613You can also use @code{TARGET_PREFERRED_OUTPUT_RELOAD_CLASS} to discourage 2614reload from using some alternatives, like @code{TARGET_PREFERRED_RELOAD_CLASS}. 2615@end deftypefn 2616 2617@defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 2618A C expression that places additional restrictions on the register class 2619to use when it is necessary to be able to hold a value of mode 2620@var{mode} in a reload register for which class @var{class} would 2621ordinarily be used. 2622 2623Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 2624there are certain modes that simply can't go in certain reload classes. 2625 2626The value is a register class; perhaps @var{class}, or perhaps another, 2627smaller class. 2628 2629Don't define this macro unless the target machine has limitations which 2630require the macro to do something nontrivial. 2631@end defmac 2632 2633@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}) 2634Many machines have some registers that cannot be copied directly to or 2635from memory or even from other types of registers. An example is the 2636@samp{MQ} register, which on most machines, can only be copied to or 2637from general registers, but not memory. Below, we shall be using the 2638term 'intermediate register' when a move operation cannot be performed 2639directly, but has to be done by copying the source into the intermediate 2640register first, and then copying the intermediate register to the 2641destination. An intermediate register always has the same mode as 2642source and destination. Since it holds the actual value being copied, 2643reload might apply optimizations to re-use an intermediate register 2644and eliding the copy from the source when it can determine that the 2645intermediate register still holds the required value. 2646 2647Another kind of secondary reload is required on some machines which 2648allow copying all registers to and from memory, but require a scratch 2649register for stores to some memory locations (e.g., those with symbolic 2650address on the RT, and those with certain symbolic address on the SPARC 2651when compiling PIC)@. Scratch registers need not have the same mode 2652as the value being copied, and usually hold a different value than 2653that being copied. Special patterns in the md file are needed to 2654describe how the copy is performed with the help of the scratch register; 2655these patterns also describe the number, register class(es) and mode(s) 2656of the scratch register(s). 2657 2658In some cases, both an intermediate and a scratch register are required. 2659 2660For input reloads, this target hook is called with nonzero @var{in_p}, 2661and @var{x} is an rtx that needs to be copied to a register of class 2662@var{reload_class} in @var{reload_mode}. For output reloads, this target 2663hook is called with zero @var{in_p}, and a register of class @var{reload_class} 2664needs to be copied to rtx @var{x} in @var{reload_mode}. 2665 2666If copying a register of @var{reload_class} from/to @var{x} requires 2667an intermediate register, the hook @code{secondary_reload} should 2668return the register class required for this intermediate register. 2669If no intermediate register is required, it should return NO_REGS. 2670If more than one intermediate register is required, describe the one 2671that is closest in the copy chain to the reload register. 2672 2673If scratch registers are needed, you also have to describe how to 2674perform the copy from/to the reload register to/from this 2675closest intermediate register. Or if no intermediate register is 2676required, but still a scratch register is needed, describe the 2677copy from/to the reload register to/from the reload operand @var{x}. 2678 2679You do this by setting @code{sri->icode} to the instruction code of a pattern 2680in the md file which performs the move. Operands 0 and 1 are the output 2681and input of this copy, respectively. Operands from operand 2 onward are 2682for scratch operands. These scratch operands must have a mode, and a 2683single-register-class 2684@c [later: or memory] 2685output constraint. 2686 2687When an intermediate register is used, the @code{secondary_reload} 2688hook will be called again to determine how to copy the intermediate 2689register to/from the reload operand @var{x}, so your hook must also 2690have code to handle the register class of the intermediate operand. 2691 2692@c [For later: maybe we'll allow multi-alternative reload patterns - 2693@c the port maintainer could name a mov<mode> pattern that has clobbers - 2694@c and match the constraints of input and output to determine the required 2695@c alternative. A restriction would be that constraints used to match 2696@c against reloads registers would have to be written as register class 2697@c constraints, or we need a new target macro / hook that tells us if an 2698@c arbitrary constraint can match an unknown register of a given class. 2699@c Such a macro / hook would also be useful in other places.] 2700 2701 2702@var{x} might be a pseudo-register or a @code{subreg} of a 2703pseudo-register, which could either be in a hard register or in memory. 2704Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2705in memory and the hard register number if it is in a register. 2706 2707Scratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are 2708currently not supported. For the time being, you will have to continue 2709to use @code{SECONDARY_MEMORY_NEEDED} for that purpose. 2710 2711@code{copy_cost} also uses this target hook to find out how values are 2712copied. If you want it to include some extra cost for the need to allocate 2713(a) scratch register(s), set @code{sri->extra_cost} to the additional cost. 2714Or if two dependent moves are supposed to have a lower cost than the sum 2715of the individual moves due to expected fortuitous scheduling and/or special 2716forwarding logic, you can set @code{sri->extra_cost} to a negative amount. 2717@end deftypefn 2718 2719@defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2720@defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2721@defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2722These macros are obsolete, new ports should use the target hook 2723@code{TARGET_SECONDARY_RELOAD} instead. 2724 2725These are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD} 2726target hook. Older ports still define these macros to indicate to the 2727reload phase that it may 2728need to allocate at least one register for a reload in addition to the 2729register to contain the data. Specifically, if copying @var{x} to a 2730register @var{class} in @var{mode} requires an intermediate register, 2731you were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 2732largest register class all of whose registers can be used as 2733intermediate registers or scratch registers. 2734 2735If copying a register @var{class} in @var{mode} to @var{x} requires an 2736intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} 2737was supposed to be defined be defined to return the largest register 2738class required. If the 2739requirements for input and output reloads were the same, the macro 2740@code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both 2741macros identically. 2742 2743The values returned by these macros are often @code{GENERAL_REGS}. 2744Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 2745can be directly copied to or from a register of @var{class} in 2746@var{mode} without requiring a scratch register. Do not define this 2747macro if it would always return @code{NO_REGS}. 2748 2749If a scratch register is required (either with or without an 2750intermediate register), you were supposed to define patterns for 2751@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 2752(@pxref{Standard Names}. These patterns, which were normally 2753implemented with a @code{define_expand}, should be similar to the 2754@samp{mov@var{m}} patterns, except that operand 2 is the scratch 2755register. 2756 2757These patterns need constraints for the reload register and scratch 2758register that 2759contain a single register class. If the original reload register (whose 2760class is @var{class}) can meet the constraint given in the pattern, the 2761value returned by these macros is used for the class of the scratch 2762register. Otherwise, two additional reload registers are required. 2763Their classes are obtained from the constraints in the insn pattern. 2764 2765@var{x} might be a pseudo-register or a @code{subreg} of a 2766pseudo-register, which could either be in a hard register or in memory. 2767Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2768in memory and the hard register number if it is in a register. 2769 2770These macros should not be used in the case where a particular class of 2771registers can only be copied to memory and not to another class of 2772registers. In that case, secondary reload registers are not needed and 2773would not be helpful. Instead, a stack location must be used to perform 2774the copy and the @code{mov@var{m}} pattern should use memory as an 2775intermediate storage. This case often occurs between floating-point and 2776general registers. 2777@end defmac 2778 2779@defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 2780Certain machines have the property that some registers cannot be copied 2781to some other registers without using memory. Define this macro on 2782those machines to be a C expression that is nonzero if objects of mode 2783@var{m} in registers of @var{class1} can only be copied to registers of 2784class @var{class2} by storing a register of @var{class1} into memory 2785and loading that memory location into a register of @var{class2}. 2786 2787Do not define this macro if its value would always be zero. 2788@end defmac 2789 2790@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) 2791Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler 2792allocates a stack slot for a memory location needed for register copies. 2793If this macro is defined, the compiler instead uses the memory location 2794defined by this macro. 2795 2796Do not define this macro if you do not define 2797@code{SECONDARY_MEMORY_NEEDED}. 2798@end defmac 2799 2800@defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) 2801When the compiler needs a secondary memory location to copy between two 2802registers of mode @var{mode}, it normally allocates sufficient memory to 2803hold a quantity of @code{BITS_PER_WORD} bits and performs the store and 2804load operations in a mode that many bits wide and whose class is the 2805same as that of @var{mode}. 2806 2807This is right thing to do on most machines because it ensures that all 2808bits of the register are copied and prevents accesses to the registers 2809in a narrower mode, which some machines prohibit for floating-point 2810registers. 2811 2812However, this default behavior is not correct on some machines, such as 2813the DEC Alpha, that store short integers in floating-point registers 2814differently than in integer registers. On those machines, the default 2815widening will not work correctly and you must define this macro to 2816suppress that widening in some cases. See the file @file{alpha.h} for 2817details. 2818 2819Do not define this macro if you do not define 2820@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that 2821is @code{BITS_PER_WORD} bits wide is correct for your machine. 2822@end defmac 2823 2824@deftypefn {Target Hook} bool TARGET_CLASS_LIKELY_SPILLED_P (reg_class_t @var{rclass}) 2825A target hook which returns @code{true} if pseudos that have been assigned 2826to registers of class @var{rclass} would likely be spilled because 2827registers of @var{rclass} are needed for spill registers. 2828 2829The default version of this target hook returns @code{true} if @var{rclass} 2830has exactly one register and @code{false} otherwise. On most machines, this 2831default should be used. Only use this target hook to some other expression 2832if pseudos allocated by @file{local-alloc.c} end up in memory because their 2833hard registers were needed for spill registers. If this target hook returns 2834@code{false} for those classes, those pseudos will only be allocated by 2835@file{global.c}, which knows how to reallocate the pseudo to another 2836register. If there would not be another register available for reallocation, 2837you should not change the implementation of this target hook since 2838the only effect of such implementation would be to slow down register 2839allocation. 2840@end deftypefn 2841 2842@deftypefn {Target Hook} {unsigned char} TARGET_CLASS_MAX_NREGS (reg_class_t @var{rclass}, enum machine_mode @var{mode}) 2843A target hook returns the maximum number of consecutive registers 2844of class @var{rclass} needed to hold a value of mode @var{mode}. 2845 2846This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 2847the value returned by @code{TARGET_CLASS_MAX_NREGS (@var{rclass}, 2848@var{mode})} target hook should be the maximum value of 2849@code{HARD_REGNO_NREGS (@var{regno}, @var{mode})} for all @var{regno} 2850values in the class @var{rclass}. 2851 2852This target hook helps control the handling of multiple-word values 2853in the reload pass. 2854 2855The default version of this target hook returns the size of @var{mode} 2856in words. 2857@end deftypefn 2858 2859@defmac CLASS_MAX_NREGS (@var{class}, @var{mode}) 2860A C expression for the maximum number of consecutive registers 2861of class @var{class} needed to hold a value of mode @var{mode}. 2862 2863This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 2864the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 2865should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, 2866@var{mode})} for all @var{regno} values in the class @var{class}. 2867 2868This macro helps control the handling of multiple-word values 2869in the reload pass. 2870@end defmac 2871 2872@defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class}) 2873If defined, a C expression that returns nonzero for a @var{class} for which 2874a change from mode @var{from} to mode @var{to} is invalid. 2875 2876For the example, loading 32-bit integer or floating-point objects into 2877floating-point registers on the Alpha extends them to 64 bits. 2878Therefore loading a 64-bit object and then storing it as a 32-bit object 2879does not store the low-order 32 bits, as would be the case for a normal 2880register. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS} 2881as below: 2882 2883@smallexample 2884#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \ 2885 (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \ 2886 ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0) 2887@end smallexample 2888@end defmac 2889 2890@node Old Constraints 2891@section Obsolete Macros for Defining Constraints 2892@cindex defining constraints, obsolete method 2893@cindex constraints, defining, obsolete method 2894 2895Machine-specific constraints can be defined with these macros instead 2896of the machine description constructs described in @ref{Define 2897Constraints}. This mechanism is obsolete. New ports should not use 2898it; old ports should convert to the new mechanism. 2899 2900@defmac CONSTRAINT_LEN (@var{char}, @var{str}) 2901For the constraint at the start of @var{str}, which starts with the letter 2902@var{c}, return the length. This allows you to have register class / 2903constant / extra constraints that are longer than a single letter; 2904you don't need to define this macro if you can do with single-letter 2905constraints only. The definition of this macro should use 2906DEFAULT_CONSTRAINT_LEN for all the characters that you don't want 2907to handle specially. 2908There are some sanity checks in genoutput.c that check the constraint lengths 2909for the md file, so you can also use this macro to help you while you are 2910transitioning from a byzantine single-letter-constraint scheme: when you 2911return a negative length for a constraint you want to re-use, genoutput 2912will complain about every instance where it is used in the md file. 2913@end defmac 2914 2915@defmac REG_CLASS_FROM_LETTER (@var{char}) 2916A C expression which defines the machine-dependent operand constraint 2917letters for register classes. If @var{char} is such a letter, the 2918value should be the register class corresponding to it. Otherwise, 2919the value should be @code{NO_REGS}. The register letter @samp{r}, 2920corresponding to class @code{GENERAL_REGS}, will not be passed 2921to this macro; you do not need to handle it. 2922@end defmac 2923 2924@defmac REG_CLASS_FROM_CONSTRAINT (@var{char}, @var{str}) 2925Like @code{REG_CLASS_FROM_LETTER}, but you also get the constraint string 2926passed in @var{str}, so that you can use suffixes to distinguish between 2927different variants. 2928@end defmac 2929 2930@defmac CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 2931A C expression that defines the machine-dependent operand constraint 2932letters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify 2933particular ranges of integer values. If @var{c} is one of those 2934letters, the expression should check that @var{value}, an integer, is in 2935the appropriate range and return 1 if so, 0 otherwise. If @var{c} is 2936not one of those letters, the value should be 0 regardless of 2937@var{value}. 2938@end defmac 2939 2940@defmac CONST_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2941Like @code{CONST_OK_FOR_LETTER_P}, but you also get the constraint 2942string passed in @var{str}, so that you can use suffixes to distinguish 2943between different variants. 2944@end defmac 2945 2946@defmac CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 2947A C expression that defines the machine-dependent operand constraint 2948letters that specify particular ranges of @code{const_double} values 2949(@samp{G} or @samp{H}). 2950 2951If @var{c} is one of those letters, the expression should check that 2952@var{value}, an RTX of code @code{const_double}, is in the appropriate 2953range and return 1 if so, 0 otherwise. If @var{c} is not one of those 2954letters, the value should be 0 regardless of @var{value}. 2955 2956@code{const_double} is used for all floating-point constants and for 2957@code{DImode} fixed-point constants. A given letter can accept either 2958or both kinds of values. It can use @code{GET_MODE} to distinguish 2959between these kinds. 2960@end defmac 2961 2962@defmac CONST_DOUBLE_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2963Like @code{CONST_DOUBLE_OK_FOR_LETTER_P}, but you also get the constraint 2964string passed in @var{str}, so that you can use suffixes to distinguish 2965between different variants. 2966@end defmac 2967 2968@defmac EXTRA_CONSTRAINT (@var{value}, @var{c}) 2969A C expression that defines the optional machine-dependent constraint 2970letters that can be used to segregate specific types of operands, usually 2971memory references, for the target machine. Any letter that is not 2972elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} / 2973@code{REG_CLASS_FROM_CONSTRAINT} 2974may be used. Normally this macro will not be defined. 2975 2976If it is required for a particular target machine, it should return 1 2977if @var{value} corresponds to the operand type represented by the 2978constraint letter @var{c}. If @var{c} is not defined as an extra 2979constraint, the value returned should be 0 regardless of @var{value}. 2980 2981For example, on the ROMP, load instructions cannot have their output 2982in r0 if the memory reference contains a symbolic address. Constraint 2983letter @samp{Q} is defined as representing a memory address that does 2984@emph{not} contain a symbolic address. An alternative is specified with 2985a @samp{Q} constraint on the input and @samp{r} on the output. The next 2986alternative specifies @samp{m} on the input and a register class that 2987does not include r0 on the output. 2988@end defmac 2989 2990@defmac EXTRA_CONSTRAINT_STR (@var{value}, @var{c}, @var{str}) 2991Like @code{EXTRA_CONSTRAINT}, but you also get the constraint string passed 2992in @var{str}, so that you can use suffixes to distinguish between different 2993variants. 2994@end defmac 2995 2996@defmac EXTRA_MEMORY_CONSTRAINT (@var{c}, @var{str}) 2997A C expression that defines the optional machine-dependent constraint 2998letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should 2999be treated like memory constraints by the reload pass. 3000 3001It should return 1 if the operand type represented by the constraint 3002at the start of @var{str}, the first letter of which is the letter @var{c}, 3003comprises a subset of all memory references including 3004all those whose address is simply a base register. This allows the reload 3005pass to reload an operand, if it does not directly correspond to the operand 3006type of @var{c}, by copying its address into a base register. 3007 3008For example, on the S/390, some instructions do not accept arbitrary 3009memory references, but only those that do not make use of an index 3010register. The constraint letter @samp{Q} is defined via 3011@code{EXTRA_CONSTRAINT} as representing a memory address of this type. 3012If the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT}, 3013a @samp{Q} constraint can handle any memory operand, because the 3014reload pass knows it can be reloaded by copying the memory address 3015into a base register if required. This is analogous to the way 3016an @samp{o} constraint can handle any memory operand. 3017@end defmac 3018 3019@defmac EXTRA_ADDRESS_CONSTRAINT (@var{c}, @var{str}) 3020A C expression that defines the optional machine-dependent constraint 3021letters, amongst those accepted by @code{EXTRA_CONSTRAINT} / 3022@code{EXTRA_CONSTRAINT_STR}, that should 3023be treated like address constraints by the reload pass. 3024 3025It should return 1 if the operand type represented by the constraint 3026at the start of @var{str}, which starts with the letter @var{c}, comprises 3027a subset of all memory addresses including 3028all those that consist of just a base register. This allows the reload 3029pass to reload an operand, if it does not directly correspond to the operand 3030type of @var{str}, by copying it into a base register. 3031 3032Any constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only 3033be used with the @code{address_operand} predicate. It is treated 3034analogously to the @samp{p} constraint. 3035@end defmac 3036 3037@node Stack and Calling 3038@section Stack Layout and Calling Conventions 3039@cindex calling conventions 3040 3041@c prevent bad page break with this line 3042This describes the stack layout and calling conventions. 3043 3044@menu 3045* Frame Layout:: 3046* Exception Handling:: 3047* Stack Checking:: 3048* Frame Registers:: 3049* Elimination:: 3050* Stack Arguments:: 3051* Register Arguments:: 3052* Scalar Return:: 3053* Aggregate Return:: 3054* Caller Saves:: 3055* Function Entry:: 3056* Profiling:: 3057* Tail Calls:: 3058* Stack Smashing Protection:: 3059@end menu 3060 3061@node Frame Layout 3062@subsection Basic Stack Layout 3063@cindex stack frame layout 3064@cindex frame layout 3065 3066@c prevent bad page break with this line 3067Here is the basic stack layout. 3068 3069@defmac STACK_GROWS_DOWNWARD 3070Define this macro if pushing a word onto the stack moves the stack 3071pointer to a smaller address. 3072 3073When we say, ``define this macro if @dots{}'', it means that the 3074compiler checks this macro only with @code{#ifdef} so the precise 3075definition used does not matter. 3076@end defmac 3077 3078@defmac STACK_PUSH_CODE 3079This macro defines the operation used when something is pushed 3080on the stack. In RTL, a push operation will be 3081@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} 3082 3083The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, 3084and @code{POST_INC}. Which of these is correct depends on 3085the stack direction and on whether the stack pointer points 3086to the last item on the stack or whether it points to the 3087space for the next item on the stack. 3088 3089The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is 3090defined, which is almost always right, and @code{PRE_INC} otherwise, 3091which is often wrong. 3092@end defmac 3093 3094@defmac FRAME_GROWS_DOWNWARD 3095Define this macro to nonzero value if the addresses of local variable slots 3096are at negative offsets from the frame pointer. 3097@end defmac 3098 3099@defmac ARGS_GROW_DOWNWARD 3100Define this macro if successive arguments to a function occupy decreasing 3101addresses on the stack. 3102@end defmac 3103 3104@defmac STARTING_FRAME_OFFSET 3105Offset from the frame pointer to the first local variable slot to be allocated. 3106 3107If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by 3108subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. 3109Otherwise, it is found by adding the length of the first slot to the 3110value @code{STARTING_FRAME_OFFSET}. 3111@c i'm not sure if the above is still correct.. had to change it to get 3112@c rid of an overfull. --mew 2feb93 3113@end defmac 3114 3115@defmac STACK_ALIGNMENT_NEEDED 3116Define to zero to disable final alignment of the stack during reload. 3117The nonzero default for this macro is suitable for most ports. 3118 3119On ports where @code{STARTING_FRAME_OFFSET} is nonzero or where there 3120is a register save block following the local block that doesn't require 3121alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable 3122stack alignment and do it in the backend. 3123@end defmac 3124 3125@defmac STACK_POINTER_OFFSET 3126Offset from the stack pointer register to the first location at which 3127outgoing arguments are placed. If not specified, the default value of 3128zero is used. This is the proper value for most machines. 3129 3130If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 3131the first location at which outgoing arguments are placed. 3132@end defmac 3133 3134@defmac FIRST_PARM_OFFSET (@var{fundecl}) 3135Offset from the argument pointer register to the first argument's 3136address. On some machines it may depend on the data type of the 3137function. 3138 3139If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 3140the first argument's address. 3141@end defmac 3142 3143@defmac STACK_DYNAMIC_OFFSET (@var{fundecl}) 3144Offset from the stack pointer register to an item dynamically allocated 3145on the stack, e.g., by @code{alloca}. 3146 3147The default value for this macro is @code{STACK_POINTER_OFFSET} plus the 3148length of the outgoing arguments. The default is correct for most 3149machines. See @file{function.c} for details. 3150@end defmac 3151 3152@defmac INITIAL_FRAME_ADDRESS_RTX 3153A C expression whose value is RTL representing the address of the initial 3154stack frame. This address is passed to @code{RETURN_ADDR_RTX} and 3155@code{DYNAMIC_CHAIN_ADDRESS}. If you don't define this macro, a reasonable 3156default value will be used. Define this macro in order to make frame pointer 3157elimination work in the presence of @code{__builtin_frame_address (count)} and 3158@code{__builtin_return_address (count)} for @code{count} not equal to zero. 3159@end defmac 3160 3161@defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 3162A C expression whose value is RTL representing the address in a stack 3163frame where the pointer to the caller's frame is stored. Assume that 3164@var{frameaddr} is an RTL expression for the address of the stack frame 3165itself. 3166 3167If you don't define this macro, the default is to return the value 3168of @var{frameaddr}---that is, the stack frame address is also the 3169address of the stack word that points to the previous frame. 3170@end defmac 3171 3172@defmac SETUP_FRAME_ADDRESSES 3173If defined, a C expression that produces the machine-specific code to 3174setup the stack so that arbitrary frames can be accessed. For example, 3175on the SPARC, we must flush all of the register windows to the stack 3176before we can access arbitrary stack frames. You will seldom need to 3177define this macro. 3178@end defmac 3179 3180@deftypefn {Target Hook} rtx TARGET_BUILTIN_SETJMP_FRAME_VALUE (void) 3181This target hook should return an rtx that is used to store 3182the address of the current frame into the built in @code{setjmp} buffer. 3183The default value, @code{virtual_stack_vars_rtx}, is correct for most 3184machines. One reason you may need to define this target hook is if 3185@code{hard_frame_pointer_rtx} is the appropriate value on your machine. 3186@end deftypefn 3187 3188@defmac FRAME_ADDR_RTX (@var{frameaddr}) 3189A C expression whose value is RTL representing the value of the frame 3190address for the current frame. @var{frameaddr} is the frame pointer 3191of the current frame. This is used for __builtin_frame_address. 3192You need only define this macro if the frame address is not the same 3193as the frame pointer. Most machines do not need to define it. 3194@end defmac 3195 3196@defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) 3197A C expression whose value is RTL representing the value of the return 3198address for the frame @var{count} steps up from the current frame, after 3199the prologue. @var{frameaddr} is the frame pointer of the @var{count} 3200frame, or the frame pointer of the @var{count} @minus{} 1 frame if 3201@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. 3202 3203The value of the expression must always be the correct address when 3204@var{count} is zero, but may be @code{NULL_RTX} if there is no way to 3205determine the return address of other frames. 3206@end defmac 3207 3208@defmac RETURN_ADDR_IN_PREVIOUS_FRAME 3209Define this if the return address of a particular stack frame is accessed 3210from the frame pointer of the previous stack frame. 3211@end defmac 3212 3213@defmac INCOMING_RETURN_ADDR_RTX 3214A C expression whose value is RTL representing the location of the 3215incoming return address at the beginning of any function, before the 3216prologue. This RTL is either a @code{REG}, indicating that the return 3217value is saved in @samp{REG}, or a @code{MEM} representing a location in 3218the stack. 3219 3220You only need to define this macro if you want to support call frame 3221debugging information like that provided by DWARF 2. 3222 3223If this RTL is a @code{REG}, you should also define 3224@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. 3225@end defmac 3226 3227@defmac DWARF_ALT_FRAME_RETURN_COLUMN 3228A C expression whose value is an integer giving a DWARF 2 column 3229number that may be used as an alternative return column. The column 3230must not correspond to any gcc hard register (that is, it must not 3231be in the range of @code{DWARF_FRAME_REGNUM}). 3232 3233This macro can be useful if @code{DWARF_FRAME_RETURN_COLUMN} is set to a 3234general register, but an alternative column needs to be used for signal 3235frames. Some targets have also used different frame return columns 3236over time. 3237@end defmac 3238 3239@defmac DWARF_ZERO_REG 3240A C expression whose value is an integer giving a DWARF 2 register 3241number that is considered to always have the value zero. This should 3242only be defined if the target has an architected zero register, and 3243someone decided it was a good idea to use that register number to 3244terminate the stack backtrace. New ports should avoid this. 3245@end defmac 3246 3247@deftypefn {Target Hook} void TARGET_DWARF_HANDLE_FRAME_UNSPEC (const char *@var{label}, rtx @var{pattern}, int @var{index}) 3248This target hook allows the backend to emit frame-related insns that 3249contain UNSPECs or UNSPEC_VOLATILEs. The DWARF 2 call frame debugging 3250info engine will invoke it on insns of the form 3251@smallexample 3252(set (reg) (unspec [@dots{}] UNSPEC_INDEX)) 3253@end smallexample 3254and 3255@smallexample 3256(set (reg) (unspec_volatile [@dots{}] UNSPECV_INDEX)). 3257@end smallexample 3258to let the backend emit the call frame instructions. @var{label} is 3259the CFI label attached to the insn, @var{pattern} is the pattern of 3260the insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}. 3261@end deftypefn 3262 3263@defmac INCOMING_FRAME_SP_OFFSET 3264A C expression whose value is an integer giving the offset, in bytes, 3265from the value of the stack pointer register to the top of the stack 3266frame at the beginning of any function, before the prologue. The top of 3267the frame is defined to be the value of the stack pointer in the 3268previous frame, just before the call instruction. 3269 3270You only need to define this macro if you want to support call frame 3271debugging information like that provided by DWARF 2. 3272@end defmac 3273 3274@defmac ARG_POINTER_CFA_OFFSET (@var{fundecl}) 3275A C expression whose value is an integer giving the offset, in bytes, 3276from the argument pointer to the canonical frame address (cfa). The 3277final value should coincide with that calculated by 3278@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable 3279during virtual register instantiation. 3280 3281The default value for this macro is 3282@code{FIRST_PARM_OFFSET (fundecl) + crtl->args.pretend_args_size}, 3283which is correct for most machines; in general, the arguments are found 3284immediately before the stack frame. Note that this is not the case on 3285some targets that save registers into the caller's frame, such as SPARC 3286and rs6000, and so such targets need to define this macro. 3287 3288You only need to define this macro if the default is incorrect, and you 3289want to support call frame debugging information like that provided by 3290DWARF 2. 3291@end defmac 3292 3293@defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl}) 3294If defined, a C expression whose value is an integer giving the offset 3295in bytes from the frame pointer to the canonical frame address (cfa). 3296The final value should coincide with that calculated by 3297@code{INCOMING_FRAME_SP_OFFSET}. 3298 3299Normally the CFA is calculated as an offset from the argument pointer, 3300via @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is 3301variable due to the ABI, this may not be possible. If this macro is 3302defined, it implies that the virtual register instantiation should be 3303based on the frame pointer instead of the argument pointer. Only one 3304of @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET} 3305should be defined. 3306@end defmac 3307 3308@defmac CFA_FRAME_BASE_OFFSET (@var{fundecl}) 3309If defined, a C expression whose value is an integer giving the offset 3310in bytes from the canonical frame address (cfa) to the frame base used 3311in DWARF 2 debug information. The default is zero. A different value 3312may reduce the size of debug information on some ports. 3313@end defmac 3314 3315@node Exception Handling 3316@subsection Exception Handling Support 3317@cindex exception handling 3318 3319@defmac EH_RETURN_DATA_REGNO (@var{N}) 3320A C expression whose value is the @var{N}th register number used for 3321data by exception handlers, or @code{INVALID_REGNUM} if fewer than 3322@var{N} registers are usable. 3323 3324The exception handling library routines communicate with the exception 3325handlers via a set of agreed upon registers. Ideally these registers 3326should be call-clobbered; it is possible to use call-saved registers, 3327but may negatively impact code size. The target must support at least 33282 data registers, but should define 4 if there are enough free registers. 3329 3330You must define this macro if you want to support call frame exception 3331handling like that provided by DWARF 2. 3332@end defmac 3333 3334@defmac EH_RETURN_STACKADJ_RTX 3335A C expression whose value is RTL representing a location in which 3336to store a stack adjustment to be applied before function return. 3337This is used to unwind the stack to an exception handler's call frame. 3338It will be assigned zero on code paths that return normally. 3339 3340Typically this is a call-clobbered hard register that is otherwise 3341untouched by the epilogue, but could also be a stack slot. 3342 3343Do not define this macro if the stack pointer is saved and restored 3344by the regular prolog and epilog code in the call frame itself; in 3345this case, the exception handling library routines will update the 3346stack location to be restored in place. Otherwise, you must define 3347this macro if you want to support call frame exception handling like 3348that provided by DWARF 2. 3349@end defmac 3350 3351@defmac EH_RETURN_HANDLER_RTX 3352A C expression whose value is RTL representing a location in which 3353to store the address of an exception handler to which we should 3354return. It will not be assigned on code paths that return normally. 3355 3356Typically this is the location in the call frame at which the normal 3357return address is stored. For targets that return by popping an 3358address off the stack, this might be a memory address just below 3359the @emph{target} call frame rather than inside the current call 3360frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already 3361been assigned, so it may be used to calculate the location of the 3362target call frame. 3363 3364Some targets have more complex requirements than storing to an 3365address calculable during initial code generation. In that case 3366the @code{eh_return} instruction pattern should be used instead. 3367 3368If you want to support call frame exception handling, you must 3369define either this macro or the @code{eh_return} instruction pattern. 3370@end defmac 3371 3372@defmac RETURN_ADDR_OFFSET 3373If defined, an integer-valued C expression for which rtl will be generated 3374to add it to the exception handler address before it is searched in the 3375exception handling tables, and to subtract it again from the address before 3376using it to return to the exception handler. 3377@end defmac 3378 3379@defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global}) 3380This macro chooses the encoding of pointers embedded in the exception 3381handling sections. If at all possible, this should be defined such 3382that the exception handling section will not require dynamic relocations, 3383and so may be read-only. 3384 3385@var{code} is 0 for data, 1 for code labels, 2 for function pointers. 3386@var{global} is true if the symbol may be affected by dynamic relocations. 3387The macro should return a combination of the @code{DW_EH_PE_*} defines 3388as found in @file{dwarf2.h}. 3389 3390If this macro is not defined, pointers will not be encoded but 3391represented directly. 3392@end defmac 3393 3394@defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) 3395This macro allows the target to emit whatever special magic is required 3396to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. 3397Generic code takes care of pc-relative and indirect encodings; this must 3398be defined if the target uses text-relative or data-relative encodings. 3399 3400This is a C statement that branches to @var{done} if the format was 3401handled. @var{encoding} is the format chosen, @var{size} is the number 3402of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} 3403to be emitted. 3404@end defmac 3405 3406@defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs}) 3407This macro allows the target to add CPU and operating system specific 3408code to the call-frame unwinder for use when there is no unwind data 3409available. The most common reason to implement this macro is to unwind 3410through signal frames. 3411 3412This macro is called from @code{uw_frame_state_for} in 3413@file{unwind-dw2.c}, @file{unwind-dw2-xtensa.c} and 3414@file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; 3415@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} 3416for the address of the code being executed and @code{context->cfa} for 3417the stack pointer value. If the frame can be decoded, the register 3418save addresses should be updated in @var{fs} and the macro should 3419evaluate to @code{_URC_NO_REASON}. If the frame cannot be decoded, 3420the macro should evaluate to @code{_URC_END_OF_STACK}. 3421 3422For proper signal handling in Java this macro is accompanied by 3423@code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers. 3424@end defmac 3425 3426@defmac MD_HANDLE_UNWABI (@var{context}, @var{fs}) 3427This macro allows the target to add operating system specific code to the 3428call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive, 3429usually used for signal or interrupt frames. 3430 3431This macro is called from @code{uw_update_context} in @file{unwind-ia64.c}. 3432@var{context} is an @code{_Unwind_Context}; 3433@var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi} 3434for the abi and context in the @code{.unwabi} directive. If the 3435@code{.unwabi} directive can be handled, the register save addresses should 3436be updated in @var{fs}. 3437@end defmac 3438 3439@defmac TARGET_USES_WEAK_UNWIND_INFO 3440A C expression that evaluates to true if the target requires unwind 3441info to be given comdat linkage. Define it to be @code{1} if comdat 3442linkage is necessary. The default is @code{0}. 3443@end defmac 3444 3445@node Stack Checking 3446@subsection Specifying How Stack Checking is Done 3447 3448GCC will check that stack references are within the boundaries of the 3449stack, if the option @option{-fstack-check} is specified, in one of 3450three ways: 3451 3452@enumerate 3453@item 3454If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC 3455will assume that you have arranged for full stack checking to be done 3456at appropriate places in the configuration files. GCC will not do 3457other special processing. 3458 3459@item 3460If @code{STACK_CHECK_BUILTIN} is zero and the value of the 3461@code{STACK_CHECK_STATIC_BUILTIN} macro is nonzero, GCC will assume 3462that you have arranged for static stack checking (checking of the 3463static stack frame of functions) to be done at appropriate places 3464in the configuration files. GCC will only emit code to do dynamic 3465stack checking (checking on dynamic stack allocations) using the third 3466approach below. 3467 3468@item 3469If neither of the above are true, GCC will generate code to periodically 3470``probe'' the stack pointer using the values of the macros defined below. 3471@end enumerate 3472 3473If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined, 3474GCC will change its allocation strategy for large objects if the option 3475@option{-fstack-check} is specified: they will always be allocated 3476dynamically if their size exceeds @code{STACK_CHECK_MAX_VAR_SIZE} bytes. 3477 3478@defmac STACK_CHECK_BUILTIN 3479A nonzero value if stack checking is done by the configuration files in a 3480machine-dependent manner. You should define this macro if stack checking 3481is required by the ABI of your machine or if you would like to do stack 3482checking in some more efficient way than the generic approach. The default 3483value of this macro is zero. 3484@end defmac 3485 3486@defmac STACK_CHECK_STATIC_BUILTIN 3487A nonzero value if static stack checking is done by the configuration files 3488in a machine-dependent manner. You should define this macro if you would 3489like to do static stack checking in some more efficient way than the generic 3490approach. The default value of this macro is zero. 3491@end defmac 3492 3493@defmac STACK_CHECK_PROBE_INTERVAL_EXP 3494An integer specifying the interval at which GCC must generate stack probe 3495instructions, defined as 2 raised to this integer. You will normally 3496define this macro so that the interval be no larger than the size of 3497the ``guard pages'' at the end of a stack area. The default value 3498of 12 (4096-byte interval) is suitable for most systems. 3499@end defmac 3500 3501@defmac STACK_CHECK_MOVING_SP 3502An integer which is nonzero if GCC should move the stack pointer page by page 3503when doing probes. This can be necessary on systems where the stack pointer 3504contains the bottom address of the memory area accessible to the executing 3505thread at any point in time. In this situation an alternate signal stack 3506is required in order to be able to recover from a stack overflow. The 3507default value of this macro is zero. 3508@end defmac 3509 3510@defmac STACK_CHECK_PROTECT 3511The number of bytes of stack needed to recover from a stack overflow, for 3512languages where such a recovery is supported. The default value of 75 words 3513with the @code{setjmp}/@code{longjmp}-based exception handling mechanism and 35148192 bytes with other exception handling mechanisms should be adequate for 3515most machines. 3516@end defmac 3517 3518The following macros are relevant only if neither STACK_CHECK_BUILTIN 3519nor STACK_CHECK_STATIC_BUILTIN is defined; you can omit them altogether 3520in the opposite case. 3521 3522@defmac STACK_CHECK_MAX_FRAME_SIZE 3523The maximum size of a stack frame, in bytes. GCC will generate probe 3524instructions in non-leaf functions to ensure at least this many bytes of 3525stack are available. If a stack frame is larger than this size, stack 3526checking will not be reliable and GCC will issue a warning. The 3527default is chosen so that GCC only generates one instruction on most 3528systems. You should normally not change the default value of this macro. 3529@end defmac 3530 3531@defmac STACK_CHECK_FIXED_FRAME_SIZE 3532GCC uses this value to generate the above warning message. It 3533represents the amount of fixed frame used by a function, not including 3534space for any callee-saved registers, temporaries and user variables. 3535You need only specify an upper bound for this amount and will normally 3536use the default of four words. 3537@end defmac 3538 3539@defmac STACK_CHECK_MAX_VAR_SIZE 3540The maximum size, in bytes, of an object that GCC will place in the 3541fixed area of the stack frame when the user specifies 3542@option{-fstack-check}. 3543GCC computed the default from the values of the above macros and you will 3544normally not need to override that default. 3545@end defmac 3546 3547@need 2000 3548@node Frame Registers 3549@subsection Registers That Address the Stack Frame 3550 3551@c prevent bad page break with this line 3552This discusses registers that address the stack frame. 3553 3554@defmac STACK_POINTER_REGNUM 3555The register number of the stack pointer register, which must also be a 3556fixed register according to @code{FIXED_REGISTERS}. On most machines, 3557the hardware determines which register this is. 3558@end defmac 3559 3560@defmac FRAME_POINTER_REGNUM 3561The register number of the frame pointer register, which is used to 3562access automatic variables in the stack frame. On some machines, the 3563hardware determines which register this is. On other machines, you can 3564choose any register you wish for this purpose. 3565@end defmac 3566 3567@defmac HARD_FRAME_POINTER_REGNUM 3568On some machines the offset between the frame pointer and starting 3569offset of the automatic variables is not known until after register 3570allocation has been done (for example, because the saved registers are 3571between these two locations). On those machines, define 3572@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to 3573be used internally until the offset is known, and define 3574@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number 3575used for the frame pointer. 3576 3577You should define this macro only in the very rare circumstances when it 3578is not possible to calculate the offset between the frame pointer and 3579the automatic variables until after register allocation has been 3580completed. When this macro is defined, you must also indicate in your 3581definition of @code{ELIMINABLE_REGS} how to eliminate 3582@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} 3583or @code{STACK_POINTER_REGNUM}. 3584 3585Do not define this macro if it would be the same as 3586@code{FRAME_POINTER_REGNUM}. 3587@end defmac 3588 3589@defmac ARG_POINTER_REGNUM 3590The register number of the arg pointer register, which is used to access 3591the function's argument list. On some machines, this is the same as the 3592frame pointer register. On some machines, the hardware determines which 3593register this is. On other machines, you can choose any register you 3594wish for this purpose. If this is not the same register as the frame 3595pointer register, then you must mark it as a fixed register according to 3596@code{FIXED_REGISTERS}, or arrange to be able to eliminate it 3597(@pxref{Elimination}). 3598@end defmac 3599 3600@defmac HARD_FRAME_POINTER_IS_FRAME_POINTER 3601Define this to a preprocessor constant that is nonzero if 3602@code{hard_frame_pointer_rtx} and @code{frame_pointer_rtx} should be 3603the same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM 3604== FRAME_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 HARD_FRAME_POINTER_IS_ARG_POINTER 3609Define this to a preprocessor constant that is nonzero if 3610@code{hard_frame_pointer_rtx} and @code{arg_pointer_rtx} should be the 3611same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM == 3612ARG_POINTER_REGNUM)}; you only need to define this macro if that 3613definition is not suitable for use in preprocessor conditionals. 3614@end defmac 3615 3616@defmac RETURN_ADDRESS_POINTER_REGNUM 3617The register number of the return address pointer register, which is used to 3618access the current function's return address from the stack. On some 3619machines, the return address is not at a fixed offset from the frame 3620pointer or stack pointer or argument pointer. This register can be defined 3621to point to the return address on the stack, and then be converted by 3622@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. 3623 3624Do not define this macro unless there is no other way to get the return 3625address from the stack. 3626@end defmac 3627 3628@defmac STATIC_CHAIN_REGNUM 3629@defmacx STATIC_CHAIN_INCOMING_REGNUM 3630Register numbers used for passing a function's static chain pointer. If 3631register windows are used, the register number as seen by the called 3632function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register 3633number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If 3634these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need 3635not be defined. 3636 3637The static chain register need not be a fixed register. 3638 3639If the static chain is passed in memory, these macros should not be 3640defined; instead, the @code{TARGET_STATIC_CHAIN} hook should be used. 3641@end defmac 3642 3643@deftypefn {Target Hook} rtx TARGET_STATIC_CHAIN (const_tree @var{fndecl}, bool @var{incoming_p}) 3644This hook replaces the use of @code{STATIC_CHAIN_REGNUM} et al for 3645targets that may use different static chain locations for different 3646nested functions. This may be required if the target has function 3647attributes that affect the calling conventions of the function and 3648those calling conventions use different static chain locations. 3649 3650The default version of this hook uses @code{STATIC_CHAIN_REGNUM} et al. 3651 3652If the static chain is passed in memory, this hook should be used to 3653provide rtx giving @code{mem} expressions that denote where they are stored. 3654Often the @code{mem} expression as seen by the caller will be at an offset 3655from the stack pointer and the @code{mem} expression as seen by the callee 3656will be at an offset from the frame pointer. 3657@findex stack_pointer_rtx 3658@findex frame_pointer_rtx 3659@findex arg_pointer_rtx 3660The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 3661@code{arg_pointer_rtx} will have been initialized and should be used 3662to refer to those items. 3663@end deftypefn 3664 3665@defmac DWARF_FRAME_REGISTERS 3666This macro specifies the maximum number of hard registers that can be 3667saved in a call frame. This is used to size data structures used in 3668DWARF2 exception handling. 3669 3670Prior to GCC 3.0, this macro was needed in order to establish a stable 3671exception handling ABI in the face of adding new hard registers for ISA 3672extensions. In GCC 3.0 and later, the EH ABI is insulated from changes 3673in the number of hard registers. Nevertheless, this macro can still be 3674used to reduce the runtime memory requirements of the exception handling 3675routines, which can be substantial if the ISA contains a lot of 3676registers that are not call-saved. 3677 3678If this macro is not defined, it defaults to 3679@code{FIRST_PSEUDO_REGISTER}. 3680@end defmac 3681 3682@defmac PRE_GCC3_DWARF_FRAME_REGISTERS 3683 3684This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided 3685for backward compatibility in pre GCC 3.0 compiled code. 3686 3687If this macro is not defined, it defaults to 3688@code{DWARF_FRAME_REGISTERS}. 3689@end defmac 3690 3691@defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno}) 3692 3693Define this macro if the target's representation for dwarf registers 3694is different than the internal representation for unwind column. 3695Given a dwarf register, this macro should return the internal unwind 3696column number to use instead. 3697 3698See the PowerPC's SPE target for an example. 3699@end defmac 3700 3701@defmac DWARF_FRAME_REGNUM (@var{regno}) 3702 3703Define this macro if the target's representation for dwarf registers 3704used in .eh_frame or .debug_frame is different from that used in other 3705debug info sections. Given a GCC hard register number, this macro 3706should return the .eh_frame register number. The default is 3707@code{DBX_REGISTER_NUMBER (@var{regno})}. 3708 3709@end defmac 3710 3711@defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh}) 3712 3713Define this macro to map register numbers held in the call frame info 3714that GCC has collected using @code{DWARF_FRAME_REGNUM} to those that 3715should be output in .debug_frame (@code{@var{for_eh}} is zero) and 3716.eh_frame (@code{@var{for_eh}} is nonzero). The default is to 3717return @code{@var{regno}}. 3718 3719@end defmac 3720 3721@defmac REG_VALUE_IN_UNWIND_CONTEXT 3722 3723Define this macro if the target stores register values as 3724@code{_Unwind_Word} type in unwind context. It should be defined if 3725target register size is larger than the size of @code{void *}. The 3726default is to store register values as @code{void *} type. 3727 3728@end defmac 3729 3730@defmac ASSUME_EXTENDED_UNWIND_CONTEXT 3731 3732Define this macro to be 1 if the target always uses extended unwind 3733context with version, args_size and by_value fields. If it is undefined, 3734it will be defined to 1 when @code{REG_VALUE_IN_UNWIND_CONTEXT} is 3735defined and 0 otherwise. 3736 3737@end defmac 3738 3739@node Elimination 3740@subsection Eliminating Frame Pointer and Arg Pointer 3741 3742@c prevent bad page break with this line 3743This is about eliminating the frame pointer and arg pointer. 3744 3745@deftypefn {Target Hook} bool TARGET_FRAME_POINTER_REQUIRED (void) 3746This target hook should return @code{true} if a function must have and use 3747a frame pointer. This target hook is called in the reload pass. If its return 3748value is @code{true} the function will have a frame pointer. 3749 3750This target hook can in principle examine the current function and decide 3751according to the facts, but on most machines the constant @code{false} or the 3752constant @code{true} suffices. Use @code{false} when the machine allows code 3753to be generated with no frame pointer, and doing so saves some time or space. 3754Use @code{true} when there is no possible advantage to avoiding a frame 3755pointer. 3756 3757In certain cases, the compiler does not know how to produce valid code 3758without a frame pointer. The compiler recognizes those cases and 3759automatically gives the function a frame pointer regardless of what 3760@code{TARGET_FRAME_POINTER_REQUIRED} returns. You don't need to worry about 3761them. 3762 3763In a function that does not require a frame pointer, the frame pointer 3764register can be allocated for ordinary usage, unless you mark it as a 3765fixed register. See @code{FIXED_REGISTERS} for more information. 3766 3767Default return value is @code{false}. 3768@end deftypefn 3769 3770@findex get_frame_size 3771@defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 3772A C statement to store in the variable @var{depth-var} the difference 3773between the frame pointer and the stack pointer values immediately after 3774the function prologue. The value would be computed from information 3775such as the result of @code{get_frame_size ()} and the tables of 3776registers @code{regs_ever_live} and @code{call_used_regs}. 3777 3778If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 3779need not be defined. Otherwise, it must be defined even if 3780@code{TARGET_FRAME_POINTER_REQUIRED} always returns true; in that 3781case, you may set @var{depth-var} to anything. 3782@end defmac 3783 3784@defmac ELIMINABLE_REGS 3785If defined, this macro specifies a table of register pairs used to 3786eliminate unneeded registers that point into the stack frame. If it is not 3787defined, the only elimination attempted by the compiler is to replace 3788references to the frame pointer with references to the stack pointer. 3789 3790The definition of this macro is a list of structure initializations, each 3791of which specifies an original and replacement register. 3792 3793On some machines, the position of the argument pointer is not known until 3794the compilation is completed. In such a case, a separate hard register 3795must be used for the argument pointer. This register can be eliminated by 3796replacing it with either the frame pointer or the argument pointer, 3797depending on whether or not the frame pointer has been eliminated. 3798 3799In this case, you might specify: 3800@smallexample 3801#define ELIMINABLE_REGS \ 3802@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 3803 @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 3804 @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 3805@end smallexample 3806 3807Note that the elimination of the argument pointer with the stack pointer is 3808specified first since that is the preferred elimination. 3809@end defmac 3810 3811@deftypefn {Target Hook} bool TARGET_CAN_ELIMINATE (const int @var{from_reg}, const int @var{to_reg}) 3812This target hook should returns @code{true} if the compiler is allowed to 3813try to replace register number @var{from_reg} with register number 3814@var{to_reg}. This target hook need only be defined if @code{ELIMINABLE_REGS} 3815is defined, and will usually be @code{true}, since most of the cases 3816preventing register elimination are things that the compiler already 3817knows about. 3818 3819Default return value is @code{true}. 3820@end deftypefn 3821 3822@defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 3823This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 3824specifies the initial difference between the specified pair of 3825registers. This macro must be defined if @code{ELIMINABLE_REGS} is 3826defined. 3827@end defmac 3828 3829@node Stack Arguments 3830@subsection Passing Function Arguments on the Stack 3831@cindex arguments on stack 3832@cindex stack arguments 3833 3834The macros in this section control how arguments are passed 3835on the stack. See the following section for other macros that 3836control passing certain arguments in registers. 3837 3838@deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (const_tree @var{fntype}) 3839This target hook returns @code{true} if an argument declared in a 3840prototype as an integral type smaller than @code{int} should actually be 3841passed as an @code{int}. In addition to avoiding errors in certain 3842cases of mismatch, it also makes for better code on certain machines. 3843The default is to not promote prototypes. 3844@end deftypefn 3845 3846@defmac PUSH_ARGS 3847A C expression. If nonzero, push insns will be used to pass 3848outgoing arguments. 3849If the target machine does not have a push instruction, set it to zero. 3850That directs GCC to use an alternate strategy: to 3851allocate the entire argument block and then store the arguments into 3852it. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. 3853@end defmac 3854 3855@defmac PUSH_ARGS_REVERSED 3856A C expression. If nonzero, function arguments will be evaluated from 3857last to first, rather than from first to last. If this macro is not 3858defined, it defaults to @code{PUSH_ARGS} on targets where the stack 3859and args grow in opposite directions, and 0 otherwise. 3860@end defmac 3861 3862@defmac PUSH_ROUNDING (@var{npushed}) 3863A C expression that is the number of bytes actually pushed onto the 3864stack when an instruction attempts to push @var{npushed} bytes. 3865 3866On some machines, the definition 3867 3868@smallexample 3869#define PUSH_ROUNDING(BYTES) (BYTES) 3870@end smallexample 3871 3872@noindent 3873will suffice. But on other machines, instructions that appear 3874to push one byte actually push two bytes in an attempt to maintain 3875alignment. Then the definition should be 3876 3877@smallexample 3878#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 3879@end smallexample 3880 3881If the value of this macro has a type, it should be an unsigned type. 3882@end defmac 3883 3884@findex current_function_outgoing_args_size 3885@defmac ACCUMULATE_OUTGOING_ARGS 3886A C expression. If nonzero, the maximum amount of space required for outgoing arguments 3887will be computed and placed into the variable 3888@code{current_function_outgoing_args_size}. No space will be pushed 3889onto the stack for each call; instead, the function prologue should 3890increase the stack frame size by this amount. 3891 3892Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 3893is not proper. 3894@end defmac 3895 3896@defmac REG_PARM_STACK_SPACE (@var{fndecl}) 3897Define this macro if functions should assume that stack space has been 3898allocated for arguments even when their values are passed in 3899registers. 3900 3901The value of this macro is the size, in bytes, of the area reserved for 3902arguments passed in registers for the function represented by @var{fndecl}, 3903which can be zero if GCC is calling a library function. 3904The argument @var{fndecl} can be the FUNCTION_DECL, or the type itself 3905of the function. 3906 3907This space can be allocated by the caller, or be a part of the 3908machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 3909which. 3910@end defmac 3911@c above is overfull. not sure what to do. --mew 5feb93 did 3912@c something, not sure if it looks good. --mew 10feb93 3913 3914@defmac OUTGOING_REG_PARM_STACK_SPACE (@var{fntype}) 3915Define this to a nonzero value if it is the responsibility of the 3916caller to allocate the area reserved for arguments passed in registers 3917when calling a function of @var{fntype}. @var{fntype} may be NULL 3918if the function called is a library function. 3919 3920If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 3921whether the space for these arguments counts in the value of 3922@code{current_function_outgoing_args_size}. 3923@end defmac 3924 3925@defmac STACK_PARMS_IN_REG_PARM_AREA 3926Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 3927stack parameters don't skip the area specified by it. 3928@c i changed this, makes more sens and it should have taken care of the 3929@c overfull.. not as specific, tho. --mew 5feb93 3930 3931Normally, when a parameter is not passed in registers, it is placed on the 3932stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 3933suppresses this behavior and causes the parameter to be passed on the 3934stack in its natural location. 3935@end defmac 3936 3937@deftypefn {Target Hook} int TARGET_RETURN_POPS_ARGS (tree @var{fundecl}, tree @var{funtype}, int @var{size}) 3938This target hook returns the number of bytes of its own arguments that 3939a function pops on returning, or 0 if the function pops no arguments 3940and the caller must therefore pop them all after the function returns. 3941 3942@var{fundecl} is a C variable whose value is a tree node that describes 3943the function in question. Normally it is a node of type 3944@code{FUNCTION_DECL} that describes the declaration of the function. 3945From this you can obtain the @code{DECL_ATTRIBUTES} of the function. 3946 3947@var{funtype} is a C variable whose value is a tree node that 3948describes the function in question. Normally it is a node of type 3949@code{FUNCTION_TYPE} that describes the data type of the function. 3950From this it is possible to obtain the data types of the value and 3951arguments (if known). 3952 3953When a call to a library function is being considered, @var{fundecl} 3954will contain an identifier node for the library function. Thus, if 3955you need to distinguish among various library functions, you can do so 3956by their names. Note that ``library function'' in this context means 3957a function used to perform arithmetic, whose name is known specially 3958in the compiler and was not mentioned in the C code being compiled. 3959 3960@var{size} is the number of bytes of arguments passed on the 3961stack. If a variable number of bytes is passed, it is zero, and 3962argument popping will always be the responsibility of the calling function. 3963 3964On the VAX, all functions always pop their arguments, so the definition 3965of this macro is @var{size}. On the 68000, using the standard 3966calling convention, no functions pop their arguments, so the value of 3967the macro is always 0 in this case. But an alternative calling 3968convention is available in which functions that take a fixed number of 3969arguments pop them but other functions (such as @code{printf}) pop 3970nothing (the caller pops all). When this convention is in use, 3971@var{funtype} is examined to determine whether a function takes a fixed 3972number of arguments. 3973@end deftypefn 3974 3975@defmac CALL_POPS_ARGS (@var{cum}) 3976A C expression that should indicate the number of bytes a call sequence 3977pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 3978when compiling a function call. 3979 3980@var{cum} is the variable in which all arguments to the called function 3981have been accumulated. 3982 3983On certain architectures, such as the SH5, a call trampoline is used 3984that pops certain registers off the stack, depending on the arguments 3985that have been passed to the function. Since this is a property of the 3986call site, not of the called function, @code{RETURN_POPS_ARGS} is not 3987appropriate. 3988@end defmac 3989 3990@node Register Arguments 3991@subsection Passing Arguments in Registers 3992@cindex arguments in registers 3993@cindex registers arguments 3994 3995This section describes the macros which let you control how various 3996types of arguments are passed in registers or how they are arranged in 3997the stack. 3998 3999@deftypefn {Target Hook} rtx TARGET_FUNCTION_ARG (cumulative_args_t @var{ca}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named}) 4000Return an RTX indicating whether a function argument is passed in a 4001register and if so, which register. 4002 4003The arguments are @var{ca}, which summarizes all the previous 4004arguments; @var{mode}, the machine mode of the argument; @var{type}, 4005the data type of the argument as a tree node or 0 if that is not known 4006(which happens for C support library functions); and @var{named}, 4007which is @code{true} for an ordinary argument and @code{false} for 4008nameless arguments that correspond to @samp{@dots{}} in the called 4009function's prototype. @var{type} can be an incomplete type if a 4010syntax error has previously occurred. 4011 4012The return value is usually either a @code{reg} RTX for the hard 4013register in which to pass the argument, or zero to pass the argument 4014on the stack. 4015 4016The value of the expression can also be a @code{parallel} RTX@. This is 4017used when an argument is passed in multiple locations. The mode of the 4018@code{parallel} should be the mode of the entire argument. The 4019@code{parallel} holds any number of @code{expr_list} pairs; each one 4020describes where part of the argument is passed. In each 4021@code{expr_list} the first operand must be a @code{reg} RTX for the hard 4022register in which to pass this part of the argument, and the mode of the 4023register RTX indicates how large this part of the argument is. The 4024second operand of the @code{expr_list} is a @code{const_int} which gives 4025the offset in bytes into the entire argument of where this part starts. 4026As a special exception the first @code{expr_list} in the @code{parallel} 4027RTX may have a first operand of zero. This indicates that the entire 4028argument is also stored on the stack. 4029 4030The last time this hook is called, it is called with @code{MODE == 4031VOIDmode}, and its result is passed to the @code{call} or @code{call_value} 4032pattern as operands 2 and 3 respectively. 4033 4034@cindex @file{stdarg.h} and register arguments 4035The usual way to make the ISO library @file{stdarg.h} work on a 4036machine where some arguments are usually passed in registers, is to 4037cause nameless arguments to be passed on the stack instead. This is 4038done by making @code{TARGET_FUNCTION_ARG} return 0 whenever 4039@var{named} is @code{false}. 4040 4041@cindex @code{TARGET_MUST_PASS_IN_STACK}, and @code{TARGET_FUNCTION_ARG} 4042@cindex @code{REG_PARM_STACK_SPACE}, and @code{TARGET_FUNCTION_ARG} 4043You may use the hook @code{targetm.calls.must_pass_in_stack} 4044in the definition of this macro to determine if this argument is of a 4045type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 4046is not defined and @code{TARGET_FUNCTION_ARG} returns nonzero for such an 4047argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 4048defined, the argument will be computed in the stack and then loaded into 4049a register. 4050@end deftypefn 4051 4052@deftypefn {Target Hook} bool TARGET_MUST_PASS_IN_STACK (enum machine_mode @var{mode}, const_tree @var{type}) 4053This target hook should return @code{true} if we should not pass @var{type} 4054solely in registers. The file @file{expr.h} defines a 4055definition that is usually appropriate, refer to @file{expr.h} for additional 4056documentation. 4057@end deftypefn 4058 4059@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}) 4060Define this hook if the target machine has ``register windows'', so 4061that the register in which a function sees an arguments is not 4062necessarily the same as the one in which the caller passed the 4063argument. 4064 4065For such machines, @code{TARGET_FUNCTION_ARG} computes the register in 4066which the caller passes the value, and 4067@code{TARGET_FUNCTION_INCOMING_ARG} should be defined in a similar 4068fashion to tell the function being called where the arguments will 4069arrive. 4070 4071If @code{TARGET_FUNCTION_INCOMING_ARG} is not defined, 4072@code{TARGET_FUNCTION_ARG} serves both purposes. 4073@end deftypefn 4074 4075@deftypefn {Target Hook} int TARGET_ARG_PARTIAL_BYTES (cumulative_args_t @var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 4076This target hook returns the number of bytes at the beginning of an 4077argument that must be put in registers. The value must be zero for 4078arguments that are passed entirely in registers or that are entirely 4079pushed on the stack. 4080 4081On some machines, certain arguments must be passed partially in 4082registers and partially in memory. On these machines, typically the 4083first few words of arguments are passed in registers, and the rest 4084on the stack. If a multi-word argument (a @code{double} or a 4085structure) crosses that boundary, its first few words must be passed 4086in registers and the rest must be pushed. This macro tells the 4087compiler when this occurs, and how many bytes should go in registers. 4088 4089@code{TARGET_FUNCTION_ARG} for these arguments should return the first 4090register to be used by the caller for this argument; likewise 4091@code{TARGET_FUNCTION_INCOMING_ARG}, for the called function. 4092@end deftypefn 4093 4094@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}) 4095This target hook should return @code{true} if an argument at the 4096position indicated by @var{cum} should be passed by reference. This 4097predicate is queried after target independent reasons for being 4098passed by reference, such as @code{TREE_ADDRESSABLE (type)}. 4099 4100If the hook returns true, a copy of that argument is made in memory and a 4101pointer to the argument is passed instead of the argument itself. 4102The pointer is passed in whatever way is appropriate for passing a pointer 4103to that type. 4104@end deftypefn 4105 4106@deftypefn {Target Hook} bool TARGET_CALLEE_COPIES (cumulative_args_t @var{cum}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named}) 4107The function argument described by the parameters to this hook is 4108known to be passed by reference. The hook should return true if the 4109function argument should be copied by the callee instead of copied 4110by the caller. 4111 4112For any argument for which the hook returns true, if it can be 4113determined that the argument is not modified, then a copy need 4114not be generated. 4115 4116The default version of this hook always returns false. 4117@end deftypefn 4118 4119@defmac CUMULATIVE_ARGS 4120A C type for declaring a variable that is used as the first argument 4121of @code{TARGET_FUNCTION_ARG} and other related values. For some 4122target machines, the type @code{int} suffices and can hold the number 4123of bytes of argument so far. 4124 4125There is no need to record in @code{CUMULATIVE_ARGS} anything about the 4126arguments that have been passed on the stack. The compiler has other 4127variables to keep track of that. For target machines on which all 4128arguments are passed on the stack, there is no need to store anything in 4129@code{CUMULATIVE_ARGS}; however, the data structure must exist and 4130should not be empty, so use @code{int}. 4131@end defmac 4132 4133@defmac OVERRIDE_ABI_FORMAT (@var{fndecl}) 4134If defined, this macro is called before generating any code for a 4135function, but after the @var{cfun} descriptor for the function has been 4136created. The back end may use this macro to update @var{cfun} to 4137reflect an ABI other than that which would normally be used by default. 4138If the compiler is generating code for a compiler-generated function, 4139@var{fndecl} may be @code{NULL}. 4140@end defmac 4141 4142@defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args}) 4143A C statement (sans semicolon) for initializing the variable 4144@var{cum} for the state at the beginning of the argument list. The 4145variable has type @code{CUMULATIVE_ARGS}. The value of @var{fntype} 4146is the tree node for the data type of the function which will receive 4147the args, or 0 if the args are to a compiler support library function. 4148For direct calls that are not libcalls, @var{fndecl} contain the 4149declaration node of the function. @var{fndecl} is also set when 4150@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 4151being compiled. @var{n_named_args} is set to the number of named 4152arguments, including a structure return address if it is passed as a 4153parameter, when making a call. When processing incoming arguments, 4154@var{n_named_args} is set to @minus{}1. 4155 4156When processing a call to a compiler support library function, 4157@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 4158contains the name of the function, as a string. @var{libname} is 0 when 4159an ordinary C function call is being processed. Thus, each time this 4160macro is called, either @var{libname} or @var{fntype} is nonzero, but 4161never both of them at once. 4162@end defmac 4163 4164@defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 4165Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 4166it gets a @code{MODE} argument instead of @var{fntype}, that would be 4167@code{NULL}. @var{indirect} would always be zero, too. If this macro 4168is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 41690)} is used instead. 4170@end defmac 4171 4172@defmac INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 4173Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 4174finding the arguments for the function being compiled. If this macro is 4175undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 4176 4177The value passed for @var{libname} is always 0, since library routines 4178with special calling conventions are never compiled with GCC@. The 4179argument @var{libname} exists for symmetry with 4180@code{INIT_CUMULATIVE_ARGS}. 4181@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 4182@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 4183@end defmac 4184 4185@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}) 4186This hook updates the summarizer variable pointed to by @var{ca} to 4187advance past an argument in the argument list. The values @var{mode}, 4188@var{type} and @var{named} describe that argument. Once this is done, 4189the variable @var{cum} is suitable for analyzing the @emph{following} 4190argument with @code{TARGET_FUNCTION_ARG}, etc. 4191 4192This hook need not do anything if the argument in question was passed 4193on the stack. The compiler knows how to track the amount of stack space 4194used for arguments without any special help. 4195@end deftypefn 4196 4197@defmac FUNCTION_ARG_OFFSET (@var{mode}, @var{type}) 4198If defined, a C expression that is the number of bytes to add to the 4199offset of the argument passed in memory. This is needed for the SPU, 4200which passes @code{char} and @code{short} arguments in the preferred 4201slot that is in the middle of the quad word instead of starting at the 4202top. 4203@end defmac 4204 4205@defmac FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 4206If defined, a C expression which determines whether, and in which direction, 4207to pad out an argument with extra space. The value should be of type 4208@code{enum direction}: either @code{upward} to pad above the argument, 4209@code{downward} to pad below, or @code{none} to inhibit padding. 4210 4211The @emph{amount} of padding is not controlled by this macro, but by the 4212target hook @code{TARGET_FUNCTION_ARG_ROUND_BOUNDARY}. It is 4213always just enough to reach the next multiple of that boundary. 4214 4215This macro has a default definition which is right for most systems. 4216For little-endian machines, the default is to pad upward. For 4217big-endian machines, the default is to pad downward for an argument of 4218constant size shorter than an @code{int}, and upward otherwise. 4219@end defmac 4220 4221@defmac PAD_VARARGS_DOWN 4222If defined, a C expression which determines whether the default 4223implementation of va_arg will attempt to pad down before reading the 4224next argument, if that argument is smaller than its aligned space as 4225controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 4226arguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 4227@end defmac 4228 4229@defmac BLOCK_REG_PADDING (@var{mode}, @var{type}, @var{first}) 4230Specify padding for the last element of a block move between registers and 4231memory. @var{first} is nonzero if this is the only element. Defining this 4232macro allows better control of register function parameters on big-endian 4233machines, without using @code{PARALLEL} rtl. In particular, 4234@code{MUST_PASS_IN_STACK} need not test padding and mode of types in 4235registers, as there is no longer a "wrong" part of a register; For example, 4236a three byte aggregate may be passed in the high part of a register if so 4237required. 4238@end defmac 4239 4240@deftypefn {Target Hook} {unsigned int} TARGET_FUNCTION_ARG_BOUNDARY (enum machine_mode @var{mode}, const_tree @var{type}) 4241This hook returns the alignment boundary, in bits, of an argument 4242with the specified mode and type. The default hook returns 4243@code{PARM_BOUNDARY} for all arguments. 4244@end deftypefn 4245 4246@deftypefn {Target Hook} {unsigned int} TARGET_FUNCTION_ARG_ROUND_BOUNDARY (enum machine_mode @var{mode}, const_tree @var{type}) 4247Normally, the size of an argument is rounded up to @code{PARM_BOUNDARY}, 4248which is the default value for this hook. You can define this hook to 4249return a different value if an argument size must be rounded to a larger 4250value. 4251@end deftypefn 4252 4253@defmac FUNCTION_ARG_REGNO_P (@var{regno}) 4254A C expression that is nonzero if @var{regno} is the number of a hard 4255register in which function arguments are sometimes passed. This does 4256@emph{not} include implicit arguments such as the static chain and 4257the structure-value address. On many machines, no registers can be 4258used for this purpose since all function arguments are pushed on the 4259stack. 4260@end defmac 4261 4262@deftypefn {Target Hook} bool TARGET_SPLIT_COMPLEX_ARG (const_tree @var{type}) 4263This hook should return true if parameter of type @var{type} are passed 4264as two scalar parameters. By default, GCC will attempt to pack complex 4265arguments into the target's word size. Some ABIs require complex arguments 4266to be split and treated as their individual components. For example, on 4267AIX64, complex floats should be passed in a pair of floating point 4268registers, even though a complex float would fit in one 64-bit floating 4269point register. 4270 4271The default value of this hook is @code{NULL}, which is treated as always 4272false. 4273@end deftypefn 4274 4275@deftypefn {Target Hook} tree TARGET_BUILD_BUILTIN_VA_LIST (void) 4276This hook returns a type node for @code{va_list} for the target. 4277The default version of the hook returns @code{void*}. 4278@end deftypefn 4279 4280@deftypefn {Target Hook} int TARGET_ENUM_VA_LIST_P (int @var{idx}, const char **@var{pname}, tree *@var{ptree}) 4281This target hook is used in function @code{c_common_nodes_and_builtins} 4282to iterate through the target specific builtin types for va_list. The 4283variable @var{idx} is used as iterator. @var{pname} has to be a pointer 4284to a @code{const char *} and @var{ptree} a pointer to a @code{tree} typed 4285variable. 4286The arguments @var{pname} and @var{ptree} are used to store the result of 4287this macro and are set to the name of the va_list builtin type and its 4288internal type. 4289If the return value of this macro is zero, then there is no more element. 4290Otherwise the @var{IDX} should be increased for the next call of this 4291macro to iterate through all types. 4292@end deftypefn 4293 4294@deftypefn {Target Hook} tree TARGET_FN_ABI_VA_LIST (tree @var{fndecl}) 4295This hook returns the va_list type of the calling convention specified by 4296@var{fndecl}. 4297The default version of this hook returns @code{va_list_type_node}. 4298@end deftypefn 4299 4300@deftypefn {Target Hook} tree TARGET_CANONICAL_VA_LIST_TYPE (tree @var{type}) 4301This hook returns the va_list type of the calling convention specified by the 4302type of @var{type}. If @var{type} is not a valid va_list type, it returns 4303@code{NULL_TREE}. 4304@end deftypefn 4305 4306@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}) 4307This hook performs target-specific gimplification of 4308@code{VA_ARG_EXPR}. The first two parameters correspond to the 4309arguments to @code{va_arg}; the latter two are as in 4310@code{gimplify.c:gimplify_expr}. 4311@end deftypefn 4312 4313@deftypefn {Target Hook} bool TARGET_VALID_POINTER_MODE (enum machine_mode @var{mode}) 4314Define this to return nonzero if the port can handle pointers 4315with machine mode @var{mode}. The default version of this 4316hook returns true for both @code{ptr_mode} and @code{Pmode}. 4317@end deftypefn 4318 4319@deftypefn {Target Hook} bool TARGET_REF_MAY_ALIAS_ERRNO (struct ao_ref_s *@var{ref}) 4320Define 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. 4321@end deftypefn 4322 4323@deftypefn {Target Hook} bool TARGET_SCALAR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4324Define this to return nonzero if the port is prepared to handle 4325insns involving scalar mode @var{mode}. For a scalar mode to be 4326considered supported, all the basic arithmetic and comparisons 4327must work. 4328 4329The default version of this hook returns true for any mode 4330required to handle the basic C types (as defined by the port). 4331Included here are the double-word arithmetic supported by the 4332code in @file{optabs.c}. 4333@end deftypefn 4334 4335@deftypefn {Target Hook} bool TARGET_VECTOR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4336Define this to return nonzero if the port is prepared to handle 4337insns involving vector mode @var{mode}. At the very least, it 4338must have move patterns for this mode. 4339@end deftypefn 4340 4341@deftypefn {Target Hook} bool TARGET_ARRAY_MODE_SUPPORTED_P (enum machine_mode @var{mode}, unsigned HOST_WIDE_INT @var{nelems}) 4342Return true if GCC should try to use a scalar mode to store an array 4343of @var{nelems} elements, given that each element has mode @var{mode}. 4344Returning true here overrides the usual @code{MAX_FIXED_MODE} limit 4345and allows GCC to use any defined integer mode. 4346 4347One use of this hook is to support vector load and store operations 4348that operate on several homogeneous vectors. For example, ARM NEON 4349has operations like: 4350 4351@smallexample 4352int8x8x3_t vld3_s8 (const int8_t *) 4353@end smallexample 4354 4355where the return type is defined as: 4356 4357@smallexample 4358typedef struct int8x8x3_t 4359@{ 4360 int8x8_t val[3]; 4361@} int8x8x3_t; 4362@end smallexample 4363 4364If this hook allows @code{val} to have a scalar mode, then 4365@code{int8x8x3_t} can have the same mode. GCC can then store 4366@code{int8x8x3_t}s in registers rather than forcing them onto the stack. 4367@end deftypefn 4368 4369@deftypefn {Target Hook} bool TARGET_SMALL_REGISTER_CLASSES_FOR_MODE_P (enum machine_mode @var{mode}) 4370Define this to return nonzero for machine modes for which the port has 4371small register classes. If this target hook returns nonzero for a given 4372@var{mode}, the compiler will try to minimize the lifetime of registers 4373in @var{mode}. The hook may be called with @code{VOIDmode} as argument. 4374In this case, the hook is expected to return nonzero if it returns nonzero 4375for any mode. 4376 4377On some machines, it is risky to let hard registers live across arbitrary 4378insns. Typically, these machines have instructions that require values 4379to be in specific registers (like an accumulator), and reload will fail 4380if the required hard register is used for another purpose across such an 4381insn. 4382 4383Passes before reload do not know which hard registers will be used 4384in an instruction, but the machine modes of the registers set or used in 4385the instruction are already known. And for some machines, register 4386classes are small for, say, integer registers but not for floating point 4387registers. For example, the AMD x86-64 architecture requires specific 4388registers for the legacy x86 integer instructions, but there are many 4389SSE registers for floating point operations. On such targets, a good 4390strategy may be to return nonzero from this hook for @code{INTEGRAL_MODE_P} 4391machine modes but zero for the SSE register classes. 4392 4393The default version of this hook returns false for any mode. It is always 4394safe to redefine this hook to return with a nonzero value. But if you 4395unnecessarily define it, you will reduce the amount of optimizations 4396that can be performed in some cases. If you do not define this hook 4397to return a nonzero value when it is required, the compiler will run out 4398of spill registers and print a fatal error message. 4399@end deftypefn 4400 4401@deftypevr {Target Hook} {unsigned int} TARGET_FLAGS_REGNUM 4402If 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. 4403@end deftypevr 4404 4405@node Scalar Return 4406@subsection How Scalar Function Values Are Returned 4407@cindex return values in registers 4408@cindex values, returned by functions 4409@cindex scalars, returned as values 4410 4411This section discusses the macros that control returning scalars as 4412values---values that can fit in registers. 4413 4414@deftypefn {Target Hook} rtx TARGET_FUNCTION_VALUE (const_tree @var{ret_type}, const_tree @var{fn_decl_or_type}, bool @var{outgoing}) 4415 4416Define this to return an RTX representing the place where a function 4417returns or receives a value of data type @var{ret_type}, a tree node 4418representing a data type. @var{fn_decl_or_type} is a tree node 4419representing @code{FUNCTION_DECL} or @code{FUNCTION_TYPE} of a 4420function being called. If @var{outgoing} is false, the hook should 4421compute the register in which the caller will see the return value. 4422Otherwise, the hook should return an RTX representing the place where 4423a function returns a value. 4424 4425On many machines, only @code{TYPE_MODE (@var{ret_type})} is relevant. 4426(Actually, on most machines, scalar values are returned in the same 4427place regardless of mode.) The value of the expression is usually a 4428@code{reg} RTX for the hard register where the return value is stored. 4429The value can also be a @code{parallel} RTX, if the return value is in 4430multiple places. See @code{TARGET_FUNCTION_ARG} for an explanation of the 4431@code{parallel} form. Note that the callee will populate every 4432location specified in the @code{parallel}, but if the first element of 4433the @code{parallel} contains the whole return value, callers will use 4434that element as the canonical location and ignore the others. The m68k 4435port uses this type of @code{parallel} to return pointers in both 4436@samp{%a0} (the canonical location) and @samp{%d0}. 4437 4438If @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply 4439the same promotion rules specified in @code{PROMOTE_MODE} if 4440@var{valtype} is a scalar type. 4441 4442If the precise function being called is known, @var{func} is a tree 4443node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 4444pointer. This makes it possible to use a different value-returning 4445convention for specific functions when all their calls are 4446known. 4447 4448Some target machines have ``register windows'' so that the register in 4449which a function returns its value is not the same as the one in which 4450the caller sees the value. For such machines, you should return 4451different RTX depending on @var{outgoing}. 4452 4453@code{TARGET_FUNCTION_VALUE} is not used for return values with 4454aggregate data types, because these are returned in another way. See 4455@code{TARGET_STRUCT_VALUE_RTX} and related macros, below. 4456@end deftypefn 4457 4458@defmac FUNCTION_VALUE (@var{valtype}, @var{func}) 4459This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for 4460a new target instead. 4461@end defmac 4462 4463@defmac LIBCALL_VALUE (@var{mode}) 4464A C expression to create an RTX representing the place where a library 4465function returns a value of mode @var{mode}. 4466 4467Note that ``library function'' in this context means a compiler 4468support routine, used to perform arithmetic, whose name is known 4469specially by the compiler and was not mentioned in the C code being 4470compiled. 4471@end defmac 4472 4473@deftypefn {Target Hook} rtx TARGET_LIBCALL_VALUE (enum machine_mode @var{mode}, const_rtx @var{fun}) 4474Define this hook if the back-end needs to know the name of the libcall 4475function in order to determine where the result should be returned. 4476 4477The mode of the result is given by @var{mode} and the name of the called 4478library function is given by @var{fun}. The hook should return an RTX 4479representing the place where the library function result will be returned. 4480 4481If this hook is not defined, then LIBCALL_VALUE will be used. 4482@end deftypefn 4483 4484@defmac FUNCTION_VALUE_REGNO_P (@var{regno}) 4485A C expression that is nonzero if @var{regno} is the number of a hard 4486register in which the values of called function may come back. 4487 4488A register whose use for returning values is limited to serving as the 4489second of a pair (for a value of type @code{double}, say) need not be 4490recognized by this macro. So for most machines, this definition 4491suffices: 4492 4493@smallexample 4494#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 4495@end smallexample 4496 4497If the machine has register windows, so that the caller and the called 4498function use different registers for the return value, this macro 4499should recognize only the caller's register numbers. 4500 4501This macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE_REGNO_P} 4502for a new target instead. 4503@end defmac 4504 4505@deftypefn {Target Hook} bool TARGET_FUNCTION_VALUE_REGNO_P (const unsigned int @var{regno}) 4506A target hook that return @code{true} if @var{regno} is the number of a hard 4507register in which the values of called function may come back. 4508 4509A register whose use for returning values is limited to serving as the 4510second of a pair (for a value of type @code{double}, say) need not be 4511recognized by this target hook. 4512 4513If the machine has register windows, so that the caller and the called 4514function use different registers for the return value, this target hook 4515should recognize only the caller's register numbers. 4516 4517If this hook is not defined, then FUNCTION_VALUE_REGNO_P will be used. 4518@end deftypefn 4519 4520@defmac APPLY_RESULT_SIZE 4521Define this macro if @samp{untyped_call} and @samp{untyped_return} 4522need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 4523saving and restoring an arbitrary return value. 4524@end defmac 4525 4526@deftypefn {Target Hook} bool TARGET_RETURN_IN_MSB (const_tree @var{type}) 4527This hook should return true if values of type @var{type} are returned 4528at the most significant end of a register (in other words, if they are 4529padded at the least significant end). You can assume that @var{type} 4530is returned in a register; the caller is required to check this. 4531 4532Note that the register provided by @code{TARGET_FUNCTION_VALUE} must 4533be able to hold the complete return value. For example, if a 1-, 2- 4534or 3-byte structure is returned at the most significant end of a 45354-byte register, @code{TARGET_FUNCTION_VALUE} should provide an 4536@code{SImode} rtx. 4537@end deftypefn 4538 4539@node Aggregate Return 4540@subsection How Large Values Are Returned 4541@cindex aggregates as return values 4542@cindex large return values 4543@cindex returning aggregate values 4544@cindex structure value address 4545 4546When a function value's mode is @code{BLKmode} (and in some other 4547cases), the value is not returned according to 4548@code{TARGET_FUNCTION_VALUE} (@pxref{Scalar Return}). Instead, the 4549caller passes the address of a block of memory in which the value 4550should be stored. This address is called the @dfn{structure value 4551address}. 4552 4553This section describes how to control returning structure values in 4554memory. 4555 4556@deftypefn {Target Hook} bool TARGET_RETURN_IN_MEMORY (const_tree @var{type}, const_tree @var{fntype}) 4557This target hook should return a nonzero value to say to return the 4558function value in memory, just as large structures are always returned. 4559Here @var{type} will be the data type of the value, and @var{fntype} 4560will be the type of the function doing the returning, or @code{NULL} for 4561libcalls. 4562 4563Note that values of mode @code{BLKmode} must be explicitly handled 4564by this function. Also, the option @option{-fpcc-struct-return} 4565takes effect regardless of this macro. On most systems, it is 4566possible to leave the hook undefined; this causes a default 4567definition to be used, whose value is the constant 1 for @code{BLKmode} 4568values, and 0 otherwise. 4569 4570Do not use this hook to indicate that structures and unions should always 4571be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 4572to indicate this. 4573@end deftypefn 4574 4575@defmac DEFAULT_PCC_STRUCT_RETURN 4576Define this macro to be 1 if all structure and union return values must be 4577in memory. Since this results in slower code, this should be defined 4578only if needed for compatibility with other compilers or with an ABI@. 4579If you define this macro to be 0, then the conventions used for structure 4580and union return values are decided by the @code{TARGET_RETURN_IN_MEMORY} 4581target hook. 4582 4583If not defined, this defaults to the value 1. 4584@end defmac 4585 4586@deftypefn {Target Hook} rtx TARGET_STRUCT_VALUE_RTX (tree @var{fndecl}, int @var{incoming}) 4587This target hook should return the location of the structure value 4588address (normally a @code{mem} or @code{reg}), or 0 if the address is 4589passed as an ``invisible'' first argument. Note that @var{fndecl} may 4590be @code{NULL}, for libcalls. You do not need to define this target 4591hook if the address is always passed as an ``invisible'' first 4592argument. 4593 4594On some architectures the place where the structure value address 4595is found by the called function is not the same place that the 4596caller put it. This can be due to register windows, or it could 4597be because the function prologue moves it to a different place. 4598@var{incoming} is @code{1} or @code{2} when the location is needed in 4599the context of the called function, and @code{0} in the context of 4600the caller. 4601 4602If @var{incoming} is nonzero and the address is to be found on the 4603stack, return a @code{mem} which refers to the frame pointer. If 4604@var{incoming} is @code{2}, the result is being used to fetch the 4605structure value address at the beginning of a function. If you need 4606to emit adjusting code, you should do it at this point. 4607@end deftypefn 4608 4609@defmac PCC_STATIC_STRUCT_RETURN 4610Define this macro if the usual system convention on the target machine 4611for returning structures and unions is for the called function to return 4612the address of a static variable containing the value. 4613 4614Do not define this if the usual system convention is for the caller to 4615pass an address to the subroutine. 4616 4617This macro has effect in @option{-fpcc-struct-return} mode, but it does 4618nothing when you use @option{-freg-struct-return} mode. 4619@end defmac 4620 4621@deftypefn {Target Hook} {enum machine_mode} TARGET_GET_RAW_RESULT_MODE (int @var{regno}) 4622This 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. 4623@end deftypefn 4624 4625@deftypefn {Target Hook} {enum machine_mode} TARGET_GET_RAW_ARG_MODE (int @var{regno}) 4626This 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. 4627@end deftypefn 4628 4629@node Caller Saves 4630@subsection Caller-Saves Register Allocation 4631 4632If you enable it, GCC can save registers around function calls. This 4633makes it possible to use call-clobbered registers to hold variables that 4634must live across calls. 4635 4636@defmac CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 4637A C expression to determine whether it is worthwhile to consider placing 4638a pseudo-register in a call-clobbered hard register and saving and 4639restoring it around each function call. The expression should be 1 when 4640this is worth doing, and 0 otherwise. 4641 4642If you don't define this macro, a default is used which is good on most 4643machines: @code{4 * @var{calls} < @var{refs}}. 4644@end defmac 4645 4646@defmac HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 4647A C expression specifying which mode is required for saving @var{nregs} 4648of a pseudo-register in call-clobbered hard register @var{regno}. If 4649@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 4650returned. For most machines this macro need not be defined since GCC 4651will select the smallest suitable mode. 4652@end defmac 4653 4654@node Function Entry 4655@subsection Function Entry and Exit 4656@cindex function entry and exit 4657@cindex prologue 4658@cindex epilogue 4659 4660This section describes the macros that output function entry 4661(@dfn{prologue}) and exit (@dfn{epilogue}) code. 4662 4663@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 4664If defined, a function that outputs the assembler code for entry to a 4665function. The prologue is responsible for setting up the stack frame, 4666initializing the frame pointer register, saving registers that must be 4667saved, and allocating @var{size} additional bytes of storage for the 4668local variables. @var{size} is an integer. @var{file} is a stdio 4669stream to which the assembler code should be output. 4670 4671The label for the beginning of the function need not be output by this 4672macro. That has already been done when the macro is run. 4673 4674@findex regs_ever_live 4675To determine which registers to save, the macro can refer to the array 4676@code{regs_ever_live}: element @var{r} is nonzero if hard register 4677@var{r} is used anywhere within the function. This implies the function 4678prologue should save register @var{r}, provided it is not one of the 4679call-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 4680@code{regs_ever_live}.) 4681 4682On machines that have ``register windows'', the function entry code does 4683not save on the stack the registers that are in the windows, even if 4684they are supposed to be preserved by function calls; instead it takes 4685appropriate steps to ``push'' the register stack, if any non-call-used 4686registers are used in the function. 4687 4688@findex frame_pointer_needed 4689On machines where functions may or may not have frame-pointers, the 4690function entry code must vary accordingly; it must set up the frame 4691pointer if one is wanted, and not otherwise. To determine whether a 4692frame pointer is in wanted, the macro can refer to the variable 4693@code{frame_pointer_needed}. The variable's value will be 1 at run 4694time in a function that needs a frame pointer. @xref{Elimination}. 4695 4696The function entry code is responsible for allocating any stack space 4697required for the function. This stack space consists of the regions 4698listed below. In most cases, these regions are allocated in the 4699order listed, with the last listed region closest to the top of the 4700stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 4701the highest address if it is not defined). You can use a different order 4702for a machine if doing so is more convenient or required for 4703compatibility reasons. Except in cases where required by standard 4704or by a debugger, there is no reason why the stack layout used by GCC 4705need agree with that used by other compilers for a machine. 4706@end deftypefn 4707 4708@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 4709If defined, a function that outputs assembler code at the end of a 4710prologue. This should be used when the function prologue is being 4711emitted as RTL, and you have some extra assembler that needs to be 4712emitted. @xref{prologue instruction pattern}. 4713@end deftypefn 4714 4715@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 4716If defined, a function that outputs assembler code at the start of an 4717epilogue. This should be used when the function epilogue is being 4718emitted as RTL, and you have some extra assembler that needs to be 4719emitted. @xref{epilogue instruction pattern}. 4720@end deftypefn 4721 4722@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 4723If defined, a function that outputs the assembler code for exit from a 4724function. The epilogue is responsible for restoring the saved 4725registers and stack pointer to their values when the function was 4726called, and returning control to the caller. This macro takes the 4727same arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 4728registers to restore are determined from @code{regs_ever_live} and 4729@code{CALL_USED_REGISTERS} in the same way. 4730 4731On some machines, there is a single instruction that does all the work 4732of returning from the function. On these machines, give that 4733instruction the name @samp{return} and do not define the macro 4734@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 4735 4736Do not define a pattern named @samp{return} if you want the 4737@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 4738switches to control whether return instructions or epilogues are used, 4739define a @samp{return} pattern with a validity condition that tests the 4740target switches appropriately. If the @samp{return} pattern's validity 4741condition is false, epilogues will be used. 4742 4743On machines where functions may or may not have frame-pointers, the 4744function exit code must vary accordingly. Sometimes the code for these 4745two cases is completely different. To determine whether a frame pointer 4746is wanted, the macro can refer to the variable 4747@code{frame_pointer_needed}. The variable's value will be 1 when compiling 4748a function that needs a frame pointer. 4749 4750Normally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 4751@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 4752The C variable @code{current_function_is_leaf} is nonzero for such a 4753function. @xref{Leaf Functions}. 4754 4755On some machines, some functions pop their arguments on exit while 4756others leave that for the caller to do. For example, the 68020 when 4757given @option{-mrtd} pops arguments in functions that take a fixed 4758number of arguments. 4759 4760@findex current_function_pops_args 4761Your definition of the macro @code{RETURN_POPS_ARGS} decides which 4762functions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 4763needs to know what was decided. The number of bytes of the current 4764function's arguments that this function should pop is available in 4765@code{crtl->args.pops_args}. @xref{Scalar Return}. 4766@end deftypefn 4767 4768@itemize @bullet 4769@item 4770@findex current_function_pretend_args_size 4771A region of @code{current_function_pretend_args_size} bytes of 4772uninitialized space just underneath the first argument arriving on the 4773stack. (This may not be at the very start of the allocated stack region 4774if the calling sequence has pushed anything else since pushing the stack 4775arguments. But usually, on such machines, nothing else has been pushed 4776yet, because the function prologue itself does all the pushing.) This 4777region is used on machines where an argument may be passed partly in 4778registers and partly in memory, and, in some cases to support the 4779features in @code{<stdarg.h>}. 4780 4781@item 4782An area of memory used to save certain registers used by the function. 4783The size of this area, which may also include space for such things as 4784the return address and pointers to previous stack frames, is 4785machine-specific and usually depends on which registers have been used 4786in the function. Machines with register windows often do not require 4787a save area. 4788 4789@item 4790A region of at least @var{size} bytes, possibly rounded up to an allocation 4791boundary, to contain the local variables of the function. On some machines, 4792this region and the save area may occur in the opposite order, with the 4793save area closer to the top of the stack. 4794 4795@item 4796@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 4797Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 4798@code{current_function_outgoing_args_size} bytes to be used for outgoing 4799argument lists of the function. @xref{Stack Arguments}. 4800@end itemize 4801 4802@defmac EXIT_IGNORE_STACK 4803Define this macro as a C expression that is nonzero if the return 4804instruction or the function epilogue ignores the value of the stack 4805pointer; in other words, if it is safe to delete an instruction to 4806adjust the stack pointer before a return from the function. The 4807default is 0. 4808 4809Note that this macro's value is relevant only for functions for which 4810frame pointers are maintained. It is never safe to delete a final 4811stack adjustment in a function that has no frame pointer, and the 4812compiler knows this regardless of @code{EXIT_IGNORE_STACK}. 4813@end defmac 4814 4815@defmac EPILOGUE_USES (@var{regno}) 4816Define this macro as a C expression that is nonzero for registers that are 4817used by the epilogue or the @samp{return} pattern. The stack and frame 4818pointer registers are already assumed to be used as needed. 4819@end defmac 4820 4821@defmac EH_USES (@var{regno}) 4822Define this macro as a C expression that is nonzero for registers that are 4823used by the exception handling mechanism, and so should be considered live 4824on entry to an exception edge. 4825@end defmac 4826 4827@defmac DELAY_SLOTS_FOR_EPILOGUE 4828Define this macro if the function epilogue contains delay slots to which 4829instructions from the rest of the function can be ``moved''. The 4830definition should be a C expression whose value is an integer 4831representing the number of delay slots there. 4832@end defmac 4833 4834@defmac ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 4835A C expression that returns 1 if @var{insn} can be placed in delay 4836slot number @var{n} of the epilogue. 4837 4838The argument @var{n} is an integer which identifies the delay slot now 4839being considered (since different slots may have different rules of 4840eligibility). It is never negative and is always less than the number 4841of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 4842If you reject a particular insn for a given delay slot, in principle, it 4843may be reconsidered for a subsequent delay slot. Also, other insns may 4844(at least in principle) be considered for the so far unfilled delay 4845slot. 4846 4847@findex current_function_epilogue_delay_list 4848@findex final_scan_insn 4849The insns accepted to fill the epilogue delay slots are put in an RTL 4850list made with @code{insn_list} objects, stored in the variable 4851@code{current_function_epilogue_delay_list}. The insn for the first 4852delay slot comes first in the list. Your definition of the macro 4853@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 4854outputting the insns in this list, usually by calling 4855@code{final_scan_insn}. 4856 4857You need not define this macro if you did not define 4858@code{DELAY_SLOTS_FOR_EPILOGUE}. 4859@end defmac 4860 4861@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}) 4862A function that outputs the assembler code for a thunk 4863function, used to implement C++ virtual function calls with multiple 4864inheritance. The thunk acts as a wrapper around a virtual function, 4865adjusting the implicit object parameter before handing control off to 4866the real function. 4867 4868First, emit code to add the integer @var{delta} to the location that 4869contains the incoming first argument. Assume that this argument 4870contains a pointer, and is the one used to pass the @code{this} pointer 4871in C++. This is the incoming argument @emph{before} the function prologue, 4872e.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 4873all other incoming arguments. 4874 4875Then, if @var{vcall_offset} is nonzero, an additional adjustment should be 4876made after adding @code{delta}. In particular, if @var{p} is the 4877adjusted pointer, the following adjustment should be made: 4878 4879@smallexample 4880p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] 4881@end smallexample 4882 4883After the additions, emit code to jump to @var{function}, which is a 4884@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 4885not touch the return address. Hence returning from @var{FUNCTION} will 4886return to whoever called the current @samp{thunk}. 4887 4888The effect must be as if @var{function} had been called directly with 4889the adjusted first argument. This macro is responsible for emitting all 4890of the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 4891and @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 4892 4893The @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 4894have already been extracted from it.) It might possibly be useful on 4895some targets, but probably not. 4896 4897If you do not define this macro, the target-independent code in the C++ 4898front end will generate a less efficient heavyweight thunk that calls 4899@var{function} instead of jumping to it. The generic approach does 4900not support varargs. 4901@end deftypefn 4902 4903@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}) 4904A function that returns true if TARGET_ASM_OUTPUT_MI_THUNK would be able 4905to output the assembler code for the thunk function specified by the 4906arguments it is passed, and false otherwise. In the latter case, the 4907generic approach will be used by the C++ front end, with the limitations 4908previously exposed. 4909@end deftypefn 4910 4911@node Profiling 4912@subsection Generating Code for Profiling 4913@cindex profiling, code generation 4914 4915These macros will help you generate code for profiling. 4916 4917@defmac FUNCTION_PROFILER (@var{file}, @var{labelno}) 4918A C statement or compound statement to output to @var{file} some 4919assembler code to call the profiling subroutine @code{mcount}. 4920 4921@findex mcount 4922The details of how @code{mcount} expects to be called are determined by 4923your operating system environment, not by GCC@. To figure them out, 4924compile a small program for profiling using the system's installed C 4925compiler and look at the assembler code that results. 4926 4927Older implementations of @code{mcount} expect the address of a counter 4928variable to be loaded into some register. The name of this variable is 4929@samp{LP} followed by the number @var{labelno}, so you would generate 4930the name using @samp{LP%d} in a @code{fprintf}. 4931@end defmac 4932 4933@defmac PROFILE_HOOK 4934A C statement or compound statement to output to @var{file} some assembly 4935code to call the profiling subroutine @code{mcount} even the target does 4936not support profiling. 4937@end defmac 4938 4939@defmac NO_PROFILE_COUNTERS 4940Define this macro to be an expression with a nonzero value if the 4941@code{mcount} subroutine on your system does not need a counter variable 4942allocated for each function. This is true for almost all modern 4943implementations. If you define this macro, you must not use the 4944@var{labelno} argument to @code{FUNCTION_PROFILER}. 4945@end defmac 4946 4947@defmac PROFILE_BEFORE_PROLOGUE 4948Define this macro if the code for function profiling should come before 4949the function prologue. Normally, the profiling code comes after. 4950@end defmac 4951 4952@node Tail Calls 4953@subsection Permitting tail calls 4954@cindex tail calls 4955 4956@deftypefn {Target Hook} bool TARGET_FUNCTION_OK_FOR_SIBCALL (tree @var{decl}, tree @var{exp}) 4957True if it is ok to do sibling call optimization for the specified 4958call expression @var{exp}. @var{decl} will be the called function, 4959or @code{NULL} if this is an indirect call. 4960 4961It is not uncommon for limitations of calling conventions to prevent 4962tail calls to functions outside the current unit of translation, or 4963during PIC compilation. The hook is used to enforce these restrictions, 4964as the @code{sibcall} md pattern can not fail, or fall over to a 4965``normal'' call. The criteria for successful sibling call optimization 4966may vary greatly between different architectures. 4967@end deftypefn 4968 4969@deftypefn {Target Hook} void TARGET_EXTRA_LIVE_ON_ENTRY (bitmap @var{regs}) 4970Add any hard registers to @var{regs} that are live on entry to the 4971function. This hook only needs to be defined to provide registers that 4972cannot be found by examination of FUNCTION_ARG_REGNO_P, the callee saved 4973registers, STATIC_CHAIN_INCOMING_REGNUM, STATIC_CHAIN_REGNUM, 4974TARGET_STRUCT_VALUE_RTX, FRAME_POINTER_REGNUM, EH_USES, 4975FRAME_POINTER_REGNUM, ARG_POINTER_REGNUM, and the PIC_OFFSET_TABLE_REGNUM. 4976@end deftypefn 4977 4978@deftypefn {Target Hook} void TARGET_SET_UP_BY_PROLOGUE (struct hard_reg_set_container *@var{}) 4979This hook should add additional registers that are computed by the prologue to the hard regset for shrink-wrapping optimization purposes. 4980@end deftypefn 4981 4982@node Stack Smashing Protection 4983@subsection Stack smashing protection 4984@cindex stack smashing protection 4985 4986@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_GUARD (void) 4987This hook returns a @code{DECL} node for the external variable to use 4988for the stack protection guard. This variable is initialized by the 4989runtime to some random value and is used to initialize the guard value 4990that is placed at the top of the local stack frame. The type of this 4991variable must be @code{ptr_type_node}. 4992 4993The default version of this hook creates a variable called 4994@samp{__stack_chk_guard}, which is normally defined in @file{libgcc2.c}. 4995@end deftypefn 4996 4997@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_FAIL (void) 4998This hook returns a tree expression that alerts the runtime that the 4999stack protect guard variable has been modified. This expression should 5000involve a call to a @code{noreturn} function. 5001 5002The default version of this hook invokes a function called 5003@samp{__stack_chk_fail}, taking no arguments. This function is 5004normally defined in @file{libgcc2.c}. 5005@end deftypefn 5006 5007@deftypefn {Common Target Hook} bool TARGET_SUPPORTS_SPLIT_STACK (bool @var{report}, struct gcc_options *@var{opts}) 5008Whether 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 5009@end deftypefn 5010 5011@node Varargs 5012@section Implementing the Varargs Macros 5013@cindex varargs implementation 5014 5015GCC comes with an implementation of @code{<varargs.h>} and 5016@code{<stdarg.h>} that work without change on machines that pass arguments 5017on the stack. Other machines require their own implementations of 5018varargs, and the two machine independent header files must have 5019conditionals to include it. 5020 5021ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 5022the calling convention for @code{va_start}. The traditional 5023implementation takes just one argument, which is the variable in which 5024to store the argument pointer. The ISO implementation of 5025@code{va_start} takes an additional second argument. The user is 5026supposed to write the last named argument of the function here. 5027 5028However, @code{va_start} should not use this argument. The way to find 5029the end of the named arguments is with the built-in functions described 5030below. 5031 5032@defmac __builtin_saveregs () 5033Use this built-in function to save the argument registers in memory so 5034that the varargs mechanism can access them. Both ISO and traditional 5035versions of @code{va_start} must use @code{__builtin_saveregs}, unless 5036you use @code{TARGET_SETUP_INCOMING_VARARGS} (see below) instead. 5037 5038On some machines, @code{__builtin_saveregs} is open-coded under the 5039control of the target hook @code{TARGET_EXPAND_BUILTIN_SAVEREGS}. On 5040other machines, it calls a routine written in assembler language, 5041found in @file{libgcc2.c}. 5042 5043Code generated for the call to @code{__builtin_saveregs} appears at the 5044beginning of the function, as opposed to where the call to 5045@code{__builtin_saveregs} is written, regardless of what the code is. 5046This is because the registers must be saved before the function starts 5047to use them for its own purposes. 5048@c i rewrote the first sentence above to fix an overfull hbox. --mew 5049@c 10feb93 5050@end defmac 5051 5052@defmac __builtin_next_arg (@var{lastarg}) 5053This builtin returns the address of the first anonymous stack 5054argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 5055returns the address of the location above the first anonymous stack 5056argument. Use it in @code{va_start} to initialize the pointer for 5057fetching arguments from the stack. Also use it in @code{va_start} to 5058verify that the second parameter @var{lastarg} is the last named argument 5059of the current function. 5060@end defmac 5061 5062@defmac __builtin_classify_type (@var{object}) 5063Since each machine has its own conventions for which data types are 5064passed in which kind of register, your implementation of @code{va_arg} 5065has to embody these conventions. The easiest way to categorize the 5066specified data type is to use @code{__builtin_classify_type} together 5067with @code{sizeof} and @code{__alignof__}. 5068 5069@code{__builtin_classify_type} ignores the value of @var{object}, 5070considering only its data type. It returns an integer describing what 5071kind of type that is---integer, floating, pointer, structure, and so on. 5072 5073The file @file{typeclass.h} defines an enumeration that you can use to 5074interpret the values of @code{__builtin_classify_type}. 5075@end defmac 5076 5077These machine description macros help implement varargs: 5078 5079@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN_SAVEREGS (void) 5080If defined, this hook produces the machine-specific code for a call to 5081@code{__builtin_saveregs}. This code will be moved to the very 5082beginning of the function, before any parameter access are made. The 5083return value of this function should be an RTX that contains the value 5084to use as the return of @code{__builtin_saveregs}. 5085@end deftypefn 5086 5087@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}) 5088This target hook offers an alternative to using 5089@code{__builtin_saveregs} and defining the hook 5090@code{TARGET_EXPAND_BUILTIN_SAVEREGS}. Use it to store the anonymous 5091register arguments into the stack so that all the arguments appear to 5092have been passed consecutively on the stack. Once this is done, you can 5093use the standard implementation of varargs that works for machines that 5094pass all their arguments on the stack. 5095 5096The argument @var{args_so_far} points to the @code{CUMULATIVE_ARGS} data 5097structure, containing the values that are obtained after processing the 5098named arguments. The arguments @var{mode} and @var{type} describe the 5099last named argument---its machine mode and its data type as a tree node. 5100 5101The target hook should do two things: first, push onto the stack all the 5102argument registers @emph{not} used for the named arguments, and second, 5103store the size of the data thus pushed into the @code{int}-valued 5104variable pointed to by @var{pretend_args_size}. The value that you 5105store here will serve as additional offset for setting up the stack 5106frame. 5107 5108Because you must generate code to push the anonymous arguments at 5109compile time without knowing their data types, 5110@code{TARGET_SETUP_INCOMING_VARARGS} is only useful on machines that 5111have just a single category of argument register and use it uniformly 5112for all data types. 5113 5114If the argument @var{second_time} is nonzero, it means that the 5115arguments of the function are being analyzed for the second time. This 5116happens for an inline function, which is not actually compiled until the 5117end of the source file. The hook @code{TARGET_SETUP_INCOMING_VARARGS} should 5118not generate any instructions in this case. 5119@end deftypefn 5120 5121@deftypefn {Target Hook} bool TARGET_STRICT_ARGUMENT_NAMING (cumulative_args_t @var{ca}) 5122Define this hook to return @code{true} if the location where a function 5123argument is passed depends on whether or not it is a named argument. 5124 5125This hook controls how the @var{named} argument to @code{TARGET_FUNCTION_ARG} 5126is set for varargs and stdarg functions. If this hook returns 5127@code{true}, the @var{named} argument is always true for named 5128arguments, and false for unnamed arguments. If it returns @code{false}, 5129but @code{TARGET_PRETEND_OUTGOING_VARARGS_NAMED} returns @code{true}, 5130then all arguments are treated as named. Otherwise, all named arguments 5131except the last are treated as named. 5132 5133You need not define this hook if it always returns @code{false}. 5134@end deftypefn 5135 5136@deftypefn {Target Hook} bool TARGET_PRETEND_OUTGOING_VARARGS_NAMED (cumulative_args_t @var{ca}) 5137If you need to conditionally change ABIs so that one works with 5138@code{TARGET_SETUP_INCOMING_VARARGS}, but the other works like neither 5139@code{TARGET_SETUP_INCOMING_VARARGS} nor @code{TARGET_STRICT_ARGUMENT_NAMING} was 5140defined, then define this hook to return @code{true} if 5141@code{TARGET_SETUP_INCOMING_VARARGS} is used, @code{false} otherwise. 5142Otherwise, you should not define this hook. 5143@end deftypefn 5144 5145@node Trampolines 5146@section Trampolines for Nested Functions 5147@cindex trampolines for nested functions 5148@cindex nested functions, trampolines for 5149 5150A @dfn{trampoline} is a small piece of code that is created at run time 5151when the address of a nested function is taken. It normally resides on 5152the stack, in the stack frame of the containing function. These macros 5153tell GCC how to generate code to allocate and initialize a 5154trampoline. 5155 5156The instructions in the trampoline must do two things: load a constant 5157address into the static chain register, and jump to the real address of 5158the nested function. On CISC machines such as the m68k, this requires 5159two instructions, a move immediate and a jump. Then the two addresses 5160exist in the trampoline as word-long immediate operands. On RISC 5161machines, it is often necessary to load each address into a register in 5162two parts. Then pieces of each address form separate immediate 5163operands. 5164 5165The code generated to initialize the trampoline must store the variable 5166parts---the static chain value and the function address---into the 5167immediate operands of the instructions. On a CISC machine, this is 5168simply a matter of copying each address to a memory reference at the 5169proper offset from the start of the trampoline. On a RISC machine, it 5170may be necessary to take out pieces of the address and store them 5171separately. 5172 5173@deftypefn {Target Hook} void TARGET_ASM_TRAMPOLINE_TEMPLATE (FILE *@var{f}) 5174This hook is called by @code{assemble_trampoline_template} to output, 5175on the stream @var{f}, assembler code for a block of data that contains 5176the constant parts of a trampoline. This code should not include a 5177label---the label is taken care of automatically. 5178 5179If you do not define this hook, it means no template is needed 5180for the target. Do not define this hook on systems where the block move 5181code to copy the trampoline into place would be larger than the code 5182to generate it on the spot. 5183@end deftypefn 5184 5185@defmac TRAMPOLINE_SECTION 5186Return the section into which the trampoline template is to be placed 5187(@pxref{Sections}). The default value is @code{readonly_data_section}. 5188@end defmac 5189 5190@defmac TRAMPOLINE_SIZE 5191A C expression for the size in bytes of the trampoline, as an integer. 5192@end defmac 5193 5194@defmac TRAMPOLINE_ALIGNMENT 5195Alignment required for trampolines, in bits. 5196 5197If you don't define this macro, the value of @code{FUNCTION_ALIGNMENT} 5198is used for aligning trampolines. 5199@end defmac 5200 5201@deftypefn {Target Hook} void TARGET_TRAMPOLINE_INIT (rtx @var{m_tramp}, tree @var{fndecl}, rtx @var{static_chain}) 5202This hook is called to initialize a trampoline. 5203@var{m_tramp} is an RTX for the memory block for the trampoline; @var{fndecl} 5204is the @code{FUNCTION_DECL} for the nested function; @var{static_chain} is an 5205RTX for the static chain value that should be passed to the function 5206when it is called. 5207 5208If the target defines @code{TARGET_ASM_TRAMPOLINE_TEMPLATE}, then the 5209first thing this hook should do is emit a block move into @var{m_tramp} 5210from the memory block returned by @code{assemble_trampoline_template}. 5211Note that the block move need only cover the constant parts of the 5212trampoline. If the target isolates the variable parts of the trampoline 5213to the end, not all @code{TRAMPOLINE_SIZE} bytes need be copied. 5214 5215If the target requires any other actions, such as flushing caches or 5216enabling stack execution, these actions should be performed after 5217initializing the trampoline proper. 5218@end deftypefn 5219 5220@deftypefn {Target Hook} rtx TARGET_TRAMPOLINE_ADJUST_ADDRESS (rtx @var{addr}) 5221This hook should perform any machine-specific adjustment in 5222the address of the trampoline. Its argument contains the address of the 5223memory block that was passed to @code{TARGET_TRAMPOLINE_INIT}. In case 5224the address to be used for a function call should be different from the 5225address at which the template was stored, the different address should 5226be returned; otherwise @var{addr} should be returned unchanged. 5227If this hook is not defined, @var{addr} will be used for function calls. 5228@end deftypefn 5229 5230Implementing trampolines is difficult on many machines because they have 5231separate instruction and data caches. Writing into a stack location 5232fails to clear the memory in the instruction cache, so when the program 5233jumps to that location, it executes the old contents. 5234 5235Here are two possible solutions. One is to clear the relevant parts of 5236the instruction cache whenever a trampoline is set up. The other is to 5237make all trampolines identical, by having them jump to a standard 5238subroutine. The former technique makes trampoline execution faster; the 5239latter makes initialization faster. 5240 5241To clear the instruction cache when a trampoline is initialized, define 5242the following macro. 5243 5244@defmac CLEAR_INSN_CACHE (@var{beg}, @var{end}) 5245If defined, expands to a C expression clearing the @emph{instruction 5246cache} in the specified interval. The definition of this macro would 5247typically be a series of @code{asm} statements. Both @var{beg} and 5248@var{end} are both pointer expressions. 5249@end defmac 5250 5251To use a standard subroutine, define the following macro. In addition, 5252you must make sure that the instructions in a trampoline fill an entire 5253cache line with identical instructions, or else ensure that the 5254beginning of the trampoline code is always aligned at the same point in 5255its cache line. Look in @file{m68k.h} as a guide. 5256 5257@defmac TRANSFER_FROM_TRAMPOLINE 5258Define this macro if trampolines need a special subroutine to do their 5259work. The macro should expand to a series of @code{asm} statements 5260which will be compiled with GCC@. They go in a library function named 5261@code{__transfer_from_trampoline}. 5262 5263If you need to avoid executing the ordinary prologue code of a compiled 5264C function when you jump to the subroutine, you can do so by placing a 5265special label of your own in the assembler code. Use one @code{asm} 5266statement to generate an assembler label, and another to make the label 5267global. Then trampolines can use that label to jump directly to your 5268special assembler code. 5269@end defmac 5270 5271@node Library Calls 5272@section Implicit Calls to Library Routines 5273@cindex library subroutine names 5274@cindex @file{libgcc.a} 5275 5276@c prevent bad page break with this line 5277Here is an explanation of implicit calls to library routines. 5278 5279@defmac DECLARE_LIBRARY_RENAMES 5280This macro, if defined, should expand to a piece of C code that will get 5281expanded when compiling functions for libgcc.a. It can be used to 5282provide alternate names for GCC's internal library functions if there 5283are ABI-mandated names that the compiler should provide. 5284@end defmac 5285 5286@findex set_optab_libfunc 5287@findex init_one_libfunc 5288@deftypefn {Target Hook} void TARGET_INIT_LIBFUNCS (void) 5289This hook should declare additional library routines or rename 5290existing ones, using the functions @code{set_optab_libfunc} and 5291@code{init_one_libfunc} defined in @file{optabs.c}. 5292@code{init_optabs} calls this macro after initializing all the normal 5293library routines. 5294 5295The default is to do nothing. Most ports don't need to define this hook. 5296@end deftypefn 5297 5298@deftypevr {Target Hook} bool TARGET_LIBFUNC_GNU_PREFIX 5299If false (the default), internal library routines start with two 5300underscores. If set to true, these routines start with @code{__gnu_} 5301instead. E.g., @code{__muldi3} changes to @code{__gnu_muldi3}. This 5302currently only affects functions defined in @file{libgcc2.c}. If this 5303is set to true, the @file{tm.h} file must also 5304@code{#define LIBGCC2_GNU_PREFIX}. 5305@end deftypevr 5306 5307@defmac FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 5308This macro should return @code{true} if the library routine that 5309implements the floating point comparison operator @var{comparison} in 5310mode @var{mode} will return a boolean, and @var{false} if it will 5311return a tristate. 5312 5313GCC's own floating point libraries return tristates from the 5314comparison operators, so the default returns false always. Most ports 5315don't need to define this macro. 5316@end defmac 5317 5318@defmac TARGET_LIB_INT_CMP_BIASED 5319This macro should evaluate to @code{true} if the integer comparison 5320functions (like @code{__cmpdi2}) return 0 to indicate that the first 5321operand is smaller than the second, 1 to indicate that they are equal, 5322and 2 to indicate that the first operand is greater than the second. 5323If this macro evaluates to @code{false} the comparison functions return 5324@minus{}1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines 5325in @file{libgcc.a}, you do not need to define this macro. 5326@end defmac 5327 5328@cindex @code{EDOM}, implicit usage 5329@findex matherr 5330@defmac TARGET_EDOM 5331The value of @code{EDOM} on the target machine, as a C integer constant 5332expression. If you don't define this macro, GCC does not attempt to 5333deposit the value of @code{EDOM} into @code{errno} directly. Look in 5334@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 5335system. 5336 5337If you do not define @code{TARGET_EDOM}, then compiled code reports 5338domain errors by calling the library function and letting it report the 5339error. If mathematical functions on your system use @code{matherr} when 5340there is an error, then you should leave @code{TARGET_EDOM} undefined so 5341that @code{matherr} is used normally. 5342@end defmac 5343 5344@cindex @code{errno}, implicit usage 5345@defmac GEN_ERRNO_RTX 5346Define this macro as a C expression to create an rtl expression that 5347refers to the global ``variable'' @code{errno}. (On certain systems, 5348@code{errno} may not actually be a variable.) If you don't define this 5349macro, a reasonable default is used. 5350@end defmac 5351 5352@cindex C99 math functions, implicit usage 5353@defmac TARGET_C99_FUNCTIONS 5354When this macro is nonzero, GCC will implicitly optimize @code{sin} calls into 5355@code{sinf} and similarly for other functions defined by C99 standard. The 5356default is zero because a number of existing systems lack support for these 5357functions in their runtime so this macro needs to be redefined to one on 5358systems that do support the C99 runtime. 5359@end defmac 5360 5361@cindex sincos math function, implicit usage 5362@defmac TARGET_HAS_SINCOS 5363When this macro is nonzero, GCC will implicitly optimize calls to @code{sin} 5364and @code{cos} with the same argument to a call to @code{sincos}. The 5365default is zero. The target has to provide the following functions: 5366@smallexample 5367void sincos(double x, double *sin, double *cos); 5368void sincosf(float x, float *sin, float *cos); 5369void sincosl(long double x, long double *sin, long double *cos); 5370@end smallexample 5371@end defmac 5372 5373@defmac NEXT_OBJC_RUNTIME 5374Set this macro to 1 to use the "NeXT" Objective-C message sending conventions 5375by default. This calling convention involves passing the object, the selector 5376and the method arguments all at once to the method-lookup library function. 5377This is the usual setting when targeting Darwin/Mac OS X systems, which have 5378the NeXT runtime installed. 5379 5380If the macro is set to 0, the "GNU" Objective-C message sending convention 5381will be used by default. This convention passes just the object and the 5382selector to the method-lookup function, which returns a pointer to the method. 5383 5384In either case, it remains possible to select code-generation for the alternate 5385scheme, by means of compiler command line switches. 5386@end defmac 5387 5388@node Addressing Modes 5389@section Addressing Modes 5390@cindex addressing modes 5391 5392@c prevent bad page break with this line 5393This is about addressing modes. 5394 5395@defmac HAVE_PRE_INCREMENT 5396@defmacx HAVE_PRE_DECREMENT 5397@defmacx HAVE_POST_INCREMENT 5398@defmacx HAVE_POST_DECREMENT 5399A C expression that is nonzero if the machine supports pre-increment, 5400pre-decrement, post-increment, or post-decrement addressing respectively. 5401@end defmac 5402 5403@defmac HAVE_PRE_MODIFY_DISP 5404@defmacx HAVE_POST_MODIFY_DISP 5405A C expression that is nonzero if the machine supports pre- or 5406post-address side-effect generation involving constants other than 5407the size of the memory operand. 5408@end defmac 5409 5410@defmac HAVE_PRE_MODIFY_REG 5411@defmacx HAVE_POST_MODIFY_REG 5412A C expression that is nonzero if the machine supports pre- or 5413post-address side-effect generation involving a register displacement. 5414@end defmac 5415 5416@defmac CONSTANT_ADDRESS_P (@var{x}) 5417A C expression that is 1 if the RTX @var{x} is a constant which 5418is a valid address. On most machines the default definition of 5419@code{(CONSTANT_P (@var{x}) && GET_CODE (@var{x}) != CONST_DOUBLE)} 5420is acceptable, but a few machines are more restrictive as to which 5421constant addresses are supported. 5422@end defmac 5423 5424@defmac CONSTANT_P (@var{x}) 5425@code{CONSTANT_P}, which is defined by target-independent code, 5426accepts integer-values expressions whose values are not explicitly 5427known, such as @code{symbol_ref}, @code{label_ref}, and @code{high} 5428expressions and @code{const} arithmetic expressions, in addition to 5429@code{const_int} and @code{const_double} expressions. 5430@end defmac 5431 5432@defmac MAX_REGS_PER_ADDRESS 5433A number, the maximum number of registers that can appear in a valid 5434memory address. Note that it is up to you to specify a value equal to 5435the maximum number that @code{TARGET_LEGITIMATE_ADDRESS_P} would ever 5436accept. 5437@end defmac 5438 5439@deftypefn {Target Hook} bool TARGET_LEGITIMATE_ADDRESS_P (enum machine_mode @var{mode}, rtx @var{x}, bool @var{strict}) 5440A function that returns whether @var{x} (an RTX) is a legitimate memory 5441address on the target machine for a memory operand of mode @var{mode}. 5442 5443Legitimate addresses are defined in two variants: a strict variant and a 5444non-strict one. The @var{strict} parameter chooses which variant is 5445desired by the caller. 5446 5447The strict variant is used in the reload pass. It must be defined so 5448that any pseudo-register that has not been allocated a hard register is 5449considered a memory reference. This is because in contexts where some 5450kind of register is required, a pseudo-register with no hard register 5451must be rejected. For non-hard registers, the strict variant should look 5452up the @code{reg_renumber} array; it should then proceed using the hard 5453register number in the array, or treat the pseudo as a memory reference 5454if the array holds @code{-1}. 5455 5456The non-strict variant is used in other passes. It must be defined to 5457accept all pseudo-registers in every context where some kind of 5458register is required. 5459 5460Normally, constant addresses which are the sum of a @code{symbol_ref} 5461and an integer are stored inside a @code{const} RTX to mark them as 5462constant. Therefore, there is no need to recognize such sums 5463specifically as legitimate addresses. Normally you would simply 5464recognize any @code{const} as legitimate. 5465 5466Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 5467sums that are not marked with @code{const}. It assumes that a naked 5468@code{plus} indicates indexing. If so, then you @emph{must} reject such 5469naked constant sums as illegitimate addresses, so that none of them will 5470be given to @code{PRINT_OPERAND_ADDRESS}. 5471 5472@cindex @code{TARGET_ENCODE_SECTION_INFO} and address validation 5473On some machines, whether a symbolic address is legitimate depends on 5474the section that the address refers to. On these machines, define the 5475target hook @code{TARGET_ENCODE_SECTION_INFO} to store the information 5476into the @code{symbol_ref}, and then check for it here. When you see a 5477@code{const}, you will have to look inside it to find the 5478@code{symbol_ref} in order to determine the section. @xref{Assembler 5479Format}. 5480 5481@cindex @code{GO_IF_LEGITIMATE_ADDRESS} 5482Some ports are still using a deprecated legacy substitute for 5483this hook, the @code{GO_IF_LEGITIMATE_ADDRESS} macro. This macro 5484has this syntax: 5485 5486@example 5487#define GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 5488@end example 5489 5490@noindent 5491and should @code{goto @var{label}} if the address @var{x} is a valid 5492address on the target machine for a memory operand of mode @var{mode}. 5493 5494@findex REG_OK_STRICT 5495Compiler source files that want to use the strict variant of this 5496macro define the macro @code{REG_OK_STRICT}. You should use an 5497@code{#ifdef REG_OK_STRICT} conditional to define the strict variant in 5498that case and the non-strict variant otherwise. 5499 5500Using the hook is usually simpler because it limits the number of 5501files that are recompiled when changes are made. 5502@end deftypefn 5503 5504@defmac TARGET_MEM_CONSTRAINT 5505A single character to be used instead of the default @code{'m'} 5506character for general memory addresses. This defines the constraint 5507letter which matches the memory addresses accepted by 5508@code{TARGET_LEGITIMATE_ADDRESS_P}. Define this macro if you want to 5509support new address formats in your back end without changing the 5510semantics of the @code{'m'} constraint. This is necessary in order to 5511preserve functionality of inline assembly constructs using the 5512@code{'m'} constraint. 5513@end defmac 5514 5515@defmac FIND_BASE_TERM (@var{x}) 5516A C expression to determine the base term of address @var{x}, 5517or to provide a simplified version of @var{x} from which @file{alias.c} 5518can easily find the base term. This macro is used in only two places: 5519@code{find_base_value} and @code{find_base_term} in @file{alias.c}. 5520 5521It is always safe for this macro to not be defined. It exists so 5522that alias analysis can understand machine-dependent addresses. 5523 5524The typical use of this macro is to handle addresses containing 5525a label_ref or symbol_ref within an UNSPEC@. 5526@end defmac 5527 5528@deftypefn {Target Hook} rtx TARGET_LEGITIMIZE_ADDRESS (rtx @var{x}, rtx @var{oldx}, enum machine_mode @var{mode}) 5529This hook is given an invalid memory address @var{x} for an 5530operand of mode @var{mode} and should try to return a valid memory 5531address. 5532 5533@findex break_out_memory_refs 5534@var{x} will always be the result of a call to @code{break_out_memory_refs}, 5535and @var{oldx} will be the operand that was given to that function to produce 5536@var{x}. 5537 5538The code of the hook should not alter the substructure of 5539@var{x}. If it transforms @var{x} into a more legitimate form, it 5540should return the new @var{x}. 5541 5542It is not necessary for this hook to come up with a legitimate address. 5543The compiler has standard ways of doing so in all cases. In fact, it 5544is safe to omit this hook or make it return @var{x} if it cannot find 5545a valid way to legitimize the address. But often a machine-dependent 5546strategy can generate better code. 5547@end deftypefn 5548 5549@defmac LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 5550A C compound statement that attempts to replace @var{x}, which is an address 5551that needs reloading, with a valid memory address for an operand of mode 5552@var{mode}. @var{win} will be a C statement label elsewhere in the code. 5553It is not necessary to define this macro, but it might be useful for 5554performance reasons. 5555 5556For example, on the i386, it is sometimes possible to use a single 5557reload register instead of two by reloading a sum of two pseudo 5558registers into a register. On the other hand, for number of RISC 5559processors offsets are limited so that often an intermediate address 5560needs to be generated in order to address a stack slot. By defining 5561@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 5562generated for adjacent some stack slots can be made identical, and thus 5563be shared. 5564 5565@emph{Note}: This macro should be used with caution. It is necessary 5566to know something of how reload works in order to effectively use this, 5567and it is quite easy to produce macros that build in too much knowledge 5568of reload internals. 5569 5570@emph{Note}: This macro must be able to reload an address created by a 5571previous invocation of this macro. If it fails to handle such addresses 5572then the compiler may generate incorrect code or abort. 5573 5574@findex push_reload 5575The macro definition should use @code{push_reload} to indicate parts that 5576need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 5577suitable to be passed unaltered to @code{push_reload}. 5578 5579The code generated by this macro must not alter the substructure of 5580@var{x}. If it transforms @var{x} into a more legitimate form, it 5581should assign @var{x} (which will always be a C variable) a new value. 5582This also applies to parts that you change indirectly by calling 5583@code{push_reload}. 5584 5585@findex strict_memory_address_p 5586The macro definition may use @code{strict_memory_address_p} to test if 5587the address has become legitimate. 5588 5589@findex copy_rtx 5590If you want to change only a part of @var{x}, one standard way of doing 5591this is to use @code{copy_rtx}. Note, however, that it unshares only a 5592single level of rtl. Thus, if the part to be changed is not at the 5593top level, you'll need to replace first the top level. 5594It is not necessary for this macro to come up with a legitimate 5595address; but often a machine-dependent strategy can generate better code. 5596@end defmac 5597 5598@deftypefn {Target Hook} bool TARGET_MODE_DEPENDENT_ADDRESS_P (const_rtx @var{addr}) 5599This hook returns @code{true} if memory address @var{addr} can have 5600different meanings depending on the machine mode of the memory 5601reference it is used for or if the address is valid for some modes 5602but not others. 5603 5604Autoincrement and autodecrement addresses typically have mode-dependent 5605effects because the amount of the increment or decrement is the size 5606of the operand being addressed. Some machines have other mode-dependent 5607addresses. Many RISC machines have no mode-dependent addresses. 5608 5609You may assume that @var{addr} is a valid address for the machine. 5610 5611The default version of this hook returns @code{false}. 5612@end deftypefn 5613 5614@defmac GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 5615A C statement or compound statement with a conditional @code{goto 5616@var{label};} executed if memory address @var{x} (an RTX) can have 5617different meanings depending on the machine mode of the memory 5618reference it is used for or if the address is valid for some modes 5619but not others. 5620 5621Autoincrement and autodecrement addresses typically have mode-dependent 5622effects because the amount of the increment or decrement is the size 5623of the operand being addressed. Some machines have other mode-dependent 5624addresses. Many RISC machines have no mode-dependent addresses. 5625 5626You may assume that @var{addr} is a valid address for the machine. 5627 5628These are obsolete macros, replaced by the 5629@code{TARGET_MODE_DEPENDENT_ADDRESS_P} target hook. 5630@end defmac 5631 5632@deftypefn {Target Hook} bool TARGET_LEGITIMATE_CONSTANT_P (enum machine_mode @var{mode}, rtx @var{x}) 5633This hook returns true if @var{x} is a legitimate constant for a 5634@var{mode}-mode immediate operand on the target machine. You can assume that 5635@var{x} satisfies @code{CONSTANT_P}, so you need not check this. 5636 5637The default definition returns true. 5638@end deftypefn 5639 5640@deftypefn {Target Hook} rtx TARGET_DELEGITIMIZE_ADDRESS (rtx @var{x}) 5641This hook is used to undo the possibly obfuscating effects of the 5642@code{LEGITIMIZE_ADDRESS} and @code{LEGITIMIZE_RELOAD_ADDRESS} target 5643macros. Some backend implementations of these macros wrap symbol 5644references inside an @code{UNSPEC} rtx to represent PIC or similar 5645addressing modes. This target hook allows GCC's optimizers to understand 5646the semantics of these opaque @code{UNSPEC}s by converting them back 5647into their original form. 5648@end deftypefn 5649 5650@deftypefn {Target Hook} bool TARGET_CONST_NOT_OK_FOR_DEBUG_P (rtx @var{x}) 5651This hook should return true if @var{x} should not be emitted into 5652debug sections. 5653@end deftypefn 5654 5655@deftypefn {Target Hook} bool TARGET_CANNOT_FORCE_CONST_MEM (enum machine_mode @var{mode}, rtx @var{x}) 5656This hook should return true if @var{x} is of a form that cannot (or 5657should not) be spilled to the constant pool. @var{mode} is the mode 5658of @var{x}. 5659 5660The default version of this hook returns false. 5661 5662The primary reason to define this hook is to prevent reload from 5663deciding that a non-legitimate constant would be better reloaded 5664from the constant pool instead of spilling and reloading a register 5665holding the constant. This restriction is often true of addresses 5666of TLS symbols for various targets. 5667@end deftypefn 5668 5669@deftypefn {Target Hook} bool TARGET_USE_BLOCKS_FOR_CONSTANT_P (enum machine_mode @var{mode}, const_rtx @var{x}) 5670This hook should return true if pool entries for constant @var{x} can 5671be placed in an @code{object_block} structure. @var{mode} is the mode 5672of @var{x}. 5673 5674The default version returns false for all constants. 5675@end deftypefn 5676 5677@deftypefn {Target Hook} tree TARGET_BUILTIN_RECIPROCAL (unsigned @var{fn}, bool @var{md_fn}, bool @var{sqrt}) 5678This hook should return the DECL of a function that implements reciprocal of 5679the builtin function with builtin function code @var{fn}, or 5680@code{NULL_TREE} if such a function is not available. @var{md_fn} is true 5681when @var{fn} is a code of a machine-dependent builtin function. When 5682@var{sqrt} is true, additional optimizations that apply only to the reciprocal 5683of a square root function are performed, and only reciprocals of @code{sqrt} 5684function are valid. 5685@end deftypefn 5686 5687@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD (void) 5688This hook should return the DECL of a function @var{f} that given an 5689address @var{addr} as an argument returns a mask @var{m} that can be 5690used to extract from two vectors the relevant data that resides in 5691@var{addr} in case @var{addr} is not properly aligned. 5692 5693The autovectorizer, when vectorizing a load operation from an address 5694@var{addr} that may be unaligned, will generate two vector loads from 5695the two aligned addresses around @var{addr}. It then generates a 5696@code{REALIGN_LOAD} operation to extract the relevant data from the 5697two loaded vectors. The first two arguments to @code{REALIGN_LOAD}, 5698@var{v1} and @var{v2}, are the two vectors, each of size @var{VS}, and 5699the third argument, @var{OFF}, defines how the data will be extracted 5700from these two vectors: if @var{OFF} is 0, then the returned vector is 5701@var{v2}; otherwise, the returned vector is composed from the last 5702@var{VS}-@var{OFF} elements of @var{v1} concatenated to the first 5703@var{OFF} elements of @var{v2}. 5704 5705If this hook is defined, the autovectorizer will generate a call 5706to @var{f} (using the DECL tree that this hook returns) and will 5707use the return value of @var{f} as the argument @var{OFF} to 5708@code{REALIGN_LOAD}. Therefore, the mask @var{m} returned by @var{f} 5709should comply with the semantics expected by @code{REALIGN_LOAD} 5710described above. 5711If this hook is not defined, then @var{addr} will be used as 5712the argument @var{OFF} to @code{REALIGN_LOAD}, in which case the low 5713log2(@var{VS}) @minus{} 1 bits of @var{addr} will be considered. 5714@end deftypefn 5715 5716@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_EVEN (tree @var{x}) 5717This hook should return the DECL of a function @var{f} that implements 5718widening multiplication of the even elements of two input vectors of type @var{x}. 5719 5720If this hook is defined, the autovectorizer will use it along with the 5721@code{TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_ODD} target hook when vectorizing 5722widening multiplication in cases that the order of the results does not have to be 5723preserved (e.g.@: used only by a reduction computation). Otherwise, the 5724@code{widen_mult_hi/lo} idioms will be used. 5725@end deftypefn 5726 5727@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_ODD (tree @var{x}) 5728This hook should return the DECL of a function @var{f} that implements 5729widening multiplication of the odd elements of two input vectors of type @var{x}. 5730 5731If this hook is defined, the autovectorizer will use it along with the 5732@code{TARGET_VECTORIZE_BUILTIN_MUL_WIDEN_EVEN} target hook when vectorizing 5733widening multiplication in cases that the order of the results does not have to be 5734preserved (e.g.@: used only by a reduction computation). Otherwise, the 5735@code{widen_mult_hi/lo} idioms will be used. 5736@end deftypefn 5737 5738@deftypefn {Target Hook} int TARGET_VECTORIZE_BUILTIN_VECTORIZATION_COST (enum vect_cost_for_stmt @var{type_of_cost}, tree @var{vectype}, int @var{misalign}) 5739Returns cost of different scalar or vector statements for vectorization cost model. 5740For vector memory operations the cost may depend on type (@var{vectype}) and 5741misalignment value (@var{misalign}). 5742@end deftypefn 5743 5744@deftypefn {Target Hook} bool TARGET_VECTORIZE_VECTOR_ALIGNMENT_REACHABLE (const_tree @var{type}, bool @var{is_packed}) 5745Return true if vector alignment is reachable (by peeling N iterations) for the given type. 5746@end deftypefn 5747 5748@deftypefn {Target Hook} bool TARGET_VECTORIZE_VEC_PERM_CONST_OK (enum @var{machine_mode}, const unsigned char *@var{sel}) 5749Return true if a vector created for @code{vec_perm_const} is valid. 5750@end deftypefn 5751 5752@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_CONVERSION (unsigned @var{code}, tree @var{dest_type}, tree @var{src_type}) 5753This hook should return the DECL of a function that implements conversion of the 5754input vector of type @var{src_type} to type @var{dest_type}. 5755The value of @var{code} is one of the enumerators in @code{enum tree_code} and 5756specifies how the conversion is to be applied 5757(truncation, rounding, etc.). 5758 5759If this hook is defined, the autovectorizer will use the 5760@code{TARGET_VECTORIZE_BUILTIN_CONVERSION} target hook when vectorizing 5761conversion. Otherwise, it will return @code{NULL_TREE}. 5762@end deftypefn 5763 5764@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_VECTORIZED_FUNCTION (tree @var{fndecl}, tree @var{vec_type_out}, tree @var{vec_type_in}) 5765This hook should return the decl of a function that implements the 5766vectorized variant of the builtin function with builtin function code 5767@var{code} or @code{NULL_TREE} if such a function is not available. 5768The value of @var{fndecl} is the builtin function declaration. The 5769return type of the vectorized function shall be of vector type 5770@var{vec_type_out} and the argument types should be @var{vec_type_in}. 5771@end deftypefn 5772 5773@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}) 5774This hook should return true if the target supports misaligned vector 5775store/load of a specific factor denoted in the @var{misalignment} 5776parameter. The vector store/load should be of machine mode @var{mode} and 5777the elements in the vectors should be of type @var{type}. @var{is_packed} 5778parameter is true if the memory access is defined in a packed struct. 5779@end deftypefn 5780 5781@deftypefn {Target Hook} {enum machine_mode} TARGET_VECTORIZE_PREFERRED_SIMD_MODE (enum machine_mode @var{mode}) 5782This hook should return the preferred mode for vectorizing scalar 5783mode @var{mode}. The default is 5784equal to @code{word_mode}, because the vectorizer can do some 5785transformations even in absence of specialized @acronym{SIMD} hardware. 5786@end deftypefn 5787 5788@deftypefn {Target Hook} {unsigned int} TARGET_VECTORIZE_AUTOVECTORIZE_VECTOR_SIZES (void) 5789This hook should return a mask of sizes that should be iterated over 5790after trying to autovectorize using the vector size derived from the 5791mode returned by @code{TARGET_VECTORIZE_PREFERRED_SIMD_MODE}. 5792The default is zero which means to not iterate over other vector sizes. 5793@end deftypefn 5794 5795@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_TM_LOAD (tree) 5796This hook should return the built-in decl needed to load a vector of the given type within a transaction. 5797@end deftypefn 5798 5799@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_TM_STORE (tree) 5800This hook should return the built-in decl needed to store a vector of the given type within a transaction. 5801@end deftypefn 5802 5803@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_GATHER (const_tree @var{mem_vectype}, const_tree @var{index_type}, int @var{scale}) 5804Target builtin that implements vector gather operation. @var{mem_vectype} 5805is the vector type of the load and @var{index_type} is scalar type of 5806the index, scaled by @var{scale}. 5807The default is @code{NULL_TREE} which means to not vectorize gather 5808loads. 5809@end deftypefn 5810 5811@node Anchored Addresses 5812@section Anchored Addresses 5813@cindex anchored addresses 5814@cindex @option{-fsection-anchors} 5815 5816GCC usually addresses every static object as a separate entity. 5817For example, if we have: 5818 5819@smallexample 5820static int a, b, c; 5821int foo (void) @{ return a + b + c; @} 5822@end smallexample 5823 5824the code for @code{foo} will usually calculate three separate symbolic 5825addresses: those of @code{a}, @code{b} and @code{c}. On some targets, 5826it would be better to calculate just one symbolic address and access 5827the three variables relative to it. The equivalent pseudocode would 5828be something like: 5829 5830@smallexample 5831int foo (void) 5832@{ 5833 register int *xr = &x; 5834 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; 5835@} 5836@end smallexample 5837 5838(which isn't valid C). We refer to shared addresses like @code{x} as 5839``section anchors''. Their use is controlled by @option{-fsection-anchors}. 5840 5841The hooks below describe the target properties that GCC needs to know 5842in order to make effective use of section anchors. It won't use 5843section anchors at all unless either @code{TARGET_MIN_ANCHOR_OFFSET} 5844or @code{TARGET_MAX_ANCHOR_OFFSET} is set to a nonzero value. 5845 5846@deftypevr {Target Hook} HOST_WIDE_INT TARGET_MIN_ANCHOR_OFFSET 5847The minimum offset that should be applied to a section anchor. 5848On most targets, it should be the smallest offset that can be 5849applied to a base register while still giving a legitimate address 5850for every mode. The default value is 0. 5851@end deftypevr 5852 5853@deftypevr {Target Hook} HOST_WIDE_INT TARGET_MAX_ANCHOR_OFFSET 5854Like @code{TARGET_MIN_ANCHOR_OFFSET}, but the maximum (inclusive) 5855offset that should be applied to section anchors. The default 5856value is 0. 5857@end deftypevr 5858 5859@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_ANCHOR (rtx @var{x}) 5860Write the assembly code to define section anchor @var{x}, which is a 5861@code{SYMBOL_REF} for which @samp{SYMBOL_REF_ANCHOR_P (@var{x})} is true. 5862The hook is called with the assembly output position set to the beginning 5863of @code{SYMBOL_REF_BLOCK (@var{x})}. 5864 5865If @code{ASM_OUTPUT_DEF} is available, the hook's default definition uses 5866it to define the symbol as @samp{. + SYMBOL_REF_BLOCK_OFFSET (@var{x})}. 5867If @code{ASM_OUTPUT_DEF} is not available, the hook's default definition 5868is @code{NULL}, which disables the use of section anchors altogether. 5869@end deftypefn 5870 5871@deftypefn {Target Hook} bool TARGET_USE_ANCHORS_FOR_SYMBOL_P (const_rtx @var{x}) 5872Return true if GCC should attempt to use anchors to access @code{SYMBOL_REF} 5873@var{x}. You can assume @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})} and 5874@samp{!SYMBOL_REF_ANCHOR_P (@var{x})}. 5875 5876The default version is correct for most targets, but you might need to 5877intercept this hook to handle things like target-specific attributes 5878or target-specific sections. 5879@end deftypefn 5880 5881@node Condition Code 5882@section Condition Code Status 5883@cindex condition code status 5884 5885The macros in this section can be split in two families, according to the 5886two ways of representing condition codes in GCC. 5887 5888The first representation is the so called @code{(cc0)} representation 5889(@pxref{Jump Patterns}), where all instructions can have an implicit 5890clobber of the condition codes. The second is the condition code 5891register representation, which provides better schedulability for 5892architectures that do have a condition code register, but on which 5893most instructions do not affect it. The latter category includes 5894most RISC machines. 5895 5896The implicit clobbering poses a strong restriction on the placement of 5897the definition and use of the condition code, which need to be in adjacent 5898insns for machines using @code{(cc0)}. This can prevent important 5899optimizations on some machines. For example, on the IBM RS/6000, there 5900is a delay for taken branches unless the condition code register is set 5901three instructions earlier than the conditional branch. The instruction 5902scheduler cannot perform this optimization if it is not permitted to 5903separate the definition and use of the condition code register. 5904 5905For this reason, it is possible and suggested to use a register to 5906represent the condition code for new ports. If there is a specific 5907condition code register in the machine, use a hard register. If the 5908condition code or comparison result can be placed in any general register, 5909or if there are multiple condition registers, use a pseudo register. 5910Registers used to store the condition code value will usually have a mode 5911that is in class @code{MODE_CC}. 5912 5913Alternatively, you can use @code{BImode} if the comparison operator is 5914specified already in the compare instruction. In this case, you are not 5915interested in most macros in this section. 5916 5917@menu 5918* CC0 Condition Codes:: Old style representation of condition codes. 5919* MODE_CC Condition Codes:: Modern representation of condition codes. 5920* Cond Exec Macros:: Macros to control conditional execution. 5921@end menu 5922 5923@node CC0 Condition Codes 5924@subsection Representation of condition codes using @code{(cc0)} 5925@findex cc0 5926 5927@findex cc_status 5928The file @file{conditions.h} defines a variable @code{cc_status} to 5929describe how the condition code was computed (in case the interpretation of 5930the condition code depends on the instruction that it was set by). This 5931variable contains the RTL expressions on which the condition code is 5932currently based, and several standard flags. 5933 5934Sometimes additional machine-specific flags must be defined in the machine 5935description header file. It can also add additional machine-specific 5936information by defining @code{CC_STATUS_MDEP}. 5937 5938@defmac CC_STATUS_MDEP 5939C code for a data type which is used for declaring the @code{mdep} 5940component of @code{cc_status}. It defaults to @code{int}. 5941 5942This macro is not used on machines that do not use @code{cc0}. 5943@end defmac 5944 5945@defmac CC_STATUS_MDEP_INIT 5946A C expression to initialize the @code{mdep} field to ``empty''. 5947The default definition does nothing, since most machines don't use 5948the field anyway. If you want to use the field, you should probably 5949define this macro to initialize it. 5950 5951This macro is not used on machines that do not use @code{cc0}. 5952@end defmac 5953 5954@defmac NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 5955A C compound statement to set the components of @code{cc_status} 5956appropriately for an insn @var{insn} whose body is @var{exp}. It is 5957this macro's responsibility to recognize insns that set the condition 5958code as a byproduct of other activity as well as those that explicitly 5959set @code{(cc0)}. 5960 5961This macro is not used on machines that do not use @code{cc0}. 5962 5963If there are insns that do not set the condition code but do alter 5964other machine registers, this macro must check to see whether they 5965invalidate the expressions that the condition code is recorded as 5966reflecting. For example, on the 68000, insns that store in address 5967registers do not set the condition code, which means that usually 5968@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 5969insns. But suppose that the previous insn set the condition code 5970based on location @samp{a4@@(102)} and the current insn stores a new 5971value in @samp{a4}. Although the condition code is not changed by 5972this, it will no longer be true that it reflects the contents of 5973@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 5974@code{cc_status} in this case to say that nothing is known about the 5975condition code value. 5976 5977The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 5978with the results of peephole optimization: insns whose patterns are 5979@code{parallel} RTXs containing various @code{reg}, @code{mem} or 5980constants which are just the operands. The RTL structure of these 5981insns is not sufficient to indicate what the insns actually do. What 5982@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 5983@code{CC_STATUS_INIT}. 5984 5985A possible definition of @code{NOTICE_UPDATE_CC} is to call a function 5986that looks at an attribute (@pxref{Insn Attributes}) named, for example, 5987@samp{cc}. This avoids having detailed information about patterns in 5988two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 5989@end defmac 5990 5991@node MODE_CC Condition Codes 5992@subsection Representation of condition codes using registers 5993@findex CCmode 5994@findex MODE_CC 5995 5996@defmac SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 5997On many machines, the condition code may be produced by other instructions 5998than compares, for example the branch can use directly the condition 5999code set by a subtract instruction. However, on some machines 6000when the condition code is set this way some bits (such as the overflow 6001bit) are not set in the same way as a test instruction, so that a different 6002branch instruction must be used for some conditional branches. When 6003this happens, use the machine mode of the condition code register to 6004record different formats of the condition code register. Modes can 6005also be used to record which compare instruction (e.g. a signed or an 6006unsigned comparison) produced the condition codes. 6007 6008If other modes than @code{CCmode} are required, add them to 6009@file{@var{machine}-modes.def} and define @code{SELECT_CC_MODE} to choose 6010a mode given an operand of a compare. This is needed because the modes 6011have to be chosen not only during RTL generation but also, for example, 6012by instruction combination. The result of @code{SELECT_CC_MODE} should 6013be consistent with the mode used in the patterns; for example to support 6014the case of the add on the SPARC discussed above, we have the pattern 6015 6016@smallexample 6017(define_insn "" 6018 [(set (reg:CC_NOOV 0) 6019 (compare:CC_NOOV 6020 (plus:SI (match_operand:SI 0 "register_operand" "%r") 6021 (match_operand:SI 1 "arith_operand" "rI")) 6022 (const_int 0)))] 6023 "" 6024 "@dots{}") 6025@end smallexample 6026 6027@noindent 6028together with a @code{SELECT_CC_MODE} that returns @code{CC_NOOVmode} 6029for comparisons whose argument is a @code{plus}: 6030 6031@smallexample 6032#define SELECT_CC_MODE(OP,X,Y) \ 6033 (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 6034 ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 6035 : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 6036 || GET_CODE (X) == NEG) \ 6037 ? CC_NOOVmode : CCmode)) 6038@end smallexample 6039 6040Another reason to use modes is to retain information on which operands 6041were used by the comparison; see @code{REVERSIBLE_CC_MODE} later in 6042this section. 6043 6044You should define this macro if and only if you define extra CC modes 6045in @file{@var{machine}-modes.def}. 6046@end defmac 6047 6048@defmac CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 6049On some machines not all possible comparisons are defined, but you can 6050convert an invalid comparison into a valid one. For example, the Alpha 6051does not have a @code{GT} comparison, but you can use an @code{LT} 6052comparison instead and swap the order of the operands. 6053 6054On such machines, define this macro to be a C statement to do any 6055required conversions. @var{code} is the initial comparison code 6056and @var{op0} and @var{op1} are the left and right operands of the 6057comparison, respectively. You should modify @var{code}, @var{op0}, and 6058@var{op1} as required. 6059 6060GCC will not assume that the comparison resulting from this macro is 6061valid but will see if the resulting insn matches a pattern in the 6062@file{md} file. 6063 6064You need not define this macro if it would never change the comparison 6065code or operands. 6066@end defmac 6067 6068@defmac REVERSIBLE_CC_MODE (@var{mode}) 6069A C expression whose value is one if it is always safe to reverse a 6070comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 6071can ever return @var{mode} for a floating-point inequality comparison, 6072then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 6073 6074You need not define this macro if it would always returns zero or if the 6075floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 6076For example, here is the definition used on the SPARC, where floating-point 6077inequality comparisons are always given @code{CCFPEmode}: 6078 6079@smallexample 6080#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 6081@end smallexample 6082@end defmac 6083 6084@defmac REVERSE_CONDITION (@var{code}, @var{mode}) 6085A C expression whose value is reversed condition code of the @var{code} for 6086comparison done in CC_MODE @var{mode}. The macro is used only in case 6087@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 6088machine has some non-standard way how to reverse certain conditionals. For 6089instance in case all floating point conditions are non-trapping, compiler may 6090freely convert unordered compares to ordered one. Then definition may look 6091like: 6092 6093@smallexample 6094#define REVERSE_CONDITION(CODE, MODE) \ 6095 ((MODE) != CCFPmode ? reverse_condition (CODE) \ 6096 : reverse_condition_maybe_unordered (CODE)) 6097@end smallexample 6098@end defmac 6099 6100@deftypefn {Target Hook} bool TARGET_FIXED_CONDITION_CODE_REGS (unsigned int *@var{p1}, unsigned int *@var{p2}) 6101On targets which do not use @code{(cc0)}, and which use a hard 6102register rather than a pseudo-register to hold condition codes, the 6103regular CSE passes are often not able to identify cases in which the 6104hard register is set to a common value. Use this hook to enable a 6105small pass which optimizes such cases. This hook should return true 6106to enable this pass, and it should set the integers to which its 6107arguments point to the hard register numbers used for condition codes. 6108When there is only one such register, as is true on most systems, the 6109integer pointed to by @var{p2} should be set to 6110@code{INVALID_REGNUM}. 6111 6112The default version of this hook returns false. 6113@end deftypefn 6114 6115@deftypefn {Target Hook} {enum machine_mode} TARGET_CC_MODES_COMPATIBLE (enum machine_mode @var{m1}, enum machine_mode @var{m2}) 6116On targets which use multiple condition code modes in class 6117@code{MODE_CC}, it is sometimes the case that a comparison can be 6118validly done in more than one mode. On such a system, define this 6119target hook to take two mode arguments and to return a mode in which 6120both comparisons may be validly done. If there is no such mode, 6121return @code{VOIDmode}. 6122 6123The default version of this hook checks whether the modes are the 6124same. If they are, it returns that mode. If they are different, it 6125returns @code{VOIDmode}. 6126@end deftypefn 6127 6128@node Cond Exec Macros 6129@subsection Macros to control conditional execution 6130@findex conditional execution 6131@findex predication 6132 6133There is one macro that may need to be defined for targets 6134supporting conditional execution, independent of how they 6135represent conditional branches. 6136 6137@defmac REVERSE_CONDEXEC_PREDICATES_P (@var{op1}, @var{op2}) 6138A C expression that returns true if the conditional execution predicate 6139@var{op1}, a comparison operation, is the inverse of @var{op2} and vice 6140versa. Define this to return 0 if the target has conditional execution 6141predicates that cannot be reversed safely. There is no need to validate 6142that the arguments of op1 and op2 are the same, this is done separately. 6143If no expansion is specified, this macro is defined as follows: 6144 6145@smallexample 6146#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 6147 (GET_CODE ((x)) == reversed_comparison_code ((y), NULL)) 6148@end smallexample 6149@end defmac 6150 6151@node Costs 6152@section Describing Relative Costs of Operations 6153@cindex costs of instructions 6154@cindex relative costs 6155@cindex speed of instructions 6156 6157These macros let you describe the relative speed of various operations 6158on the target machine. 6159 6160@defmac REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 6161A C expression for the cost of moving data of mode @var{mode} from a 6162register in class @var{from} to one in class @var{to}. The classes are 6163expressed using the enumeration values such as @code{GENERAL_REGS}. A 6164value of 2 is the default; other values are interpreted relative to 6165that. 6166 6167It is not required that the cost always equal 2 when @var{from} is the 6168same as @var{to}; on some machines it is expensive to move between 6169registers if they are not general registers. 6170 6171If reload sees an insn consisting of a single @code{set} between two 6172hard registers, and if @code{REGISTER_MOVE_COST} applied to their 6173classes returns a value of 2, reload does not check to ensure that the 6174constraints of the insn are met. Setting a cost of other than 2 will 6175allow reload to verify that the constraints are met. You should do this 6176if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 6177 6178These macros are obsolete, new ports should use the target hook 6179@code{TARGET_REGISTER_MOVE_COST} instead. 6180@end defmac 6181 6182@deftypefn {Target Hook} int TARGET_REGISTER_MOVE_COST (enum machine_mode @var{mode}, reg_class_t @var{from}, reg_class_t @var{to}) 6183This target hook should return the cost of moving data of mode @var{mode} 6184from a register in class @var{from} to one in class @var{to}. The classes 6185are expressed using the enumeration values such as @code{GENERAL_REGS}. 6186A value of 2 is the default; other values are interpreted relative to 6187that. 6188 6189It is not required that the cost always equal 2 when @var{from} is the 6190same as @var{to}; on some machines it is expensive to move between 6191registers if they are not general registers. 6192 6193If reload sees an insn consisting of a single @code{set} between two 6194hard registers, and if @code{TARGET_REGISTER_MOVE_COST} applied to their 6195classes returns a value of 2, reload does not check to ensure that the 6196constraints of the insn are met. Setting a cost of other than 2 will 6197allow reload to verify that the constraints are met. You should do this 6198if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 6199 6200The default version of this function returns 2. 6201@end deftypefn 6202 6203@defmac MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 6204A C expression for the cost of moving data of mode @var{mode} between a 6205register of class @var{class} and memory; @var{in} is zero if the value 6206is to be written to memory, nonzero if it is to be read in. This cost 6207is relative to those in @code{REGISTER_MOVE_COST}. If moving between 6208registers and memory is more expensive than between two registers, you 6209should define this macro to express the relative cost. 6210 6211If you do not define this macro, GCC uses a default cost of 4 plus 6212the cost of copying via a secondary reload register, if one is 6213needed. If your machine requires a secondary reload register to copy 6214between memory and a register of @var{class} but the reload mechanism is 6215more complex than copying via an intermediate, define this macro to 6216reflect the actual cost of the move. 6217 6218GCC defines the function @code{memory_move_secondary_cost} if 6219secondary reloads are needed. It computes the costs due to copying via 6220a secondary register. If your machine copies from memory using a 6221secondary register in the conventional way but the default base value of 62224 is not correct for your machine, define this macro to add some other 6223value to the result of that function. The arguments to that function 6224are the same as to this macro. 6225 6226These macros are obsolete, new ports should use the target hook 6227@code{TARGET_MEMORY_MOVE_COST} instead. 6228@end defmac 6229 6230@deftypefn {Target Hook} int TARGET_MEMORY_MOVE_COST (enum machine_mode @var{mode}, reg_class_t @var{rclass}, bool @var{in}) 6231This target hook should return the cost of moving data of mode @var{mode} 6232between a register of class @var{rclass} and memory; @var{in} is @code{false} 6233if the value is to be written to memory, @code{true} if it is to be read in. 6234This cost is relative to those in @code{TARGET_REGISTER_MOVE_COST}. 6235If moving between registers and memory is more expensive than between two 6236registers, you should add this target hook to express the relative cost. 6237 6238If you do not add this target hook, GCC uses a default cost of 4 plus 6239the cost of copying via a secondary reload register, if one is 6240needed. If your machine requires a secondary reload register to copy 6241between memory and a register of @var{rclass} but the reload mechanism is 6242more complex than copying via an intermediate, use this target hook to 6243reflect the actual cost of the move. 6244 6245GCC defines the function @code{memory_move_secondary_cost} if 6246secondary reloads are needed. It computes the costs due to copying via 6247a secondary register. If your machine copies from memory using a 6248secondary register in the conventional way but the default base value of 62494 is not correct for your machine, use this target hook to add some other 6250value to the result of that function. The arguments to that function 6251are the same as to this target hook. 6252@end deftypefn 6253 6254@defmac BRANCH_COST (@var{speed_p}, @var{predictable_p}) 6255A C expression for the cost of a branch instruction. A value of 1 is 6256the default; other values are interpreted relative to that. Parameter 6257@var{speed_p} is true when the branch in question should be optimized 6258for speed. When it is false, @code{BRANCH_COST} should return a value 6259optimal for code size rather than performance. @var{predictable_p} is 6260true for well-predicted branches. On many architectures the 6261@code{BRANCH_COST} can be reduced then. 6262@end defmac 6263 6264Here are additional macros which do not specify precise relative costs, 6265but only that certain actions are more expensive than GCC would 6266ordinarily expect. 6267 6268@defmac SLOW_BYTE_ACCESS 6269Define this macro as a C expression which is nonzero if accessing less 6270than a word of memory (i.e.@: a @code{char} or a @code{short}) is no 6271faster than accessing a word of memory, i.e., if such access 6272require more than one instruction or if there is no difference in cost 6273between byte and (aligned) word loads. 6274 6275When this macro is not defined, the compiler will access a field by 6276finding the smallest containing object; when it is defined, a fullword 6277load will be used if alignment permits. Unless bytes accesses are 6278faster than word accesses, using word accesses is preferable since it 6279may eliminate subsequent memory access if subsequent accesses occur to 6280other fields in the same word of the structure, but to different bytes. 6281@end defmac 6282 6283@defmac SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 6284Define this macro to be the value 1 if memory accesses described by the 6285@var{mode} and @var{alignment} parameters have a cost many times greater 6286than aligned accesses, for example if they are emulated in a trap 6287handler. 6288 6289When this macro is nonzero, the compiler will act as if 6290@code{STRICT_ALIGNMENT} were nonzero when generating code for block 6291moves. This can cause significantly more instructions to be produced. 6292Therefore, do not set this macro nonzero if unaligned accesses only add a 6293cycle or two to the time for a memory access. 6294 6295If the value of this macro is always zero, it need not be defined. If 6296this macro is defined, it should produce a nonzero value when 6297@code{STRICT_ALIGNMENT} is nonzero. 6298@end defmac 6299 6300@defmac MOVE_RATIO (@var{speed}) 6301The threshold of number of scalar memory-to-memory move insns, @emph{below} 6302which a sequence of insns should be generated instead of a 6303string move insn or a library call. Increasing the value will always 6304make code faster, but eventually incurs high cost in increased code size. 6305 6306Note that on machines where the corresponding move insn is a 6307@code{define_expand} that emits a sequence of insns, this macro counts 6308the number of such sequences. 6309 6310The parameter @var{speed} is true if the code is currently being 6311optimized for speed rather than size. 6312 6313If you don't define this, a reasonable default is used. 6314@end defmac 6315 6316@defmac MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 6317A C expression used to determine whether @code{move_by_pieces} will be used to 6318copy a chunk of memory, or whether some other block move mechanism 6319will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6320than @code{MOVE_RATIO}. 6321@end defmac 6322 6323@defmac MOVE_MAX_PIECES 6324A C expression used by @code{move_by_pieces} to determine the largest unit 6325a load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 6326@end defmac 6327 6328@defmac CLEAR_RATIO (@var{speed}) 6329The threshold of number of scalar move insns, @emph{below} which a sequence 6330of insns should be generated to clear memory instead of a string clear insn 6331or a library call. Increasing the value will always make code faster, but 6332eventually incurs high cost in increased code size. 6333 6334The parameter @var{speed} is true if the code is currently being 6335optimized for speed rather than size. 6336 6337If you don't define this, a reasonable default is used. 6338@end defmac 6339 6340@defmac CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) 6341A C expression used to determine whether @code{clear_by_pieces} will be used 6342to clear a chunk of memory, or whether some other block clear mechanism 6343will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6344than @code{CLEAR_RATIO}. 6345@end defmac 6346 6347@defmac SET_RATIO (@var{speed}) 6348The threshold of number of scalar move insns, @emph{below} which a sequence 6349of insns should be generated to set memory to a constant value, instead of 6350a block set insn or a library call. 6351Increasing the value will always make code faster, but 6352eventually incurs high cost in increased code size. 6353 6354The parameter @var{speed} is true if the code is currently being 6355optimized for speed rather than size. 6356 6357If you don't define this, it defaults to the value of @code{MOVE_RATIO}. 6358@end defmac 6359 6360@defmac SET_BY_PIECES_P (@var{size}, @var{alignment}) 6361A C expression used to determine whether @code{store_by_pieces} will be 6362used to set a chunk of memory to a constant value, or whether some 6363other mechanism will be used. Used by @code{__builtin_memset} when 6364storing values other than constant zero. 6365Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6366than @code{SET_RATIO}. 6367@end defmac 6368 6369@defmac STORE_BY_PIECES_P (@var{size}, @var{alignment}) 6370A C expression used to determine whether @code{store_by_pieces} will be 6371used to set a chunk of memory to a constant string value, or whether some 6372other mechanism will be used. Used by @code{__builtin_strcpy} when 6373called with a constant source string. 6374Defaults to 1 if @code{move_by_pieces_ninsns} returns less 6375than @code{MOVE_RATIO}. 6376@end defmac 6377 6378@defmac USE_LOAD_POST_INCREMENT (@var{mode}) 6379A C expression used to determine whether a load postincrement is a good 6380thing to use for a given mode. Defaults to the value of 6381@code{HAVE_POST_INCREMENT}. 6382@end defmac 6383 6384@defmac USE_LOAD_POST_DECREMENT (@var{mode}) 6385A C expression used to determine whether a load postdecrement is a good 6386thing to use for a given mode. Defaults to the value of 6387@code{HAVE_POST_DECREMENT}. 6388@end defmac 6389 6390@defmac USE_LOAD_PRE_INCREMENT (@var{mode}) 6391A C expression used to determine whether a load preincrement is a good 6392thing to use for a given mode. Defaults to the value of 6393@code{HAVE_PRE_INCREMENT}. 6394@end defmac 6395 6396@defmac USE_LOAD_PRE_DECREMENT (@var{mode}) 6397A C expression used to determine whether a load predecrement is a good 6398thing to use for a given mode. Defaults to the value of 6399@code{HAVE_PRE_DECREMENT}. 6400@end defmac 6401 6402@defmac USE_STORE_POST_INCREMENT (@var{mode}) 6403A C expression used to determine whether a store postincrement is a good 6404thing to use for a given mode. Defaults to the value of 6405@code{HAVE_POST_INCREMENT}. 6406@end defmac 6407 6408@defmac USE_STORE_POST_DECREMENT (@var{mode}) 6409A C expression used to determine whether a store postdecrement is a good 6410thing to use for a given mode. Defaults to the value of 6411@code{HAVE_POST_DECREMENT}. 6412@end defmac 6413 6414@defmac USE_STORE_PRE_INCREMENT (@var{mode}) 6415This macro is used to determine whether a store preincrement is a good 6416thing to use for a given mode. Defaults to the value of 6417@code{HAVE_PRE_INCREMENT}. 6418@end defmac 6419 6420@defmac USE_STORE_PRE_DECREMENT (@var{mode}) 6421This macro is used to determine whether a store predecrement is a good 6422thing to use for a given mode. Defaults to the value of 6423@code{HAVE_PRE_DECREMENT}. 6424@end defmac 6425 6426@defmac NO_FUNCTION_CSE 6427Define this macro if it is as good or better to call a constant 6428function address than to call an address kept in a register. 6429@end defmac 6430 6431@defmac RANGE_TEST_NON_SHORT_CIRCUIT 6432Define this macro if a non-short-circuit operation produced by 6433@samp{fold_range_test ()} is optimal. This macro defaults to true if 6434@code{BRANCH_COST} is greater than or equal to the value 2. 6435@end defmac 6436 6437@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}) 6438This target hook describes the relative costs of RTL expressions. 6439 6440The cost may depend on the precise form of the expression, which is 6441available for examination in @var{x}, and the fact that @var{x} appears 6442as operand @var{opno} of an expression with rtx code @var{outer_code}. 6443That is, the hook can assume that there is some rtx @var{y} such 6444that @samp{GET_CODE (@var{y}) == @var{outer_code}} and such that 6445either (a) @samp{XEXP (@var{y}, @var{opno}) == @var{x}} or 6446(b) @samp{XVEC (@var{y}, @var{opno})} contains @var{x}. 6447 6448@var{code} is @var{x}'s expression code---redundant, since it can be 6449obtained with @code{GET_CODE (@var{x})}. 6450 6451In implementing this hook, you can use the construct 6452@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 6453instructions. 6454 6455On entry to the hook, @code{*@var{total}} contains a default estimate 6456for the cost of the expression. The hook should modify this value as 6457necessary. Traditionally, the default costs are @code{COSTS_N_INSNS (5)} 6458for multiplications, @code{COSTS_N_INSNS (7)} for division and modulus 6459operations, and @code{COSTS_N_INSNS (1)} for all other operations. 6460 6461When optimizing for code size, i.e.@: when @code{speed} is 6462false, this target hook should be used to estimate the relative 6463size cost of an expression, again relative to @code{COSTS_N_INSNS}. 6464 6465The hook returns true when all subexpressions of @var{x} have been 6466processed, and false when @code{rtx_cost} should recurse. 6467@end deftypefn 6468 6469@deftypefn {Target Hook} int TARGET_ADDRESS_COST (rtx @var{address}, bool @var{speed}) 6470This hook computes the cost of an addressing mode that contains 6471@var{address}. If not defined, the cost is computed from 6472the @var{address} expression and the @code{TARGET_RTX_COST} hook. 6473 6474For most CISC machines, the default cost is a good approximation of the 6475true cost of the addressing mode. However, on RISC machines, all 6476instructions normally have the same length and execution time. Hence 6477all addresses will have equal costs. 6478 6479In cases where more than one form of an address is known, the form with 6480the lowest cost will be used. If multiple forms have the same, lowest, 6481cost, the one that is the most complex will be used. 6482 6483For example, suppose an address that is equal to the sum of a register 6484and a constant is used twice in the same basic block. When this macro 6485is not defined, the address will be computed in a register and memory 6486references will be indirect through that register. On machines where 6487the cost of the addressing mode containing the sum is no higher than 6488that of a simple indirect reference, this will produce an additional 6489instruction and possibly require an additional register. Proper 6490specification of this macro eliminates this overhead for such machines. 6491 6492This hook is never called with an invalid address. 6493 6494On machines where an address involving more than one register is as 6495cheap as an address computation involving only one register, defining 6496@code{TARGET_ADDRESS_COST} to reflect this can cause two registers to 6497be live over a region of code where only one would have been if 6498@code{TARGET_ADDRESS_COST} were not defined in that manner. This effect 6499should be considered in the definition of this macro. Equivalent costs 6500should probably only be given to addresses with different numbers of 6501registers on machines with lots of registers. 6502@end deftypefn 6503 6504@node Scheduling 6505@section Adjusting the Instruction Scheduler 6506 6507The instruction scheduler may need a fair amount of machine-specific 6508adjustment in order to produce good code. GCC provides several target 6509hooks for this purpose. It is usually enough to define just a few of 6510them: try the first ones in this list first. 6511 6512@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 6513This hook returns the maximum number of instructions that can ever 6514issue at the same time on the target machine. The default is one. 6515Although the insn scheduler can define itself the possibility of issue 6516an insn on the same cycle, the value can serve as an additional 6517constraint to issue insns on the same simulated processor cycle (see 6518hooks @samp{TARGET_SCHED_REORDER} and @samp{TARGET_SCHED_REORDER2}). 6519This value must be constant over the entire compilation. If you need 6520it to vary depending on what the instructions are, you must use 6521@samp{TARGET_SCHED_VARIABLE_ISSUE}. 6522@end deftypefn 6523 6524@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 6525This hook is executed by the scheduler after it has scheduled an insn 6526from the ready list. It should return the number of insns which can 6527still be issued in the current cycle. The default is 6528@samp{@w{@var{more} - 1}} for insns other than @code{CLOBBER} and 6529@code{USE}, which normally are not counted against the issue rate. 6530You should define this hook if some insns take more machine resources 6531than others, so that fewer insns can follow them in the same cycle. 6532@var{file} is either a null pointer, or a stdio stream to write any 6533debug output to. @var{verbose} is the verbose level provided by 6534@option{-fsched-verbose-@var{n}}. @var{insn} is the instruction that 6535was scheduled. 6536@end deftypefn 6537 6538@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 6539This function corrects the value of @var{cost} based on the 6540relationship between @var{insn} and @var{dep_insn} through the 6541dependence @var{link}. It should return the new value. The default 6542is to make no adjustment to @var{cost}. This can be used for example 6543to specify to the scheduler using the traditional pipeline description 6544that an output- or anti-dependence does not incur the same cost as a 6545data-dependence. If the scheduler using the automaton based pipeline 6546description, the cost of anti-dependence is zero and the cost of 6547output-dependence is maximum of one and the difference of latency 6548times of the first and the second insns. If these values are not 6549acceptable, you could use the hook to modify them too. See also 6550@pxref{Processor pipeline description}. 6551@end deftypefn 6552 6553@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 6554This hook adjusts the integer scheduling priority @var{priority} of 6555@var{insn}. It should return the new priority. Increase the priority to 6556execute @var{insn} earlier, reduce the priority to execute @var{insn} 6557later. Do not define this hook if you do not need to adjust the 6558scheduling priorities of insns. 6559@end deftypefn 6560 6561@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 6562This hook is executed by the scheduler after it has scheduled the ready 6563list, to allow the machine description to reorder it (for example to 6564combine two small instructions together on @samp{VLIW} machines). 6565@var{file} is either a null pointer, or a stdio stream to write any 6566debug output to. @var{verbose} is the verbose level provided by 6567@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 6568list of instructions that are ready to be scheduled. @var{n_readyp} is 6569a pointer to the number of elements in the ready list. The scheduler 6570reads the ready list in reverse order, starting with 6571@var{ready}[@var{*n_readyp} @minus{} 1] and going to @var{ready}[0]. @var{clock} 6572is the timer tick of the scheduler. You may modify the ready list and 6573the number of ready insns. The return value is the number of insns that 6574can issue this cycle; normally this is just @code{issue_rate}. See also 6575@samp{TARGET_SCHED_REORDER2}. 6576@end deftypefn 6577 6578@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 6579Like @samp{TARGET_SCHED_REORDER}, but called at a different time. That 6580function is called whenever the scheduler starts a new cycle. This one 6581is called once per iteration over a cycle, immediately after 6582@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 6583return the number of insns to be scheduled in the same cycle. Defining 6584this hook can be useful if there are frequent situations where 6585scheduling one insn causes other insns to become ready in the same 6586cycle. These other insns can then be taken into account properly. 6587@end deftypefn 6588 6589@deftypefn {Target Hook} void TARGET_SCHED_DEPENDENCIES_EVALUATION_HOOK (rtx @var{head}, rtx @var{tail}) 6590This hook is called after evaluation forward dependencies of insns in 6591chain given by two parameter values (@var{head} and @var{tail} 6592correspondingly) but before insns scheduling of the insn chain. For 6593example, it can be used for better insn classification if it requires 6594analysis of dependencies. This hook can use backward and forward 6595dependencies of the insn scheduler because they are already 6596calculated. 6597@end deftypefn 6598 6599@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 6600This hook is executed by the scheduler at the beginning of each block of 6601instructions that are to be scheduled. @var{file} is either a null 6602pointer, or a stdio stream to write any debug output to. @var{verbose} 6603is the verbose level provided by @option{-fsched-verbose-@var{n}}. 6604@var{max_ready} is the maximum number of insns in the current scheduling 6605region that can be live at the same time. This can be used to allocate 6606scratch space if it is needed, e.g.@: by @samp{TARGET_SCHED_REORDER}. 6607@end deftypefn 6608 6609@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 6610This hook is executed by the scheduler at the end of each block of 6611instructions that are to be scheduled. It can be used to perform 6612cleanup of any actions done by the other scheduling hooks. @var{file} 6613is either a null pointer, or a stdio stream to write any debug output 6614to. @var{verbose} is the verbose level provided by 6615@option{-fsched-verbose-@var{n}}. 6616@end deftypefn 6617 6618@deftypefn {Target Hook} void TARGET_SCHED_INIT_GLOBAL (FILE *@var{file}, int @var{verbose}, int @var{old_max_uid}) 6619This hook is executed by the scheduler after function level initializations. 6620@var{file} is either a null pointer, or a stdio stream to write any debug output to. 6621@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 6622@var{old_max_uid} is the maximum insn uid when scheduling begins. 6623@end deftypefn 6624 6625@deftypefn {Target Hook} void TARGET_SCHED_FINISH_GLOBAL (FILE *@var{file}, int @var{verbose}) 6626This is the cleanup hook corresponding to @code{TARGET_SCHED_INIT_GLOBAL}. 6627@var{file} is either a null pointer, or a stdio stream to write any debug output to. 6628@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 6629@end deftypefn 6630 6631@deftypefn {Target Hook} rtx TARGET_SCHED_DFA_PRE_CYCLE_INSN (void) 6632The hook returns an RTL insn. The automaton state used in the 6633pipeline hazard recognizer is changed as if the insn were scheduled 6634when the new simulated processor cycle starts. Usage of the hook may 6635simplify the automaton pipeline description for some @acronym{VLIW} 6636processors. If the hook is defined, it is used only for the automaton 6637based pipeline description. The default is not to change the state 6638when the new simulated processor cycle starts. 6639@end deftypefn 6640 6641@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN (void) 6642The hook can be used to initialize data used by the previous hook. 6643@end deftypefn 6644 6645@deftypefn {Target Hook} rtx TARGET_SCHED_DFA_POST_CYCLE_INSN (void) 6646The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used 6647to changed the state as if the insn were scheduled when the new 6648simulated processor cycle finishes. 6649@end deftypefn 6650 6651@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN (void) 6652The hook is analogous to @samp{TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN} but 6653used to initialize data used by the previous hook. 6654@end deftypefn 6655 6656@deftypefn {Target Hook} void TARGET_SCHED_DFA_PRE_ADVANCE_CYCLE (void) 6657The hook to notify target that the current simulated cycle is about to finish. 6658The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used 6659to change the state in more complicated situations - e.g., when advancing 6660state on a single insn is not enough. 6661@end deftypefn 6662 6663@deftypefn {Target Hook} void TARGET_SCHED_DFA_POST_ADVANCE_CYCLE (void) 6664The hook to notify target that new simulated cycle has just started. 6665The hook is analogous to @samp{TARGET_SCHED_DFA_POST_CYCLE_INSN} but used 6666to change the state in more complicated situations - e.g., when advancing 6667state on a single insn is not enough. 6668@end deftypefn 6669 6670@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD (void) 6671This hook controls better choosing an insn from the ready insn queue 6672for the @acronym{DFA}-based insn scheduler. Usually the scheduler 6673chooses the first insn from the queue. If the hook returns a positive 6674value, an additional scheduler code tries all permutations of 6675@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD ()} 6676subsequent ready insns to choose an insn whose issue will result in 6677maximal number of issued insns on the same cycle. For the 6678@acronym{VLIW} processor, the code could actually solve the problem of 6679packing simple insns into the @acronym{VLIW} insn. Of course, if the 6680rules of @acronym{VLIW} packing are described in the automaton. 6681 6682This code also could be used for superscalar @acronym{RISC} 6683processors. Let us consider a superscalar @acronym{RISC} processor 6684with 3 pipelines. Some insns can be executed in pipelines @var{A} or 6685@var{B}, some insns can be executed only in pipelines @var{B} or 6686@var{C}, and one insn can be executed in pipeline @var{B}. The 6687processor may issue the 1st insn into @var{A} and the 2nd one into 6688@var{B}. In this case, the 3rd insn will wait for freeing @var{B} 6689until the next cycle. If the scheduler issues the 3rd insn the first, 6690the processor could issue all 3 insns per cycle. 6691 6692Actually this code demonstrates advantages of the automaton based 6693pipeline hazard recognizer. We try quickly and easy many insn 6694schedules to choose the best one. 6695 6696The default is no multipass scheduling. 6697@end deftypefn 6698 6699@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD (rtx @var{insn}) 6700 6701This hook controls what insns from the ready insn queue will be 6702considered for the multipass insn scheduling. If the hook returns 6703zero for @var{insn}, the insn will be not chosen to 6704be issued. 6705 6706The default is that any ready insns can be chosen to be issued. 6707@end deftypefn 6708 6709@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}) 6710This hook prepares the target backend for a new round of multipass 6711scheduling. 6712@end deftypefn 6713 6714@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}) 6715This hook is called when multipass scheduling evaluates instruction INSN. 6716@end deftypefn 6717 6718@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_BACKTRACK (const void *@var{data}, char *@var{ready_try}, int @var{n_ready}) 6719This is called when multipass scheduling backtracks from evaluation of 6720an instruction. 6721@end deftypefn 6722 6723@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_END (const void *@var{data}) 6724This hook notifies the target about the result of the concluded current 6725round of multipass scheduling. 6726@end deftypefn 6727 6728@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_INIT (void *@var{data}) 6729This hook initializes target-specific data used in multipass scheduling. 6730@end deftypefn 6731 6732@deftypefn {Target Hook} void TARGET_SCHED_FIRST_CYCLE_MULTIPASS_FINI (void *@var{data}) 6733This hook finalizes target-specific data used in multipass scheduling. 6734@end deftypefn 6735 6736@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}) 6737This hook is called by the insn scheduler before issuing @var{insn} 6738on cycle @var{clock}. If the hook returns nonzero, 6739@var{insn} is not issued on this processor cycle. Instead, 6740the processor cycle is advanced. If *@var{sort_p} 6741is zero, the insn ready queue is not sorted on the new cycle 6742start as usually. @var{dump} and @var{verbose} specify the file and 6743verbosity level to use for debugging output. 6744@var{last_clock} and @var{clock} are, respectively, the 6745processor cycle on which the previous insn has been issued, 6746and the current processor cycle. 6747@end deftypefn 6748 6749@deftypefn {Target Hook} bool TARGET_SCHED_IS_COSTLY_DEPENDENCE (struct _dep *@var{_dep}, int @var{cost}, int @var{distance}) 6750This hook is used to define which dependences are considered costly by 6751the target, so costly that it is not advisable to schedule the insns that 6752are involved in the dependence too close to one another. The parameters 6753to this hook are as follows: The first parameter @var{_dep} is the dependence 6754being evaluated. The second parameter @var{cost} is the cost of the 6755dependence as estimated by the scheduler, and the third 6756parameter @var{distance} is the distance in cycles between the two insns. 6757The hook returns @code{true} if considering the distance between the two 6758insns the dependence between them is considered costly by the target, 6759and @code{false} otherwise. 6760 6761Defining this hook can be useful in multiple-issue out-of-order machines, 6762where (a) it's practically hopeless to predict the actual data/resource 6763delays, however: (b) there's a better chance to predict the actual grouping 6764that will be formed, and (c) correctly emulating the grouping can be very 6765important. In such targets one may want to allow issuing dependent insns 6766closer to one another---i.e., closer than the dependence distance; however, 6767not in cases of ``costly dependences'', which this hooks allows to define. 6768@end deftypefn 6769 6770@deftypefn {Target Hook} void TARGET_SCHED_H_I_D_EXTENDED (void) 6771This hook is called by the insn scheduler after emitting a new instruction to 6772the instruction stream. The hook notifies a target backend to extend its 6773per instruction data structures. 6774@end deftypefn 6775 6776@deftypefn {Target Hook} {void *} TARGET_SCHED_ALLOC_SCHED_CONTEXT (void) 6777Return a pointer to a store large enough to hold target scheduling context. 6778@end deftypefn 6779 6780@deftypefn {Target Hook} void TARGET_SCHED_INIT_SCHED_CONTEXT (void *@var{tc}, bool @var{clean_p}) 6781Initialize store pointed to by @var{tc} to hold target scheduling context. 6782It @var{clean_p} is true then initialize @var{tc} as if scheduler is at the 6783beginning of the block. Otherwise, copy the current context into @var{tc}. 6784@end deftypefn 6785 6786@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_CONTEXT (void *@var{tc}) 6787Copy target scheduling context pointed to by @var{tc} to the current context. 6788@end deftypefn 6789 6790@deftypefn {Target Hook} void TARGET_SCHED_CLEAR_SCHED_CONTEXT (void *@var{tc}) 6791Deallocate internal data in target scheduling context pointed to by @var{tc}. 6792@end deftypefn 6793 6794@deftypefn {Target Hook} void TARGET_SCHED_FREE_SCHED_CONTEXT (void *@var{tc}) 6795Deallocate a store for target scheduling context pointed to by @var{tc}. 6796@end deftypefn 6797 6798@deftypefn {Target Hook} int TARGET_SCHED_SPECULATE_INSN (rtx @var{insn}, int @var{request}, rtx *@var{new_pat}) 6799This hook is called by the insn scheduler when @var{insn} has only 6800speculative dependencies and therefore can be scheduled speculatively. 6801The hook is used to check if the pattern of @var{insn} has a speculative 6802version and, in case of successful check, to generate that speculative 6803pattern. The hook should return 1, if the instruction has a speculative form, 6804or @minus{}1, if it doesn't. @var{request} describes the type of requested 6805speculation. If the return value equals 1 then @var{new_pat} is assigned 6806the generated speculative pattern. 6807@end deftypefn 6808 6809@deftypefn {Target Hook} bool TARGET_SCHED_NEEDS_BLOCK_P (int @var{dep_status}) 6810This hook is called by the insn scheduler during generation of recovery code 6811for @var{insn}. It should return @code{true}, if the corresponding check 6812instruction should branch to recovery code, or @code{false} otherwise. 6813@end deftypefn 6814 6815@deftypefn {Target Hook} rtx TARGET_SCHED_GEN_SPEC_CHECK (rtx @var{insn}, rtx @var{label}, int @var{mutate_p}) 6816This hook is called by the insn scheduler to generate a pattern for recovery 6817check instruction. If @var{mutate_p} is zero, then @var{insn} is a 6818speculative instruction for which the check should be generated. 6819@var{label} is either a label of a basic block, where recovery code should 6820be emitted, or a null pointer, when requested check doesn't branch to 6821recovery code (a simple check). If @var{mutate_p} is nonzero, then 6822a pattern for a branchy check corresponding to a simple check denoted by 6823@var{insn} should be generated. In this case @var{label} can't be null. 6824@end deftypefn 6825 6826@deftypefn {Target Hook} bool TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD_SPEC (const_rtx @var{insn}) 6827This hook is used as a workaround for 6828@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD} not being 6829called on the first instruction of the ready list. The hook is used to 6830discard speculative instructions that stand first in the ready list from 6831being scheduled on the current cycle. If the hook returns @code{false}, 6832@var{insn} will not be chosen to be issued. 6833For non-speculative instructions, 6834the hook should always return @code{true}. For example, in the ia64 backend 6835the hook is used to cancel data speculative insns when the ALAT table 6836is nearly full. 6837@end deftypefn 6838 6839@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_FLAGS (struct spec_info_def *@var{spec_info}) 6840This hook is used by the insn scheduler to find out what features should be 6841enabled/used. 6842The structure *@var{spec_info} should be filled in by the target. 6843The structure describes speculation types that can be used in the scheduler. 6844@end deftypefn 6845 6846@deftypefn {Target Hook} int TARGET_SCHED_SMS_RES_MII (struct ddg *@var{g}) 6847This hook is called by the swing modulo scheduler to calculate a 6848resource-based lower bound which is based on the resources available in 6849the machine and the resources required by each instruction. The target 6850backend can use @var{g} to calculate such bound. A very simple lower 6851bound will be used in case this hook is not implemented: the total number 6852of instructions divided by the issue rate. 6853@end deftypefn 6854 6855@deftypefn {Target Hook} bool TARGET_SCHED_DISPATCH (rtx @var{insn}, int @var{x}) 6856This hook is called by Haifa Scheduler. It returns true if dispatch scheduling 6857is supported in hardware and the condition specified in the parameter is true. 6858@end deftypefn 6859 6860@deftypefn {Target Hook} void TARGET_SCHED_DISPATCH_DO (rtx @var{insn}, int @var{x}) 6861This hook is called by Haifa Scheduler. It performs the operation specified 6862in its second parameter. 6863@end deftypefn 6864 6865@deftypevr {Target Hook} bool TARGET_SCHED_EXPOSED_PIPELINE 6866True if the processor has an exposed pipeline, which means that not just 6867the order of instructions is important for correctness when scheduling, but 6868also the latencies of operations. 6869@end deftypevr 6870 6871@deftypefn {Target Hook} int TARGET_SCHED_REASSOCIATION_WIDTH (unsigned int @var{opc}, enum machine_mode @var{mode}) 6872This hook is called by tree reassociator to determine a level of 6873parallelism required in output calculations chain. 6874@end deftypefn 6875 6876@node Sections 6877@section Dividing the Output into Sections (Texts, Data, @dots{}) 6878@c the above section title is WAY too long. maybe cut the part between 6879@c the (...)? --mew 10feb93 6880 6881An object file is divided into sections containing different types of 6882data. In the most common case, there are three sections: the @dfn{text 6883section}, which holds instructions and read-only data; the @dfn{data 6884section}, which holds initialized writable data; and the @dfn{bss 6885section}, which holds uninitialized data. Some systems have other kinds 6886of sections. 6887 6888@file{varasm.c} provides several well-known sections, such as 6889@code{text_section}, @code{data_section} and @code{bss_section}. 6890The normal way of controlling a @code{@var{foo}_section} variable 6891is to define the associated @code{@var{FOO}_SECTION_ASM_OP} macro, 6892as described below. The macros are only read once, when @file{varasm.c} 6893initializes itself, so their values must be run-time constants. 6894They may however depend on command-line flags. 6895 6896@emph{Note:} Some run-time files, such @file{crtstuff.c}, also make 6897use of the @code{@var{FOO}_SECTION_ASM_OP} macros, and expect them 6898to be string literals. 6899 6900Some assemblers require a different string to be written every time a 6901section is selected. If your assembler falls into this category, you 6902should define the @code{TARGET_ASM_INIT_SECTIONS} hook and use 6903@code{get_unnamed_section} to set up the sections. 6904 6905You must always create a @code{text_section}, either by defining 6906@code{TEXT_SECTION_ASM_OP} or by initializing @code{text_section} 6907in @code{TARGET_ASM_INIT_SECTIONS}. The same is true of 6908@code{data_section} and @code{DATA_SECTION_ASM_OP}. If you do not 6909create a distinct @code{readonly_data_section}, the default is to 6910reuse @code{text_section}. 6911 6912All the other @file{varasm.c} sections are optional, and are null 6913if the target does not provide them. 6914 6915@defmac TEXT_SECTION_ASM_OP 6916A C expression whose value is a string, including spacing, containing the 6917assembler operation that should precede instructions and read-only data. 6918Normally @code{"\t.text"} is right. 6919@end defmac 6920 6921@defmac HOT_TEXT_SECTION_NAME 6922If defined, a C string constant for the name of the section containing most 6923frequently executed functions of the program. If not defined, GCC will provide 6924a default definition if the target supports named sections. 6925@end defmac 6926 6927@defmac UNLIKELY_EXECUTED_TEXT_SECTION_NAME 6928If defined, a C string constant for the name of the section containing unlikely 6929executed functions in the program. 6930@end defmac 6931 6932@defmac DATA_SECTION_ASM_OP 6933A C expression whose value is a string, including spacing, containing the 6934assembler operation to identify the following data as writable initialized 6935data. Normally @code{"\t.data"} is right. 6936@end defmac 6937 6938@defmac SDATA_SECTION_ASM_OP 6939If defined, a C expression whose value is a string, including spacing, 6940containing the assembler operation to identify the following data as 6941initialized, writable small data. 6942@end defmac 6943 6944@defmac READONLY_DATA_SECTION_ASM_OP 6945A C expression whose value is a string, including spacing, containing the 6946assembler operation to identify the following data as read-only initialized 6947data. 6948@end defmac 6949 6950@defmac BSS_SECTION_ASM_OP 6951If defined, a C expression whose value is a string, including spacing, 6952containing the assembler operation to identify the following data as 6953uninitialized global data. If not defined, and 6954@code{ASM_OUTPUT_ALIGNED_BSS} not defined, 6955uninitialized global data will be output in the data section if 6956@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 6957used. 6958@end defmac 6959 6960@defmac SBSS_SECTION_ASM_OP 6961If defined, a C expression whose value is a string, including spacing, 6962containing the assembler operation to identify the following data as 6963uninitialized, writable small data. 6964@end defmac 6965 6966@defmac TLS_COMMON_ASM_OP 6967If defined, a C expression whose value is a string containing the 6968assembler operation to identify the following data as thread-local 6969common data. The default is @code{".tls_common"}. 6970@end defmac 6971 6972@defmac TLS_SECTION_ASM_FLAG 6973If defined, a C expression whose value is a character constant 6974containing the flag used to mark a section as a TLS section. The 6975default is @code{'T'}. 6976@end defmac 6977 6978@defmac INIT_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 6981initialization code. If not defined, GCC will assume such a section does 6982not exist. This section has no corresponding @code{init_section} 6983variable; it is used entirely in runtime code. 6984@end defmac 6985 6986@defmac FINI_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 6989finalization code. If not defined, GCC will assume such a section does 6990not exist. This section has no corresponding @code{fini_section} 6991variable; it is used entirely in runtime code. 6992@end defmac 6993 6994@defmac INIT_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{.init_array} (or equivalent) section. If not 6998defined, GCC will assume such a section does not exist. Do not define 6999both this macro and @code{INIT_SECTION_ASM_OP}. 7000@end defmac 7001 7002@defmac FINI_ARRAY_SECTION_ASM_OP 7003If defined, a C expression whose value is a string, including spacing, 7004containing the assembler operation to identify the following data as 7005part of the @code{.fini_array} (or equivalent) section. If not 7006defined, GCC will assume such a section does not exist. Do not define 7007both this macro and @code{FINI_SECTION_ASM_OP}. 7008@end defmac 7009 7010@defmac CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 7011If defined, an ASM statement that switches to a different section 7012via @var{section_op}, calls @var{function}, and switches back to 7013the text section. This is used in @file{crtstuff.c} if 7014@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 7015to initialization and finalization functions from the init and fini 7016sections. By default, this macro uses a simple function call. Some 7017ports need hand-crafted assembly code to avoid dependencies on 7018registers initialized in the function prologue or to ensure that 7019constant pools don't end up too far way in the text section. 7020@end defmac 7021 7022@defmac TARGET_LIBGCC_SDATA_SECTION 7023If defined, a string which names the section into which small 7024variables defined in crtstuff and libgcc should go. This is useful 7025when the target has options for optimizing access to small data, and 7026you want the crtstuff and libgcc routines to be conservative in what 7027they expect of your application yet liberal in what your application 7028expects. For example, for targets with a @code{.sdata} section (like 7029MIPS), you could compile crtstuff with @code{-G 0} so that it doesn't 7030require small data support from your application, but use this macro 7031to put small data into @code{.sdata} so that your application can 7032access these variables whether it uses small data or not. 7033@end defmac 7034 7035@defmac FORCE_CODE_SECTION_ALIGN 7036If defined, an ASM statement that aligns a code section to some 7037arbitrary boundary. This is used to force all fragments of the 7038@code{.init} and @code{.fini} sections to have to same alignment 7039and thus prevent the linker from having to add any padding. 7040@end defmac 7041 7042@defmac JUMP_TABLES_IN_TEXT_SECTION 7043Define this macro to be an expression with a nonzero value if jump 7044tables (for @code{tablejump} insns) should be output in the text 7045section, along with the assembler instructions. Otherwise, the 7046readonly data section is used. 7047 7048This macro is irrelevant if there is no separate readonly data section. 7049@end defmac 7050 7051@deftypefn {Target Hook} void TARGET_ASM_INIT_SECTIONS (void) 7052Define this hook if you need to do something special to set up the 7053@file{varasm.c} sections, or if your target has some special sections 7054of its own that you need to create. 7055 7056GCC calls this hook after processing the command line, but before writing 7057any assembly code, and before calling any of the section-returning hooks 7058described below. 7059@end deftypefn 7060 7061@deftypefn {Target Hook} int TARGET_ASM_RELOC_RW_MASK (void) 7062Return a mask describing how relocations should be treated when 7063selecting sections. Bit 1 should be set if global relocations 7064should be placed in a read-write section; bit 0 should be set if 7065local relocations should be placed in a read-write section. 7066 7067The default version of this function returns 3 when @option{-fpic} 7068is in effect, and 0 otherwise. The hook is typically redefined 7069when the target cannot support (some kinds of) dynamic relocations 7070in read-only sections even in executables. 7071@end deftypefn 7072 7073@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align}) 7074Return the section into which @var{exp} should be placed. You can 7075assume that @var{exp} is either a @code{VAR_DECL} node or a constant of 7076some sort. @var{reloc} indicates whether the initial value of @var{exp} 7077requires link-time relocations. Bit 0 is set when variable contains 7078local relocations only, while bit 1 is set for global relocations. 7079@var{align} is the constant alignment in bits. 7080 7081The default version of this function takes care of putting read-only 7082variables in @code{readonly_data_section}. 7083 7084See also @var{USE_SELECT_SECTION_FOR_FUNCTIONS}. 7085@end deftypefn 7086 7087@defmac USE_SELECT_SECTION_FOR_FUNCTIONS 7088Define this macro if you wish TARGET_ASM_SELECT_SECTION to be called 7089for @code{FUNCTION_DECL}s as well as for variables and constants. 7090 7091In the case of a @code{FUNCTION_DECL}, @var{reloc} will be zero if the 7092function has been determined to be likely to be called, and nonzero if 7093it is unlikely to be called. 7094@end defmac 7095 7096@deftypefn {Target Hook} void TARGET_ASM_UNIQUE_SECTION (tree @var{decl}, int @var{reloc}) 7097Build up a unique section name, expressed as a @code{STRING_CST} node, 7098and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 7099As with @code{TARGET_ASM_SELECT_SECTION}, @var{reloc} indicates whether 7100the initial value of @var{exp} requires link-time relocations. 7101 7102The default version of this function appends the symbol name to the 7103ELF section name that would normally be used for the symbol. For 7104example, the function @code{foo} would be placed in @code{.text.foo}. 7105Whatever the actual target object format, this is often good enough. 7106@end deftypefn 7107 7108@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_RODATA_SECTION (tree @var{decl}) 7109Return the readonly data section associated with 7110@samp{DECL_SECTION_NAME (@var{decl})}. 7111The default version of this function selects @code{.gnu.linkonce.r.name} if 7112the function's section is @code{.gnu.linkonce.t.name}, @code{.rodata.name} 7113if function is in @code{.text.name}, and the normal readonly-data section 7114otherwise. 7115@end deftypefn 7116 7117@deftypevr {Target Hook} {const char *} TARGET_ASM_MERGEABLE_RODATA_PREFIX 7118Usually, the compiler uses the prefix @code{".rodata"} to construct 7119section names for mergeable constant data. Define this macro to override 7120the string if a different section name should be used. 7121@end deftypevr 7122 7123@deftypefn {Target Hook} {section *} TARGET_ASM_TM_CLONE_TABLE_SECTION (void) 7124Return the section that should be used for transactional memory clone tables. 7125@end deftypefn 7126 7127@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_RTX_SECTION (enum machine_mode @var{mode}, rtx @var{x}, unsigned HOST_WIDE_INT @var{align}) 7128Return the section into which a constant @var{x}, of mode @var{mode}, 7129should be placed. You can assume that @var{x} is some kind of 7130constant in RTL@. The argument @var{mode} is redundant except in the 7131case of a @code{const_int} rtx. @var{align} is the constant alignment 7132in bits. 7133 7134The default version of this function takes care of putting symbolic 7135constants in @code{flag_pic} mode in @code{data_section} and everything 7136else in @code{readonly_data_section}. 7137@end deftypefn 7138 7139@deftypefn {Target Hook} tree TARGET_MANGLE_DECL_ASSEMBLER_NAME (tree @var{decl}, tree @var{id}) 7140Define this hook if you need to postprocess the assembler name generated 7141by target-independent code. The @var{id} provided to this hook will be 7142the computed name (e.g., the macro @code{DECL_NAME} of the @var{decl} in C, 7143or the mangled name of the @var{decl} in C++). The return value of the 7144hook is an @code{IDENTIFIER_NODE} for the appropriate mangled name on 7145your target system. The default implementation of this hook just 7146returns the @var{id} provided. 7147@end deftypefn 7148 7149@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, rtx @var{rtl}, int @var{new_decl_p}) 7150Define this hook if references to a symbol or a constant must be 7151treated differently depending on something about the variable or 7152function named by the symbol (such as what section it is in). 7153 7154The hook is executed immediately after rtl has been created for 7155@var{decl}, which may be a variable or function declaration or 7156an entry in the constant pool. In either case, @var{rtl} is the 7157rtl in question. Do @emph{not} use @code{DECL_RTL (@var{decl})} 7158in this hook; that field may not have been initialized yet. 7159 7160In the case of a constant, it is safe to assume that the rtl is 7161a @code{mem} whose address is a @code{symbol_ref}. Most decls 7162will also have this form, but that is not guaranteed. Global 7163register variables, for instance, will have a @code{reg} for their 7164rtl. (Normally the right thing to do with such unusual rtl is 7165leave it alone.) 7166 7167The @var{new_decl_p} argument will be true if this is the first time 7168that @code{TARGET_ENCODE_SECTION_INFO} has been invoked on this decl. It will 7169be false for subsequent invocations, which will happen for duplicate 7170declarations. Whether or not anything must be done for the duplicate 7171declaration depends on whether the hook examines @code{DECL_ATTRIBUTES}. 7172@var{new_decl_p} is always true when the hook is called for a constant. 7173 7174@cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO} 7175The usual thing for this hook to do is to record flags in the 7176@code{symbol_ref}, using @code{SYMBOL_REF_FLAG} or @code{SYMBOL_REF_FLAGS}. 7177Historically, the name string was modified if it was necessary to 7178encode more than one bit of information, but this practice is now 7179discouraged; use @code{SYMBOL_REF_FLAGS}. 7180 7181The default definition of this hook, @code{default_encode_section_info} 7182in @file{varasm.c}, sets a number of commonly-useful bits in 7183@code{SYMBOL_REF_FLAGS}. Check whether the default does what you need 7184before overriding it. 7185@end deftypefn 7186 7187@deftypefn {Target Hook} {const char *} TARGET_STRIP_NAME_ENCODING (const char *@var{name}) 7188Decode @var{name} and return the real name part, sans 7189the characters that @code{TARGET_ENCODE_SECTION_INFO} 7190may have added. 7191@end deftypefn 7192 7193@deftypefn {Target Hook} bool TARGET_IN_SMALL_DATA_P (const_tree @var{exp}) 7194Returns true if @var{exp} should be placed into a ``small data'' section. 7195The default version of this hook always returns false. 7196@end deftypefn 7197 7198@deftypevr {Target Hook} bool TARGET_HAVE_SRODATA_SECTION 7199Contains the value true if the target places read-only 7200``small data'' into a separate section. The default value is false. 7201@end deftypevr 7202 7203@deftypefn {Target Hook} bool TARGET_PROFILE_BEFORE_PROLOGUE (void) 7204It returns true if target wants profile code emitted before prologue. 7205 7206The default version of this hook use the target macro 7207@code{PROFILE_BEFORE_PROLOGUE}. 7208@end deftypefn 7209 7210@deftypefn {Target Hook} bool TARGET_BINDS_LOCAL_P (const_tree @var{exp}) 7211Returns true if @var{exp} names an object for which name resolution 7212rules must resolve to the current ``module'' (dynamic shared library 7213or executable image). 7214 7215The default version of this hook implements the name resolution rules 7216for ELF, which has a looser model of global name binding than other 7217currently supported object file formats. 7218@end deftypefn 7219 7220@deftypevr {Target Hook} bool TARGET_HAVE_TLS 7221Contains the value true if the target supports thread-local storage. 7222The default value is false. 7223@end deftypevr 7224 7225 7226@node PIC 7227@section Position Independent Code 7228@cindex position independent code 7229@cindex PIC 7230 7231This section describes macros that help implement generation of position 7232independent code. Simply defining these macros is not enough to 7233generate valid PIC; you must also add support to the hook 7234@code{TARGET_LEGITIMATE_ADDRESS_P} and to the macro 7235@code{PRINT_OPERAND_ADDRESS}, as well as @code{LEGITIMIZE_ADDRESS}. You 7236must modify the definition of @samp{movsi} to do something appropriate 7237when the source operand contains a symbolic address. You may also 7238need to alter the handling of switch statements so that they use 7239relative addresses. 7240@c i rearranged the order of the macros above to try to force one of 7241@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 7242 7243@defmac PIC_OFFSET_TABLE_REGNUM 7244The register number of the register used to address a table of static 7245data addresses in memory. In some cases this register is defined by a 7246processor's ``application binary interface'' (ABI)@. When this macro 7247is defined, RTL is generated for this register once, as with the stack 7248pointer and frame pointer registers. If this macro is not defined, it 7249is up to the machine-dependent files to allocate such a register (if 7250necessary). Note that this register must be fixed when in use (e.g.@: 7251when @code{flag_pic} is true). 7252@end defmac 7253 7254@defmac PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 7255A C expression that is nonzero if the register defined by 7256@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. If not defined, 7257the default is zero. Do not define 7258this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 7259@end defmac 7260 7261@defmac LEGITIMATE_PIC_OPERAND_P (@var{x}) 7262A C expression that is nonzero if @var{x} is a legitimate immediate 7263operand on the target machine when generating position independent code. 7264You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 7265check this. You can also assume @var{flag_pic} is true, so you need not 7266check it either. You need not define this macro if all constants 7267(including @code{SYMBOL_REF}) can be immediate operands when generating 7268position independent code. 7269@end defmac 7270 7271@node Assembler Format 7272@section Defining the Output Assembler Language 7273 7274This section describes macros whose principal purpose is to describe how 7275to write instructions in assembler language---rather than what the 7276instructions do. 7277 7278@menu 7279* File Framework:: Structural information for the assembler file. 7280* Data Output:: Output of constants (numbers, strings, addresses). 7281* Uninitialized Data:: Output of uninitialized variables. 7282* Label Output:: Output and generation of labels. 7283* Initialization:: General principles of initialization 7284 and termination routines. 7285* Macros for Initialization:: 7286 Specific macros that control the handling of 7287 initialization and termination routines. 7288* Instruction Output:: Output of actual instructions. 7289* Dispatch Tables:: Output of jump tables. 7290* Exception Region Output:: Output of exception region code. 7291* Alignment Output:: Pseudo ops for alignment and skipping data. 7292@end menu 7293 7294@node File Framework 7295@subsection The Overall Framework of an Assembler File 7296@cindex assembler format 7297@cindex output of assembler code 7298 7299@c prevent bad page break with this line 7300This describes the overall framework of an assembly file. 7301 7302@findex default_file_start 7303@deftypefn {Target Hook} void TARGET_ASM_FILE_START (void) 7304Output to @code{asm_out_file} any text which the assembler expects to 7305find at the beginning of a file. The default behavior is controlled 7306by two flags, documented below. Unless your target's assembler is 7307quite unusual, if you override the default, you should call 7308@code{default_file_start} at some point in your target hook. This 7309lets other target files rely on these variables. 7310@end deftypefn 7311 7312@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_APP_OFF 7313If this flag is true, the text of the macro @code{ASM_APP_OFF} will be 7314printed as the very first line in the assembly file, unless 7315@option{-fverbose-asm} is in effect. (If that macro has been defined 7316to the empty string, this variable has no effect.) With the normal 7317definition of @code{ASM_APP_OFF}, the effect is to notify the GNU 7318assembler that it need not bother stripping comments or extra 7319whitespace from its input. This allows it to work a bit faster. 7320 7321The default is false. You should not set it to true unless you have 7322verified that your port does not generate any extra whitespace or 7323comments that will cause GAS to issue errors in NO_APP mode. 7324@end deftypevr 7325 7326@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_FILE_DIRECTIVE 7327If this flag is true, @code{output_file_directive} will be called 7328for the primary source file, immediately after printing 7329@code{ASM_APP_OFF} (if that is enabled). Most ELF assemblers expect 7330this to be done. The default is false. 7331@end deftypevr 7332 7333@deftypefn {Target Hook} void TARGET_ASM_FILE_END (void) 7334Output to @code{asm_out_file} any text which the assembler expects 7335to find at the end of a file. The default is to output nothing. 7336@end deftypefn 7337 7338@deftypefun void file_end_indicate_exec_stack () 7339Some systems use a common convention, the @samp{.note.GNU-stack} 7340special section, to indicate whether or not an object file relies on 7341the stack being executable. If your system uses this convention, you 7342should define @code{TARGET_ASM_FILE_END} to this function. If you 7343need to do other things in that hook, have your hook function call 7344this function. 7345@end deftypefun 7346 7347@deftypefn {Target Hook} void TARGET_ASM_LTO_START (void) 7348Output to @code{asm_out_file} any text which the assembler expects 7349to find at the start of an LTO section. The default is to output 7350nothing. 7351@end deftypefn 7352 7353@deftypefn {Target Hook} void TARGET_ASM_LTO_END (void) 7354Output to @code{asm_out_file} any text which the assembler expects 7355to find at the end of an LTO section. The default is to output 7356nothing. 7357@end deftypefn 7358 7359@deftypefn {Target Hook} void TARGET_ASM_CODE_END (void) 7360Output to @code{asm_out_file} any text which is needed before emitting 7361unwind info and debug info at the end of a file. Some targets emit 7362here PIC setup thunks that cannot be emitted at the end of file, 7363because they couldn't have unwind info then. The default is to output 7364nothing. 7365@end deftypefn 7366 7367@defmac ASM_COMMENT_START 7368A C string constant describing how to begin a comment in the target 7369assembler language. The compiler assumes that the comment will end at 7370the end of the line. 7371@end defmac 7372 7373@defmac ASM_APP_ON 7374A C string constant for text to be output before each @code{asm} 7375statement or group of consecutive ones. Normally this is 7376@code{"#APP"}, which is a comment that has no effect on most 7377assemblers but tells the GNU assembler that it must check the lines 7378that follow for all valid assembler constructs. 7379@end defmac 7380 7381@defmac ASM_APP_OFF 7382A C string constant for text to be output after each @code{asm} 7383statement or group of consecutive ones. Normally this is 7384@code{"#NO_APP"}, which tells the GNU assembler to resume making the 7385time-saving assumptions that are valid for ordinary compiler output. 7386@end defmac 7387 7388@defmac ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 7389A C statement to output COFF information or DWARF debugging information 7390which indicates that filename @var{name} is the current source file to 7391the stdio stream @var{stream}. 7392 7393This macro need not be defined if the standard form of output 7394for the file format in use is appropriate. 7395@end defmac 7396 7397@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_SOURCE_FILENAME (FILE *@var{file}, const char *@var{name}) 7398Output COFF information or DWARF debugging information which indicates that filename @var{name} is the current source file to the stdio stream @var{file}. 7399 7400 This target hook need not be defined if the standard form of output for the file format in use is appropriate. 7401@end deftypefn 7402 7403@defmac OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 7404A C statement to output the string @var{string} to the stdio stream 7405@var{stream}. If you do not call the function @code{output_quoted_string} 7406in your config files, GCC will only call it to output filenames to 7407the assembler source. So you can use it to canonicalize the format 7408of the filename using this macro. 7409@end defmac 7410 7411@defmac ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 7412A C statement to output something to the assembler file to handle a 7413@samp{#ident} directive containing the text @var{string}. If this 7414macro is not defined, nothing is output for a @samp{#ident} directive. 7415@end defmac 7416 7417@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, tree @var{decl}) 7418Output assembly directives to switch to section @var{name}. The section 7419should have attributes as specified by @var{flags}, which is a bit mask 7420of the @code{SECTION_*} flags defined in @file{output.h}. If @var{decl} 7421is non-NULL, it is the @code{VAR_DECL} or @code{FUNCTION_DECL} with which 7422this section is associated. 7423@end deftypefn 7424 7425@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_SECTION (tree @var{decl}, enum node_frequency @var{freq}, bool @var{startup}, bool @var{exit}) 7426Return preferred text (sub)section for function @var{decl}. 7427Main purpose of this function is to separate cold, normal and hot 7428functions. @var{startup} is true when function is known to be used only 7429at startup (from static constructors or it is @code{main()}). 7430@var{exit} is true when function is known to be used only at exit 7431(from static destructors). 7432Return NULL if function should go to default text section. 7433@end deftypefn 7434 7435@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_SWITCHED_TEXT_SECTIONS (FILE *@var{file}, tree @var{decl}, bool @var{new_is_cold}) 7436Used 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}. 7437@end deftypefn 7438 7439@deftypevr {Common Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 7440This flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 7441It must not be modified by command-line option processing. 7442@end deftypevr 7443 7444@anchor{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS} 7445@deftypevr {Target Hook} bool TARGET_HAVE_SWITCHABLE_BSS_SECTIONS 7446This flag is true if we can create zeroed data by switching to a BSS 7447section and then using @code{ASM_OUTPUT_SKIP} to allocate the space. 7448This is true on most ELF targets. 7449@end deftypevr 7450 7451@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 7452Choose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 7453based on a variable or function decl, a section name, and whether or not the 7454declaration's initializer may contain runtime relocations. @var{decl} may be 7455null, in which case read-write data should be assumed. 7456 7457The default version of this function handles choosing code vs data, 7458read-only vs read-write data, and @code{flag_pic}. You should only 7459need to override this if your target has special flags that might be 7460set via @code{__attribute__}. 7461@end deftypefn 7462 7463@deftypefn {Target Hook} int TARGET_ASM_RECORD_GCC_SWITCHES (print_switch_type @var{type}, const char *@var{text}) 7464Provides the target with the ability to record the gcc command line 7465switches that have been passed to the compiler, and options that are 7466enabled. The @var{type} argument specifies what is being recorded. 7467It can take the following values: 7468 7469@table @gcctabopt 7470@item SWITCH_TYPE_PASSED 7471@var{text} is a command line switch that has been set by the user. 7472 7473@item SWITCH_TYPE_ENABLED 7474@var{text} is an option which has been enabled. This might be as a 7475direct result of a command line switch, or because it is enabled by 7476default or because it has been enabled as a side effect of a different 7477command line switch. For example, the @option{-O2} switch enables 7478various different individual optimization passes. 7479 7480@item SWITCH_TYPE_DESCRIPTIVE 7481@var{text} is either NULL or some descriptive text which should be 7482ignored. If @var{text} is NULL then it is being used to warn the 7483target hook that either recording is starting or ending. The first 7484time @var{type} is SWITCH_TYPE_DESCRIPTIVE and @var{text} is NULL, the 7485warning is for start up and the second time the warning is for 7486wind down. This feature is to allow the target hook to make any 7487necessary preparations before it starts to record switches and to 7488perform any necessary tidying up after it has finished recording 7489switches. 7490 7491@item SWITCH_TYPE_LINE_START 7492This option can be ignored by this target hook. 7493 7494@item SWITCH_TYPE_LINE_END 7495This option can be ignored by this target hook. 7496@end table 7497 7498The hook's return value must be zero. Other return values may be 7499supported in the future. 7500 7501By default this hook is set to NULL, but an example implementation is 7502provided for ELF based targets. Called @var{elf_record_gcc_switches}, 7503it records the switches as ASCII text inside a new, string mergeable 7504section in the assembler output file. The name of the new section is 7505provided by the @code{TARGET_ASM_RECORD_GCC_SWITCHES_SECTION} target 7506hook. 7507@end deftypefn 7508 7509@deftypevr {Target Hook} {const char *} TARGET_ASM_RECORD_GCC_SWITCHES_SECTION 7510This is the name of the section that will be created by the example 7511ELF implementation of the @code{TARGET_ASM_RECORD_GCC_SWITCHES} target 7512hook. 7513@end deftypevr 7514 7515@need 2000 7516@node Data Output 7517@subsection Output of Data 7518 7519 7520@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 7521@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 7522@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 7523@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 7524@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 7525@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 7526@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 7527@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 7528@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 7529These hooks specify assembly directives for creating certain kinds 7530of integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 7531byte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 7532aligned two-byte object, and so on. Any of the hooks may be 7533@code{NULL}, indicating that no suitable directive is available. 7534 7535The compiler will print these strings at the start of a new line, 7536followed immediately by the object's initial value. In most cases, 7537the string should contain a tab, a pseudo-op, and then another tab. 7538@end deftypevr 7539 7540@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 7541The @code{assemble_integer} function uses this hook to output an 7542integer object. @var{x} is the object's value, @var{size} is its size 7543in bytes and @var{aligned_p} indicates whether it is aligned. The 7544function should return @code{true} if it was able to output the 7545object. If it returns false, @code{assemble_integer} will try to 7546split the object into smaller parts. 7547 7548The default implementation of this hook will use the 7549@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 7550when the relevant string is @code{NULL}. 7551@end deftypefn 7552 7553@deftypefn {Target Hook} bool TARGET_ASM_OUTPUT_ADDR_CONST_EXTRA (FILE *@var{file}, rtx @var{x}) 7554A target hook to recognize @var{rtx} patterns that @code{output_addr_const} 7555can't deal with, and output assembly code to @var{file} corresponding to 7556the pattern @var{x}. This may be used to allow machine-dependent 7557@code{UNSPEC}s to appear within constants. 7558 7559If target hook fails to recognize a pattern, it must return @code{false}, 7560so that a standard error message is printed. If it prints an error message 7561itself, by calling, for example, @code{output_operand_lossage}, it may just 7562return @code{true}. 7563@end deftypefn 7564 7565@defmac ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 7566A C statement to output to the stdio stream @var{stream} an assembler 7567instruction to assemble a string constant containing the @var{len} 7568bytes at @var{ptr}. @var{ptr} will be a C expression of type 7569@code{char *} and @var{len} a C expression of type @code{int}. 7570 7571If the assembler has a @code{.ascii} pseudo-op as found in the 7572Berkeley Unix assembler, do not define the macro 7573@code{ASM_OUTPUT_ASCII}. 7574@end defmac 7575 7576@defmac ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 7577A C statement to output word @var{n} of a function descriptor for 7578@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 7579is defined, and is otherwise unused. 7580@end defmac 7581 7582@defmac CONSTANT_POOL_BEFORE_FUNCTION 7583You may define this macro as a C expression. You should define the 7584expression to have a nonzero value if GCC should output the constant 7585pool for a function before the code for the function, or a zero value if 7586GCC should output the constant pool after the function. If you do 7587not define this macro, the usual case, GCC will output the constant 7588pool before the function. 7589@end defmac 7590 7591@defmac ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 7592A C statement to output assembler commands to define the start of the 7593constant pool for a function. @var{funname} is a string giving 7594the name of the function. Should the return type of the function 7595be required, it can be obtained via @var{fundecl}. @var{size} 7596is the size, in bytes, of the constant pool that will be written 7597immediately after this call. 7598 7599If no constant-pool prefix is required, the usual case, this macro need 7600not be defined. 7601@end defmac 7602 7603@defmac ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 7604A C statement (with or without semicolon) to output a constant in the 7605constant pool, if it needs special treatment. (This macro need not do 7606anything for RTL expressions that can be output normally.) 7607 7608The argument @var{file} is the standard I/O stream to output the 7609assembler code on. @var{x} is the RTL expression for the constant to 7610output, and @var{mode} is the machine mode (in case @var{x} is a 7611@samp{const_int}). @var{align} is the required alignment for the value 7612@var{x}; you should output an assembler directive to force this much 7613alignment. 7614 7615The argument @var{labelno} is a number to use in an internal label for 7616the address of this pool entry. The definition of this macro is 7617responsible for outputting the label definition at the proper place. 7618Here is how to do this: 7619 7620@smallexample 7621@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno}); 7622@end smallexample 7623 7624When you output a pool entry specially, you should end with a 7625@code{goto} to the label @var{jumpto}. This will prevent the same pool 7626entry from being output a second time in the usual manner. 7627 7628You need not define this macro if it would do nothing. 7629@end defmac 7630 7631@defmac ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 7632A C statement to output assembler commands to at the end of the constant 7633pool for a function. @var{funname} is a string giving the name of the 7634function. Should the return type of the function be required, you can 7635obtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 7636constant pool that GCC wrote immediately before this call. 7637 7638If no constant-pool epilogue is required, the usual case, you need not 7639define this macro. 7640@end defmac 7641 7642@defmac IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}, @var{STR}) 7643Define this macro as a C expression which is nonzero if @var{C} is 7644used as a logical line separator by the assembler. @var{STR} points 7645to the position in the string where @var{C} was found; this can be used if 7646a line separator uses multiple characters. 7647 7648If you do not define this macro, the default is that only 7649the character @samp{;} is treated as a logical line separator. 7650@end defmac 7651 7652@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 7653@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 7654These target hooks are C string constants, describing the syntax in the 7655assembler for grouping arithmetic expressions. If not overridden, they 7656default to normal parentheses, which is correct for most assemblers. 7657@end deftypevr 7658 7659These macros are provided by @file{real.h} for writing the definitions 7660of @code{ASM_OUTPUT_DOUBLE} and the like: 7661 7662@defmac REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 7663@defmacx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 7664@defmacx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 7665@defmacx REAL_VALUE_TO_TARGET_DECIMAL32 (@var{x}, @var{l}) 7666@defmacx REAL_VALUE_TO_TARGET_DECIMAL64 (@var{x}, @var{l}) 7667@defmacx REAL_VALUE_TO_TARGET_DECIMAL128 (@var{x}, @var{l}) 7668These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the 7669target's floating point representation, and store its bit pattern in 7670the variable @var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE} and 7671@code{REAL_VALUE_TO_TARGET_DECIMAL32}, this variable should be a 7672simple @code{long int}. For the others, it should be an array of 7673@code{long int}. The number of elements in this array is determined 7674by the size of the desired target floating point data type: 32 bits of 7675it go in each @code{long int} array element. Each array element holds 767632 bits of the result, even if @code{long int} is wider than 32 bits 7677on the host machine. 7678 7679The array element values are designed so that you can print them out 7680using @code{fprintf} in the order they should appear in the target 7681machine's memory. 7682@end defmac 7683 7684@node Uninitialized Data 7685@subsection Output of Uninitialized Variables 7686 7687Each of the macros in this section is used to do the whole job of 7688outputting a single uninitialized variable. 7689 7690@defmac ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 7691A C statement (sans semicolon) to output to the stdio stream 7692@var{stream} the assembler definition of a common-label named 7693@var{name} whose size is @var{size} bytes. The variable @var{rounded} 7694is the size rounded up to whatever alignment the caller wants. It is 7695possible that @var{size} may be zero, for instance if a struct with no 7696other member than a zero-length array is defined. In this case, the 7697backend must output a symbol definition that allocates at least one 7698byte, both so that the address of the resulting object does not compare 7699equal to any other, and because some object formats cannot even express 7700the concept of a zero-sized common symbol, as that is how they represent 7701an ordinary undefined external. 7702 7703Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7704output the name itself; before and after that, output the additional 7705assembler syntax for defining the name, and a newline. 7706 7707This macro controls how the assembler definitions of uninitialized 7708common global variables are output. 7709@end defmac 7710 7711@defmac ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 7712Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 7713separate, explicit argument. If you define this macro, it is used in 7714place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 7715handling the required alignment of the variable. The alignment is specified 7716as the number of bits. 7717@end defmac 7718 7719@defmac ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 7720Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 7721variable to be output, if there is one, or @code{NULL_TREE} if there 7722is no corresponding variable. If you define this macro, GCC will use it 7723in place of both @code{ASM_OUTPUT_COMMON} and 7724@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 7725the variable's decl in order to chose what to output. 7726@end defmac 7727 7728@defmac ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 7729A C statement (sans semicolon) to output to the stdio stream 7730@var{stream} the assembler definition of uninitialized global @var{decl} named 7731@var{name} whose size is @var{size} bytes. The variable @var{alignment} 7732is the alignment specified as the number of bits. 7733 7734Try to use function @code{asm_output_aligned_bss} defined in file 7735@file{varasm.c} when defining this macro. If unable, use the expression 7736@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 7737before and after that, output the additional assembler syntax for defining 7738the name, and a newline. 7739 7740There are two ways of handling global BSS@. One is to define this macro. 7741The other is to have @code{TARGET_ASM_SELECT_SECTION} return a 7742switchable BSS section (@pxref{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}). 7743You do not need to do both. 7744 7745Some languages do not have @code{common} data, and require a 7746non-common form of global BSS in order to handle uninitialized globals 7747efficiently. C++ is one example of this. However, if the target does 7748not support global BSS, the front end may choose to make globals 7749common in order to save space in the object file. 7750@end defmac 7751 7752@defmac ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 7753A C statement (sans semicolon) to output to the stdio stream 7754@var{stream} the assembler definition of a local-common-label named 7755@var{name} whose size is @var{size} bytes. The variable @var{rounded} 7756is the size rounded up to whatever alignment the caller wants. 7757 7758Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7759output the name itself; before and after that, output the additional 7760assembler syntax for defining the name, and a newline. 7761 7762This macro controls how the assembler definitions of uninitialized 7763static variables are output. 7764@end defmac 7765 7766@defmac ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 7767Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 7768separate, explicit argument. If you define this macro, it is used in 7769place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 7770handling the required alignment of the variable. The alignment is specified 7771as the number of bits. 7772@end defmac 7773 7774@defmac ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 7775Like @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 7776variable to be output, if there is one, or @code{NULL_TREE} if there 7777is no corresponding variable. If you define this macro, GCC will use it 7778in place of both @code{ASM_OUTPUT_DECL} and 7779@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 7780the variable's decl in order to chose what to output. 7781@end defmac 7782 7783@node Label Output 7784@subsection Output and Generation of Labels 7785 7786@c prevent bad page break with this line 7787This is about outputting labels. 7788 7789@findex assemble_name 7790@defmac ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 7791A C statement (sans semicolon) to output to the stdio stream 7792@var{stream} the assembler definition of a label named @var{name}. 7793Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7794output the name itself; before and after that, output the additional 7795assembler syntax for defining the name, and a newline. A default 7796definition of this macro is provided which is correct for most systems. 7797@end defmac 7798 7799@defmac ASM_OUTPUT_FUNCTION_LABEL (@var{stream}, @var{name}, @var{decl}) 7800A C statement (sans semicolon) to output to the stdio stream 7801@var{stream} the assembler definition of a label named @var{name} of 7802a function. 7803Use the expression @code{assemble_name (@var{stream}, @var{name})} to 7804output the name itself; before and after that, output the additional 7805assembler syntax for defining the name, and a newline. A default 7806definition of this macro is provided which is correct for most systems. 7807 7808If this macro is not defined, then the function name is defined in the 7809usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 7810@end defmac 7811 7812@findex assemble_name_raw 7813@defmac ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{name}) 7814Identical to @code{ASM_OUTPUT_LABEL}, except that @var{name} is known 7815to refer to a compiler-generated label. The default definition uses 7816@code{assemble_name_raw}, which is like @code{assemble_name} except 7817that it is more efficient. 7818@end defmac 7819 7820@defmac SIZE_ASM_OP 7821A C string containing the appropriate assembler directive to specify the 7822size of a symbol, without any arguments. On systems that use ELF, the 7823default (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other 7824systems, the default is not to define this macro. 7825 7826Define this macro only if it is correct to use the default definitions 7827of @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE} 7828for your system. If you need your own custom definitions of those 7829macros, or if you do not need explicit symbol sizes at all, do not 7830define this macro. 7831@end defmac 7832 7833@defmac ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) 7834A C statement (sans semicolon) to output to the stdio stream 7835@var{stream} a directive telling the assembler that the size of the 7836symbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}. 7837If you define @code{SIZE_ASM_OP}, a default definition of this macro is 7838provided. 7839@end defmac 7840 7841@defmac ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) 7842A C statement (sans semicolon) to output to the stdio stream 7843@var{stream} a directive telling the assembler to calculate the size of 7844the symbol @var{name} by subtracting its address from the current 7845address. 7846 7847If you define @code{SIZE_ASM_OP}, a default definition of this macro is 7848provided. The default assumes that the assembler recognizes a special 7849@samp{.} symbol as referring to the current address, and can calculate 7850the difference between this and another symbol. If your assembler does 7851not recognize @samp{.} or cannot do calculations with it, you will need 7852to redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique. 7853@end defmac 7854 7855@defmac TYPE_ASM_OP 7856A C string containing the appropriate assembler directive to specify the 7857type of a symbol, without any arguments. On systems that use ELF, the 7858default (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other 7859systems, the default is not to define this macro. 7860 7861Define this macro only if it is correct to use the default definition of 7862@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 7863custom definition of this macro, or if you do not need explicit symbol 7864types at all, do not define this macro. 7865@end defmac 7866 7867@defmac TYPE_OPERAND_FMT 7868A C string which specifies (using @code{printf} syntax) the format of 7869the second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the 7870default (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems, 7871the default is not to define this macro. 7872 7873Define this macro only if it is correct to use the default definition of 7874@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 7875custom definition of this macro, or if you do not need explicit symbol 7876types at all, do not define this macro. 7877@end defmac 7878 7879@defmac ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) 7880A C statement (sans semicolon) to output to the stdio stream 7881@var{stream} a directive telling the assembler that the type of the 7882symbol @var{name} is @var{type}. @var{type} is a C string; currently, 7883that string is always either @samp{"function"} or @samp{"object"}, but 7884you should not count on this. 7885 7886If you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default 7887definition of this macro is provided. 7888@end defmac 7889 7890@defmac ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 7891A C statement (sans semicolon) to output to the stdio stream 7892@var{stream} any text necessary for declaring the name @var{name} of a 7893function which is being defined. This macro is responsible for 7894outputting the label definition (perhaps using 7895@code{ASM_OUTPUT_FUNCTION_LABEL}). The argument @var{decl} is the 7896@code{FUNCTION_DECL} tree node representing the function. 7897 7898If this macro is not defined, then the function name is defined in the 7899usual manner as a label (by means of @code{ASM_OUTPUT_FUNCTION_LABEL}). 7900 7901You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 7902of this macro. 7903@end defmac 7904 7905@defmac ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 7906A C statement (sans semicolon) to output to the stdio stream 7907@var{stream} any text necessary for declaring the size of a function 7908which is being defined. The argument @var{name} is the name of the 7909function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 7910representing the function. 7911 7912If this macro is not defined, then the function size is not defined. 7913 7914You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition 7915of this macro. 7916@end defmac 7917 7918@defmac ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 7919A C statement (sans semicolon) to output to the stdio stream 7920@var{stream} any text necessary for declaring the name @var{name} of an 7921initialized variable which is being defined. This macro must output the 7922label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 7923@var{decl} is the @code{VAR_DECL} tree node representing the variable. 7924 7925If this macro is not defined, then the variable name is defined in the 7926usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 7927 7928You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or 7929@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro. 7930@end defmac 7931 7932@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}) 7933A target hook to output to the stdio stream @var{file} any text necessary 7934for declaring the name @var{name} of a constant which is being defined. This 7935target hook is responsible for outputting the label definition (perhaps using 7936@code{assemble_label}). The argument @var{exp} is the value of the constant, 7937and @var{size} is the size of the constant in bytes. The @var{name} 7938will be an internal label. 7939 7940The default version of this target hook, define the @var{name} in the 7941usual manner as a label (by means of @code{assemble_label}). 7942 7943You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in this target hook. 7944@end deftypefn 7945 7946@defmac ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 7947A C statement (sans semicolon) to output to the stdio stream 7948@var{stream} any text necessary for claiming a register @var{regno} 7949for a global variable @var{decl} with name @var{name}. 7950 7951If you don't define this macro, that is equivalent to defining it to do 7952nothing. 7953@end defmac 7954 7955@defmac ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 7956A C statement (sans semicolon) to finish up declaring a variable name 7957once the compiler has processed its initializer fully and thus has had a 7958chance to determine the size of an array when controlled by an 7959initializer. This is used on systems where it's necessary to declare 7960something about the size of the object. 7961 7962If you don't define this macro, that is equivalent to defining it to do 7963nothing. 7964 7965You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or 7966@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. 7967@end defmac 7968 7969@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) 7970This target hook is a function to output to the stdio stream 7971@var{stream} some commands that will make the label @var{name} global; 7972that is, available for reference from other files. 7973 7974The default implementation relies on a proper definition of 7975@code{GLOBAL_ASM_OP}. 7976@end deftypefn 7977 7978@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_DECL_NAME (FILE *@var{stream}, tree @var{decl}) 7979This target hook is a function to output to the stdio stream 7980@var{stream} some commands that will make the name associated with @var{decl} 7981global; that is, available for reference from other files. 7982 7983The default implementation uses the TARGET_ASM_GLOBALIZE_LABEL target hook. 7984@end deftypefn 7985 7986@defmac ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 7987A C statement (sans semicolon) to output to the stdio stream 7988@var{stream} some commands that will make the label @var{name} weak; 7989that is, available for reference from other files but only used if 7990no other definition is available. Use the expression 7991@code{assemble_name (@var{stream}, @var{name})} to output the name 7992itself; before and after that, output the additional assembler syntax 7993for making that name weak, and a newline. 7994 7995If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 7996support weak symbols and you should not define the @code{SUPPORTS_WEAK} 7997macro. 7998@end defmac 7999 8000@defmac ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 8001Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 8002@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 8003or variable decl. If @var{value} is not @code{NULL}, this C statement 8004should output to the stdio stream @var{stream} assembler code which 8005defines (equates) the weak symbol @var{name} to have the value 8006@var{value}. If @var{value} is @code{NULL}, it should output commands 8007to make @var{name} weak. 8008@end defmac 8009 8010@defmac ASM_OUTPUT_WEAKREF (@var{stream}, @var{decl}, @var{name}, @var{value}) 8011Outputs a directive that enables @var{name} to be used to refer to 8012symbol @var{value} with weak-symbol semantics. @code{decl} is the 8013declaration of @code{name}. 8014@end defmac 8015 8016@defmac SUPPORTS_WEAK 8017A preprocessor constant expression which evaluates to true if the target 8018supports weak symbols. 8019 8020If you don't define this macro, @file{defaults.h} provides a default 8021definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 8022is defined, the default definition is @samp{1}; otherwise, it is @samp{0}. 8023@end defmac 8024 8025@defmac TARGET_SUPPORTS_WEAK 8026A C expression which evaluates to true if the target supports weak symbols. 8027 8028If you don't define this macro, @file{defaults.h} provides a default 8029definition. The default definition is @samp{(SUPPORTS_WEAK)}. Define 8030this macro if you want to control weak symbol support with a compiler 8031flag such as @option{-melf}. 8032@end defmac 8033 8034@defmac MAKE_DECL_ONE_ONLY (@var{decl}) 8035A C statement (sans semicolon) to mark @var{decl} to be emitted as a 8036public symbol such that extra copies in multiple translation units will 8037be discarded by the linker. Define this macro if your object file 8038format provides support for this concept, such as the @samp{COMDAT} 8039section flags in the Microsoft Windows PE/COFF format, and this support 8040requires changes to @var{decl}, such as putting it in a separate section. 8041@end defmac 8042 8043@defmac SUPPORTS_ONE_ONLY 8044A C expression which evaluates to true if the target supports one-only 8045semantics. 8046 8047If you don't define this macro, @file{varasm.c} provides a default 8048definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 8049definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 8050you want to control one-only symbol support with a compiler flag, or if 8051setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 8052be emitted as one-only. 8053@end defmac 8054 8055@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, int @var{visibility}) 8056This target hook is a function to output to @var{asm_out_file} some 8057commands that will make the symbol(s) associated with @var{decl} have 8058hidden, protected or internal visibility as specified by @var{visibility}. 8059@end deftypefn 8060 8061@defmac TARGET_WEAK_NOT_IN_ARCHIVE_TOC 8062A C expression that evaluates to true if the target's linker expects 8063that weak symbols do not appear in a static archive's table of contents. 8064The default is @code{0}. 8065 8066Leaving weak symbols out of an archive's table of contents means that, 8067if a symbol will only have a definition in one translation unit and 8068will have undefined references from other translation units, that 8069symbol should not be weak. Defining this macro to be nonzero will 8070thus have the effect that certain symbols that would normally be weak 8071(explicit template instantiations, and vtables for polymorphic classes 8072with noninline key methods) will instead be nonweak. 8073 8074The C++ ABI requires this macro to be zero. Define this macro for 8075targets where full C++ ABI compliance is impossible and where linker 8076restrictions require weak symbols to be left out of a static archive's 8077table of contents. 8078@end defmac 8079 8080@defmac ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 8081A C statement (sans semicolon) to output to the stdio stream 8082@var{stream} any text necessary for declaring the name of an external 8083symbol named @var{name} which is referenced in this compilation but 8084not defined. The value of @var{decl} is the tree node for the 8085declaration. 8086 8087This macro need not be defined if it does not need to output anything. 8088The GNU assembler and most Unix assemblers don't require anything. 8089@end defmac 8090 8091@deftypefn {Target Hook} void TARGET_ASM_EXTERNAL_LIBCALL (rtx @var{symref}) 8092This target hook is a function to output to @var{asm_out_file} an assembler 8093pseudo-op to declare a library function name external. The name of the 8094library function is given by @var{symref}, which is a @code{symbol_ref}. 8095@end deftypefn 8096 8097@deftypefn {Target Hook} void TARGET_ASM_MARK_DECL_PRESERVED (const char *@var{symbol}) 8098This target hook is a function to output to @var{asm_out_file} an assembler 8099directive to annotate @var{symbol} as used. The Darwin target uses the 8100.no_dead_code_strip directive. 8101@end deftypefn 8102 8103@defmac ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 8104A C statement (sans semicolon) to output to the stdio stream 8105@var{stream} a reference in assembler syntax to a label named 8106@var{name}. This should add @samp{_} to the front of the name, if that 8107is customary on your operating system, as it is in most Berkeley Unix 8108systems. This macro is used in @code{assemble_name}. 8109@end defmac 8110 8111@deftypefn {Target Hook} tree TARGET_MANGLE_ASSEMBLER_NAME (const char *@var{name}) 8112Given 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. 8113@end deftypefn 8114 8115@defmac ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 8116A C statement (sans semicolon) to output a reference to 8117@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 8118will be used to output the name of the symbol. This macro may be used 8119to modify the way a symbol is referenced depending on information 8120encoded by @code{TARGET_ENCODE_SECTION_INFO}. 8121@end defmac 8122 8123@defmac ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 8124A C statement (sans semicolon) to output a reference to @var{buf}, the 8125result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, 8126@code{assemble_name} will be used to output the name of the symbol. 8127This macro is not used by @code{output_asm_label}, or the @code{%l} 8128specifier that calls it; the intention is that this macro should be set 8129when it is necessary to output a label differently when its address is 8130being taken. 8131@end defmac 8132 8133@deftypefn {Target Hook} void TARGET_ASM_INTERNAL_LABEL (FILE *@var{stream}, const char *@var{prefix}, unsigned long @var{labelno}) 8134A function to output to the stdio stream @var{stream} a label whose 8135name is made from the string @var{prefix} and the number @var{labelno}. 8136 8137It is absolutely essential that these labels be distinct from the labels 8138used for user-level functions and variables. Otherwise, certain programs 8139will have name conflicts with internal labels. 8140 8141It is desirable to exclude internal labels from the symbol table of the 8142object file. Most assemblers have a naming convention for labels that 8143should be excluded; on many systems, the letter @samp{L} at the 8144beginning of a label has this effect. You should find out what 8145convention your system uses, and follow it. 8146 8147The default version of this function utilizes @code{ASM_GENERATE_INTERNAL_LABEL}. 8148@end deftypefn 8149 8150@defmac ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 8151A C statement to output to the stdio stream @var{stream} a debug info 8152label whose name is made from the string @var{prefix} and the number 8153@var{num}. This is useful for VLIW targets, where debug info labels 8154may need to be treated differently than branch target labels. On some 8155systems, branch target labels must be at the beginning of instruction 8156bundles, but debug info labels can occur in the middle of instruction 8157bundles. 8158 8159If this macro is not defined, then @code{(*targetm.asm_out.internal_label)} will be 8160used. 8161@end defmac 8162 8163@defmac ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 8164A C statement to store into the string @var{string} a label whose name 8165is made from the string @var{prefix} and the number @var{num}. 8166 8167This string, when output subsequently by @code{assemble_name}, should 8168produce the output that @code{(*targetm.asm_out.internal_label)} would produce 8169with the same @var{prefix} and @var{num}. 8170 8171If the string begins with @samp{*}, then @code{assemble_name} will 8172output the rest of the string unchanged. It is often convenient for 8173@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 8174string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 8175to output the string, and may change it. (Of course, 8176@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 8177you should know what it does on your machine.) 8178@end defmac 8179 8180@defmac ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 8181A C expression to assign to @var{outvar} (which is a variable of type 8182@code{char *}) a newly allocated string made from the string 8183@var{name} and the number @var{number}, with some suitable punctuation 8184added. Use @code{alloca} to get space for the string. 8185 8186The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 8187produce an assembler label for an internal static variable whose name is 8188@var{name}. Therefore, the string must be such as to result in valid 8189assembler code. The argument @var{number} is different each time this 8190macro is executed; it prevents conflicts between similarly-named 8191internal static variables in different scopes. 8192 8193Ideally this string should not be a valid C identifier, to prevent any 8194conflict with the user's own symbols. Most assemblers allow periods 8195or percent signs in assembler symbols; putting at least one of these 8196between the name and the number will suffice. 8197 8198If this macro is not defined, a default definition will be provided 8199which is correct for most systems. 8200@end defmac 8201 8202@defmac ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 8203A C statement to output to the stdio stream @var{stream} assembler code 8204which defines (equates) the symbol @var{name} to have the value @var{value}. 8205 8206@findex SET_ASM_OP 8207If @code{SET_ASM_OP} is defined, a default definition is provided which is 8208correct for most systems. 8209@end defmac 8210 8211@defmac ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 8212A C statement to output to the stdio stream @var{stream} assembler code 8213which defines (equates) the symbol whose tree node is @var{decl_of_name} 8214to have the value of the tree node @var{decl_of_value}. This macro will 8215be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 8216the tree nodes are available. 8217 8218@findex SET_ASM_OP 8219If @code{SET_ASM_OP} is defined, a default definition is provided which is 8220correct for most systems. 8221@end defmac 8222 8223@defmac TARGET_DEFERRED_OUTPUT_DEFS (@var{decl_of_name}, @var{decl_of_value}) 8224A C statement that evaluates to true if the assembler code which defines 8225(equates) the symbol whose tree node is @var{decl_of_name} to have the value 8226of the tree node @var{decl_of_value} should be emitted near the end of the 8227current compilation unit. The default is to not defer output of defines. 8228This macro affects defines output by @samp{ASM_OUTPUT_DEF} and 8229@samp{ASM_OUTPUT_DEF_FROM_DECLS}. 8230@end defmac 8231 8232@defmac ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 8233A C statement to output to the stdio stream @var{stream} assembler code 8234which defines (equates) the weak symbol @var{name} to have the value 8235@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 8236an undefined weak symbol. 8237 8238Define this macro if the target only supports weak aliases; define 8239@code{ASM_OUTPUT_DEF} instead if possible. 8240@end defmac 8241 8242@defmac OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 8243Define this macro to override the default assembler names used for 8244Objective-C methods. 8245 8246The default name is a unique method number followed by the name of the 8247class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 8248the category is also included in the assembler name (e.g.@: 8249@samp{_1_Foo_Bar}). 8250 8251These names are safe on most systems, but make debugging difficult since 8252the method's selector is not present in the name. Therefore, particular 8253systems define other ways of computing names. 8254 8255@var{buf} is an expression of type @code{char *} which gives you a 8256buffer in which to store the name; its length is as long as 8257@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 825850 characters extra. 8259 8260The argument @var{is_inst} specifies whether the method is an instance 8261method or a class method; @var{class_name} is the name of the class; 8262@var{cat_name} is the name of the category (or @code{NULL} if the method is not 8263in a category); and @var{sel_name} is the name of the selector. 8264 8265On systems where the assembler can handle quoted names, you can use this 8266macro to provide more human-readable names. 8267@end defmac 8268 8269@node Initialization 8270@subsection How Initialization Functions Are Handled 8271@cindex initialization routines 8272@cindex termination routines 8273@cindex constructors, output of 8274@cindex destructors, output of 8275 8276The compiled code for certain languages includes @dfn{constructors} 8277(also called @dfn{initialization routines})---functions to initialize 8278data in the program when the program is started. These functions need 8279to be called before the program is ``started''---that is to say, before 8280@code{main} is called. 8281 8282Compiling some languages generates @dfn{destructors} (also called 8283@dfn{termination routines}) that should be called when the program 8284terminates. 8285 8286To make the initialization and termination functions work, the compiler 8287must output something in the assembler code to cause those functions to 8288be called at the appropriate time. When you port the compiler to a new 8289system, you need to specify how to do this. 8290 8291There are two major ways that GCC currently supports the execution of 8292initialization and termination functions. Each way has two variants. 8293Much of the structure is common to all four variations. 8294 8295@findex __CTOR_LIST__ 8296@findex __DTOR_LIST__ 8297The linker must build two lists of these functions---a list of 8298initialization functions, called @code{__CTOR_LIST__}, and a list of 8299termination functions, called @code{__DTOR_LIST__}. 8300 8301Each list always begins with an ignored function pointer (which may hold 83020, @minus{}1, or a count of the function pointers after it, depending on 8303the environment). This is followed by a series of zero or more function 8304pointers to constructors (or destructors), followed by a function 8305pointer containing zero. 8306 8307Depending on the operating system and its executable file format, either 8308@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 8309time and exit time. Constructors are called in reverse order of the 8310list; destructors in forward order. 8311 8312The best way to handle static constructors works only for object file 8313formats which provide arbitrarily-named sections. A section is set 8314aside for a list of constructors, and another for a list of destructors. 8315Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each 8316object file that defines an initialization function also puts a word in 8317the constructor section to point to that function. The linker 8318accumulates all these words into one contiguous @samp{.ctors} section. 8319Termination functions are handled similarly. 8320 8321This method will be chosen as the default by @file{target-def.h} if 8322@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 8323support arbitrary sections, but does support special designated 8324constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 8325and @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 8326 8327When arbitrary sections are available, there are two variants, depending 8328upon how the code in @file{crtstuff.c} is called. On systems that 8329support a @dfn{.init} section which is executed at program startup, 8330parts of @file{crtstuff.c} are compiled into that section. The 8331program is linked by the @command{gcc} driver like this: 8332 8333@smallexample 8334ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 8335@end smallexample 8336 8337The prologue of a function (@code{__init}) appears in the @code{.init} 8338section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 8339for the function @code{__fini} in the @dfn{.fini} section. Normally these 8340files are provided by the operating system or by the GNU C library, but 8341are provided by GCC for a few targets. 8342 8343The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 8344compiled from @file{crtstuff.c}. They contain, among other things, code 8345fragments within the @code{.init} and @code{.fini} sections that branch 8346to routines in the @code{.text} section. The linker will pull all parts 8347of a section together, which results in a complete @code{__init} function 8348that invokes the routines we need at startup. 8349 8350To use this variant, you must define the @code{INIT_SECTION_ASM_OP} 8351macro properly. 8352 8353If no init section is available, when GCC compiles any function called 8354@code{main} (or more accurately, any function designated as a program 8355entry point by the language front end calling @code{expand_main_function}), 8356it inserts a procedure call to @code{__main} as the first executable code 8357after the function prologue. The @code{__main} function is defined 8358in @file{libgcc2.c} and runs the global constructors. 8359 8360In file formats that don't support arbitrary sections, there are again 8361two variants. In the simplest variant, the GNU linker (GNU @code{ld}) 8362and an `a.out' format must be used. In this case, 8363@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 8364entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 8365and with the address of the void function containing the initialization 8366code as its value. The GNU linker recognizes this as a request to add 8367the value to a @dfn{set}; the values are accumulated, and are eventually 8368placed in the executable as a vector in the format described above, with 8369a leading (ignored) count and a trailing zero element. 8370@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 8371section is available, the absence of @code{INIT_SECTION_ASM_OP} causes 8372the compilation of @code{main} to call @code{__main} as above, starting 8373the initialization process. 8374 8375The last variant uses neither arbitrary sections nor the GNU linker. 8376This is preferable when you want to do dynamic linking and when using 8377file formats which the GNU linker does not support, such as `ECOFF'@. In 8378this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 8379termination functions are recognized simply by their names. This requires 8380an extra program in the linkage step, called @command{collect2}. This program 8381pretends to be the linker, for use with GCC; it does its job by running 8382the ordinary linker, but also arranges to include the vectors of 8383initialization and termination functions. These functions are called 8384via @code{__main} as described above. In order to use this method, 8385@code{use_collect2} must be defined in the target in @file{config.gcc}. 8386 8387@ifinfo 8388The following section describes the specific macros that control and 8389customize the handling of initialization and termination functions. 8390@end ifinfo 8391 8392@node Macros for Initialization 8393@subsection Macros Controlling Initialization Routines 8394 8395Here are the macros that control how the compiler handles initialization 8396and termination functions: 8397 8398@defmac INIT_SECTION_ASM_OP 8399If defined, a C string constant, including spacing, for the assembler 8400operation to identify the following data as initialization code. If not 8401defined, GCC will assume such a section does not exist. When you are 8402using special sections for initialization and termination functions, this 8403macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 8404run the initialization functions. 8405@end defmac 8406 8407@defmac HAS_INIT_SECTION 8408If defined, @code{main} will not call @code{__main} as described above. 8409This macro should be defined for systems that control start-up code 8410on a symbol-by-symbol basis, such as OSF/1, and should not 8411be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 8412@end defmac 8413 8414@defmac LD_INIT_SWITCH 8415If defined, a C string constant for a switch that tells the linker that 8416the following symbol is an initialization routine. 8417@end defmac 8418 8419@defmac LD_FINI_SWITCH 8420If defined, a C string constant for a switch that tells the linker that 8421the following symbol is a finalization routine. 8422@end defmac 8423 8424@defmac COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 8425If defined, a C statement that will write a function that can be 8426automatically called when a shared library is loaded. The function 8427should call @var{func}, which takes no arguments. If not defined, and 8428the object format requires an explicit initialization function, then a 8429function called @code{_GLOBAL__DI} will be generated. 8430 8431This function and the following one are used by collect2 when linking a 8432shared library that needs constructors or destructors, or has DWARF2 8433exception tables embedded in the code. 8434@end defmac 8435 8436@defmac COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 8437If defined, a C statement that will write a function that can be 8438automatically called when a shared library is unloaded. The function 8439should call @var{func}, which takes no arguments. If not defined, and 8440the object format requires an explicit finalization function, then a 8441function called @code{_GLOBAL__DD} will be generated. 8442@end defmac 8443 8444@defmac INVOKE__main 8445If defined, @code{main} will call @code{__main} despite the presence of 8446@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 8447where the init section is not actually run automatically, but is still 8448useful for collecting the lists of constructors and destructors. 8449@end defmac 8450 8451@defmac SUPPORTS_INIT_PRIORITY 8452If nonzero, the C++ @code{init_priority} attribute is supported and the 8453compiler should emit instructions to control the order of initialization 8454of objects. If zero, the compiler will issue an error message upon 8455encountering an @code{init_priority} attribute. 8456@end defmac 8457 8458@deftypevr {Target Hook} bool TARGET_HAVE_CTORS_DTORS 8459This value is true if the target supports some ``native'' method of 8460collecting constructors and destructors to be run at startup and exit. 8461It is false if we must use @command{collect2}. 8462@end deftypevr 8463 8464@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 8465If defined, a function that outputs assembler code to arrange to call 8466the function referenced by @var{symbol} at initialization time. 8467 8468Assume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 8469no arguments and with no return value. If the target supports initialization 8470priorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 8471otherwise it must be @code{DEFAULT_INIT_PRIORITY}. 8472 8473If this macro is not defined by the target, a suitable default will 8474be chosen if (1) the target supports arbitrary section names, (2) the 8475target defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 8476is not defined. 8477@end deftypefn 8478 8479@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 8480This is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 8481functions rather than initialization functions. 8482@end deftypefn 8483 8484If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 8485generated for the generated object file will have static linkage. 8486 8487If your system uses @command{collect2} as the means of processing 8488constructors, then that program normally uses @command{nm} to scan 8489an object file for constructor functions to be called. 8490 8491On certain kinds of systems, you can define this macro to make 8492@command{collect2} work faster (and, in some cases, make it work at all): 8493 8494@defmac OBJECT_FORMAT_COFF 8495Define this macro if the system uses COFF (Common Object File Format) 8496object files, so that @command{collect2} can assume this format and scan 8497object files directly for dynamic constructor/destructor functions. 8498 8499This macro is effective only in a native compiler; @command{collect2} as 8500part of a cross compiler always uses @command{nm} for the target machine. 8501@end defmac 8502 8503@defmac REAL_NM_FILE_NAME 8504Define this macro as a C string constant containing the file name to use 8505to execute @command{nm}. The default is to search the path normally for 8506@command{nm}. 8507@end defmac 8508 8509@defmac NM_FLAGS 8510@command{collect2} calls @command{nm} to scan object files for static 8511constructors and destructors and LTO info. By default, @option{-n} is 8512passed. Define @code{NM_FLAGS} to a C string constant if other options 8513are needed to get the same output format as GNU @command{nm -n} 8514produces. 8515@end defmac 8516 8517If your system supports shared libraries and has a program to list the 8518dynamic dependencies of a given library or executable, you can define 8519these macros to enable support for running initialization and 8520termination functions in shared libraries: 8521 8522@defmac LDD_SUFFIX 8523Define this macro to a C string constant containing the name of the program 8524which lists dynamic dependencies, like @command{ldd} under SunOS 4. 8525@end defmac 8526 8527@defmac PARSE_LDD_OUTPUT (@var{ptr}) 8528Define this macro to be C code that extracts filenames from the output 8529of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 8530of type @code{char *} that points to the beginning of a line of output 8531from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 8532code must advance @var{ptr} to the beginning of the filename on that 8533line. Otherwise, it must set @var{ptr} to @code{NULL}. 8534@end defmac 8535 8536@defmac SHLIB_SUFFIX 8537Define this macro to a C string constant containing the default shared 8538library extension of the target (e.g., @samp{".so"}). @command{collect2} 8539strips version information after this suffix when generating global 8540constructor and destructor names. This define is only needed on targets 8541that use @command{collect2} to process constructors and destructors. 8542@end defmac 8543 8544@node Instruction Output 8545@subsection Output of Assembler Instructions 8546 8547@c prevent bad page break with this line 8548This describes assembler instruction output. 8549 8550@defmac REGISTER_NAMES 8551A C initializer containing the assembler's names for the machine 8552registers, each one as a C string constant. This is what translates 8553register numbers in the compiler into assembler language. 8554@end defmac 8555 8556@defmac ADDITIONAL_REGISTER_NAMES 8557If defined, a C initializer for an array of structures containing a name 8558and a register number. This macro defines additional names for hard 8559registers, thus allowing the @code{asm} option in declarations to refer 8560to registers using alternate names. 8561@end defmac 8562 8563@defmac OVERLAPPING_REGISTER_NAMES 8564If defined, a C initializer for an array of structures containing a 8565name, a register number and a count of the number of consecutive 8566machine registers the name overlaps. This macro defines additional 8567names for hard registers, thus allowing the @code{asm} option in 8568declarations to refer to registers using alternate names. Unlike 8569@code{ADDITIONAL_REGISTER_NAMES}, this macro should be used when the 8570register name implies multiple underlying registers. 8571 8572This macro should be used when it is important that a clobber in an 8573@code{asm} statement clobbers all the underlying values implied by the 8574register name. For example, on ARM, clobbering the double-precision 8575VFP register ``d0'' implies clobbering both single-precision registers 8576``s0'' and ``s1''. 8577@end defmac 8578 8579@defmac ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 8580Define this macro if you are using an unusual assembler that 8581requires different names for the machine instructions. 8582 8583The definition is a C statement or statements which output an 8584assembler instruction opcode to the stdio stream @var{stream}. The 8585macro-operand @var{ptr} is a variable of type @code{char *} which 8586points to the opcode name in its ``internal'' form---the form that is 8587written in the machine description. The definition should output the 8588opcode name to @var{stream}, performing any translation you desire, and 8589increment the variable @var{ptr} to point at the end of the opcode 8590so that it will not be output twice. 8591 8592In fact, your macro definition may process less than the entire opcode 8593name, or more than the opcode name; but if you want to process text 8594that includes @samp{%}-sequences to substitute operands, you must take 8595care of the substitution yourself. Just be sure to increment 8596@var{ptr} over whatever text should not be output normally. 8597 8598@findex recog_data.operand 8599If you need to look at the operand values, they can be found as the 8600elements of @code{recog_data.operand}. 8601 8602If the macro definition does nothing, the instruction is output 8603in the usual way. 8604@end defmac 8605 8606@defmac FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 8607If defined, a C statement to be executed just prior to the output of 8608assembler code for @var{insn}, to modify the extracted operands so 8609they will be output differently. 8610 8611Here the argument @var{opvec} is the vector containing the operands 8612extracted from @var{insn}, and @var{noperands} is the number of 8613elements of the vector which contain meaningful data for this insn. 8614The contents of this vector are what will be used to convert the insn 8615template into assembler code, so you can change the assembler output 8616by changing the contents of the vector. 8617 8618This macro is useful when various assembler syntaxes share a single 8619file of instruction patterns; by defining this macro differently, you 8620can cause a large class of instructions to be output differently (such 8621as with rearranged operands). Naturally, variations in assembler 8622syntax affecting individual insn patterns ought to be handled by 8623writing conditional output routines in those patterns. 8624 8625If this macro is not defined, it is equivalent to a null statement. 8626@end defmac 8627 8628@deftypefn {Target Hook} void TARGET_ASM_FINAL_POSTSCAN_INSN (FILE *@var{file}, rtx @var{insn}, rtx *@var{opvec}, int @var{noperands}) 8629If defined, this target hook is a function which is executed just after the 8630output of assembler code for @var{insn}, to change the mode of the assembler 8631if necessary. 8632 8633Here the argument @var{opvec} is the vector containing the operands 8634extracted from @var{insn}, and @var{noperands} is the number of 8635elements of the vector which contain meaningful data for this insn. 8636The contents of this vector are what was used to convert the insn 8637template into assembler code, so you can change the assembler mode 8638by checking the contents of the vector. 8639@end deftypefn 8640 8641@defmac PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 8642A C compound statement to output to stdio stream @var{stream} the 8643assembler syntax for an instruction operand @var{x}. @var{x} is an 8644RTL expression. 8645 8646@var{code} is a value that can be used to specify one of several ways 8647of printing the operand. It is used when identical operands must be 8648printed differently depending on the context. @var{code} comes from 8649the @samp{%} specification that was used to request printing of the 8650operand. If the specification was just @samp{%@var{digit}} then 8651@var{code} is 0; if the specification was @samp{%@var{ltr} 8652@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 8653 8654@findex reg_names 8655If @var{x} is a register, this macro should print the register's name. 8656The names can be found in an array @code{reg_names} whose type is 8657@code{char *[]}. @code{reg_names} is initialized from 8658@code{REGISTER_NAMES}. 8659 8660When the machine description has a specification @samp{%@var{punct}} 8661(a @samp{%} followed by a punctuation character), this macro is called 8662with a null pointer for @var{x} and the punctuation character for 8663@var{code}. 8664@end defmac 8665 8666@defmac PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 8667A C expression which evaluates to true if @var{code} is a valid 8668punctuation character for use in the @code{PRINT_OPERAND} macro. If 8669@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 8670punctuation characters (except for the standard one, @samp{%}) are used 8671in this way. 8672@end defmac 8673 8674@defmac PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 8675A C compound statement to output to stdio stream @var{stream} the 8676assembler syntax for an instruction operand that is a memory reference 8677whose address is @var{x}. @var{x} is an RTL expression. 8678 8679@cindex @code{TARGET_ENCODE_SECTION_INFO} usage 8680On some machines, the syntax for a symbolic address depends on the 8681section that the address refers to. On these machines, define the hook 8682@code{TARGET_ENCODE_SECTION_INFO} to store the information into the 8683@code{symbol_ref}, and then check for it here. @xref{Assembler 8684Format}. 8685@end defmac 8686 8687@findex dbr_sequence_length 8688@defmac DBR_OUTPUT_SEQEND (@var{file}) 8689A C statement, to be executed after all slot-filler instructions have 8690been output. If necessary, call @code{dbr_sequence_length} to 8691determine the number of slots filled in a sequence (zero if not 8692currently outputting a sequence), to decide how many no-ops to output, 8693or whatever. 8694 8695Don't define this macro if it has nothing to do, but it is helpful in 8696reading assembly output if the extent of the delay sequence is made 8697explicit (e.g.@: with white space). 8698@end defmac 8699 8700@findex final_sequence 8701Note that output routines for instructions with delay slots must be 8702prepared to deal with not being output as part of a sequence 8703(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 8704found.) The variable @code{final_sequence} is null when not 8705processing a sequence, otherwise it contains the @code{sequence} rtx 8706being output. 8707 8708@findex asm_fprintf 8709@defmac REGISTER_PREFIX 8710@defmacx LOCAL_LABEL_PREFIX 8711@defmacx USER_LABEL_PREFIX 8712@defmacx IMMEDIATE_PREFIX 8713If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 8714@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 8715@file{final.c}). These are useful when a single @file{md} file must 8716support multiple assembler formats. In that case, the various @file{tm.h} 8717files can define these macros differently. 8718@end defmac 8719 8720@defmac ASM_FPRINTF_EXTENSIONS (@var{file}, @var{argptr}, @var{format}) 8721If defined this macro should expand to a series of @code{case} 8722statements which will be parsed inside the @code{switch} statement of 8723the @code{asm_fprintf} function. This allows targets to define extra 8724printf formats which may useful when generating their assembler 8725statements. Note that uppercase letters are reserved for future 8726generic extensions to asm_fprintf, and so are not available to target 8727specific code. The output file is given by the parameter @var{file}. 8728The varargs input pointer is @var{argptr} and the rest of the format 8729string, starting the character after the one that is being switched 8730upon, is pointed to by @var{format}. 8731@end defmac 8732 8733@defmac ASSEMBLER_DIALECT 8734If your target supports multiple dialects of assembler language (such as 8735different opcodes), define this macro as a C expression that gives the 8736numeric index of the assembler language dialect to use, with zero as the 8737first variant. 8738 8739If this macro is defined, you may use constructs of the form 8740@smallexample 8741@samp{@{option0|option1|option2@dots{}@}} 8742@end smallexample 8743@noindent 8744in the output templates of patterns (@pxref{Output Template}) or in the 8745first argument of @code{asm_fprintf}. This construct outputs 8746@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 8747@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 8748within these strings retain their usual meaning. If there are fewer 8749alternatives within the braces than the value of 8750@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 8751 8752If you do not define this macro, the characters @samp{@{}, @samp{|} and 8753@samp{@}} do not have any special meaning when used in templates or 8754operands to @code{asm_fprintf}. 8755 8756Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 8757@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 8758the variations in assembler language syntax with that mechanism. Define 8759@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 8760if the syntax variant are larger and involve such things as different 8761opcodes or operand order. 8762@end defmac 8763 8764@defmac ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 8765A C expression to output to @var{stream} some assembler code 8766which will push hard register number @var{regno} onto the stack. 8767The code need not be optimal, since this macro is used only when 8768profiling. 8769@end defmac 8770 8771@defmac ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 8772A C expression to output to @var{stream} some assembler code 8773which will pop hard register number @var{regno} off of the stack. 8774The code need not be optimal, since this macro is used only when 8775profiling. 8776@end defmac 8777 8778@node Dispatch Tables 8779@subsection Output of Dispatch Tables 8780 8781@c prevent bad page break with this line 8782This concerns dispatch tables. 8783 8784@cindex dispatch table 8785@defmac ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 8786A C statement to output to the stdio stream @var{stream} an assembler 8787pseudo-instruction to generate a difference between two labels. 8788@var{value} and @var{rel} are the numbers of two internal labels. The 8789definitions of these labels are output using 8790@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same 8791way here. For example, 8792 8793@smallexample 8794fprintf (@var{stream}, "\t.word L%d-L%d\n", 8795 @var{value}, @var{rel}) 8796@end smallexample 8797 8798You must provide this macro on machines where the addresses in a 8799dispatch table are relative to the table's own address. If defined, GCC 8800will also use this macro on all machines when producing PIC@. 8801@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 8802mode and flags can be read. 8803@end defmac 8804 8805@defmac ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 8806This macro should be provided on machines where the addresses 8807in a dispatch table are absolute. 8808 8809The definition should be a C statement to output to the stdio stream 8810@var{stream} an assembler pseudo-instruction to generate a reference to 8811a label. @var{value} is the number of an internal label whose 8812definition is output using @code{(*targetm.asm_out.internal_label)}. 8813For example, 8814 8815@smallexample 8816fprintf (@var{stream}, "\t.word L%d\n", @var{value}) 8817@end smallexample 8818@end defmac 8819 8820@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 8821Define this if the label before a jump-table needs to be output 8822specially. The first three arguments are the same as for 8823@code{(*targetm.asm_out.internal_label)}; the fourth argument is the 8824jump-table which follows (a @code{jump_insn} containing an 8825@code{addr_vec} or @code{addr_diff_vec}). 8826 8827This feature is used on system V to output a @code{swbeg} statement 8828for the table. 8829 8830If this macro is not defined, these labels are output with 8831@code{(*targetm.asm_out.internal_label)}. 8832@end defmac 8833 8834@defmac ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 8835Define this if something special must be output at the end of a 8836jump-table. The definition should be a C statement to be executed 8837after the assembler code for the table is written. It should write 8838the appropriate code to stdio stream @var{stream}. The argument 8839@var{table} is the jump-table insn, and @var{num} is the label-number 8840of the preceding label. 8841 8842If this macro is not defined, nothing special is output at the end of 8843the jump-table. 8844@end defmac 8845 8846@deftypefn {Target Hook} void TARGET_ASM_EMIT_UNWIND_LABEL (FILE *@var{stream}, tree @var{decl}, int @var{for_eh}, int @var{empty}) 8847This target hook emits a label at the beginning of each FDE@. It 8848should be defined on targets where FDEs need special labels, and it 8849should write the appropriate label, for the FDE associated with the 8850function declaration @var{decl}, to the stdio stream @var{stream}. 8851The third argument, @var{for_eh}, is a boolean: true if this is for an 8852exception table. The fourth argument, @var{empty}, is a boolean: 8853true if this is a placeholder label for an omitted FDE@. 8854 8855The default is that FDEs are not given nonlocal labels. 8856@end deftypefn 8857 8858@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL (FILE *@var{stream}) 8859This target hook emits a label at the beginning of the exception table. 8860It should be defined on targets where it is desirable for the table 8861to be broken up according to function. 8862 8863The default is that no label is emitted. 8864@end deftypefn 8865 8866@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_PERSONALITY (rtx @var{personality}) 8867If 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. 8868@end deftypefn 8869 8870@deftypefn {Target Hook} void TARGET_ASM_UNWIND_EMIT (FILE *@var{stream}, rtx @var{insn}) 8871This target hook emits assembly directives required to unwind the 8872given instruction. This is only used when @code{TARGET_EXCEPT_UNWIND_INFO} 8873returns @code{UI_TARGET}. 8874@end deftypefn 8875 8876@deftypevr {Target Hook} bool TARGET_ASM_UNWIND_EMIT_BEFORE_INSN 8877True 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. 8878@end deftypevr 8879 8880@node Exception Region Output 8881@subsection Assembler Commands for Exception Regions 8882 8883@c prevent bad page break with this line 8884 8885This describes commands marking the start and the end of an exception 8886region. 8887 8888@defmac EH_FRAME_SECTION_NAME 8889If defined, a C string constant for the name of the section containing 8890exception handling frame unwind information. If not defined, GCC will 8891provide a default definition if the target supports named sections. 8892@file{crtstuff.c} uses this macro to switch to the appropriate section. 8893 8894You should define this symbol if your target supports DWARF 2 frame 8895unwind information and the default definition does not work. 8896@end defmac 8897 8898@defmac EH_FRAME_IN_DATA_SECTION 8899If defined, DWARF 2 frame unwind information will be placed in the 8900data section even though the target supports named sections. This 8901might be necessary, for instance, if the system linker does garbage 8902collection and sections cannot be marked as not to be collected. 8903 8904Do not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 8905also defined. 8906@end defmac 8907 8908@defmac EH_TABLES_CAN_BE_READ_ONLY 8909Define this macro to 1 if your target is such that no frame unwind 8910information encoding used with non-PIC code will ever require a 8911runtime relocation, but the linker may not support merging read-only 8912and read-write sections into a single read-write section. 8913@end defmac 8914 8915@defmac MASK_RETURN_ADDR 8916An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 8917that it does not contain any extraneous set bits in it. 8918@end defmac 8919 8920@defmac DWARF2_UNWIND_INFO 8921Define this macro to 0 if your target supports DWARF 2 frame unwind 8922information, but it does not yet work with exception handling. 8923Otherwise, if your target supports this information (if it defines 8924@code{INCOMING_RETURN_ADDR_RTX} and either @code{UNALIGNED_INT_ASM_OP} 8925or @code{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 1. 8926@end defmac 8927 8928@deftypefn {Common Target Hook} {enum unwind_info_type} TARGET_EXCEPT_UNWIND_INFO (struct gcc_options *@var{opts}) 8929This hook defines the mechanism that will be used for exception handling 8930by the target. If the target has ABI specified unwind tables, the hook 8931should return @code{UI_TARGET}. If the target is to use the 8932@code{setjmp}/@code{longjmp}-based exception handling scheme, the hook 8933should return @code{UI_SJLJ}. If the target supports DWARF 2 frame unwind 8934information, the hook should return @code{UI_DWARF2}. 8935 8936A target may, if exceptions are disabled, choose to return @code{UI_NONE}. 8937This may end up simplifying other parts of target-specific code. The 8938default implementation of this hook never returns @code{UI_NONE}. 8939 8940Note that the value returned by this hook should be constant. It should 8941not depend on anything except the command-line switches described by 8942@var{opts}. In particular, the 8943setting @code{UI_SJLJ} must be fixed at compiler start-up as C pre-processor 8944macros and builtin functions related to exception handling are set up 8945depending on this setting. 8946 8947The default implementation of the hook first honors the 8948@option{--enable-sjlj-exceptions} configure option, then 8949@code{DWARF2_UNWIND_INFO}, and finally defaults to @code{UI_SJLJ}. If 8950@code{DWARF2_UNWIND_INFO} depends on command-line options, the target 8951must define this hook so that @var{opts} is used correctly. 8952@end deftypefn 8953 8954@deftypevr {Common Target Hook} bool TARGET_UNWIND_TABLES_DEFAULT 8955This variable should be set to @code{true} if the target ABI requires unwinding 8956tables even when exceptions are not used. It must not be modified by 8957command-line option processing. 8958@end deftypevr 8959 8960@defmac DONT_USE_BUILTIN_SETJMP 8961Define this macro to 1 if the @code{setjmp}/@code{longjmp}-based scheme 8962should use the @code{setjmp}/@code{longjmp} functions from the C library 8963instead of the @code{__builtin_setjmp}/@code{__builtin_longjmp} machinery. 8964@end defmac 8965 8966@defmac DWARF_CIE_DATA_ALIGNMENT 8967This macro need only be defined if the target might save registers in the 8968function prologue at an offset to the stack pointer that is not aligned to 8969@code{UNITS_PER_WORD}. The definition should be the negative minimum 8970alignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 8971minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 8972the target supports DWARF 2 frame unwind information. 8973@end defmac 8974 8975@deftypevr {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO 8976Contains the value true if the target should add a zero word onto the 8977end of a Dwarf-2 frame info section when used for exception handling. 8978Default value is false if @code{EH_FRAME_SECTION_NAME} is defined, and 8979true otherwise. 8980@end deftypevr 8981 8982@deftypefn {Target Hook} rtx TARGET_DWARF_REGISTER_SPAN (rtx @var{reg}) 8983Given a register, this hook should return a parallel of registers to 8984represent where to find the register pieces. Define this hook if the 8985register and its mode are represented in Dwarf in non-contiguous 8986locations, or if the register should be represented in more than one 8987register in Dwarf. Otherwise, this hook should return @code{NULL_RTX}. 8988If not defined, the default is to return @code{NULL_RTX}. 8989@end deftypefn 8990 8991@deftypefn {Target Hook} void TARGET_INIT_DWARF_REG_SIZES_EXTRA (tree @var{address}) 8992If some registers are represented in Dwarf-2 unwind information in 8993multiple pieces, define this hook to fill in information about the 8994sizes of those pieces in the table used by the unwinder at runtime. 8995It will be called by @code{expand_builtin_init_dwarf_reg_sizes} after 8996filling in a single size corresponding to each hard register; 8997@var{address} is the address of the table. 8998@end deftypefn 8999 9000@deftypefn {Target Hook} bool TARGET_ASM_TTYPE (rtx @var{sym}) 9001This hook is used to output a reference from a frame unwinding table to 9002the type_info object identified by @var{sym}. It should return @code{true} 9003if the reference was output. Returning @code{false} will cause the 9004reference to be output using the normal Dwarf2 routines. 9005@end deftypefn 9006 9007@deftypevr {Target Hook} bool TARGET_ARM_EABI_UNWINDER 9008This flag should be set to @code{true} on targets that use an ARM EABI 9009based unwinding library, and @code{false} on other targets. This effects 9010the format of unwinding tables, and how the unwinder in entered after 9011running a cleanup. The default is @code{false}. 9012@end deftypevr 9013 9014@node Alignment Output 9015@subsection Assembler Commands for Alignment 9016 9017@c prevent bad page break with this line 9018This describes commands for alignment. 9019 9020@defmac JUMP_ALIGN (@var{label}) 9021The alignment (log base 2) to put in front of @var{label}, which is 9022a common destination of jumps and has no fallthru incoming edge. 9023 9024This macro need not be defined if you don't want any special alignment 9025to be done at such a time. Most machine descriptions do not currently 9026define the macro. 9027 9028Unless it's necessary to inspect the @var{label} parameter, it is better 9029to set the variable @var{align_jumps} in the target's 9030@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's 9031selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 9032@end defmac 9033 9034@deftypefn {Target Hook} int TARGET_ASM_JUMP_ALIGN_MAX_SKIP (rtx @var{label}) 9035The maximum number of bytes to skip before @var{label} when applying 9036@code{JUMP_ALIGN}. This works only if 9037@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 9038@end deftypefn 9039 9040@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label}) 9041The alignment (log base 2) to put in front of @var{label}, which follows 9042a @code{BARRIER}. 9043 9044This macro need not be defined if you don't want any special alignment 9045to be done at such a time. Most machine descriptions do not currently 9046define the macro. 9047@end defmac 9048 9049@deftypefn {Target Hook} int TARGET_ASM_LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP (rtx @var{label}) 9050The maximum number of bytes to skip before @var{label} when applying 9051@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 9052@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 9053@end deftypefn 9054 9055@defmac LOOP_ALIGN (@var{label}) 9056The alignment (log base 2) to put in front of @var{label}, which follows 9057a @code{NOTE_INSN_LOOP_BEG} note. 9058 9059This macro need not be defined if you don't want any special alignment 9060to be done at such a time. Most machine descriptions do not currently 9061define the macro. 9062 9063Unless it's necessary to inspect the @var{label} parameter, it is better 9064to set the variable @code{align_loops} in the target's 9065@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's 9066selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 9067@end defmac 9068 9069@deftypefn {Target Hook} int TARGET_ASM_LOOP_ALIGN_MAX_SKIP (rtx @var{label}) 9070The maximum number of bytes to skip when applying @code{LOOP_ALIGN} to 9071@var{label}. This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is 9072defined. 9073@end deftypefn 9074 9075@defmac LABEL_ALIGN (@var{label}) 9076The alignment (log base 2) to put in front of @var{label}. 9077If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 9078the maximum of the specified values is used. 9079 9080Unless it's necessary to inspect the @var{label} parameter, it is better 9081to set the variable @code{align_labels} in the target's 9082@code{TARGET_OPTION_OVERRIDE}. Otherwise, you should try to honor the user's 9083selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 9084@end defmac 9085 9086@deftypefn {Target Hook} int TARGET_ASM_LABEL_ALIGN_MAX_SKIP (rtx @var{label}) 9087The maximum number of bytes to skip when applying @code{LABEL_ALIGN} 9088to @var{label}. This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} 9089is defined. 9090@end deftypefn 9091 9092@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 9093A C statement to output to the stdio stream @var{stream} an assembler 9094instruction to advance the location counter by @var{nbytes} bytes. 9095Those bytes should be zero when loaded. @var{nbytes} will be a C 9096expression of type @code{unsigned HOST_WIDE_INT}. 9097@end defmac 9098 9099@defmac ASM_NO_SKIP_IN_TEXT 9100Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 9101text section because it fails to put zeros in the bytes that are skipped. 9102This is true on many Unix systems, where the pseudo--op to skip bytes 9103produces no-op instructions rather than zeros when used in the text 9104section. 9105@end defmac 9106 9107@defmac ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 9108A C statement to output to the stdio stream @var{stream} an assembler 9109command to advance the location counter to a multiple of 2 to the 9110@var{power} bytes. @var{power} will be a C expression of type @code{int}. 9111@end defmac 9112 9113@defmac ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) 9114Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used 9115for padding, if necessary. 9116@end defmac 9117 9118@defmac ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 9119A C statement to output to the stdio stream @var{stream} an assembler 9120command to advance the location counter to a multiple of 2 to the 9121@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 9122satisfy the alignment request. @var{power} and @var{max_skip} will be 9123a C expression of type @code{int}. 9124@end defmac 9125 9126@need 3000 9127@node Debugging Info 9128@section Controlling Debugging Information Format 9129 9130@c prevent bad page break with this line 9131This describes how to specify debugging information. 9132 9133@menu 9134* All Debuggers:: Macros that affect all debugging formats uniformly. 9135* DBX Options:: Macros enabling specific options in DBX format. 9136* DBX Hooks:: Hook macros for varying DBX format. 9137* File Names and DBX:: Macros controlling output of file names in DBX format. 9138* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 9139* VMS Debug:: Macros for VMS debug format. 9140@end menu 9141 9142@node All Debuggers 9143@subsection Macros Affecting All Debugging Formats 9144 9145@c prevent bad page break with this line 9146These macros affect all debugging formats. 9147 9148@defmac DBX_REGISTER_NUMBER (@var{regno}) 9149A C expression that returns the DBX register number for the compiler 9150register number @var{regno}. In the default macro provided, the value 9151of this expression will be @var{regno} itself. But sometimes there are 9152some registers that the compiler knows about and DBX does not, or vice 9153versa. In such cases, some register may need to have one number in the 9154compiler and another for DBX@. 9155 9156If two registers have consecutive numbers inside GCC, and they can be 9157used as a pair to hold a multiword value, then they @emph{must} have 9158consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 9159Otherwise, debuggers will be unable to access such a pair, because they 9160expect register pairs to be consecutive in their own numbering scheme. 9161 9162If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 9163does not preserve register pairs, then what you must do instead is 9164redefine the actual register numbering scheme. 9165@end defmac 9166 9167@defmac DEBUGGER_AUTO_OFFSET (@var{x}) 9168A C expression that returns the integer offset value for an automatic 9169variable having address @var{x} (an RTL expression). The default 9170computation assumes that @var{x} is based on the frame-pointer and 9171gives the offset from the frame-pointer. This is required for targets 9172that produce debugging output for DBX or COFF-style debugging output 9173for SDB and allow the frame-pointer to be eliminated when the 9174@option{-g} options is used. 9175@end defmac 9176 9177@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 9178A C expression that returns the integer offset value for an argument 9179having address @var{x} (an RTL expression). The nominal offset is 9180@var{offset}. 9181@end defmac 9182 9183@defmac PREFERRED_DEBUGGING_TYPE 9184A C expression that returns the type of debugging output GCC should 9185produce when the user specifies just @option{-g}. Define 9186this if you have arranged for GCC to support more than one format of 9187debugging output. Currently, the allowable values are @code{DBX_DEBUG}, 9188@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 9189@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 9190 9191When the user specifies @option{-ggdb}, GCC normally also uses the 9192value of this macro to select the debugging output format, but with two 9193exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined, GCC uses the 9194value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 9195defined, GCC uses @code{DBX_DEBUG}. 9196 9197The value of this macro only affects the default debugging output; the 9198user can always get a specific type of output by using @option{-gstabs}, 9199@option{-gcoff}, @option{-gdwarf-2}, @option{-gxcoff}, or @option{-gvms}. 9200@end defmac 9201 9202@node DBX Options 9203@subsection Specific Options for DBX Output 9204 9205@c prevent bad page break with this line 9206These are specific options for DBX output. 9207 9208@defmac DBX_DEBUGGING_INFO 9209Define this macro if GCC should produce debugging output for DBX 9210in response to the @option{-g} option. 9211@end defmac 9212 9213@defmac XCOFF_DEBUGGING_INFO 9214Define this macro if GCC should produce XCOFF format debugging output 9215in response to the @option{-g} option. This is a variant of DBX format. 9216@end defmac 9217 9218@defmac DEFAULT_GDB_EXTENSIONS 9219Define this macro to control whether GCC should by default generate 9220GDB's extended version of DBX debugging information (assuming DBX-format 9221debugging information is enabled at all). If you don't define the 9222macro, the default is 1: always generate the extended information 9223if there is any occasion to. 9224@end defmac 9225 9226@defmac DEBUG_SYMS_TEXT 9227Define this macro if all @code{.stabs} commands should be output while 9228in the text section. 9229@end defmac 9230 9231@defmac ASM_STABS_OP 9232A C string constant, including spacing, naming the assembler pseudo op to 9233use instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 9234If you don't define this macro, @code{"\t.stabs\t"} is used. This macro 9235applies only to DBX debugging information format. 9236@end defmac 9237 9238@defmac ASM_STABD_OP 9239A C string constant, including spacing, naming the assembler pseudo op to 9240use instead of @code{"\t.stabd\t"} to define a debugging symbol whose 9241value is the current location. If you don't define this macro, 9242@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 9243information format. 9244@end defmac 9245 9246@defmac ASM_STABN_OP 9247A C string constant, including spacing, naming the assembler pseudo op to 9248use instead of @code{"\t.stabn\t"} to define a debugging symbol with no 9249name. If you don't define this macro, @code{"\t.stabn\t"} is used. This 9250macro applies only to DBX debugging information format. 9251@end defmac 9252 9253@defmac DBX_NO_XREFS 9254Define this macro if DBX on your system does not support the construct 9255@samp{xs@var{tagname}}. On some systems, this construct is used to 9256describe a forward reference to a structure named @var{tagname}. 9257On other systems, this construct is not supported at all. 9258@end defmac 9259 9260@defmac DBX_CONTIN_LENGTH 9261A symbol name in DBX-format debugging information is normally 9262continued (split into two separate @code{.stabs} directives) when it 9263exceeds a certain length (by default, 80 characters). On some 9264operating systems, DBX requires this splitting; on others, splitting 9265must not be done. You can inhibit splitting by defining this macro 9266with the value zero. You can override the default splitting-length by 9267defining this macro as an expression for the length you desire. 9268@end defmac 9269 9270@defmac DBX_CONTIN_CHAR 9271Normally continuation is indicated by adding a @samp{\} character to 9272the end of a @code{.stabs} string when a continuation follows. To use 9273a different character instead, define this macro as a character 9274constant for the character you want to use. Do not define this macro 9275if backslash is correct for your system. 9276@end defmac 9277 9278@defmac DBX_STATIC_STAB_DATA_SECTION 9279Define this macro if it is necessary to go to the data section before 9280outputting the @samp{.stabs} pseudo-op for a non-global static 9281variable. 9282@end defmac 9283 9284@defmac DBX_TYPE_DECL_STABS_CODE 9285The value to use in the ``code'' field of the @code{.stabs} directive 9286for a typedef. The default is @code{N_LSYM}. 9287@end defmac 9288 9289@defmac DBX_STATIC_CONST_VAR_CODE 9290The value to use in the ``code'' field of the @code{.stabs} directive 9291for a static variable located in the text section. DBX format does not 9292provide any ``right'' way to do this. The default is @code{N_FUN}. 9293@end defmac 9294 9295@defmac DBX_REGPARM_STABS_CODE 9296The value to use in the ``code'' field of the @code{.stabs} directive 9297for a parameter passed in registers. DBX format does not provide any 9298``right'' way to do this. The default is @code{N_RSYM}. 9299@end defmac 9300 9301@defmac DBX_REGPARM_STABS_LETTER 9302The letter to use in DBX symbol data to identify a symbol as a parameter 9303passed in registers. DBX format does not customarily provide any way to 9304do this. The default is @code{'P'}. 9305@end defmac 9306 9307@defmac DBX_FUNCTION_FIRST 9308Define this macro if the DBX information for a function and its 9309arguments should precede the assembler code for the function. Normally, 9310in DBX format, the debugging information entirely follows the assembler 9311code. 9312@end defmac 9313 9314@defmac DBX_BLOCKS_FUNCTION_RELATIVE 9315Define this macro, with value 1, if the value of a symbol describing 9316the scope of a block (@code{N_LBRAC} or @code{N_RBRAC}) should be 9317relative to the start of the enclosing function. Normally, GCC uses 9318an absolute address. 9319@end defmac 9320 9321@defmac DBX_LINES_FUNCTION_RELATIVE 9322Define this macro, with value 1, if the value of a symbol indicating 9323the current line number (@code{N_SLINE}) should be relative to the 9324start of the enclosing function. Normally, GCC uses an absolute address. 9325@end defmac 9326 9327@defmac DBX_USE_BINCL 9328Define this macro if GCC should generate @code{N_BINCL} and 9329@code{N_EINCL} stabs for included header files, as on Sun systems. This 9330macro also directs GCC to output a type number as a pair of a file 9331number and a type number within the file. Normally, GCC does not 9332generate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 9333number for a type number. 9334@end defmac 9335 9336@node DBX Hooks 9337@subsection Open-Ended Hooks for DBX Format 9338 9339@c prevent bad page break with this line 9340These are hooks for DBX format. 9341 9342@defmac DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 9343Define this macro to say how to output to @var{stream} the debugging 9344information for the start of a scope level for variable names. The 9345argument @var{name} is the name of an assembler symbol (for use with 9346@code{assemble_name}) whose value is the address where the scope begins. 9347@end defmac 9348 9349@defmac DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 9350Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 9351@end defmac 9352 9353@defmac DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 9354Define this macro if the target machine requires special handling to 9355output an @code{N_FUN} entry for the function @var{decl}. 9356@end defmac 9357 9358@defmac DBX_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}, @var{counter}) 9359A C statement to output DBX debugging information before code for line 9360number @var{line} of the current source file to the stdio stream 9361@var{stream}. @var{counter} is the number of time the macro was 9362invoked, including the current invocation; it is intended to generate 9363unique labels in the assembly output. 9364 9365This macro should not be defined if the default output is correct, or 9366if it can be made correct by defining @code{DBX_LINES_FUNCTION_RELATIVE}. 9367@end defmac 9368 9369@defmac NO_DBX_FUNCTION_END 9370Some stabs encapsulation formats (in particular ECOFF), cannot handle the 9371@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 9372On those machines, define this macro to turn this feature off without 9373disturbing the rest of the gdb extensions. 9374@end defmac 9375 9376@defmac NO_DBX_BNSYM_ENSYM 9377Some assemblers cannot handle the @code{.stabd BNSYM/ENSYM,0,0} gdb dbx 9378extension construct. On those machines, define this macro to turn this 9379feature off without disturbing the rest of the gdb extensions. 9380@end defmac 9381 9382@node File Names and DBX 9383@subsection File Names in DBX Format 9384 9385@c prevent bad page break with this line 9386This describes file names in DBX format. 9387 9388@defmac DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 9389A C statement to output DBX debugging information to the stdio stream 9390@var{stream}, which indicates that file @var{name} is the main source 9391file---the file specified as the input file for compilation. 9392This macro is called only once, at the beginning of compilation. 9393 9394This macro need not be defined if the standard form of output 9395for DBX debugging information is appropriate. 9396 9397It may be necessary to refer to a label equal to the beginning of the 9398text section. You can use @samp{assemble_name (stream, ltext_label_name)} 9399to do so. If you do this, you must also set the variable 9400@var{used_ltext_label_name} to @code{true}. 9401@end defmac 9402 9403@defmac NO_DBX_MAIN_SOURCE_DIRECTORY 9404Define this macro, with value 1, if GCC should not emit an indication 9405of the current directory for compilation and current source language at 9406the beginning of the file. 9407@end defmac 9408 9409@defmac NO_DBX_GCC_MARKER 9410Define this macro, with value 1, if GCC should not emit an indication 9411that this object file was compiled by GCC@. The default is to emit 9412an @code{N_OPT} stab at the beginning of every source file, with 9413@samp{gcc2_compiled.} for the string and value 0. 9414@end defmac 9415 9416@defmac DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 9417A C statement to output DBX debugging information at the end of 9418compilation of the main source file @var{name}. Output should be 9419written to the stdio stream @var{stream}. 9420 9421If you don't define this macro, nothing special is output at the end 9422of compilation, which is correct for most machines. 9423@end defmac 9424 9425@defmac DBX_OUTPUT_NULL_N_SO_AT_MAIN_SOURCE_FILE_END 9426Define this macro @emph{instead of} defining 9427@code{DBX_OUTPUT_MAIN_SOURCE_FILE_END}, if what needs to be output at 9428the end of compilation is an @code{N_SO} stab with an empty string, 9429whose value is the highest absolute text address in the file. 9430@end defmac 9431 9432@need 2000 9433@node SDB and DWARF 9434@subsection Macros for SDB and DWARF Output 9435 9436@c prevent bad page break with this line 9437Here are macros for SDB and DWARF output. 9438 9439@defmac SDB_DEBUGGING_INFO 9440Define this macro if GCC should produce COFF-style debugging output 9441for SDB in response to the @option{-g} option. 9442@end defmac 9443 9444@defmac DWARF2_DEBUGGING_INFO 9445Define this macro if GCC should produce dwarf version 2 format 9446debugging output in response to the @option{-g} option. 9447 9448@deftypefn {Target Hook} int TARGET_DWARF_CALLING_CONVENTION (const_tree @var{function}) 9449Define this to enable the dwarf attribute @code{DW_AT_calling_convention} to 9450be emitted for each function. Instead of an integer return the enum 9451value for the @code{DW_CC_} tag. 9452@end deftypefn 9453 9454To support optional call frame debugging information, you must also 9455define @code{INCOMING_RETURN_ADDR_RTX} and either set 9456@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 9457prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 9458as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 9459@end defmac 9460 9461@defmac DWARF2_FRAME_INFO 9462Define this macro to a nonzero value if GCC should always output 9463Dwarf 2 frame information. If @code{TARGET_EXCEPT_UNWIND_INFO} 9464(@pxref{Exception Region Output}) returns @code{UI_DWARF2}, and 9465exceptions are enabled, GCC will output this information not matter 9466how you define @code{DWARF2_FRAME_INFO}. 9467@end defmac 9468 9469@deftypefn {Target Hook} {enum unwind_info_type} TARGET_DEBUG_UNWIND_INFO (void) 9470This hook defines the mechanism that will be used for describing frame 9471unwind information to the debugger. Normally the hook will return 9472@code{UI_DWARF2} if DWARF 2 debug information is enabled, and 9473return @code{UI_NONE} otherwise. 9474 9475A target may return @code{UI_DWARF2} even when DWARF 2 debug information 9476is disabled in order to always output DWARF 2 frame information. 9477 9478A target may return @code{UI_TARGET} if it has ABI specified unwind tables. 9479This will suppress generation of the normal debug frame unwind information. 9480@end deftypefn 9481 9482@defmac DWARF2_ASM_LINE_DEBUG_INFO 9483Define this macro to be a nonzero value if the assembler can generate Dwarf 2 9484line debug info sections. This will result in much more compact line number 9485tables, and hence is desirable if it works. 9486@end defmac 9487 9488@deftypevr {Target Hook} bool TARGET_WANT_DEBUG_PUB_SECTIONS 9489True 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. 9490@end deftypevr 9491 9492@deftypevr {Target Hook} bool TARGET_FORCE_AT_COMP_DIR 9493True if the @code{DW_AT_comp_dir} attribute should be emitted for each compilation unit. This attribute is required for the darwin linker to emit debug information. 9494@end deftypevr 9495 9496@deftypevr {Target Hook} bool TARGET_DELAY_SCHED2 9497True if sched2 is not to be run at its normal place. This usually means it will be run as part of machine-specific reorg. 9498@end deftypevr 9499 9500@deftypevr {Target Hook} bool TARGET_DELAY_VARTRACK 9501True if vartrack is not to be run at its normal place. This usually means it will be run as part of machine-specific reorg. 9502@end deftypevr 9503 9504@defmac ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 9505A C statement to issue assembly directives that create a difference 9506@var{lab1} minus @var{lab2}, using an integer of the given @var{size}. 9507@end defmac 9508 9509@defmac ASM_OUTPUT_DWARF_VMS_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 9510A C statement to issue assembly directives that create a difference 9511between the two given labels in system defined units, e.g. instruction 9512slots on IA64 VMS, using an integer of the given size. 9513@end defmac 9514 9515@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{section}) 9516A C statement to issue assembly directives that create a 9517section-relative reference to the given @var{label}, using an integer of the 9518given @var{size}. The label is known to be defined in the given @var{section}. 9519@end defmac 9520 9521@defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) 9522A C statement to issue assembly directives that create a self-relative 9523reference to the given @var{label}, using an integer of the given @var{size}. 9524@end defmac 9525 9526@defmac ASM_OUTPUT_DWARF_TABLE_REF (@var{label}) 9527A C statement to issue assembly directives that create a reference to 9528the DWARF table identifier @var{label} from the current section. This 9529is used on some systems to avoid garbage collecting a DWARF table which 9530is referenced by a function. 9531@end defmac 9532 9533@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_DWARF_DTPREL (FILE *@var{file}, int @var{size}, rtx @var{x}) 9534If defined, this target hook is a function which outputs a DTP-relative 9535reference to the given TLS symbol of the specified size. 9536@end deftypefn 9537 9538@defmac PUT_SDB_@dots{} 9539Define these macros to override the assembler syntax for the special 9540SDB assembler directives. See @file{sdbout.c} for a list of these 9541macros and their arguments. If the standard syntax is used, you need 9542not define them yourself. 9543@end defmac 9544 9545@defmac SDB_DELIM 9546Some assemblers do not support a semicolon as a delimiter, even between 9547SDB assembler directives. In that case, define this macro to be the 9548delimiter to use (usually @samp{\n}). It is not necessary to define 9549a new set of @code{PUT_SDB_@var{op}} macros if this is the only change 9550required. 9551@end defmac 9552 9553@defmac SDB_ALLOW_UNKNOWN_REFERENCES 9554Define this macro to allow references to unknown structure, 9555union, or enumeration tags to be emitted. Standard COFF does not 9556allow handling of unknown references, MIPS ECOFF has support for 9557it. 9558@end defmac 9559 9560@defmac SDB_ALLOW_FORWARD_REFERENCES 9561Define this macro to allow references to structure, union, or 9562enumeration tags that have not yet been seen to be handled. Some 9563assemblers choke if forward tags are used, while some require it. 9564@end defmac 9565 9566@defmac SDB_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 9567A C statement to output SDB debugging information before code for line 9568number @var{line} of the current source file to the stdio stream 9569@var{stream}. The default is to emit an @code{.ln} directive. 9570@end defmac 9571 9572@need 2000 9573@node VMS Debug 9574@subsection Macros for VMS Debug Format 9575 9576@c prevent bad page break with this line 9577Here are macros for VMS debug format. 9578 9579@defmac VMS_DEBUGGING_INFO 9580Define this macro if GCC should produce debugging output for VMS 9581in response to the @option{-g} option. The default behavior for VMS 9582is to generate minimal debug info for a traceback in the absence of 9583@option{-g} unless explicitly overridden with @option{-g0}. This 9584behavior is controlled by @code{TARGET_OPTION_OPTIMIZATION} and 9585@code{TARGET_OPTION_OVERRIDE}. 9586@end defmac 9587 9588@node Floating Point 9589@section Cross Compilation and Floating Point 9590@cindex cross compilation and floating point 9591@cindex floating point and cross compilation 9592 9593While all modern machines use twos-complement representation for integers, 9594there are a variety of representations for floating point numbers. This 9595means that in a cross-compiler the representation of floating point numbers 9596in the compiled program may be different from that used in the machine 9597doing the compilation. 9598 9599Because different representation systems may offer different amounts of 9600range and precision, all floating point constants must be represented in 9601the target machine's format. Therefore, the cross compiler cannot 9602safely use the host machine's floating point arithmetic; it must emulate 9603the target's arithmetic. To ensure consistency, GCC always uses 9604emulation to work with floating point values, even when the host and 9605target floating point formats are identical. 9606 9607The following macros are provided by @file{real.h} for the compiler to 9608use. All parts of the compiler which generate or optimize 9609floating-point calculations must use these macros. They may evaluate 9610their operands more than once, so operands must not have side effects. 9611 9612@defmac REAL_VALUE_TYPE 9613The C data type to be used to hold a floating point value in the target 9614machine's format. Typically this is a @code{struct} containing an 9615array of @code{HOST_WIDE_INT}, but all code should treat it as an opaque 9616quantity. 9617@end defmac 9618 9619@deftypefn Macro int REAL_VALUES_EQUAL (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 9620Compares for equality the two values, @var{x} and @var{y}. If the target 9621floating point format supports negative zeroes and/or NaNs, 9622@samp{REAL_VALUES_EQUAL (-0.0, 0.0)} is true, and 9623@samp{REAL_VALUES_EQUAL (NaN, NaN)} is false. 9624@end deftypefn 9625 9626@deftypefn Macro int REAL_VALUES_LESS (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 9627Tests whether @var{x} is less than @var{y}. 9628@end deftypefn 9629 9630@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x}) 9631Truncates @var{x} to a signed integer, rounding toward zero. 9632@end deftypefn 9633 9634@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x}) 9635Truncates @var{x} to an unsigned integer, rounding toward zero. If 9636@var{x} is negative, returns zero. 9637@end deftypefn 9638 9639@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, enum machine_mode @var{mode}) 9640Converts @var{string} into a floating point number in the target machine's 9641representation for mode @var{mode}. This routine can handle both 9642decimal and hexadecimal floating point constants, using the syntax 9643defined by the C language for both. 9644@end deftypefn 9645 9646@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x}) 9647Returns 1 if @var{x} is negative (including negative zero), 0 otherwise. 9648@end deftypefn 9649 9650@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x}) 9651Determines whether @var{x} represents infinity (positive or negative). 9652@end deftypefn 9653 9654@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x}) 9655Determines whether @var{x} represents a ``NaN'' (not-a-number). 9656@end deftypefn 9657 9658@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}) 9659Calculates an arithmetic operation on the two floating point values 9660@var{x} and @var{y}, storing the result in @var{output} (which must be a 9661variable). 9662 9663The operation to be performed is specified by @var{code}. Only the 9664following codes are supported: @code{PLUS_EXPR}, @code{MINUS_EXPR}, 9665@code{MULT_EXPR}, @code{RDIV_EXPR}, @code{MAX_EXPR}, @code{MIN_EXPR}. 9666 9667If @code{REAL_ARITHMETIC} is asked to evaluate division by zero and the 9668target's floating point format cannot represent infinity, it will call 9669@code{abort}. Callers should check for this situation first, using 9670@code{MODE_HAS_INFINITIES}. @xref{Storage Layout}. 9671@end deftypefn 9672 9673@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x}) 9674Returns the negative of the floating point value @var{x}. 9675@end deftypefn 9676 9677@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x}) 9678Returns the absolute value of @var{x}. 9679@end deftypefn 9680 9681@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_TRUNCATE (REAL_VALUE_TYPE @var{mode}, enum machine_mode @var{x}) 9682Truncates the floating point value @var{x} to fit in @var{mode}. The 9683return value is still a full-size @code{REAL_VALUE_TYPE}, but it has an 9684appropriate bit pattern to be output as a floating constant whose 9685precision accords with mode @var{mode}. 9686@end deftypefn 9687 9688@deftypefn Macro void REAL_VALUE_TO_INT (HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, REAL_VALUE_TYPE @var{x}) 9689Converts a floating point value @var{x} into a double-precision integer 9690which is then stored into @var{low} and @var{high}. If the value is not 9691integral, it is truncated. 9692@end deftypefn 9693 9694@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}) 9695Converts a double-precision integer found in @var{low} and @var{high}, 9696into a floating point value which is then stored into @var{x}. The 9697value is truncated to fit in mode @var{mode}. 9698@end deftypefn 9699 9700@node Mode Switching 9701@section Mode Switching Instructions 9702@cindex mode switching 9703The following macros control mode switching optimizations: 9704 9705@defmac OPTIMIZE_MODE_SWITCHING (@var{entity}) 9706Define this macro if the port needs extra instructions inserted for mode 9707switching in an optimizing compilation. 9708 9709For an example, the SH4 can perform both single and double precision 9710floating point operations, but to perform a single precision operation, 9711the FPSCR PR bit has to be cleared, while for a double precision 9712operation, this bit has to be set. Changing the PR bit requires a general 9713purpose register as a scratch register, hence these FPSCR sets have to 9714be inserted before reload, i.e.@: you can't put this into instruction emitting 9715or @code{TARGET_MACHINE_DEPENDENT_REORG}. 9716 9717You can have multiple entities that are mode-switched, and select at run time 9718which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 9719return nonzero for any @var{entity} that needs mode-switching. 9720If you define this macro, you also have to define 9721@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 9722@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 9723@code{MODE_AFTER}, @code{MODE_ENTRY}, and @code{MODE_EXIT} 9724are optional. 9725@end defmac 9726 9727@defmac NUM_MODES_FOR_MODE_SWITCHING 9728If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 9729initializer for an array of integers. Each initializer element 9730N refers to an entity that needs mode switching, and specifies the number 9731of different modes that might need to be set for this entity. 9732The position of the initializer in the initializer---starting counting at 9733zero---determines the integer that is used to refer to the mode-switched 9734entity in question. 9735In macros that take mode arguments / yield a mode result, modes are 9736represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 9737switch is needed / supplied. 9738@end defmac 9739 9740@defmac MODE_NEEDED (@var{entity}, @var{insn}) 9741@var{entity} is an integer specifying a mode-switched entity. If 9742@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 9743return an integer value not larger than the corresponding element in 9744@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 9745be switched into prior to the execution of @var{insn}. 9746@end defmac 9747 9748@defmac MODE_AFTER (@var{mode}, @var{insn}) 9749If this macro is defined, it is evaluated for every @var{insn} during 9750mode switching. It determines the mode that an insn results in (if 9751different from the incoming mode). 9752@end defmac 9753 9754@defmac MODE_ENTRY (@var{entity}) 9755If this macro is defined, it is evaluated for every @var{entity} that needs 9756mode switching. It should evaluate to an integer, which is a mode that 9757@var{entity} is assumed to be switched to at function entry. If @code{MODE_ENTRY} 9758is defined then @code{MODE_EXIT} must be defined. 9759@end defmac 9760 9761@defmac MODE_EXIT (@var{entity}) 9762If this macro is defined, it is evaluated for every @var{entity} that needs 9763mode switching. It should evaluate to an integer, which is a mode that 9764@var{entity} is assumed to be switched to at function exit. If @code{MODE_EXIT} 9765is defined then @code{MODE_ENTRY} must be defined. 9766@end defmac 9767 9768@defmac MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 9769This macro specifies the order in which modes for @var{entity} are processed. 97700 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 9771lowest. The value of the macro should be an integer designating a mode 9772for @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 9773(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 9774@code{num_modes_for_mode_switching[@var{entity}] - 1}. 9775@end defmac 9776 9777@defmac EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 9778Generate one or more insns to set @var{entity} to @var{mode}. 9779@var{hard_reg_live} is the set of hard registers live at the point where 9780the insn(s) are to be inserted. 9781@end defmac 9782 9783@node Target Attributes 9784@section Defining target-specific uses of @code{__attribute__} 9785@cindex target attributes 9786@cindex machine attributes 9787@cindex attributes, target-specific 9788 9789Target-specific attributes may be defined for functions, data and types. 9790These are described using the following target hooks; they also need to 9791be documented in @file{extend.texi}. 9792 9793@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 9794If defined, this target hook points to an array of @samp{struct 9795attribute_spec} (defined in @file{tree.h}) specifying the machine 9796specific attributes for this target and some of the restrictions on the 9797entities to which these attributes are applied and the arguments they 9798take. 9799@end deftypevr 9800 9801@deftypefn {Target Hook} bool TARGET_ATTRIBUTE_TAKES_IDENTIFIER_P (const_tree @var{name}) 9802If defined, this target hook is a function which returns true if the 9803machine-specific attribute named @var{name} expects an identifier 9804given as its first argument to be passed on as a plain identifier, not 9805subjected to name lookup. If this is not defined, the default is 9806false for all machine-specific attributes. 9807@end deftypefn 9808 9809@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (const_tree @var{type1}, const_tree @var{type2}) 9810If defined, this target hook is a function which returns zero if the attributes on 9811@var{type1} and @var{type2} are incompatible, one if they are compatible, 9812and two if they are nearly compatible (which causes a warning to be 9813generated). If this is not defined, machine-specific attributes are 9814supposed always to be compatible. 9815@end deftypefn 9816 9817@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 9818If defined, this target hook is a function which assigns default attributes to 9819the newly defined @var{type}. 9820@end deftypefn 9821 9822@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 9823Define this target hook if the merging of type attributes needs special 9824handling. If defined, the result is a list of the combined 9825@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 9826that @code{comptypes} has already been called and returned 1. This 9827function may call @code{merge_attributes} to handle machine-independent 9828merging. 9829@end deftypefn 9830 9831@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 9832Define this target hook if the merging of decl attributes needs special 9833handling. If defined, the result is a list of the combined 9834@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 9835@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 9836when this is needed are when one attribute overrides another, or when an 9837attribute is nullified by a subsequent definition. This function may 9838call @code{merge_attributes} to handle machine-independent merging. 9839 9840@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 9841If the only target-specific handling you require is @samp{dllimport} 9842for Microsoft Windows targets, you should define the macro 9843@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES} to @code{1}. The compiler 9844will then define a function called 9845@code{merge_dllimport_decl_attributes} which can then be defined as 9846the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. You can also 9847add @code{handle_dll_attribute} in the attribute table for your port 9848to perform initial processing of the @samp{dllimport} and 9849@samp{dllexport} attributes. This is done in @file{i386/cygwin.h} and 9850@file{i386/i386.c}, for example. 9851@end deftypefn 9852 9853@deftypefn {Target Hook} bool TARGET_VALID_DLLIMPORT_ATTRIBUTE_P (const_tree @var{decl}) 9854@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}. 9855@end deftypefn 9856 9857@defmac TARGET_DECLSPEC 9858Define this macro to a nonzero value if you want to treat 9859@code{__declspec(X)} as equivalent to @code{__attribute((X))}. By 9860default, this behavior is enabled only for targets that define 9861@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. The current implementation 9862of @code{__declspec} is via a built-in macro, but you should not rely 9863on this implementation detail. 9864@end defmac 9865 9866@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 9867Define this target hook if you want to be able to add attributes to a decl 9868when it is being created. This is normally useful for back ends which 9869wish to implement a pragma by using the attributes which correspond to 9870the pragma's effect. The @var{node} argument is the decl which is being 9871created. The @var{attr_ptr} argument is a pointer to the attribute list 9872for this decl. The list itself should not be modified, since it may be 9873shared with other decls, but attributes may be chained on the head of 9874the list and @code{*@var{attr_ptr}} modified to point to the new 9875attributes, or a copy of the list may be made if further changes are 9876needed. 9877@end deftypefn 9878 9879@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (const_tree @var{fndecl}) 9880@cindex inlining 9881This target hook returns @code{true} if it is ok to inline @var{fndecl} 9882into the current function, despite its having target-specific 9883attributes, @code{false} otherwise. By default, if a function has a 9884target specific attribute attached to it, it will not be inlined. 9885@end deftypefn 9886 9887@deftypefn {Target Hook} bool TARGET_OPTION_VALID_ATTRIBUTE_P (tree @var{fndecl}, tree @var{name}, tree @var{args}, int @var{flags}) 9888This hook is called to parse the @code{attribute(option("..."))}, and 9889it allows the function to set different target machine compile time 9890options for the current function that might be different than the 9891options specified on the command line. The hook should return 9892@code{true} if the options are valid. 9893 9894The hook should set the @var{DECL_FUNCTION_SPECIFIC_TARGET} field in 9895the function declaration to hold a pointer to a target specific 9896@var{struct cl_target_option} structure. 9897@end deftypefn 9898 9899@deftypefn {Target Hook} void TARGET_OPTION_SAVE (struct cl_target_option *@var{ptr}) 9900This hook is called to save any additional target specific information 9901in the @var{struct cl_target_option} structure for function specific 9902options. 9903@xref{Option file format}. 9904@end deftypefn 9905 9906@deftypefn {Target Hook} void TARGET_OPTION_RESTORE (struct cl_target_option *@var{ptr}) 9907This hook is called to restore any additional target specific 9908information in the @var{struct cl_target_option} structure for 9909function specific options. 9910@end deftypefn 9911 9912@deftypefn {Target Hook} void TARGET_OPTION_PRINT (FILE *@var{file}, int @var{indent}, struct cl_target_option *@var{ptr}) 9913This hook is called to print any additional target specific 9914information in the @var{struct cl_target_option} structure for 9915function specific options. 9916@end deftypefn 9917 9918@deftypefn {Target Hook} bool TARGET_OPTION_PRAGMA_PARSE (tree @var{args}, tree @var{pop_target}) 9919This target hook parses the options for @code{#pragma GCC option} to 9920set the machine specific options for functions that occur later in the 9921input stream. The options should be the same as handled by the 9922@code{TARGET_OPTION_VALID_ATTRIBUTE_P} hook. 9923@end deftypefn 9924 9925@deftypefn {Target Hook} void TARGET_OPTION_OVERRIDE (void) 9926Sometimes certain combinations of command options do not make sense on 9927a particular target machine. You can override the hook 9928@code{TARGET_OPTION_OVERRIDE} to take account of this. This hooks is called 9929once just after all the command options have been parsed. 9930 9931Don't use this hook to turn on various extra optimizations for 9932@option{-O}. That is what @code{TARGET_OPTION_OPTIMIZATION} is for. 9933 9934If you need to do something whenever the optimization level is 9935changed via the optimize attribute or pragma, see 9936@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE} 9937@end deftypefn 9938 9939@deftypefn {Target Hook} bool TARGET_CAN_INLINE_P (tree @var{caller}, tree @var{callee}) 9940This target hook returns @code{false} if the @var{caller} function 9941cannot inline @var{callee}, based on target specific information. By 9942default, inlining is not allowed if the callee function has function 9943specific target options and the caller does not use the same options. 9944@end deftypefn 9945 9946@node Emulated TLS 9947@section Emulating TLS 9948@cindex Emulated TLS 9949 9950For targets whose psABI does not provide Thread Local Storage via 9951specific relocations and instruction sequences, an emulation layer is 9952used. A set of target hooks allows this emulation layer to be 9953configured for the requirements of a particular target. For instance 9954the psABI may in fact specify TLS support in terms of an emulation 9955layer. 9956 9957The emulation layer works by creating a control object for every TLS 9958object. To access the TLS object, a lookup function is provided 9959which, when given the address of the control object, will return the 9960address of the current thread's instance of the TLS object. 9961 9962@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_GET_ADDRESS 9963Contains the name of the helper function that uses a TLS control 9964object to locate a TLS instance. The default causes libgcc's 9965emulated TLS helper function to be used. 9966@end deftypevr 9967 9968@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_REGISTER_COMMON 9969Contains the name of the helper function that should be used at 9970program startup to register TLS objects that are implicitly 9971initialized to zero. If this is @code{NULL}, all TLS objects will 9972have explicit initializers. The default causes libgcc's emulated TLS 9973registration function to be used. 9974@end deftypevr 9975 9976@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_VAR_SECTION 9977Contains the name of the section in which TLS control variables should 9978be placed. The default of @code{NULL} allows these to be placed in 9979any section. 9980@end deftypevr 9981 9982@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_TMPL_SECTION 9983Contains the name of the section in which TLS initializers should be 9984placed. The default of @code{NULL} allows these to be placed in any 9985section. 9986@end deftypevr 9987 9988@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_VAR_PREFIX 9989Contains the prefix to be prepended to TLS control variable names. 9990The default of @code{NULL} uses a target-specific prefix. 9991@end deftypevr 9992 9993@deftypevr {Target Hook} {const char *} TARGET_EMUTLS_TMPL_PREFIX 9994Contains the prefix to be prepended to TLS initializer objects. The 9995default of @code{NULL} uses a target-specific prefix. 9996@end deftypevr 9997 9998@deftypefn {Target Hook} tree TARGET_EMUTLS_VAR_FIELDS (tree @var{type}, tree *@var{name}) 9999Specifies a function that generates the FIELD_DECLs for a TLS control 10000object type. @var{type} is the RECORD_TYPE the fields are for and 10001@var{name} should be filled with the structure tag, if the default of 10002@code{__emutls_object} is unsuitable. The default creates a type suitable 10003for libgcc's emulated TLS function. 10004@end deftypefn 10005 10006@deftypefn {Target Hook} tree TARGET_EMUTLS_VAR_INIT (tree @var{var}, tree @var{decl}, tree @var{tmpl_addr}) 10007Specifies a function that generates the CONSTRUCTOR to initialize a 10008TLS control object. @var{var} is the TLS control object, @var{decl} 10009is the TLS object and @var{tmpl_addr} is the address of the 10010initializer. The default initializes libgcc's emulated TLS control object. 10011@end deftypefn 10012 10013@deftypevr {Target Hook} bool TARGET_EMUTLS_VAR_ALIGN_FIXED 10014Specifies whether the alignment of TLS control variable objects is 10015fixed and should not be increased as some backends may do to optimize 10016single objects. The default is false. 10017@end deftypevr 10018 10019@deftypevr {Target Hook} bool TARGET_EMUTLS_DEBUG_FORM_TLS_ADDRESS 10020Specifies whether a DWARF @code{DW_OP_form_tls_address} location descriptor 10021may be used to describe emulated TLS control objects. 10022@end deftypevr 10023 10024@node MIPS Coprocessors 10025@section Defining coprocessor specifics for MIPS targets. 10026@cindex MIPS coprocessor-definition macros 10027 10028The MIPS specification allows MIPS implementations to have as many as 4 10029coprocessors, each with as many as 32 private registers. GCC supports 10030accessing these registers and transferring values between the registers 10031and memory using asm-ized variables. For example: 10032 10033@smallexample 10034 register unsigned int cp0count asm ("c0r1"); 10035 unsigned int d; 10036 10037 d = cp0count + 3; 10038@end smallexample 10039 10040(``c0r1'' is the default name of register 1 in coprocessor 0; alternate 10041names may be added as described below, or the default names may be 10042overridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.) 10043 10044Coprocessor registers are assumed to be epilogue-used; sets to them will 10045be preserved even if it does not appear that the register is used again 10046later in the function. 10047 10048Another note: according to the MIPS spec, coprocessor 1 (if present) is 10049the FPU@. One accesses COP1 registers through standard mips 10050floating-point support; they are not included in this mechanism. 10051 10052There is one macro used in defining the MIPS coprocessor interface which 10053you may want to override in subtargets; it is described below. 10054 10055@defmac ALL_COP_ADDITIONAL_REGISTER_NAMES 10056A comma-separated list (with leading comma) of pairs describing the 10057alternate names of coprocessor registers. The format of each entry should be 10058@smallexample 10059@{ @var{alternatename}, @var{register_number}@} 10060@end smallexample 10061Default: empty. 10062@end defmac 10063 10064@node PCH Target 10065@section Parameters for Precompiled Header Validity Checking 10066@cindex parameters, precompiled headers 10067 10068@deftypefn {Target Hook} {void *} TARGET_GET_PCH_VALIDITY (size_t *@var{sz}) 10069This hook returns a pointer to the data needed by 10070@code{TARGET_PCH_VALID_P} and sets 10071@samp{*@var{sz}} to the size of the data in bytes. 10072@end deftypefn 10073 10074@deftypefn {Target Hook} {const char *} TARGET_PCH_VALID_P (const void *@var{data}, size_t @var{sz}) 10075This hook checks whether the options used to create a PCH file are 10076compatible with the current settings. It returns @code{NULL} 10077if so and a suitable error message if not. Error messages will 10078be presented to the user and must be localized using @samp{_(@var{msg})}. 10079 10080@var{data} is the data that was returned by @code{TARGET_GET_PCH_VALIDITY} 10081when the PCH file was created and @var{sz} is the size of that data in bytes. 10082It's safe to assume that the data was created by the same version of the 10083compiler, so no format checking is needed. 10084 10085The default definition of @code{default_pch_valid_p} should be 10086suitable for most targets. 10087@end deftypefn 10088 10089@deftypefn {Target Hook} {const char *} TARGET_CHECK_PCH_TARGET_FLAGS (int @var{pch_flags}) 10090If this hook is nonnull, the default implementation of 10091@code{TARGET_PCH_VALID_P} will use it to check for compatible values 10092of @code{target_flags}. @var{pch_flags} specifies the value that 10093@code{target_flags} had when the PCH file was created. The return 10094value is the same as for @code{TARGET_PCH_VALID_P}. 10095@end deftypefn 10096 10097@deftypefn {Target Hook} void TARGET_PREPARE_PCH_SAVE (void) 10098Called before writing out a PCH file. If the target has some 10099garbage-collected data that needs to be in a particular state on PCH loads, 10100it can use this hook to enforce that state. Very few targets need 10101to do anything here. 10102@end deftypefn 10103 10104@node C++ ABI 10105@section C++ ABI parameters 10106@cindex parameters, c++ abi 10107 10108@deftypefn {Target Hook} tree TARGET_CXX_GUARD_TYPE (void) 10109Define this hook to override the integer type used for guard variables. 10110These are used to implement one-time construction of static objects. The 10111default is long_long_integer_type_node. 10112@end deftypefn 10113 10114@deftypefn {Target Hook} bool TARGET_CXX_GUARD_MASK_BIT (void) 10115This hook determines how guard variables are used. It should return 10116@code{false} (the default) if the first byte should be used. A return value of 10117@code{true} indicates that only the least significant bit should be used. 10118@end deftypefn 10119 10120@deftypefn {Target Hook} tree TARGET_CXX_GET_COOKIE_SIZE (tree @var{type}) 10121This hook returns the size of the cookie to use when allocating an array 10122whose elements have the indicated @var{type}. Assumes that it is already 10123known that a cookie is needed. The default is 10124@code{max(sizeof (size_t), alignof(type))}, as defined in section 2.7 of the 10125IA64/Generic C++ ABI@. 10126@end deftypefn 10127 10128@deftypefn {Target Hook} bool TARGET_CXX_COOKIE_HAS_SIZE (void) 10129This hook should return @code{true} if the element size should be stored in 10130array cookies. The default is to return @code{false}. 10131@end deftypefn 10132 10133@deftypefn {Target Hook} int TARGET_CXX_IMPORT_EXPORT_CLASS (tree @var{type}, int @var{import_export}) 10134If defined by a backend this hook allows the decision made to export 10135class @var{type} to be overruled. Upon entry @var{import_export} 10136will contain 1 if the class is going to be exported, @minus{}1 if it is going 10137to be imported and 0 otherwise. This function should return the 10138modified value and perform any other actions necessary to support the 10139backend's targeted operating system. 10140@end deftypefn 10141 10142@deftypefn {Target Hook} bool TARGET_CXX_CDTOR_RETURNS_THIS (void) 10143This hook should return @code{true} if constructors and destructors return 10144the address of the object created/destroyed. The default is to return 10145@code{false}. 10146@end deftypefn 10147 10148@deftypefn {Target Hook} bool TARGET_CXX_KEY_METHOD_MAY_BE_INLINE (void) 10149This hook returns true if the key method for a class (i.e., the method 10150which, if defined in the current translation unit, causes the virtual 10151table to be emitted) may be an inline function. Under the standard 10152Itanium C++ ABI the key method may be an inline function so long as 10153the function is not declared inline in the class definition. Under 10154some variants of the ABI, an inline function can never be the key 10155method. The default is to return @code{true}. 10156@end deftypefn 10157 10158@deftypefn {Target Hook} void TARGET_CXX_DETERMINE_CLASS_DATA_VISIBILITY (tree @var{decl}) 10159@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}. 10160@end deftypefn 10161 10162@deftypefn {Target Hook} bool TARGET_CXX_CLASS_DATA_ALWAYS_COMDAT (void) 10163This hook returns true (the default) if virtual tables and other 10164similar implicit class data objects are always COMDAT if they have 10165external linkage. If this hook returns false, then class data for 10166classes whose virtual table will be emitted in only one translation 10167unit will not be COMDAT. 10168@end deftypefn 10169 10170@deftypefn {Target Hook} bool TARGET_CXX_LIBRARY_RTTI_COMDAT (void) 10171This hook returns true (the default) if the RTTI information for 10172the basic types which is defined in the C++ runtime should always 10173be COMDAT, false if it should not be COMDAT. 10174@end deftypefn 10175 10176@deftypefn {Target Hook} bool TARGET_CXX_USE_AEABI_ATEXIT (void) 10177This hook returns true if @code{__aeabi_atexit} (as defined by the ARM EABI) 10178should be used to register static destructors when @option{-fuse-cxa-atexit} 10179is in effect. The default is to return false to use @code{__cxa_atexit}. 10180@end deftypefn 10181 10182@deftypefn {Target Hook} bool TARGET_CXX_USE_ATEXIT_FOR_CXA_ATEXIT (void) 10183This hook returns true if the target @code{atexit} function can be used 10184in the same manner as @code{__cxa_atexit} to register C++ static 10185destructors. This requires that @code{atexit}-registered functions in 10186shared libraries are run in the correct order when the libraries are 10187unloaded. The default is to return false. 10188@end deftypefn 10189 10190@deftypefn {Target Hook} void TARGET_CXX_ADJUST_CLASS_AT_DEFINITION (tree @var{type}) 10191@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). 10192@end deftypefn 10193 10194@deftypefn {Target Hook} tree TARGET_CXX_DECL_MANGLING_CONTEXT (const_tree @var{decl}) 10195Return target-specific mangling context of @var{decl} or @code{NULL_TREE}. 10196@end deftypefn 10197 10198@node Named Address Spaces 10199@section Adding support for named address spaces 10200@cindex named address spaces 10201 10202The draft technical report of the ISO/IEC JTC1 S22 WG14 N1275 10203standards committee, @cite{Programming Languages - C - Extensions to 10204support embedded processors}, specifies a syntax for embedded 10205processors to specify alternate address spaces. You can configure a 10206GCC port to support section 5.1 of the draft report to add support for 10207address spaces other than the default address space. These address 10208spaces are new keywords that are similar to the @code{volatile} and 10209@code{const} type attributes. 10210 10211Pointers to named address spaces can have a different size than 10212pointers to the generic address space. 10213 10214For example, the SPU port uses the @code{__ea} address space to refer 10215to memory in the host processor, rather than memory local to the SPU 10216processor. Access to memory in the @code{__ea} address space involves 10217issuing DMA operations to move data between the host processor and the 10218local processor memory address space. Pointers in the @code{__ea} 10219address space are either 32 bits or 64 bits based on the 10220@option{-mea32} or @option{-mea64} switches (native SPU pointers are 10221always 32 bits). 10222 10223Internally, address spaces are represented as a small integer in the 10224range 0 to 15 with address space 0 being reserved for the generic 10225address space. 10226 10227To register a named address space qualifier keyword with the C front end, 10228the target may call the @code{c_register_addr_space} routine. For example, 10229the SPU port uses the following to declare @code{__ea} as the keyword for 10230named address space #1: 10231@smallexample 10232#define ADDR_SPACE_EA 1 10233c_register_addr_space ("__ea", ADDR_SPACE_EA); 10234@end smallexample 10235 10236@deftypefn {Target Hook} {enum machine_mode} TARGET_ADDR_SPACE_POINTER_MODE (addr_space_t @var{address_space}) 10237Define this to return the machine mode to use for pointers to 10238@var{address_space} if the target supports named address spaces. 10239The default version of this hook returns @code{ptr_mode} for the 10240generic address space only. 10241@end deftypefn 10242 10243@deftypefn {Target Hook} {enum machine_mode} TARGET_ADDR_SPACE_ADDRESS_MODE (addr_space_t @var{address_space}) 10244Define this to return the machine mode to use for addresses in 10245@var{address_space} if the target supports named address spaces. 10246The default version of this hook returns @code{Pmode} for the 10247generic address space only. 10248@end deftypefn 10249 10250@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_VALID_POINTER_MODE (enum machine_mode @var{mode}, addr_space_t @var{as}) 10251Define this to return nonzero if the port can handle pointers 10252with machine mode @var{mode} to address space @var{as}. This target 10253hook is the same as the @code{TARGET_VALID_POINTER_MODE} target hook, 10254except that it includes explicit named address space support. The default 10255version of this hook returns true for the modes returned by either the 10256@code{TARGET_ADDR_SPACE_POINTER_MODE} or @code{TARGET_ADDR_SPACE_ADDRESS_MODE} 10257target hooks for the given address space. 10258@end deftypefn 10259 10260@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}) 10261Define this to return true if @var{exp} is a valid address for mode 10262@var{mode} in the named address space @var{as}. The @var{strict} 10263parameter says whether strict addressing is in effect after reload has 10264finished. This target hook is the same as the 10265@code{TARGET_LEGITIMATE_ADDRESS_P} target hook, except that it includes 10266explicit named address space support. 10267@end deftypefn 10268 10269@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}) 10270Define this to modify an invalid address @var{x} to be a valid address 10271with mode @var{mode} in the named address space @var{as}. This target 10272hook is the same as the @code{TARGET_LEGITIMIZE_ADDRESS} target hook, 10273except that it includes explicit named address space support. 10274@end deftypefn 10275 10276@deftypefn {Target Hook} bool TARGET_ADDR_SPACE_SUBSET_P (addr_space_t @var{subset}, addr_space_t @var{superset}) 10277Define this to return whether the @var{subset} named address space is 10278contained within the @var{superset} named address space. Pointers to 10279a named address space that is a subset of another named address space 10280will be converted automatically without a cast if used together in 10281arithmetic operations. Pointers to a superset address space can be 10282converted to pointers to a subset address space via explicit casts. 10283@end deftypefn 10284 10285@deftypefn {Target Hook} rtx TARGET_ADDR_SPACE_CONVERT (rtx @var{op}, tree @var{from_type}, tree @var{to_type}) 10286Define this to convert the pointer expression represented by the RTL 10287@var{op} with type @var{from_type} that points to a named address 10288space to a new pointer expression with type @var{to_type} that points 10289to a different named address space. When this hook it called, it is 10290guaranteed that one of the two address spaces is a subset of the other, 10291as determined by the @code{TARGET_ADDR_SPACE_SUBSET_P} target hook. 10292@end deftypefn 10293 10294@node Misc 10295@section Miscellaneous Parameters 10296@cindex parameters, miscellaneous 10297 10298@c prevent bad page break with this line 10299Here are several miscellaneous parameters. 10300 10301@defmac HAS_LONG_COND_BRANCH 10302Define this boolean macro to indicate whether or not your architecture 10303has conditional branches that can span all of memory. It is used in 10304conjunction with an optimization that partitions hot and cold basic 10305blocks into separate sections of the executable. If this macro is 10306set to false, gcc will convert any conditional branches that attempt 10307to cross between sections into unconditional branches or indirect jumps. 10308@end defmac 10309 10310@defmac HAS_LONG_UNCOND_BRANCH 10311Define this boolean macro to indicate whether or not your architecture 10312has unconditional branches that can span all of memory. It is used in 10313conjunction with an optimization that partitions hot and cold basic 10314blocks into separate sections of the executable. If this macro is 10315set to false, gcc will convert any unconditional branches that attempt 10316to cross between sections into indirect jumps. 10317@end defmac 10318 10319@defmac CASE_VECTOR_MODE 10320An alias for a machine mode name. This is the machine mode that 10321elements of a jump-table should have. 10322@end defmac 10323 10324@defmac CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 10325Optional: return the preferred mode for an @code{addr_diff_vec} 10326when the minimum and maximum offset are known. If you define this, 10327it enables extra code in branch shortening to deal with @code{addr_diff_vec}. 10328To make this work, you also have to define @code{INSN_ALIGN} and 10329make the alignment for @code{addr_diff_vec} explicit. 10330The @var{body} argument is provided so that the offset_unsigned and scale 10331flags can be updated. 10332@end defmac 10333 10334@defmac CASE_VECTOR_PC_RELATIVE 10335Define this macro to be a C expression to indicate when jump-tables 10336should contain relative addresses. You need not define this macro if 10337jump-tables never contain relative addresses, or jump-tables should 10338contain relative addresses only when @option{-fPIC} or @option{-fPIC} 10339is in effect. 10340@end defmac 10341 10342@deftypefn {Target Hook} {unsigned int} TARGET_CASE_VALUES_THRESHOLD (void) 10343This function return the smallest number of different values for which it 10344is best to use a jump-table instead of a tree of conditional branches. 10345The default is four for machines with a @code{casesi} instruction and 10346five otherwise. This is best for most machines. 10347@end deftypefn 10348 10349@defmac CASE_USE_BIT_TESTS 10350Define this macro to be a C expression to indicate whether C switch 10351statements may be implemented by a sequence of bit tests. This is 10352advantageous on processors that can efficiently implement left shift 10353of 1 by the number of bits held in a register, but inappropriate on 10354targets that would require a loop. By default, this macro returns 10355@code{true} if the target defines an @code{ashlsi3} pattern, and 10356@code{false} otherwise. 10357@end defmac 10358 10359@defmac WORD_REGISTER_OPERATIONS 10360Define this macro if operations between registers with integral mode 10361smaller than a word are always performed on the entire register. 10362Most RISC machines have this property and most CISC machines do not. 10363@end defmac 10364 10365@defmac LOAD_EXTEND_OP (@var{mem_mode}) 10366Define this macro to be a C expression indicating when insns that read 10367memory in @var{mem_mode}, an integral mode narrower than a word, set the 10368bits outside of @var{mem_mode} to be either the sign-extension or the 10369zero-extension of the data read. Return @code{SIGN_EXTEND} for values 10370of @var{mem_mode} for which the 10371insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 10372@code{UNKNOWN} for other modes. 10373 10374This macro is not called with @var{mem_mode} non-integral or with a width 10375greater than or equal to @code{BITS_PER_WORD}, so you may return any 10376value in this case. Do not define this macro if it would always return 10377@code{UNKNOWN}. On machines where this macro is defined, you will normally 10378define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 10379 10380You may return a non-@code{UNKNOWN} value even if for some hard registers 10381the sign extension is not performed, if for the @code{REGNO_REG_CLASS} 10382of these hard registers @code{CANNOT_CHANGE_MODE_CLASS} returns nonzero 10383when the @var{from} mode is @var{mem_mode} and the @var{to} mode is any 10384integral mode larger than this but not larger than @code{word_mode}. 10385 10386You must return @code{UNKNOWN} if for some hard registers that allow this 10387mode, @code{CANNOT_CHANGE_MODE_CLASS} says that they cannot change to 10388@code{word_mode}, but that they can change to another integral mode that 10389is larger then @var{mem_mode} but still smaller than @code{word_mode}. 10390@end defmac 10391 10392@defmac SHORT_IMMEDIATES_SIGN_EXTEND 10393Define this macro if loading short immediate values into registers sign 10394extends. 10395@end defmac 10396 10397@defmac FIXUNS_TRUNC_LIKE_FIX_TRUNC 10398Define this macro if the same instructions that convert a floating 10399point number to a signed fixed point number also convert validly to an 10400unsigned one. 10401@end defmac 10402 10403@deftypefn {Target Hook} {unsigned int} TARGET_MIN_DIVISIONS_FOR_RECIP_MUL (enum machine_mode @var{mode}) 10404When @option{-ffast-math} is in effect, GCC tries to optimize 10405divisions by the same divisor, by turning them into multiplications by 10406the reciprocal. This target hook specifies the minimum number of divisions 10407that should be there for GCC to perform the optimization for a variable 10408of mode @var{mode}. The default implementation returns 3 if the machine 10409has an instruction for the division, and 2 if it does not. 10410@end deftypefn 10411 10412@defmac MOVE_MAX 10413The maximum number of bytes that a single instruction can move quickly 10414between memory and registers or between two memory locations. 10415@end defmac 10416 10417@defmac MAX_MOVE_MAX 10418The maximum number of bytes that a single instruction can move quickly 10419between memory and registers or between two memory locations. If this 10420is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 10421constant value that is the largest value that @code{MOVE_MAX} can have 10422at run-time. 10423@end defmac 10424 10425@defmac SHIFT_COUNT_TRUNCATED 10426A C expression that is nonzero if on this machine the number of bits 10427actually used for the count of a shift operation is equal to the number 10428of bits needed to represent the size of the object being shifted. When 10429this macro is nonzero, the compiler will assume that it is safe to omit 10430a sign-extend, zero-extend, and certain bitwise `and' instructions that 10431truncates the count of a shift operation. On machines that have 10432instructions that act on bit-fields at variable positions, which may 10433include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 10434also enables deletion of truncations of the values that serve as 10435arguments to bit-field instructions. 10436 10437If both types of instructions truncate the count (for shifts) and 10438position (for bit-field operations), or if no variable-position bit-field 10439instructions exist, you should define this macro. 10440 10441However, on some machines, such as the 80386 and the 680x0, truncation 10442only applies to shift operations and not the (real or pretended) 10443bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 10444such machines. Instead, add patterns to the @file{md} file that include 10445the implied truncation of the shift instructions. 10446 10447You need not define this macro if it would always have the value of zero. 10448@end defmac 10449 10450@anchor{TARGET_SHIFT_TRUNCATION_MASK} 10451@deftypefn {Target Hook} {unsigned HOST_WIDE_INT} TARGET_SHIFT_TRUNCATION_MASK (enum machine_mode @var{mode}) 10452This function describes how the standard shift patterns for @var{mode} 10453deal with shifts by negative amounts or by more than the width of the mode. 10454@xref{shift patterns}. 10455 10456On many machines, the shift patterns will apply a mask @var{m} to the 10457shift count, meaning that a fixed-width shift of @var{x} by @var{y} is 10458equivalent to an arbitrary-width shift of @var{x} by @var{y & m}. If 10459this is true for mode @var{mode}, the function should return @var{m}, 10460otherwise it should return 0. A return value of 0 indicates that no 10461particular behavior is guaranteed. 10462 10463Note that, unlike @code{SHIFT_COUNT_TRUNCATED}, this function does 10464@emph{not} apply to general shift rtxes; it applies only to instructions 10465that are generated by the named shift patterns. 10466 10467The default implementation of this function returns 10468@code{GET_MODE_BITSIZE (@var{mode}) - 1} if @code{SHIFT_COUNT_TRUNCATED} 10469and 0 otherwise. This definition is always safe, but if 10470@code{SHIFT_COUNT_TRUNCATED} is false, and some shift patterns 10471nevertheless truncate the shift count, you may get better code 10472by overriding it. 10473@end deftypefn 10474 10475@defmac TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 10476A C expression which is nonzero if on this machine it is safe to 10477``convert'' an integer of @var{inprec} bits to one of @var{outprec} 10478bits (where @var{outprec} is smaller than @var{inprec}) by merely 10479operating on it as if it had only @var{outprec} bits. 10480 10481On many machines, this expression can be 1. 10482 10483@c rearranged this, removed the phrase "it is reported that". this was 10484@c to fix an overfull hbox. --mew 10feb93 10485When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 10486modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 10487If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 10488such cases may improve things. 10489@end defmac 10490 10491@deftypefn {Target Hook} int TARGET_MODE_REP_EXTENDED (enum machine_mode @var{mode}, enum machine_mode @var{rep_mode}) 10492The representation of an integral mode can be such that the values 10493are always extended to a wider integral mode. Return 10494@code{SIGN_EXTEND} if values of @var{mode} are represented in 10495sign-extended form to @var{rep_mode}. Return @code{UNKNOWN} 10496otherwise. (Currently, none of the targets use zero-extended 10497representation this way so unlike @code{LOAD_EXTEND_OP}, 10498@code{TARGET_MODE_REP_EXTENDED} is expected to return either 10499@code{SIGN_EXTEND} or @code{UNKNOWN}. Also no target extends 10500@var{mode} to @var{rep_mode} so that @var{rep_mode} is not the next 10501widest integral mode and currently we take advantage of this fact.) 10502 10503Similarly to @code{LOAD_EXTEND_OP} you may return a non-@code{UNKNOWN} 10504value even if the extension is not performed on certain hard registers 10505as long as for the @code{REGNO_REG_CLASS} of these hard registers 10506@code{CANNOT_CHANGE_MODE_CLASS} returns nonzero. 10507 10508Note that @code{TARGET_MODE_REP_EXTENDED} and @code{LOAD_EXTEND_OP} 10509describe two related properties. If you define 10510@code{TARGET_MODE_REP_EXTENDED (mode, word_mode)} you probably also want 10511to define @code{LOAD_EXTEND_OP (mode)} to return the same type of 10512extension. 10513 10514In order to enforce the representation of @code{mode}, 10515@code{TRULY_NOOP_TRUNCATION} should return false when truncating to 10516@code{mode}. 10517@end deftypefn 10518 10519@defmac STORE_FLAG_VALUE 10520A C expression describing the value returned by a comparison operator 10521with an integral mode and stored by a store-flag instruction 10522(@samp{cstore@var{mode}4}) when the condition is true. This description must 10523apply to @emph{all} the @samp{cstore@var{mode}4} patterns and all the 10524comparison operators whose results have a @code{MODE_INT} mode. 10525 10526A value of 1 or @minus{}1 means that the instruction implementing the 10527comparison operator returns exactly 1 or @minus{}1 when the comparison is true 10528and 0 when the comparison is false. Otherwise, the value indicates 10529which bits of the result are guaranteed to be 1 when the comparison is 10530true. This value is interpreted in the mode of the comparison 10531operation, which is given by the mode of the first operand in the 10532@samp{cstore@var{mode}4} pattern. Either the low bit or the sign bit of 10533@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 10534the compiler. 10535 10536If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 10537generate code that depends only on the specified bits. It can also 10538replace comparison operators with equivalent operations if they cause 10539the required bits to be set, even if the remaining bits are undefined. 10540For example, on a machine whose comparison operators return an 10541@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 10542@samp{0x80000000}, saying that just the sign bit is relevant, the 10543expression 10544 10545@smallexample 10546(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 10547@end smallexample 10548 10549@noindent 10550can be converted to 10551 10552@smallexample 10553(ashift:SI @var{x} (const_int @var{n})) 10554@end smallexample 10555 10556@noindent 10557where @var{n} is the appropriate shift count to move the bit being 10558tested into the sign bit. 10559 10560There is no way to describe a machine that always sets the low-order bit 10561for a true value, but does not guarantee the value of any other bits, 10562but we do not know of any machine that has such an instruction. If you 10563are trying to port GCC to such a machine, include an instruction to 10564perform a logical-and of the result with 1 in the pattern for the 10565comparison operators and let us know at @email{gcc@@gcc.gnu.org}. 10566 10567Often, a machine will have multiple instructions that obtain a value 10568from a comparison (or the condition codes). Here are rules to guide the 10569choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 10570to be used: 10571 10572@itemize @bullet 10573@item 10574Use the shortest sequence that yields a valid definition for 10575@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 10576``normalize'' the value (convert it to, e.g., 1 or 0) than for the 10577comparison operators to do so because there may be opportunities to 10578combine the normalization with other operations. 10579 10580@item 10581For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 10582slightly preferred on machines with expensive jumps and 1 preferred on 10583other machines. 10584 10585@item 10586As a second choice, choose a value of @samp{0x80000001} if instructions 10587exist that set both the sign and low-order bits but do not define the 10588others. 10589 10590@item 10591Otherwise, use a value of @samp{0x80000000}. 10592@end itemize 10593 10594Many machines can produce both the value chosen for 10595@code{STORE_FLAG_VALUE} and its negation in the same number of 10596instructions. On those machines, you should also define a pattern for 10597those cases, e.g., one matching 10598 10599@smallexample 10600(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 10601@end smallexample 10602 10603Some machines can also perform @code{and} or @code{plus} operations on 10604condition code values with less instructions than the corresponding 10605@samp{cstore@var{mode}4} insn followed by @code{and} or @code{plus}. On those 10606machines, define the appropriate patterns. Use the names @code{incscc} 10607and @code{decscc}, respectively, for the patterns which perform 10608@code{plus} or @code{minus} operations on condition code values. See 10609@file{rs6000.md} for some examples. The GNU Superoptimizer can be used to 10610find such instruction sequences on other machines. 10611 10612If this macro is not defined, the default value, 1, is used. You need 10613not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 10614instructions, or if the value generated by these instructions is 1. 10615@end defmac 10616 10617@defmac FLOAT_STORE_FLAG_VALUE (@var{mode}) 10618A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 10619returned when comparison operators with floating-point results are true. 10620Define this macro on machines that have comparison operations that return 10621floating-point values. If there are no such operations, do not define 10622this macro. 10623@end defmac 10624 10625@defmac VECTOR_STORE_FLAG_VALUE (@var{mode}) 10626A C expression that gives a rtx representing the nonzero true element 10627for vector comparisons. The returned rtx should be valid for the inner 10628mode of @var{mode} which is guaranteed to be a vector mode. Define 10629this macro on machines that have vector comparison operations that 10630return a vector result. If there are no such operations, do not define 10631this macro. Typically, this macro is defined as @code{const1_rtx} or 10632@code{constm1_rtx}. This macro may return @code{NULL_RTX} to prevent 10633the compiler optimizing such vector comparison operations for the 10634given mode. 10635@end defmac 10636 10637@defmac CLZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 10638@defmacx CTZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 10639A C expression that indicates whether the architecture defines a value 10640for @code{clz} or @code{ctz} with a zero operand. 10641A result of @code{0} indicates the value is undefined. 10642If the value is defined for only the RTL expression, the macro should 10643evaluate to @code{1}; if the value applies also to the corresponding optab 10644entry (which is normally the case if it expands directly into 10645the corresponding RTL), then the macro should evaluate to @code{2}. 10646In the cases where the value is defined, @var{value} should be set to 10647this value. 10648 10649If this macro is not defined, the value of @code{clz} or 10650@code{ctz} at zero is assumed to be undefined. 10651 10652This macro must be defined if the target's expansion for @code{ffs} 10653relies on a particular value to get correct results. Otherwise it 10654is not necessary, though it may be used to optimize some corner cases, and 10655to provide a default expansion for the @code{ffs} optab. 10656 10657Note that regardless of this macro the ``definedness'' of @code{clz} 10658and @code{ctz} at zero do @emph{not} extend to the builtin functions 10659visible to the user. Thus one may be free to adjust the value at will 10660to match the target expansion of these operations without fear of 10661breaking the API@. 10662@end defmac 10663 10664@defmac Pmode 10665An alias for the machine mode for pointers. On most machines, define 10666this to be the integer mode corresponding to the width of a hardware 10667pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 10668On some machines you must define this to be one of the partial integer 10669modes, such as @code{PSImode}. 10670 10671The width of @code{Pmode} must be at least as large as the value of 10672@code{POINTER_SIZE}. If it is not equal, you must define the macro 10673@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 10674to @code{Pmode}. 10675@end defmac 10676 10677@defmac FUNCTION_MODE 10678An alias for the machine mode used for memory references to functions 10679being called, in @code{call} RTL expressions. On most CISC machines, 10680where an instruction can begin at any byte address, this should be 10681@code{QImode}. On most RISC machines, where all instructions have fixed 10682size and alignment, this should be a mode with the same size and alignment 10683as the machine instruction words - typically @code{SImode} or @code{HImode}. 10684@end defmac 10685 10686@defmac STDC_0_IN_SYSTEM_HEADERS 10687In normal operation, the preprocessor expands @code{__STDC__} to the 10688constant 1, to signify that GCC conforms to ISO Standard C@. On some 10689hosts, like Solaris, the system compiler uses a different convention, 10690where @code{__STDC__} is normally 0, but is 1 if the user specifies 10691strict conformance to the C Standard. 10692 10693Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 10694convention when processing system header files, but when processing user 10695files @code{__STDC__} will always expand to 1. 10696@end defmac 10697 10698@defmac NO_IMPLICIT_EXTERN_C 10699Define this macro if the system header files support C++ as well as C@. 10700This macro inhibits the usual method of using system header files in 10701C++, which is to pretend that the file's contents are enclosed in 10702@samp{extern "C" @{@dots{}@}}. 10703@end defmac 10704 10705@findex #pragma 10706@findex pragma 10707@defmac REGISTER_TARGET_PRAGMAS () 10708Define this macro if you want to implement any target-specific pragmas. 10709If defined, it is a C expression which makes a series of calls to 10710@code{c_register_pragma} or @code{c_register_pragma_with_expansion} 10711for each pragma. The macro may also do any 10712setup required for the pragmas. 10713 10714The primary reason to define this macro is to provide compatibility with 10715other compilers for the same target. In general, we discourage 10716definition of target-specific pragmas for GCC@. 10717 10718If the pragma can be implemented by attributes then you should consider 10719defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 10720 10721Preprocessor macros that appear on pragma lines are not expanded. All 10722@samp{#pragma} directives that do not match any registered pragma are 10723silently ignored, unless the user specifies @option{-Wunknown-pragmas}. 10724@end defmac 10725 10726@deftypefun void c_register_pragma (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 10727@deftypefunx void c_register_pragma_with_expansion (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 10728 10729Each call to @code{c_register_pragma} or 10730@code{c_register_pragma_with_expansion} establishes one pragma. The 10731@var{callback} routine will be called when the preprocessor encounters a 10732pragma of the form 10733 10734@smallexample 10735#pragma [@var{space}] @var{name} @dots{} 10736@end smallexample 10737 10738@var{space} is the case-sensitive namespace of the pragma, or 10739@code{NULL} to put the pragma in the global namespace. The callback 10740routine receives @var{pfile} as its first argument, which can be passed 10741on to cpplib's functions if necessary. You can lex tokens after the 10742@var{name} by calling @code{pragma_lex}. Tokens that are not read by the 10743callback will be silently ignored. The end of the line is indicated by 10744a token of type @code{CPP_EOF}. Macro expansion occurs on the 10745arguments of pragmas registered with 10746@code{c_register_pragma_with_expansion} but not on the arguments of 10747pragmas registered with @code{c_register_pragma}. 10748 10749Note that the use of @code{pragma_lex} is specific to the C and C++ 10750compilers. It will not work in the Java or Fortran compilers, or any 10751other language compilers for that matter. Thus if @code{pragma_lex} is going 10752to be called from target-specific code, it must only be done so when 10753building the C and C++ compilers. This can be done by defining the 10754variables @code{c_target_objs} and @code{cxx_target_objs} in the 10755target entry in the @file{config.gcc} file. These variables should name 10756the target-specific, language-specific object file which contains the 10757code that uses @code{pragma_lex}. Note it will also be necessary to add a 10758rule to the makefile fragment pointed to by @code{tmake_file} that shows 10759how to build this object file. 10760@end deftypefun 10761 10762@defmac HANDLE_PRAGMA_PACK_WITH_EXPANSION 10763Define this macro if macros should be expanded in the 10764arguments of @samp{#pragma pack}. 10765@end defmac 10766 10767@deftypevr {Target Hook} bool TARGET_HANDLE_PRAGMA_EXTERN_PREFIX 10768True if @code{#pragma extern_prefix} is to be supported. 10769@end deftypevr 10770 10771@defmac TARGET_DEFAULT_PACK_STRUCT 10772If your target requires a structure packing default other than 0 (meaning 10773the machine default), define this macro to the necessary value (in bytes). 10774This must be a value that would also be valid to use with 10775@samp{#pragma pack()} (that is, a small power of two). 10776@end defmac 10777 10778@defmac DOLLARS_IN_IDENTIFIERS 10779Define this macro to control use of the character @samp{$} in 10780identifier names for the C family of languages. 0 means @samp{$} is 10781not allowed by default; 1 means it is allowed. 1 is the default; 10782there is no need to define this macro in that case. 10783@end defmac 10784 10785@defmac NO_DOLLAR_IN_LABEL 10786Define this macro if the assembler does not accept the character 10787@samp{$} in label names. By default constructors and destructors in 10788G++ have @samp{$} in the identifiers. If this macro is defined, 10789@samp{.} is used instead. 10790@end defmac 10791 10792@defmac NO_DOT_IN_LABEL 10793Define this macro if the assembler does not accept the character 10794@samp{.} in label names. By default constructors and destructors in G++ 10795have names that use @samp{.}. If this macro is defined, these names 10796are rewritten to avoid @samp{.}. 10797@end defmac 10798 10799@defmac INSN_SETS_ARE_DELAYED (@var{insn}) 10800Define this macro as a C expression that is nonzero if it is safe for the 10801delay slot scheduler to place instructions in the delay slot of @var{insn}, 10802even if they appear to use a resource set or clobbered in @var{insn}. 10803@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 10804every @code{call_insn} has this behavior. On machines where some @code{insn} 10805or @code{jump_insn} is really a function call and hence has this behavior, 10806you should define this macro. 10807 10808You need not define this macro if it would always return zero. 10809@end defmac 10810 10811@defmac INSN_REFERENCES_ARE_DELAYED (@var{insn}) 10812Define this macro as a C expression that is nonzero if it is safe for the 10813delay slot scheduler to place instructions in the delay slot of @var{insn}, 10814even if they appear to set or clobber a resource referenced in @var{insn}. 10815@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 10816some @code{insn} or @code{jump_insn} is really a function call and its operands 10817are registers whose use is actually in the subroutine it calls, you should 10818define this macro. Doing so allows the delay slot scheduler to move 10819instructions which copy arguments into the argument registers into the delay 10820slot of @var{insn}. 10821 10822You need not define this macro if it would always return zero. 10823@end defmac 10824 10825@defmac MULTIPLE_SYMBOL_SPACES 10826Define this macro as a C expression that is nonzero if, in some cases, 10827global symbols from one translation unit may not be bound to undefined 10828symbols in another translation unit without user intervention. For 10829instance, under Microsoft Windows symbols must be explicitly imported 10830from shared libraries (DLLs). 10831 10832You need not define this macro if it would always evaluate to zero. 10833@end defmac 10834 10835@deftypefn {Target Hook} tree TARGET_MD_ASM_CLOBBERS (tree @var{outputs}, tree @var{inputs}, tree @var{clobbers}) 10836This target hook should add to @var{clobbers} @code{STRING_CST} trees for 10837any hard regs the port wishes to automatically clobber for an asm. 10838It should return the result of the last @code{tree_cons} used to add a 10839clobber. The @var{outputs}, @var{inputs} and @var{clobber} lists are the 10840corresponding parameters to the asm and may be inspected to avoid 10841clobbering a register that is an input or output of the asm. You can use 10842@code{tree_overlaps_hard_reg_set}, declared in @file{tree.h}, to test 10843for overlap with regards to asm-declared registers. 10844@end deftypefn 10845 10846@defmac MATH_LIBRARY 10847Define this macro as a C string constant for the linker argument to link 10848in the system math library, minus the initial @samp{"-l"}, or 10849@samp{""} if the target does not have a 10850separate math library. 10851 10852You need only define this macro if the default of @samp{"m"} is wrong. 10853@end defmac 10854 10855@defmac LIBRARY_PATH_ENV 10856Define this macro as a C string constant for the environment variable that 10857specifies where the linker should look for libraries. 10858 10859You need only define this macro if the default of @samp{"LIBRARY_PATH"} 10860is wrong. 10861@end defmac 10862 10863@defmac TARGET_POSIX_IO 10864Define this macro if the target supports the following POSIX@ file 10865functions, access, mkdir and file locking with fcntl / F_SETLKW@. 10866Defining @code{TARGET_POSIX_IO} will enable the test coverage code 10867to use file locking when exiting a program, which avoids race conditions 10868if the program has forked. It will also create directories at run-time 10869for cross-profiling. 10870@end defmac 10871 10872@defmac MAX_CONDITIONAL_EXECUTE 10873 10874A C expression for the maximum number of instructions to execute via 10875conditional execution instructions instead of a branch. A value of 10876@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 108771 if it does use cc0. 10878@end defmac 10879 10880@defmac IFCVT_MODIFY_TESTS (@var{ce_info}, @var{true_expr}, @var{false_expr}) 10881Used if the target needs to perform machine-dependent modifications on the 10882conditionals used for turning basic blocks into conditionally executed code. 10883@var{ce_info} points to a data structure, @code{struct ce_if_block}, which 10884contains information about the currently processed blocks. @var{true_expr} 10885and @var{false_expr} are the tests that are used for converting the 10886then-block and the else-block, respectively. Set either @var{true_expr} or 10887@var{false_expr} to a null pointer if the tests cannot be converted. 10888@end defmac 10889 10890@defmac IFCVT_MODIFY_MULTIPLE_TESTS (@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) 10891Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated 10892if-statements into conditions combined by @code{and} and @code{or} operations. 10893@var{bb} contains the basic block that contains the test that is currently 10894being processed and about to be turned into a condition. 10895@end defmac 10896 10897@defmac IFCVT_MODIFY_INSN (@var{ce_info}, @var{pattern}, @var{insn}) 10898A C expression to modify the @var{PATTERN} of an @var{INSN} that is to 10899be converted to conditional execution format. @var{ce_info} points to 10900a data structure, @code{struct ce_if_block}, which contains information 10901about the currently processed blocks. 10902@end defmac 10903 10904@defmac IFCVT_MODIFY_FINAL (@var{ce_info}) 10905A C expression to perform any final machine dependent modifications in 10906converting code to conditional execution. The involved basic blocks 10907can be found in the @code{struct ce_if_block} structure that is pointed 10908to by @var{ce_info}. 10909@end defmac 10910 10911@defmac IFCVT_MODIFY_CANCEL (@var{ce_info}) 10912A C expression to cancel any machine dependent modifications in 10913converting code to conditional execution. The involved basic blocks 10914can be found in the @code{struct ce_if_block} structure that is pointed 10915to by @var{ce_info}. 10916@end defmac 10917 10918@defmac IFCVT_INIT_EXTRA_FIELDS (@var{ce_info}) 10919A C expression to initialize any extra fields in a @code{struct ce_if_block} 10920structure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. 10921@end defmac 10922 10923@defmac IFCVT_EXTRA_FIELDS 10924If defined, it should expand to a set of field declarations that will be 10925added to the @code{struct ce_if_block} structure. These should be initialized 10926by the @code{IFCVT_INIT_EXTRA_FIELDS} macro. 10927@end defmac 10928 10929@deftypefn {Target Hook} void TARGET_MACHINE_DEPENDENT_REORG (void) 10930If non-null, this hook performs a target-specific pass over the 10931instruction stream. The compiler will run it at all optimization levels, 10932just before the point at which it normally does delayed-branch scheduling. 10933 10934The exact purpose of the hook varies from target to target. Some use 10935it to do transformations that are necessary for correctness, such as 10936laying out in-function constant pools or avoiding hardware hazards. 10937Others use it as an opportunity to do some machine-dependent optimizations. 10938 10939You need not implement the hook if it has nothing to do. The default 10940definition is null. 10941@end deftypefn 10942 10943@deftypefn {Target Hook} void TARGET_INIT_BUILTINS (void) 10944Define this hook if you have any machine-specific built-in functions 10945that need to be defined. It should be a function that performs the 10946necessary setup. 10947 10948Machine specific built-in functions can be useful to expand special machine 10949instructions that would otherwise not normally be generated because 10950they have no equivalent in the source language (for example, SIMD vector 10951instructions or prefetch instructions). 10952 10953To create a built-in function, call the function 10954@code{lang_hooks.builtin_function} 10955which is defined by the language front end. You can use any type nodes set 10956up by @code{build_common_tree_nodes}; 10957only language front ends that use those two functions will call 10958@samp{TARGET_INIT_BUILTINS}. 10959@end deftypefn 10960 10961@deftypefn {Target Hook} tree TARGET_BUILTIN_DECL (unsigned @var{code}, bool @var{initialize_p}) 10962Define this hook if you have any machine-specific built-in functions 10963that need to be defined. It should be a function that returns the 10964builtin function declaration for the builtin function code @var{code}. 10965If there is no such builtin and it cannot be initialized at this time 10966if @var{initialize_p} is true the function should return @code{NULL_TREE}. 10967If @var{code} is out of range the function should return 10968@code{error_mark_node}. 10969@end deftypefn 10970 10971@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 10972 10973Expand a call to a machine specific built-in function that was set up by 10974@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 10975function call; the result should go to @var{target} if that is 10976convenient, and have mode @var{mode} if that is convenient. 10977@var{subtarget} may be used as the target for computing one of 10978@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 10979ignored. This function should return the result of the call to the 10980built-in function. 10981@end deftypefn 10982 10983@deftypefn {Target Hook} tree TARGET_RESOLVE_OVERLOADED_BUILTIN (unsigned int @var{loc}, tree @var{fndecl}, void *@var{arglist}) 10984Select a replacement for a machine specific built-in function that 10985was set up by @samp{TARGET_INIT_BUILTINS}. This is done 10986@emph{before} regular type checking, and so allows the target to 10987implement a crude form of function overloading. @var{fndecl} is the 10988declaration of the built-in function. @var{arglist} is the list of 10989arguments passed to the built-in function. The result is a 10990complete expression that implements the operation, usually 10991another @code{CALL_EXPR}. 10992@var{arglist} really has type @samp{VEC(tree,gc)*} 10993@end deftypefn 10994 10995@deftypefn {Target Hook} tree TARGET_FOLD_BUILTIN (tree @var{fndecl}, int @var{n_args}, tree *@var{argp}, bool @var{ignore}) 10996Fold a call to a machine specific built-in function that was set up by 10997@samp{TARGET_INIT_BUILTINS}. @var{fndecl} is the declaration of the 10998built-in function. @var{n_args} is the number of arguments passed to 10999the function; the arguments themselves are pointed to by @var{argp}. 11000The result is another tree containing a simplified expression for the 11001call's result. If @var{ignore} is true the value will be ignored. 11002@end deftypefn 11003 11004@deftypefn {Target Hook} {const char *} TARGET_INVALID_WITHIN_DOLOOP (const_rtx @var{insn}) 11005 11006Take an instruction in @var{insn} and return NULL if it is valid within a 11007low-overhead loop, otherwise return a string explaining why doloop 11008could not be applied. 11009 11010Many targets use special registers for low-overhead looping. For any 11011instruction that clobbers these this function should return a string indicating 11012the reason why the doloop could not be applied. 11013By default, the RTL loop optimizer does not use a present doloop pattern for 11014loops containing function calls or branch on table instructions. 11015@end deftypefn 11016 11017@defmac MD_CAN_REDIRECT_BRANCH (@var{branch1}, @var{branch2}) 11018 11019Take a branch insn in @var{branch1} and another in @var{branch2}. 11020Return true if redirecting @var{branch1} to the destination of 11021@var{branch2} is possible. 11022 11023On some targets, branches may have a limited range. Optimizing the 11024filling of delay slots can result in branches being redirected, and this 11025may in turn cause a branch offset to overflow. 11026@end defmac 11027 11028@deftypefn {Target Hook} bool TARGET_COMMUTATIVE_P (const_rtx @var{x}, int @var{outer_code}) 11029This target hook returns @code{true} if @var{x} is considered to be commutative. 11030Usually, this is just COMMUTATIVE_P (@var{x}), but the HP PA doesn't consider 11031PLUS to be commutative inside a MEM@. @var{outer_code} is the rtx code 11032of the enclosing rtl, if known, otherwise it is UNKNOWN. 11033@end deftypefn 11034 11035@deftypefn {Target Hook} rtx TARGET_ALLOCATE_INITIAL_VALUE (rtx @var{hard_reg}) 11036 11037When the initial value of a hard register has been copied in a pseudo 11038register, it is often not necessary to actually allocate another register 11039to this pseudo register, because the original hard register or a stack slot 11040it has been saved into can be used. @code{TARGET_ALLOCATE_INITIAL_VALUE} 11041is called at the start of register allocation once for each hard register 11042that had its initial value copied by using 11043@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 11044Possible values are @code{NULL_RTX}, if you don't want 11045to do any special allocation, a @code{REG} rtx---that would typically be 11046the hard register itself, if it is known not to be clobbered---or a 11047@code{MEM}. 11048If you are returning a @code{MEM}, this is only a hint for the allocator; 11049it might decide to use another register anyways. 11050You may use @code{current_function_leaf_function} in the hook, functions 11051that use @code{REG_N_SETS}, to determine if the hard 11052register in question will not be clobbered. 11053The default value of this hook is @code{NULL}, which disables any special 11054allocation. 11055@end deftypefn 11056 11057@deftypefn {Target Hook} int TARGET_UNSPEC_MAY_TRAP_P (const_rtx @var{x}, unsigned @var{flags}) 11058This target hook returns nonzero if @var{x}, an @code{unspec} or 11059@code{unspec_volatile} operation, might cause a trap. Targets can use 11060this hook to enhance precision of analysis for @code{unspec} and 11061@code{unspec_volatile} operations. You may call @code{may_trap_p_1} 11062to analyze inner elements of @var{x} in which case @var{flags} should be 11063passed along. 11064@end deftypefn 11065 11066@deftypefn {Target Hook} void TARGET_SET_CURRENT_FUNCTION (tree @var{decl}) 11067The compiler invokes this hook whenever it changes its current function 11068context (@code{cfun}). You can define this function if 11069the back end needs to perform any initialization or reset actions on a 11070per-function basis. For example, it may be used to implement function 11071attributes that affect register usage or code generation patterns. 11072The argument @var{decl} is the declaration for the new function context, 11073and may be null to indicate that the compiler has left a function context 11074and is returning to processing at the top level. 11075The default hook function does nothing. 11076 11077GCC sets @code{cfun} to a dummy function context during initialization of 11078some parts of the back end. The hook function is not invoked in this 11079situation; you need not worry about the hook being invoked recursively, 11080or when the back end is in a partially-initialized state. 11081@code{cfun} might be @code{NULL} to indicate processing at top level, 11082outside of any function scope. 11083@end deftypefn 11084 11085@defmac TARGET_OBJECT_SUFFIX 11086Define this macro to be a C string representing the suffix for object 11087files on your target machine. If you do not define this macro, GCC will 11088use @samp{.o} as the suffix for object files. 11089@end defmac 11090 11091@defmac TARGET_EXECUTABLE_SUFFIX 11092Define this macro to be a C string representing the suffix to be 11093automatically added to executable files on your target machine. If you 11094do not define this macro, GCC will use the null string as the suffix for 11095executable files. 11096@end defmac 11097 11098@defmac COLLECT_EXPORT_LIST 11099If defined, @code{collect2} will scan the individual object files 11100specified on its command line and create an export list for the linker. 11101Define this macro for systems like AIX, where the linker discards 11102object files that are not referenced from @code{main} and uses export 11103lists. 11104@end defmac 11105 11106@defmac MODIFY_JNI_METHOD_CALL (@var{mdecl}) 11107Define this macro to a C expression representing a variant of the 11108method call @var{mdecl}, if Java Native Interface (JNI) methods 11109must be invoked differently from other methods on your target. 11110For example, on 32-bit Microsoft Windows, JNI methods must be invoked using 11111the @code{stdcall} calling convention and this macro is then 11112defined as this expression: 11113 11114@smallexample 11115build_type_attribute_variant (@var{mdecl}, 11116 build_tree_list 11117 (get_identifier ("stdcall"), 11118 NULL)) 11119@end smallexample 11120@end defmac 11121 11122@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 11123This target hook returns @code{true} past the point in which new jump 11124instructions could be created. On machines that require a register for 11125every jump such as the SHmedia ISA of SH5, this point would typically be 11126reload, so this target hook should be defined to a function such as: 11127 11128@smallexample 11129static bool 11130cannot_modify_jumps_past_reload_p () 11131@{ 11132 return (reload_completed || reload_in_progress); 11133@} 11134@end smallexample 11135@end deftypefn 11136 11137@deftypefn {Target Hook} reg_class_t TARGET_BRANCH_TARGET_REGISTER_CLASS (void) 11138This target hook returns a register class for which branch target register 11139optimizations should be applied. All registers in this class should be 11140usable interchangeably. After reload, registers in this class will be 11141re-allocated and loads will be hoisted out of loops and be subjected 11142to inter-block scheduling. 11143@end deftypefn 11144 11145@deftypefn {Target Hook} bool TARGET_BRANCH_TARGET_REGISTER_CALLEE_SAVED (bool @var{after_prologue_epilogue_gen}) 11146Branch target register optimization will by default exclude callee-saved 11147registers 11148that are not already live during the current function; if this target hook 11149returns true, they will be included. The target code must than make sure 11150that all target registers in the class returned by 11151@samp{TARGET_BRANCH_TARGET_REGISTER_CLASS} that might need saving are 11152saved. @var{after_prologue_epilogue_gen} indicates if prologues and 11153epilogues have already been generated. Note, even if you only return 11154true when @var{after_prologue_epilogue_gen} is false, you still are likely 11155to have to make special provisions in @code{INITIAL_ELIMINATION_OFFSET} 11156to reserve space for caller-saved target registers. 11157@end deftypefn 11158 11159@deftypefn {Target Hook} bool TARGET_HAVE_CONDITIONAL_EXECUTION (void) 11160This target hook returns true if the target supports conditional execution. 11161This target hook is required only when the target has several different 11162modes and they have different conditional execution capability, such as ARM. 11163@end deftypefn 11164 11165@deftypefn {Target Hook} unsigned TARGET_LOOP_UNROLL_ADJUST (unsigned @var{nunroll}, struct loop *@var{loop}) 11166This target hook returns a new value for the number of times @var{loop} 11167should be unrolled. The parameter @var{nunroll} is the number of times 11168the loop is to be unrolled. The parameter @var{loop} is a pointer to 11169the loop, which is going to be checked for unrolling. This target hook 11170is required only when the target has special constraints like maximum 11171number of memory accesses. 11172@end deftypefn 11173 11174@defmac POWI_MAX_MULTS 11175If defined, this macro is interpreted as a signed integer C expression 11176that specifies the maximum number of floating point multiplications 11177that should be emitted when expanding exponentiation by an integer 11178constant inline. When this value is defined, exponentiation requiring 11179more than this number of multiplications is implemented by calling the 11180system library's @code{pow}, @code{powf} or @code{powl} routines. 11181The default value places no upper bound on the multiplication count. 11182@end defmac 11183 11184@deftypefn Macro void TARGET_EXTRA_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 11185This target hook should register any extra include files for the 11186target. The parameter @var{stdinc} indicates if normal include files 11187are present. The parameter @var{sysroot} is the system root directory. 11188The parameter @var{iprefix} is the prefix for the gcc directory. 11189@end deftypefn 11190 11191@deftypefn Macro void TARGET_EXTRA_PRE_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 11192This target hook should register any extra include files for the 11193target before any standard headers. The parameter @var{stdinc} 11194indicates if normal include files are present. The parameter 11195@var{sysroot} is the system root directory. The parameter 11196@var{iprefix} is the prefix for the gcc directory. 11197@end deftypefn 11198 11199@deftypefn Macro void TARGET_OPTF (char *@var{path}) 11200This target hook should register special include paths for the target. 11201The parameter @var{path} is the include to register. On Darwin 11202systems, this is used for Framework includes, which have semantics 11203that are different from @option{-I}. 11204@end deftypefn 11205 11206@defmac bool TARGET_USE_LOCAL_THUNK_ALIAS_P (tree @var{fndecl}) 11207This target macro returns @code{true} if it is safe to use a local alias 11208for a virtual function @var{fndecl} when constructing thunks, 11209@code{false} otherwise. By default, the macro returns @code{true} for all 11210functions, if a target supports aliases (i.e.@: defines 11211@code{ASM_OUTPUT_DEF}), @code{false} otherwise, 11212@end defmac 11213 11214@defmac TARGET_FORMAT_TYPES 11215If defined, this macro is the name of a global variable containing 11216target-specific format checking information for the @option{-Wformat} 11217option. The default is to have no target-specific format checks. 11218@end defmac 11219 11220@defmac TARGET_N_FORMAT_TYPES 11221If defined, this macro is the number of entries in 11222@code{TARGET_FORMAT_TYPES}. 11223@end defmac 11224 11225@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES 11226If defined, this macro is the name of a global variable containing 11227target-specific format overrides for the @option{-Wformat} option. The 11228default is to have no target-specific format overrides. If defined, 11229@code{TARGET_FORMAT_TYPES} must be defined, too. 11230@end defmac 11231 11232@defmac TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT 11233If defined, this macro specifies the number of entries in 11234@code{TARGET_OVERRIDES_FORMAT_ATTRIBUTES}. 11235@end defmac 11236 11237@defmac TARGET_OVERRIDES_FORMAT_INIT 11238If defined, this macro specifies the optional initialization 11239routine for target specific customizations of the system printf 11240and scanf formatter settings. 11241@end defmac 11242 11243@deftypevr {Target Hook} bool TARGET_RELAXED_ORDERING 11244If set to @code{true}, means that the target's memory model does not 11245guarantee that loads which do not depend on one another will access 11246main memory in the order of the instruction stream; if ordering is 11247important, an explicit memory barrier must be used. This is true of 11248many recent processors which implement a policy of ``relaxed,'' 11249``weak,'' or ``release'' memory consistency, such as Alpha, PowerPC, 11250and ia64. The default is @code{false}. 11251@end deftypevr 11252 11253@deftypefn {Target Hook} {const char *} TARGET_INVALID_ARG_FOR_UNPROTOTYPED_FN (const_tree @var{typelist}, const_tree @var{funcdecl}, const_tree @var{val}) 11254If defined, this macro returns the diagnostic message when it is 11255illegal to pass argument @var{val} to function @var{funcdecl} 11256with prototype @var{typelist}. 11257@end deftypefn 11258 11259@deftypefn {Target Hook} {const char *} TARGET_INVALID_CONVERSION (const_tree @var{fromtype}, const_tree @var{totype}) 11260If defined, this macro returns the diagnostic message when it is 11261invalid to convert from @var{fromtype} to @var{totype}, or @code{NULL} 11262if validity should be determined by the front end. 11263@end deftypefn 11264 11265@deftypefn {Target Hook} {const char *} TARGET_INVALID_UNARY_OP (int @var{op}, const_tree @var{type}) 11266If defined, this macro returns the diagnostic message when it is 11267invalid to apply operation @var{op} (where unary plus is denoted by 11268@code{CONVERT_EXPR}) to an operand of type @var{type}, or @code{NULL} 11269if validity should be determined by the front end. 11270@end deftypefn 11271 11272@deftypefn {Target Hook} {const char *} TARGET_INVALID_BINARY_OP (int @var{op}, const_tree @var{type1}, const_tree @var{type2}) 11273If defined, this macro returns the diagnostic message when it is 11274invalid to apply operation @var{op} to operands of types @var{type1} 11275and @var{type2}, or @code{NULL} if validity should be determined by 11276the front end. 11277@end deftypefn 11278 11279@deftypefn {Target Hook} {const char *} TARGET_INVALID_PARAMETER_TYPE (const_tree @var{type}) 11280If defined, this macro returns the diagnostic message when it is 11281invalid for functions to include parameters of type @var{type}, 11282or @code{NULL} if validity should be determined by 11283the front end. This is currently used only by the C and C++ front ends. 11284@end deftypefn 11285 11286@deftypefn {Target Hook} {const char *} TARGET_INVALID_RETURN_TYPE (const_tree @var{type}) 11287If defined, this macro returns the diagnostic message when it is 11288invalid for functions to have return type @var{type}, 11289or @code{NULL} if validity should be determined by 11290the front end. This is currently used only by the C and C++ front ends. 11291@end deftypefn 11292 11293@deftypefn {Target Hook} tree TARGET_PROMOTED_TYPE (const_tree @var{type}) 11294If defined, this target hook returns the type to which values of 11295@var{type} should be promoted when they appear in expressions, 11296analogous to the integer promotions, or @code{NULL_TREE} to use the 11297front end's normal promotion rules. This hook is useful when there are 11298target-specific types with special promotion rules. 11299This is currently used only by the C and C++ front ends. 11300@end deftypefn 11301 11302@deftypefn {Target Hook} tree TARGET_CONVERT_TO_TYPE (tree @var{type}, tree @var{expr}) 11303If defined, this hook returns the result of converting @var{expr} to 11304@var{type}. It should return the converted expression, 11305or @code{NULL_TREE} to apply the front end's normal conversion rules. 11306This hook is useful when there are target-specific types with special 11307conversion rules. 11308This is currently used only by the C and C++ front ends. 11309@end deftypefn 11310 11311@defmac TARGET_USE_JCR_SECTION 11312This macro determines whether to use the JCR section to register Java 11313classes. By default, TARGET_USE_JCR_SECTION is defined to 1 if both 11314SUPPORTS_WEAK and TARGET_HAVE_NAMED_SECTIONS are true, else 0. 11315@end defmac 11316 11317@defmac OBJC_JBLEN 11318This macro determines the size of the objective C jump buffer for the 11319NeXT runtime. By default, OBJC_JBLEN is defined to an innocuous value. 11320@end defmac 11321 11322@defmac LIBGCC2_UNWIND_ATTRIBUTE 11323Define this macro if any target-specific attributes need to be attached 11324to the functions in @file{libgcc} that provide low-level support for 11325call stack unwinding. It is used in declarations in @file{unwind-generic.h} 11326and the associated definitions of those functions. 11327@end defmac 11328 11329@deftypefn {Target Hook} void TARGET_UPDATE_STACK_BOUNDARY (void) 11330Define this macro to update the current function stack boundary if 11331necessary. 11332@end deftypefn 11333 11334@deftypefn {Target Hook} rtx TARGET_GET_DRAP_RTX (void) 11335This hook should return an rtx for Dynamic Realign Argument Pointer (DRAP) if a 11336different argument pointer register is needed to access the function's 11337argument list due to stack realignment. Return @code{NULL} if no DRAP 11338is needed. 11339@end deftypefn 11340 11341@deftypefn {Target Hook} bool TARGET_ALLOCATE_STACK_SLOTS_FOR_ARGS (void) 11342When optimization is disabled, this hook indicates whether or not 11343arguments should be allocated to stack slots. Normally, GCC allocates 11344stacks slots for arguments when not optimizing in order to make 11345debugging easier. However, when a function is declared with 11346@code{__attribute__((naked))}, there is no stack frame, and the compiler 11347cannot safely move arguments from the registers in which they are passed 11348to the stack. Therefore, this hook should return true in general, but 11349false for naked functions. The default implementation always returns true. 11350@end deftypefn 11351 11352@deftypevr {Target Hook} {unsigned HOST_WIDE_INT} TARGET_CONST_ANCHOR 11353On some architectures it can take multiple instructions to synthesize 11354a constant. If there is another constant already in a register that 11355is close enough in value then it is preferable that the new constant 11356is computed from this register using immediate addition or 11357subtraction. We accomplish this through CSE. Besides the value of 11358the constant we also add a lower and an upper constant anchor to the 11359available expressions. These are then queried when encountering new 11360constants. The anchors are computed by rounding the constant up and 11361down to a multiple of the value of @code{TARGET_CONST_ANCHOR}. 11362@code{TARGET_CONST_ANCHOR} should be the maximum positive value 11363accepted by immediate-add plus one. We currently assume that the 11364value of @code{TARGET_CONST_ANCHOR} is a power of 2. For example, on 11365MIPS, where add-immediate takes a 16-bit signed value, 11366@code{TARGET_CONST_ANCHOR} is set to @samp{0x8000}. The default value 11367is zero, which disables this optimization. @end deftypevr 11368 11369@deftypevr {Target Hook} {unsigned char} TARGET_ATOMIC_TEST_AND_SET_TRUEVAL 11370This 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}. 11371@end deftypevr 11372