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