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