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