tm.texi revision 103445
190075Sobrien@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002 290075Sobrien@c Free Software Foundation, Inc. 390075Sobrien@c This is part of the GCC manual. 490075Sobrien@c For copying conditions, see the file gcc.texi. 590075Sobrien 690075Sobrien@node Target Macros 790075Sobrien@chapter Target Description Macros and Functions 890075Sobrien@cindex machine description macros 990075Sobrien@cindex target description macros 1090075Sobrien@cindex macros, target description 1190075Sobrien@cindex @file{tm.h} macros 1290075Sobrien 1390075SobrienIn addition to the file @file{@var{machine}.md}, a machine description 1490075Sobrienincludes a C header file conventionally given the name 1590075Sobrien@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}. 1690075SobrienThe header file defines numerous macros that convey the information 1790075Sobrienabout the target machine that does not fit into the scheme of the 1890075Sobrien@file{.md} file. The file @file{tm.h} should be a link to 1990075Sobrien@file{@var{machine}.h}. The header file @file{config.h} includes 2090075Sobrien@file{tm.h} and most compiler source files include @file{config.h}. The 2190075Sobriensource file defines a variable @code{targetm}, which is a structure 2290075Sobriencontaining pointers to functions and data relating to the target 2390075Sobrienmachine. @file{@var{machine}.c} should also contain their definitions, 2490075Sobrienif they are not defined elsewhere in GCC, and other functions called 2590075Sobrienthrough the macros defined in the @file{.h} file. 2690075Sobrien 2790075Sobrien@menu 2890075Sobrien* Target Structure:: The @code{targetm} variable. 2990075Sobrien* Driver:: Controlling how the driver runs the compilation passes. 3090075Sobrien* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}. 3190075Sobrien* Per-Function Data:: Defining data structures for per-function information. 3290075Sobrien* Storage Layout:: Defining sizes and alignments of data. 3390075Sobrien* Type Layout:: Defining sizes and properties of basic user data types. 3490075Sobrien* Escape Sequences:: Defining the value of target character escape sequences 3590075Sobrien* Registers:: Naming and describing the hardware registers. 3690075Sobrien* Register Classes:: Defining the classes of hardware registers. 3790075Sobrien* Stack and Calling:: Defining which way the stack grows and by how much. 3890075Sobrien* Varargs:: Defining the varargs macros. 3990075Sobrien* Trampolines:: Code set up at run time to enter a nested function. 4090075Sobrien* Library Calls:: Controlling how library routines are implicitly called. 4190075Sobrien* Addressing Modes:: Defining addressing modes valid for memory operands. 4290075Sobrien* Condition Code:: Defining how insns update the condition code. 4390075Sobrien* Costs:: Defining relative costs of different operations. 4490075Sobrien* Scheduling:: Adjusting the behavior of the instruction scheduler. 4590075Sobrien* Sections:: Dividing storage into text, data, and other sections. 4690075Sobrien* PIC:: Macros for position independent code. 4790075Sobrien* Assembler Format:: Defining how to write insns and pseudo-ops to output. 4890075Sobrien* Debugging Info:: Defining the format of debugging output. 4990075Sobrien* Cross-compilation:: Handling floating point for cross-compilers. 5090075Sobrien* Mode Switching:: Insertion of mode-switching instructions. 5190075Sobrien* Target Attributes:: Defining target-specific uses of @code{__attribute__}. 5290075Sobrien* Misc:: Everything else. 5390075Sobrien@end menu 5490075Sobrien 5590075Sobrien@node Target Structure 5690075Sobrien@section The Global @code{targetm} Variable 5790075Sobrien@cindex target hooks 5890075Sobrien@cindex target functions 5990075Sobrien 6090075Sobrien@deftypevar {struct gcc_target} targetm 6190075SobrienThe target @file{.c} file must define the global @code{targetm} variable 6290075Sobrienwhich contains pointers to functions and data relating to the target 6390075Sobrienmachine. The variable is declared in @file{target.h}; 6490075Sobrien@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is 6590075Sobrienused to initialize the variable, and macros for the default initializers 6690075Sobrienfor elements of the structure. The @file{.c} file should override those 6790075Sobrienmacros for which the default definition is inappropriate. For example: 6890075Sobrien@smallexample 6990075Sobrien#include "target.h" 7090075Sobrien#include "target-def.h" 7190075Sobrien 7290075Sobrien/* @r{Initialize the GCC target structure.} */ 7390075Sobrien 7490075Sobrien#undef TARGET_COMP_TYPE_ATTRIBUTES 7590075Sobrien#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes 7690075Sobrien 7790075Sobrienstruct gcc_target targetm = TARGET_INITIALIZER; 7890075Sobrien@end smallexample 7990075Sobrien@end deftypevar 8090075Sobrien 8190075SobrienWhere a macro should be defined in the @file{.c} file in this manner to 8290075Sobrienform part of the @code{targetm} structure, it is documented below as a 8390075Sobrien``Target Hook'' with a prototype. Many macros will change in future 8490075Sobrienfrom being defined in the @file{.h} file to being part of the 8590075Sobrien@code{targetm} structure. 8690075Sobrien 8790075Sobrien@node Driver 8890075Sobrien@section Controlling the Compilation Driver, @file{gcc} 8990075Sobrien@cindex driver 9090075Sobrien@cindex controlling the compilation driver 9190075Sobrien 9290075Sobrien@c prevent bad page break with this line 9390075SobrienYou can control the compilation driver. 9490075Sobrien 9590075Sobrien@table @code 9690075Sobrien@findex SWITCH_TAKES_ARG 9790075Sobrien@item SWITCH_TAKES_ARG (@var{char}) 9890075SobrienA C expression which determines whether the option @option{-@var{char}} 9990075Sobrientakes arguments. The value should be the number of arguments that 10090075Sobrienoption takes--zero, for many options. 10190075Sobrien 10290075SobrienBy default, this macro is defined as 10390075Sobrien@code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options 10490075Sobrienproperly. You need not define @code{SWITCH_TAKES_ARG} unless you 10590075Sobrienwish to add additional options which take arguments. Any redefinition 10690075Sobrienshould call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for 10790075Sobrienadditional options. 10890075Sobrien 10990075Sobrien@findex WORD_SWITCH_TAKES_ARG 11090075Sobrien@item WORD_SWITCH_TAKES_ARG (@var{name}) 11190075SobrienA C expression which determines whether the option @option{-@var{name}} 11290075Sobrientakes arguments. The value should be the number of arguments that 11390075Sobrienoption takes--zero, for many options. This macro rather than 11490075Sobrien@code{SWITCH_TAKES_ARG} is used for multi-character option names. 11590075Sobrien 11690075SobrienBy default, this macro is defined as 11790075Sobrien@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options 11890075Sobrienproperly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you 11990075Sobrienwish to add additional options which take arguments. Any redefinition 12090075Sobrienshould call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for 12190075Sobrienadditional options. 12290075Sobrien 12390075Sobrien@findex SWITCH_CURTAILS_COMPILATION 12490075Sobrien@item SWITCH_CURTAILS_COMPILATION (@var{char}) 12590075SobrienA C expression which determines whether the option @option{-@var{char}} 12690075Sobrienstops compilation before the generation of an executable. The value is 12790075Sobrienboolean, nonzero if the option does stop an executable from being 12890075Sobriengenerated, zero otherwise. 12990075Sobrien 13090075SobrienBy default, this macro is defined as 13190075Sobrien@code{DEFAULT_SWITCH_CURTAILS_COMPILATION}, which handles the standard 13290075Sobrienoptions properly. You need not define 13390075Sobrien@code{SWITCH_CURTAILS_COMPILATION} unless you wish to add additional 13490075Sobrienoptions which affect the generation of an executable. Any redefinition 13590075Sobrienshould call @code{DEFAULT_SWITCH_CURTAILS_COMPILATION} and then check 13690075Sobrienfor additional options. 13790075Sobrien 13890075Sobrien@findex SWITCHES_NEED_SPACES 13990075Sobrien@item SWITCHES_NEED_SPACES 14090075SobrienA string-valued C expression which enumerates the options for which 14190075Sobrienthe linker needs a space between the option and its argument. 14290075Sobrien 14390075SobrienIf this macro is not defined, the default value is @code{""}. 14490075Sobrien 14590075Sobrien@findex TARGET_OPTION_TRANSLATE_TABLE 14690075Sobrien@item TARGET_OPTION_TRANSLATE_TABLE 14790075SobrienIf defined, a list of pairs of strings, the first of which is a 14890075Sobrienpotential command line target to the @file{gcc} driver program, and the 14990075Sobriensecond of which is a space-separated (tabs and other whitespace are not 15090075Sobriensupported) list of options with which to replace the first option. The 15190075Sobrientarget defining this list is responsible for assuring that the results 15290075Sobrienare valid. Replacement options may not be the @code{--opt} style, they 15390075Sobrienmust be the @code{-opt} style. It is the intention of this macro to 15490075Sobrienprovide a mechanism for substitution that affects the multilibs chosen, 15590075Sobriensuch as one option that enables many options, some of which select 15690075Sobrienmultilibs. Example nonsensical definition, where @code{-malt-abi}, 15790075Sobrien@code{-EB}, and @code{-mspoo} cause different multilibs to be chosen: 15890075Sobrien 159103445Skan@smallexample 16090075Sobrien#define TARGET_OPTION_TRANSLATE_TABLE \ 16190075Sobrien@{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \ 16290075Sobrien@{ "-compat", "-EB -malign=4 -mspoo" @} 163103445Skan@end smallexample 16490075Sobrien 16590075Sobrien@findex CPP_SPEC 16690075Sobrien@item CPP_SPEC 16790075SobrienA C string constant that tells the GCC driver program options to 16890075Sobrienpass to CPP@. It can also specify how to translate options you 16990075Sobriengive to GCC into options for GCC to pass to the CPP@. 17090075Sobrien 17190075SobrienDo not define this macro if it does not need to do anything. 17290075Sobrien 17390075Sobrien@findex CPLUSPLUS_CPP_SPEC 17490075Sobrien@item CPLUSPLUS_CPP_SPEC 17590075SobrienThis macro is just like @code{CPP_SPEC}, but is used for C++, rather 17690075Sobrienthan C@. If you do not define this macro, then the value of 17790075Sobrien@code{CPP_SPEC} (if any) will be used instead. 17890075Sobrien 17990075Sobrien@findex NO_BUILTIN_SIZE_TYPE 18090075Sobrien@item NO_BUILTIN_SIZE_TYPE 18190075SobrienIf this macro is defined, the preprocessor will not define the built-in macro 18290075Sobrien@code{__SIZE_TYPE__}. The macro @code{__SIZE_TYPE__} must then be defined 18390075Sobrienby @code{CPP_SPEC} instead. 18490075Sobrien 18590075SobrienThis should be defined if @code{SIZE_TYPE} depends on target dependent flags 18690075Sobrienwhich are not accessible to the preprocessor. Otherwise, it should not 18790075Sobrienbe defined. 18890075Sobrien 18990075Sobrien@findex NO_BUILTIN_PTRDIFF_TYPE 19090075Sobrien@item NO_BUILTIN_PTRDIFF_TYPE 19190075SobrienIf this macro is defined, the preprocessor will not define the built-in macro 19290075Sobrien@code{__PTRDIFF_TYPE__}. The macro @code{__PTRDIFF_TYPE__} must then be 19390075Sobriendefined by @code{CPP_SPEC} instead. 19490075Sobrien 19590075SobrienThis should be defined if @code{PTRDIFF_TYPE} depends on target dependent flags 19690075Sobrienwhich are not accessible to the preprocessor. Otherwise, it should not 19790075Sobrienbe defined. 19890075Sobrien 19990075Sobrien@findex NO_BUILTIN_WCHAR_TYPE 20090075Sobrien@item NO_BUILTIN_WCHAR_TYPE 20190075SobrienIf this macro is defined, the preprocessor will not define the built-in macro 20290075Sobrien@code{__WCHAR_TYPE__}. The macro @code{__WCHAR_TYPE__} must then be 20390075Sobriendefined by @code{CPP_SPEC} instead. 20490075Sobrien 20590075SobrienThis should be defined if @code{WCHAR_TYPE} depends on target dependent flags 20690075Sobrienwhich are not accessible to the preprocessor. Otherwise, it should not 20790075Sobrienbe defined. 20890075Sobrien 20990075Sobrien@findex NO_BUILTIN_WINT_TYPE 21090075Sobrien@item NO_BUILTIN_WINT_TYPE 21190075SobrienIf this macro is defined, the preprocessor will not define the built-in macro 21290075Sobrien@code{__WINT_TYPE__}. The macro @code{__WINT_TYPE__} must then be 21390075Sobriendefined by @code{CPP_SPEC} instead. 21490075Sobrien 21590075SobrienThis should be defined if @code{WINT_TYPE} depends on target dependent flags 21690075Sobrienwhich are not accessible to the preprocessor. Otherwise, it should not 21790075Sobrienbe defined. 21890075Sobrien 21990075Sobrien@findex CC1_SPEC 22090075Sobrien@item CC1_SPEC 22190075SobrienA C string constant that tells the GCC driver program options to 22290075Sobrienpass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language 22390075Sobrienfront ends. 22490075SobrienIt can also specify how to translate options you give to GCC into options 22590075Sobrienfor GCC to pass to front ends. 22690075Sobrien 22790075SobrienDo not define this macro if it does not need to do anything. 22890075Sobrien 22990075Sobrien@findex CC1PLUS_SPEC 23090075Sobrien@item CC1PLUS_SPEC 23190075SobrienA C string constant that tells the GCC driver program options to 23290075Sobrienpass to @code{cc1plus}. It can also specify how to translate options you 23390075Sobriengive to GCC into options for GCC to pass to the @code{cc1plus}. 23490075Sobrien 23590075SobrienDo not define this macro if it does not need to do anything. 23690075SobrienNote that everything defined in CC1_SPEC is already passed to 23790075Sobrien@code{cc1plus} so there is no need to duplicate the contents of 23890075SobrienCC1_SPEC in CC1PLUS_SPEC@. 23990075Sobrien 24090075Sobrien@findex ASM_SPEC 24190075Sobrien@item ASM_SPEC 24290075SobrienA C string constant that tells the GCC driver program options to 24390075Sobrienpass to the assembler. It can also specify how to translate options 24490075Sobrienyou give to GCC into options for GCC to pass to the assembler. 24590075SobrienSee the file @file{sun3.h} for an example of this. 24690075Sobrien 24790075SobrienDo not define this macro if it does not need to do anything. 24890075Sobrien 24990075Sobrien@findex ASM_FINAL_SPEC 25090075Sobrien@item ASM_FINAL_SPEC 25190075SobrienA C string constant that tells the GCC driver program how to 25290075Sobrienrun any programs which cleanup after the normal assembler. 25390075SobrienNormally, this is not needed. See the file @file{mips.h} for 25490075Sobrienan example of this. 25590075Sobrien 25690075SobrienDo not define this macro if it does not need to do anything. 25790075Sobrien 25890075Sobrien@findex LINK_SPEC 25990075Sobrien@item LINK_SPEC 26090075SobrienA C string constant that tells the GCC driver program options to 26190075Sobrienpass to the linker. It can also specify how to translate options you 26290075Sobriengive to GCC into options for GCC to pass to the linker. 26390075Sobrien 26490075SobrienDo not define this macro if it does not need to do anything. 26590075Sobrien 26690075Sobrien@findex LIB_SPEC 26790075Sobrien@item LIB_SPEC 26890075SobrienAnother C string constant used much like @code{LINK_SPEC}. The difference 26990075Sobrienbetween the two is that @code{LIB_SPEC} is used at the end of the 27090075Sobriencommand given to the linker. 27190075Sobrien 27290075SobrienIf this macro is not defined, a default is provided that 27390075Sobrienloads the standard C library from the usual place. See @file{gcc.c}. 27490075Sobrien 27590075Sobrien@findex LIBGCC_SPEC 27690075Sobrien@item LIBGCC_SPEC 27790075SobrienAnother C string constant that tells the GCC driver program 27890075Sobrienhow and when to place a reference to @file{libgcc.a} into the 27990075Sobrienlinker command line. This constant is placed both before and after 28090075Sobrienthe value of @code{LIB_SPEC}. 28190075Sobrien 28290075SobrienIf this macro is not defined, the GCC driver provides a default that 28390075Sobrienpasses the string @option{-lgcc} to the linker. 28490075Sobrien 28590075Sobrien@findex STARTFILE_SPEC 28690075Sobrien@item STARTFILE_SPEC 28790075SobrienAnother C string constant used much like @code{LINK_SPEC}. The 28890075Sobriendifference between the two is that @code{STARTFILE_SPEC} is used at 28990075Sobrienthe very beginning of the command given to the linker. 29090075Sobrien 29190075SobrienIf this macro is not defined, a default is provided that loads the 29290075Sobrienstandard C startup file from the usual place. See @file{gcc.c}. 29390075Sobrien 29490075Sobrien@findex ENDFILE_SPEC 29590075Sobrien@item ENDFILE_SPEC 29690075SobrienAnother C string constant used much like @code{LINK_SPEC}. The 29790075Sobriendifference between the two is that @code{ENDFILE_SPEC} is used at 29890075Sobrienthe very end of the command given to the linker. 29990075Sobrien 30090075SobrienDo not define this macro if it does not need to do anything. 30190075Sobrien 30290075Sobrien@findex THREAD_MODEL_SPEC 30390075Sobrien@item THREAD_MODEL_SPEC 30490075SobrienGCC @code{-v} will print the thread model GCC was configured to use. 30590075SobrienHowever, this doesn't work on platforms that are multilibbed on thread 30690075Sobrienmodels, such as AIX 4.3. On such platforms, define 30790075Sobrien@code{THREAD_MODEL_SPEC} such that it evaluates to a string without 30890075Sobrienblanks that names one of the recognized thread models. @code{%*}, the 30990075Sobriendefault value of this macro, will expand to the value of 31090075Sobrien@code{thread_file} set in @file{config.gcc}. 31190075Sobrien 31290075Sobrien@findex EXTRA_SPECS 31390075Sobrien@item EXTRA_SPECS 31490075SobrienDefine this macro to provide additional specifications to put in the 31590075Sobrien@file{specs} file that can be used in various specifications like 31690075Sobrien@code{CC1_SPEC}. 31790075Sobrien 31890075SobrienThe definition should be an initializer for an array of structures, 31990075Sobriencontaining a string constant, that defines the specification name, and a 32090075Sobrienstring constant that provides the specification. 32190075Sobrien 32290075SobrienDo not define this macro if it does not need to do anything. 32390075Sobrien 32490075Sobrien@code{EXTRA_SPECS} is useful when an architecture contains several 32590075Sobrienrelated targets, which have various @code{@dots{}_SPECS} which are similar 32690075Sobriento each other, and the maintainer would like one central place to keep 32790075Sobrienthese definitions. 32890075Sobrien 32990075SobrienFor example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to 33090075Sobriendefine either @code{_CALL_SYSV} when the System V calling sequence is 33190075Sobrienused or @code{_CALL_AIX} when the older AIX-based calling sequence is 33290075Sobrienused. 33390075Sobrien 33490075SobrienThe @file{config/rs6000/rs6000.h} target file defines: 33590075Sobrien 33690075Sobrien@example 33790075Sobrien#define EXTRA_SPECS \ 33890075Sobrien @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, 33990075Sobrien 34090075Sobrien#define CPP_SYS_DEFAULT "" 34190075Sobrien@end example 34290075Sobrien 34390075SobrienThe @file{config/rs6000/sysv.h} target file defines: 34490075Sobrien@smallexample 34590075Sobrien#undef CPP_SPEC 34690075Sobrien#define CPP_SPEC \ 34790075Sobrien"%@{posix: -D_POSIX_SOURCE @} \ 34890075Sobrien%@{mcall-sysv: -D_CALL_SYSV @} %@{mcall-aix: -D_CALL_AIX @} \ 34990075Sobrien%@{!mcall-sysv: %@{!mcall-aix: %(cpp_sysv_default) @}@} \ 35090075Sobrien%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" 35190075Sobrien 35290075Sobrien#undef CPP_SYSV_DEFAULT 35390075Sobrien#define CPP_SYSV_DEFAULT "-D_CALL_SYSV" 35490075Sobrien@end smallexample 35590075Sobrien 35690075Sobrienwhile the @file{config/rs6000/eabiaix.h} target file defines 35790075Sobrien@code{CPP_SYSV_DEFAULT} as: 35890075Sobrien 35990075Sobrien@smallexample 36090075Sobrien#undef CPP_SYSV_DEFAULT 36190075Sobrien#define CPP_SYSV_DEFAULT "-D_CALL_AIX" 36290075Sobrien@end smallexample 36390075Sobrien 36490075Sobrien@findex LINK_LIBGCC_SPECIAL 36590075Sobrien@item LINK_LIBGCC_SPECIAL 36690075SobrienDefine this macro if the driver program should find the library 36790075Sobrien@file{libgcc.a} itself and should not pass @option{-L} options to the 36890075Sobrienlinker. If you do not define this macro, the driver program will pass 36990075Sobrienthe argument @option{-lgcc} to tell the linker to do the search and will 37090075Sobrienpass @option{-L} options to it. 37190075Sobrien 37290075Sobrien@findex LINK_LIBGCC_SPECIAL_1 37390075Sobrien@item LINK_LIBGCC_SPECIAL_1 37490075SobrienDefine this macro if the driver program should find the library 37590075Sobrien@file{libgcc.a}. If you do not define this macro, the driver program will pass 37690075Sobrienthe argument @option{-lgcc} to tell the linker to do the search. 37790075SobrienThis macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it does 37890075Sobriennot affect @option{-L} options. 37990075Sobrien 38096263Sobrien@findex LINK_GCC_C_SEQUENCE_SPEC 38196263Sobrien@item LINK_GCC_C_SEQUENCE_SPEC 38296263SobrienThe sequence in which libgcc and libc are specified to the linker. 38396263SobrienBy default this is @code{%G %L %G}. 38496263Sobrien 38590075Sobrien@findex LINK_COMMAND_SPEC 38690075Sobrien@item LINK_COMMAND_SPEC 38790075SobrienA C string constant giving the complete command line need to execute the 38890075Sobrienlinker. When you do this, you will need to update your port each time a 38990075Sobrienchange is made to the link command line within @file{gcc.c}. Therefore, 39090075Sobriendefine this macro only if you need to completely redefine the command 39190075Sobrienline for invoking the linker and there is no other way to accomplish 39296263Sobrienthe effect you need. Overriding this macro may be avoidable by overriding 39396263Sobrien@code{LINK_GCC_C_SEQUENCE_SPEC} instead. 39490075Sobrien 39590075Sobrien@findex LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 39690075Sobrien@item LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 39790075SobrienA nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search 39890075Sobriendirectories from linking commands. Do not give it a nonzero value if 39990075Sobrienremoving duplicate search directories changes the linker's semantics. 40090075Sobrien 40190075Sobrien@findex MULTILIB_DEFAULTS 40290075Sobrien@item MULTILIB_DEFAULTS 40390075SobrienDefine this macro as a C expression for the initializer of an array of 40490075Sobrienstring to tell the driver program which options are defaults for this 40590075Sobrientarget and thus do not need to be handled specially when using 40690075Sobrien@code{MULTILIB_OPTIONS}. 40790075Sobrien 40890075SobrienDo not define this macro if @code{MULTILIB_OPTIONS} is not defined in 40990075Sobrienthe target makefile fragment or if none of the options listed in 41090075Sobrien@code{MULTILIB_OPTIONS} are set by default. 41190075Sobrien@xref{Target Fragment}. 41290075Sobrien 41390075Sobrien@findex RELATIVE_PREFIX_NOT_LINKDIR 41490075Sobrien@item RELATIVE_PREFIX_NOT_LINKDIR 41590075SobrienDefine this macro to tell @code{gcc} that it should only translate 41690075Sobriena @option{-B} prefix into a @option{-L} linker option if the prefix 41790075Sobrienindicates an absolute file name. 41890075Sobrien 41990075Sobrien@findex STANDARD_EXEC_PREFIX 42090075Sobrien@item STANDARD_EXEC_PREFIX 42190075SobrienDefine this macro as a C string constant if you wish to override the 42290075Sobrienstandard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to 42390075Sobrientry when searching for the executable files of the compiler. 42490075Sobrien 42590075Sobrien@findex MD_EXEC_PREFIX 42690075Sobrien@item MD_EXEC_PREFIX 42790075SobrienIf defined, this macro is an additional prefix to try after 42890075Sobrien@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched 42990075Sobrienwhen the @option{-b} option is used, or the compiler is built as a cross 43090075Sobriencompiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it 43190075Sobriento the list of directories used to find the assembler in @file{configure.in}. 43290075Sobrien 43390075Sobrien@findex STANDARD_STARTFILE_PREFIX 43490075Sobrien@item STANDARD_STARTFILE_PREFIX 43590075SobrienDefine this macro as a C string constant if you wish to override the 43690075Sobrienstandard choice of @file{/usr/local/lib/} as the default prefix to 43790075Sobrientry when searching for startup files such as @file{crt0.o}. 43890075Sobrien 43990075Sobrien@findex MD_STARTFILE_PREFIX 44090075Sobrien@item MD_STARTFILE_PREFIX 44190075SobrienIf defined, this macro supplies an additional prefix to try after the 44290075Sobrienstandard prefixes. @code{MD_EXEC_PREFIX} is not searched when the 44390075Sobrien@option{-b} option is used, or when the compiler is built as a cross 44490075Sobriencompiler. 44590075Sobrien 44690075Sobrien@findex MD_STARTFILE_PREFIX_1 44790075Sobrien@item MD_STARTFILE_PREFIX_1 44890075SobrienIf defined, this macro supplies yet another prefix to try after the 44990075Sobrienstandard prefixes. It is not searched when the @option{-b} option is 45090075Sobrienused, or when the compiler is built as a cross compiler. 45190075Sobrien 45290075Sobrien@findex INIT_ENVIRONMENT 45390075Sobrien@item INIT_ENVIRONMENT 45490075SobrienDefine this macro as a C string constant if you wish to set environment 45590075Sobrienvariables for programs called by the driver, such as the assembler and 45690075Sobrienloader. The driver passes the value of this macro to @code{putenv} to 45790075Sobrieninitialize the necessary environment variables. 45890075Sobrien 45990075Sobrien@findex LOCAL_INCLUDE_DIR 46090075Sobrien@item LOCAL_INCLUDE_DIR 46190075SobrienDefine this macro as a C string constant if you wish to override the 46290075Sobrienstandard choice of @file{/usr/local/include} as the default prefix to 46390075Sobrientry when searching for local header files. @code{LOCAL_INCLUDE_DIR} 46490075Sobriencomes before @code{SYSTEM_INCLUDE_DIR} in the search order. 46590075Sobrien 46690075SobrienCross compilers do not search either @file{/usr/local/include} or its 46790075Sobrienreplacement. 46890075Sobrien 46990075Sobrien@findex MODIFY_TARGET_NAME 47090075Sobrien@item MODIFY_TARGET_NAME 47190075SobrienDefine this macro if you with to define command-line switches that modify the 47290075Sobriendefault target name 47390075Sobrien 47490075SobrienFor each switch, you can include a string to be appended to the first 47590075Sobrienpart of the configuration name or a string to be deleted from the 47690075Sobrienconfiguration name, if present. The definition should be an initializer 47790075Sobrienfor an array of structures. Each array element should have three 47890075Sobrienelements: the switch name (a string constant, including the initial 47990075Sobriendash), one of the enumeration codes @code{ADD} or @code{DELETE} to 48090075Sobrienindicate whether the string should be inserted or deleted, and the string 48190075Sobriento be inserted or deleted (a string constant). 48290075Sobrien 48390075SobrienFor example, on a machine where @samp{64} at the end of the 48490075Sobrienconfiguration name denotes a 64-bit target and you want the @option{-32} 48590075Sobrienand @option{-64} switches to select between 32- and 64-bit targets, you would 48690075Sobriencode 48790075Sobrien 48890075Sobrien@smallexample 48990075Sobrien#define MODIFY_TARGET_NAME \ 49090075Sobrien @{ @{ "-32", DELETE, "64"@}, \ 49190075Sobrien @{"-64", ADD, "64"@}@} 49290075Sobrien@end smallexample 49390075Sobrien 49490075Sobrien 49590075Sobrien@findex SYSTEM_INCLUDE_DIR 49690075Sobrien@item SYSTEM_INCLUDE_DIR 49790075SobrienDefine this macro as a C string constant if you wish to specify a 49890075Sobriensystem-specific directory to search for header files before the standard 49990075Sobriendirectory. @code{SYSTEM_INCLUDE_DIR} comes before 50090075Sobrien@code{STANDARD_INCLUDE_DIR} in the search order. 50190075Sobrien 50290075SobrienCross compilers do not use this macro and do not search the directory 50390075Sobrienspecified. 50490075Sobrien 50590075Sobrien@findex STANDARD_INCLUDE_DIR 50690075Sobrien@item STANDARD_INCLUDE_DIR 50790075SobrienDefine this macro as a C string constant if you wish to override the 50890075Sobrienstandard choice of @file{/usr/include} as the default prefix to 50990075Sobrientry when searching for header files. 51090075Sobrien 51190075SobrienCross compilers do not use this macro and do not search either 51290075Sobrien@file{/usr/include} or its replacement. 51390075Sobrien 51490075Sobrien@findex STANDARD_INCLUDE_COMPONENT 51590075Sobrien@item STANDARD_INCLUDE_COMPONENT 51690075SobrienThe ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}. 51790075SobrienSee @code{INCLUDE_DEFAULTS}, below, for the description of components. 51890075SobrienIf you do not define this macro, no component is used. 51990075Sobrien 52090075Sobrien@findex INCLUDE_DEFAULTS 52190075Sobrien@item INCLUDE_DEFAULTS 52290075SobrienDefine this macro if you wish to override the entire default search path 52390075Sobrienfor include files. For a native compiler, the default search path 52490075Sobrienusually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, 52590075Sobrien@code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and 52690075Sobrien@code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} 52790075Sobrienand @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, 52890075Sobrienand specify private search areas for GCC@. The directory 52990075Sobrien@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. 53090075Sobrien 53190075SobrienThe definition should be an initializer for an array of structures. 53290075SobrienEach array element should have four elements: the directory name (a 53390075Sobrienstring constant), the component name (also a string constant), a flag 53490075Sobrienfor C++-only directories, 53590075Sobrienand a flag showing that the includes in the directory don't need to be 53690075Sobrienwrapped in @code{extern @samp{C}} when compiling C++. Mark the end of 53790075Sobrienthe array with a null element. 53890075Sobrien 53990075SobrienThe component name denotes what GNU package the include file is part of, 54090075Sobrienif any, in all upper-case letters. For example, it might be @samp{GCC} 54190075Sobrienor @samp{BINUTILS}. If the package is part of a vendor-supplied 54290075Sobrienoperating system, code the component name as @samp{0}. 54390075Sobrien 54490075SobrienFor example, here is the definition used for VAX/VMS: 54590075Sobrien 54690075Sobrien@example 54790075Sobrien#define INCLUDE_DEFAULTS \ 54890075Sobrien@{ \ 54990075Sobrien @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ 55090075Sobrien @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \ 55190075Sobrien @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \ 55290075Sobrien @{ ".", 0, 0, 0@}, \ 55390075Sobrien @{ 0, 0, 0, 0@} \ 55490075Sobrien@} 55590075Sobrien@end example 55690075Sobrien@end table 55790075Sobrien 55890075SobrienHere is the order of prefixes tried for exec files: 55990075Sobrien 56090075Sobrien@enumerate 56190075Sobrien@item 56290075SobrienAny prefixes specified by the user with @option{-B}. 56390075Sobrien 56490075Sobrien@item 56590075SobrienThe environment variable @code{GCC_EXEC_PREFIX}, if any. 56690075Sobrien 56790075Sobrien@item 56890075SobrienThe directories specified by the environment variable @code{COMPILER_PATH}. 56990075Sobrien 57090075Sobrien@item 57190075SobrienThe macro @code{STANDARD_EXEC_PREFIX}. 57290075Sobrien 57390075Sobrien@item 57490075Sobrien@file{/usr/lib/gcc/}. 57590075Sobrien 57690075Sobrien@item 57790075SobrienThe macro @code{MD_EXEC_PREFIX}, if any. 57890075Sobrien@end enumerate 57990075Sobrien 58090075SobrienHere is the order of prefixes tried for startfiles: 58190075Sobrien 58290075Sobrien@enumerate 58390075Sobrien@item 58490075SobrienAny prefixes specified by the user with @option{-B}. 58590075Sobrien 58690075Sobrien@item 58790075SobrienThe environment variable @code{GCC_EXEC_PREFIX}, if any. 58890075Sobrien 58990075Sobrien@item 59090075SobrienThe directories specified by the environment variable @code{LIBRARY_PATH} 59190075Sobrien(or port-specific name; native only, cross compilers do not use this). 59290075Sobrien 59390075Sobrien@item 59490075SobrienThe macro @code{STANDARD_EXEC_PREFIX}. 59590075Sobrien 59690075Sobrien@item 59790075Sobrien@file{/usr/lib/gcc/}. 59890075Sobrien 59990075Sobrien@item 60090075SobrienThe macro @code{MD_EXEC_PREFIX}, if any. 60190075Sobrien 60290075Sobrien@item 60390075SobrienThe macro @code{MD_STARTFILE_PREFIX}, if any. 60490075Sobrien 60590075Sobrien@item 60690075SobrienThe macro @code{STANDARD_STARTFILE_PREFIX}. 60790075Sobrien 60890075Sobrien@item 60990075Sobrien@file{/lib/}. 61090075Sobrien 61190075Sobrien@item 61290075Sobrien@file{/usr/lib/}. 61390075Sobrien@end enumerate 61490075Sobrien 61590075Sobrien@node Run-time Target 61690075Sobrien@section Run-time Target Specification 61790075Sobrien@cindex run-time target specification 61890075Sobrien@cindex predefined macros 61990075Sobrien@cindex target specifications 62090075Sobrien 62190075Sobrien@c prevent bad page break with this line 62290075SobrienHere are run-time target specifications. 62390075Sobrien 62490075Sobrien@table @code 62590075Sobrien@findex CPP_PREDEFINES 62690075Sobrien@item CPP_PREDEFINES 62790075SobrienDefine this to be a string constant containing @option{-D} options to 62890075Sobriendefine the predefined macros that identify this machine and system. 62990075SobrienThese macros will be predefined unless the @option{-ansi} option (or a 63090075Sobrien@option{-std} option for strict ISO C conformance) is specified. 63190075Sobrien 63290075SobrienIn addition, a parallel set of macros are predefined, whose names are 63390075Sobrienmade by appending @samp{__} at the beginning and at the end. These 63490075Sobrien@samp{__} macros are permitted by the ISO standard, so they are 63590075Sobrienpredefined regardless of whether @option{-ansi} or a @option{-std} option 63690075Sobrienis specified. 63790075Sobrien 63890075SobrienFor example, on the Sun, one can use the following value: 63990075Sobrien 64090075Sobrien@smallexample 64190075Sobrien"-Dmc68000 -Dsun -Dunix" 64290075Sobrien@end smallexample 64390075Sobrien 64490075SobrienThe result is to define the macros @code{__mc68000__}, @code{__sun__} 64590075Sobrienand @code{__unix__} unconditionally, and the macros @code{mc68000}, 64690075Sobrien@code{sun} and @code{unix} provided @option{-ansi} is not specified. 64790075Sobrien 64890075Sobrien@findex extern int target_flags 64990075Sobrien@item extern int target_flags; 65090075SobrienThis declaration should be present. 65190075Sobrien 65290075Sobrien@cindex optional hardware or system features 65390075Sobrien@cindex features, optional, in system conventions 65490075Sobrien@item TARGET_@dots{} 65590075SobrienThis series of macros is to allow compiler command arguments to 65690075Sobrienenable or disable the use of optional features of the target machine. 65790075SobrienFor example, one machine description serves both the 68000 and 65890075Sobrienthe 68020; a command argument tells the compiler whether it should 65990075Sobrienuse 68020-only instructions or not. This command argument works 66090075Sobrienby means of a macro @code{TARGET_68020} that tests a bit in 66190075Sobrien@code{target_flags}. 66290075Sobrien 66390075SobrienDefine a macro @code{TARGET_@var{featurename}} for each such option. 66490075SobrienIts definition should test a bit in @code{target_flags}. It is 66590075Sobrienrecommended that a helper macro @code{TARGET_MASK_@var{featurename}} 66690075Sobrienis defined for each bit-value to test, and used in 66790075Sobrien@code{TARGET_@var{featurename}} and @code{TARGET_SWITCHES}. For 66890075Sobrienexample: 66990075Sobrien 67090075Sobrien@smallexample 67190075Sobrien#define TARGET_MASK_68020 1 67290075Sobrien#define TARGET_68020 (target_flags & TARGET_MASK_68020) 67390075Sobrien@end smallexample 67490075Sobrien 67590075SobrienOne place where these macros are used is in the condition-expressions 67690075Sobrienof instruction patterns. Note how @code{TARGET_68020} appears 67790075Sobrienfrequently in the 68000 machine description file, @file{m68k.md}. 67890075SobrienAnother place they are used is in the definitions of the other 67990075Sobrienmacros in the @file{@var{machine}.h} file. 68090075Sobrien 68190075Sobrien@findex TARGET_SWITCHES 68290075Sobrien@item TARGET_SWITCHES 68390075SobrienThis macro defines names of command options to set and clear 68490075Sobrienbits in @code{target_flags}. Its definition is an initializer 68590075Sobrienwith a subgrouping for each command option. 68690075Sobrien 68790075SobrienEach subgrouping contains a string constant, that defines the option 68890075Sobrienname, a number, which contains the bits to set in 68990075Sobrien@code{target_flags}, and a second string which is the description 69090075Sobriendisplayed by @option{--help}. If the number is negative then the bits specified 69190075Sobrienby the number are cleared instead of being set. If the description 69290075Sobrienstring is present but empty, then no help information will be displayed 69390075Sobrienfor that option, but it will not count as an undocumented option. The 69490075Sobrienactual option name is made by appending @samp{-m} to the specified name. 69590075SobrienNon-empty description strings should be marked with @code{N_(@dots{})} for 69696263Sobrien@command{xgettext}. Please do not mark empty strings because the empty 69796263Sobrienstring is reserved by GNU gettext. @code{gettext("")} returns the header entry 69896263Sobrienof the message catalog with meta information, not the empty string. 69996263Sobrien 70096263SobrienIn addition to the description for @option{--help}, 70190075Sobrienmore detailed documentation for each option should be added to 70290075Sobrien@file{invoke.texi}. 70390075Sobrien 70490075SobrienOne of the subgroupings should have a null string. The number in 70590075Sobrienthis grouping is the default value for @code{target_flags}. Any 70690075Sobrientarget options act starting with that value. 70790075Sobrien 70890075SobrienHere is an example which defines @option{-m68000} and @option{-m68020} 70990075Sobrienwith opposite meanings, and picks the latter as the default: 71090075Sobrien 71190075Sobrien@smallexample 71290075Sobrien#define TARGET_SWITCHES \ 71390075Sobrien @{ @{ "68020", TARGET_MASK_68020, "" @}, \ 71490075Sobrien @{ "68000", -TARGET_MASK_68020, \ 71590075Sobrien N_("Compile for the 68000") @}, \ 71690075Sobrien @{ "", TARGET_MASK_68020, "" @}@} 71790075Sobrien@end smallexample 71890075Sobrien 71990075Sobrien@findex TARGET_OPTIONS 72090075Sobrien@item TARGET_OPTIONS 72190075SobrienThis macro is similar to @code{TARGET_SWITCHES} but defines names of command 72290075Sobrienoptions that have values. Its definition is an initializer with a 72390075Sobriensubgrouping for each command option. 72490075Sobrien 72590075SobrienEach subgrouping contains a string constant, that defines the fixed part 72696263Sobrienof the option name, the address of a variable, and a description string. 72796263SobrienNon-empty description strings should be marked with @code{N_(@dots{})} for 72896263Sobrien@command{xgettext}. Please do not mark empty strings because the empty 72996263Sobrienstring is reserved by GNU gettext. @code{gettext("")} returns the header entry 73096263Sobrienof the message catalog with meta information, not the empty string. 73196263Sobrien 73290075SobrienThe variable, type @code{char *}, is set to the variable part of the 73390075Sobriengiven option if the fixed part matches. The actual option name is made 73490075Sobrienby appending @samp{-m} to the specified name. Again, each option should 73590075Sobrienalso be documented in @file{invoke.texi}. 73690075Sobrien 73790075SobrienHere is an example which defines @option{-mshort-data-@var{number}}. If the 73890075Sobriengiven option is @option{-mshort-data-512}, the variable @code{m88k_short_data} 73990075Sobrienwill be set to the string @code{"512"}. 74090075Sobrien 74190075Sobrien@smallexample 74290075Sobrienextern char *m88k_short_data; 74390075Sobrien#define TARGET_OPTIONS \ 74490075Sobrien @{ @{ "short-data-", &m88k_short_data, \ 74590075Sobrien N_("Specify the size of the short data section") @} @} 74690075Sobrien@end smallexample 74790075Sobrien 74890075Sobrien@findex TARGET_VERSION 74990075Sobrien@item TARGET_VERSION 75090075SobrienThis macro is a C statement to print on @code{stderr} a string 75190075Sobriendescribing the particular machine description choice. Every machine 75290075Sobriendescription should define @code{TARGET_VERSION}. For example: 75390075Sobrien 75490075Sobrien@smallexample 75590075Sobrien#ifdef MOTOROLA 75690075Sobrien#define TARGET_VERSION \ 75790075Sobrien fprintf (stderr, " (68k, Motorola syntax)"); 75890075Sobrien#else 75990075Sobrien#define TARGET_VERSION \ 76090075Sobrien fprintf (stderr, " (68k, MIT syntax)"); 76190075Sobrien#endif 76290075Sobrien@end smallexample 76390075Sobrien 76490075Sobrien@findex OVERRIDE_OPTIONS 76590075Sobrien@item OVERRIDE_OPTIONS 76690075SobrienSometimes certain combinations of command options do not make sense on 76790075Sobriena particular target machine. You can define a macro 76890075Sobrien@code{OVERRIDE_OPTIONS} to take account of this. This macro, if 76990075Sobriendefined, is executed once just after all the command options have been 77090075Sobrienparsed. 77190075Sobrien 77290075SobrienDon't use this macro to turn on various extra optimizations for 77390075Sobrien@option{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. 77490075Sobrien 77590075Sobrien@findex OPTIMIZATION_OPTIONS 77690075Sobrien@item OPTIMIZATION_OPTIONS (@var{level}, @var{size}) 77790075SobrienSome machines may desire to change what optimizations are performed for 77890075Sobrienvarious optimization levels. This macro, if defined, is executed once 77990075Sobrienjust after the optimization level is determined and before the remainder 78090075Sobrienof the command options have been parsed. Values set in this macro are 78190075Sobrienused as the default values for the other command line options. 78290075Sobrien 78390075Sobrien@var{level} is the optimization level specified; 2 if @option{-O2} is 78490075Sobrienspecified, 1 if @option{-O} is specified, and 0 if neither is specified. 78590075Sobrien 78690075Sobrien@var{size} is nonzero if @option{-Os} is specified and zero otherwise. 78790075Sobrien 78890075SobrienYou should not use this macro to change options that are not 78990075Sobrienmachine-specific. These should uniformly selected by the same 79090075Sobrienoptimization level on all supported machines. Use this macro to enable 79190075Sobrienmachine-specific optimizations. 79290075Sobrien 79390075Sobrien@strong{Do not examine @code{write_symbols} in 79490075Sobrienthis macro!} The debugging options are not supposed to alter the 79590075Sobriengenerated code. 79690075Sobrien 79790075Sobrien@findex CAN_DEBUG_WITHOUT_FP 79890075Sobrien@item CAN_DEBUG_WITHOUT_FP 79990075SobrienDefine this macro if debugging can be performed even without a frame 80090075Sobrienpointer. If this macro is defined, GCC will turn on the 80190075Sobrien@option{-fomit-frame-pointer} option whenever @option{-O} is specified. 80290075Sobrien@end table 80390075Sobrien 80490075Sobrien@node Per-Function Data 80590075Sobrien@section Defining data structures for per-function information. 80690075Sobrien@cindex per-function data 80790075Sobrien@cindex data structures 80890075Sobrien 80990075SobrienIf the target needs to store information on a per-function basis, GCC 81090075Sobrienprovides a macro and a couple of variables to allow this. Note, just 81190075Sobrienusing statics to store the information is a bad idea, since GCC supports 81290075Sobriennested functions, so you can be halfway through encoding one function 81390075Sobrienwhen another one comes along. 81490075Sobrien 81590075SobrienGCC defines a data structure called @code{struct function} which 81690075Sobriencontains all of the data specific to an individual function. This 81790075Sobrienstructure contains a field called @code{machine} whose type is 81890075Sobrien@code{struct machine_function *}, which can be used by targets to point 81990075Sobriento their own specific data. 82090075Sobrien 82190075SobrienIf a target needs per-function specific data it should define the type 82290075Sobrien@code{struct machine_function} and also the macro 82390075Sobrien@code{INIT_EXPANDERS}. This macro should be used to initialize some or 82490075Sobrienall of the function pointers @code{init_machine_status}, 82590075Sobrien@code{free_machine_status} and @code{mark_machine_status}. These 82690075Sobrienpointers are explained below. 82790075Sobrien 82890075SobrienOne typical use of per-function, target specific data is to create an 82990075SobrienRTX to hold the register containing the function's return address. This 83090075SobrienRTX can then be used to implement the @code{__builtin_return_address} 83190075Sobrienfunction, for level 0. 83290075Sobrien 83390075SobrienNote---earlier implementations of GCC used a single data area to hold 83490075Sobrienall of the per-function information. Thus when processing of a nested 83590075Sobrienfunction began the old per-function data had to be pushed onto a 83690075Sobrienstack, and when the processing was finished, it had to be popped off the 83790075Sobrienstack. GCC used to provide function pointers called 83890075Sobrien@code{save_machine_status} and @code{restore_machine_status} to handle 83990075Sobrienthe saving and restoring of the target specific information. Since the 84090075Sobriensingle data area approach is no longer used, these pointers are no 84190075Sobrienlonger supported. 84290075Sobrien 84390075SobrienThe macro and function pointers are described below. 84490075Sobrien 84590075Sobrien@table @code 84690075Sobrien@findex INIT_EXPANDERS 84790075Sobrien@item INIT_EXPANDERS 84890075SobrienMacro called to initialize any target specific information. This macro 84990075Sobrienis called once per function, before generation of any RTL has begun. 85090075SobrienThe intention of this macro is to allow the initialization of the 85190075Sobrienfunction pointers below. 85290075Sobrien 85390075Sobrien@findex init_machine_status 85490075Sobrien@item init_machine_status 85590075SobrienThis is a @code{void (*)(struct function *)} function pointer. If this 85690075Sobrienpointer is non-@code{NULL} it will be called once per function, before function 85790075Sobriencompilation starts, in order to allow the target to perform any target 85890075Sobrienspecific initialization of the @code{struct function} structure. It is 85990075Sobrienintended that this would be used to initialize the @code{machine} of 86090075Sobrienthat structure. 86190075Sobrien 86290075Sobrien@findex free_machine_status 86390075Sobrien@item free_machine_status 86490075SobrienThis is a @code{void (*)(struct function *)} function pointer. If this 86590075Sobrienpointer is non-@code{NULL} it will be called once per function, after the 86690075Sobrienfunction has been compiled, in order to allow any memory allocated 86790075Sobrienduring the @code{init_machine_status} function call to be freed. 86890075Sobrien 86990075Sobrien@findex mark_machine_status 87090075Sobrien@item mark_machine_status 87190075SobrienThis is a @code{void (*)(struct function *)} function pointer. If this 87290075Sobrienpointer is non-@code{NULL} it will be called once per function in order to mark 87390075Sobrienany data items in the @code{struct machine_function} structure which 87490075Sobrienneed garbage collection. 87590075Sobrien 87690075Sobrien@end table 87790075Sobrien 87890075Sobrien@node Storage Layout 87990075Sobrien@section Storage Layout 88090075Sobrien@cindex storage layout 88190075Sobrien 88290075SobrienNote that the definitions of the macros in this table which are sizes or 88390075Sobrienalignments measured in bits do not need to be constant. They can be C 88490075Sobrienexpressions that refer to static variables, such as the @code{target_flags}. 88590075Sobrien@xref{Run-time Target}. 88690075Sobrien 88790075Sobrien@table @code 88890075Sobrien@findex BITS_BIG_ENDIAN 88990075Sobrien@item BITS_BIG_ENDIAN 89090075SobrienDefine this macro to have the value 1 if the most significant bit in a 89190075Sobrienbyte has the lowest number; otherwise define it to have the value zero. 89290075SobrienThis means that bit-field instructions count from the most significant 89390075Sobrienbit. If the machine has no bit-field instructions, then this must still 89490075Sobrienbe defined, but it doesn't matter which value it is defined to. This 89590075Sobrienmacro need not be a constant. 89690075Sobrien 89790075SobrienThis macro does not affect the way structure fields are packed into 89890075Sobrienbytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 89990075Sobrien 90090075Sobrien@findex BYTES_BIG_ENDIAN 90190075Sobrien@item BYTES_BIG_ENDIAN 90290075SobrienDefine this macro to have the value 1 if the most significant byte in a 90390075Sobrienword has the lowest number. This macro need not be a constant. 90490075Sobrien 90590075Sobrien@findex WORDS_BIG_ENDIAN 90690075Sobrien@item WORDS_BIG_ENDIAN 90790075SobrienDefine this macro to have the value 1 if, in a multiword object, the 90890075Sobrienmost significant word has the lowest number. This applies to both 90990075Sobrienmemory locations and registers; GCC fundamentally assumes that the 91090075Sobrienorder of words in memory is the same as the order in registers. This 91190075Sobrienmacro need not be a constant. 91290075Sobrien 91390075Sobrien@findex LIBGCC2_WORDS_BIG_ENDIAN 91490075Sobrien@item LIBGCC2_WORDS_BIG_ENDIAN 91590075SobrienDefine this macro if @code{WORDS_BIG_ENDIAN} is not constant. This must be a 91690075Sobrienconstant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be 91790075Sobrienused only when compiling @file{libgcc2.c}. Typically the value will be set 91890075Sobrienbased on preprocessor defines. 91990075Sobrien 92090075Sobrien@findex FLOAT_WORDS_BIG_ENDIAN 92190075Sobrien@item FLOAT_WORDS_BIG_ENDIAN 92290075SobrienDefine this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 92390075Sobrien@code{TFmode} floating point numbers are stored in memory with the word 92490075Sobriencontaining the sign bit at the lowest address; otherwise define it to 92590075Sobrienhave the value 0. This macro need not be a constant. 92690075Sobrien 92790075SobrienYou need not define this macro if the ordering is the same as for 92890075Sobrienmulti-word integers. 92990075Sobrien 93090075Sobrien@findex BITS_PER_UNIT 93190075Sobrien@item BITS_PER_UNIT 93290075SobrienDefine this macro to be the number of bits in an addressable storage 93390075Sobrienunit (byte); normally 8. 93490075Sobrien 93590075Sobrien@findex BITS_PER_WORD 93690075Sobrien@item BITS_PER_WORD 93790075SobrienNumber of bits in a word; normally 32. 93890075Sobrien 93990075Sobrien@findex MAX_BITS_PER_WORD 94090075Sobrien@item MAX_BITS_PER_WORD 94190075SobrienMaximum number of bits in a word. If this is undefined, the default is 94290075Sobrien@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 94390075Sobrienlargest value that @code{BITS_PER_WORD} can have at run-time. 94490075Sobrien 94590075Sobrien@findex UNITS_PER_WORD 94690075Sobrien@item UNITS_PER_WORD 94790075SobrienNumber of storage units in a word; normally 4. 94890075Sobrien 94990075Sobrien@findex MIN_UNITS_PER_WORD 95090075Sobrien@item MIN_UNITS_PER_WORD 95190075SobrienMinimum number of units in a word. If this is undefined, the default is 95290075Sobrien@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 95390075Sobriensmallest value that @code{UNITS_PER_WORD} can have at run-time. 95490075Sobrien 95590075Sobrien@findex POINTER_SIZE 95690075Sobrien@item POINTER_SIZE 95790075SobrienWidth of a pointer, in bits. You must specify a value no wider than the 95890075Sobrienwidth of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 95990075Sobrienyou must define @code{POINTERS_EXTEND_UNSIGNED}. 96090075Sobrien 96190075Sobrien@findex POINTERS_EXTEND_UNSIGNED 96290075Sobrien@item POINTERS_EXTEND_UNSIGNED 96390075SobrienA C expression whose value is greater than zero if pointers that need to be 96490075Sobrienextended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to 96590075Sobrienbe zero-extended and zero if they are to be sign-extended. If the value 96690075Sobrienis less then zero then there must be an "ptr_extend" instruction that 96790075Sobrienextends a pointer from @code{POINTER_SIZE} to @code{Pmode}. 96890075Sobrien 96990075SobrienYou need not define this macro if the @code{POINTER_SIZE} is equal 97090075Sobriento the width of @code{Pmode}. 97190075Sobrien 97290075Sobrien@findex PROMOTE_MODE 97390075Sobrien@item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 97490075SobrienA macro to update @var{m} and @var{unsignedp} when an object whose type 97590075Sobrienis @var{type} and which has the specified mode and signedness is to be 97690075Sobrienstored in a register. This macro is only called when @var{type} is a 97790075Sobrienscalar type. 97890075Sobrien 97990075SobrienOn most RISC machines, which only have operations that operate on a full 98090075Sobrienregister, define this macro to set @var{m} to @code{word_mode} if 98190075Sobrien@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 98290075Sobriencases, only integer modes should be widened because wider-precision 98390075Sobrienfloating-point operations are usually more expensive than their narrower 98490075Sobriencounterparts. 98590075Sobrien 98690075SobrienFor most machines, the macro definition does not change @var{unsignedp}. 98790075SobrienHowever, some machines, have instructions that preferentially handle 98890075Sobrieneither signed or unsigned quantities of certain modes. For example, on 98990075Sobrienthe DEC Alpha, 32-bit loads from memory and 32-bit add instructions 99090075Sobriensign-extend the result to 64 bits. On such machines, set 99190075Sobrien@var{unsignedp} according to which kind of extension is more efficient. 99290075Sobrien 99390075SobrienDo not define this macro if it would never modify @var{m}. 99490075Sobrien 99590075Sobrien@findex PROMOTE_FUNCTION_ARGS 99690075Sobrien@item PROMOTE_FUNCTION_ARGS 99790075SobrienDefine this macro if the promotion described by @code{PROMOTE_MODE} 99890075Sobrienshould also be done for outgoing function arguments. 99990075Sobrien 100090075Sobrien@findex PROMOTE_FUNCTION_RETURN 100190075Sobrien@item PROMOTE_FUNCTION_RETURN 100290075SobrienDefine this macro if the promotion described by @code{PROMOTE_MODE} 100390075Sobrienshould also be done for the return value of functions. 100490075Sobrien 100590075SobrienIf this macro is defined, @code{FUNCTION_VALUE} must perform the same 100690075Sobrienpromotions done by @code{PROMOTE_MODE}. 100790075Sobrien 100890075Sobrien@findex PROMOTE_FOR_CALL_ONLY 100990075Sobrien@item PROMOTE_FOR_CALL_ONLY 101090075SobrienDefine this macro if the promotion described by @code{PROMOTE_MODE} 101190075Sobrienshould @emph{only} be performed for outgoing function arguments or 101290075Sobrienfunction return values, as specified by @code{PROMOTE_FUNCTION_ARGS} 101390075Sobrienand @code{PROMOTE_FUNCTION_RETURN}, respectively. 101490075Sobrien 101590075Sobrien@findex PARM_BOUNDARY 101690075Sobrien@item PARM_BOUNDARY 101790075SobrienNormal alignment required for function parameters on the stack, in 101890075Sobrienbits. All stack parameters receive at least this much alignment 101990075Sobrienregardless of data type. On most machines, this is the same as the 102090075Sobriensize of an integer. 102190075Sobrien 102290075Sobrien@findex STACK_BOUNDARY 102390075Sobrien@item STACK_BOUNDARY 102490075SobrienDefine this macro to the minimum alignment enforced by hardware for the 102590075Sobrienstack pointer on this machine. The definition is a C expression for the 102690075Sobriendesired alignment (measured in bits). This value is used as a default 102790075Sobrienif @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 102890075Sobrienthis should be the same as @code{PARM_BOUNDARY}. 102990075Sobrien 103090075Sobrien@findex PREFERRED_STACK_BOUNDARY 103190075Sobrien@item PREFERRED_STACK_BOUNDARY 103290075SobrienDefine this macro if you wish to preserve a certain alignment for the 103390075Sobrienstack pointer, greater than what the hardware enforces. The definition 103490075Sobrienis a C expression for the desired alignment (measured in bits). This 103590075Sobrienmacro must evaluate to a value equal to or larger than 103690075Sobrien@code{STACK_BOUNDARY}. 103790075Sobrien 103890075Sobrien@findex FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 103990075Sobrien@item FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 104090075SobrienA C expression that evaluates true if @code{PREFERRED_STACK_BOUNDARY} is 104190075Sobriennot guaranteed by the runtime and we should emit code to align the stack 104290075Sobrienat the beginning of @code{main}. 104390075Sobrien 104490075Sobrien@cindex @code{PUSH_ROUNDING}, interaction with @code{PREFERRED_STACK_BOUNDARY} 104590075SobrienIf @code{PUSH_ROUNDING} is not defined, the stack will always be aligned 104690075Sobriento the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies 104790075Sobriena less strict alignment than @code{PREFERRED_STACK_BOUNDARY}, the stack may 104890075Sobrienbe momentarily unaligned while pushing arguments. 104990075Sobrien 105090075Sobrien@findex FUNCTION_BOUNDARY 105190075Sobrien@item FUNCTION_BOUNDARY 105290075SobrienAlignment required for a function entry point, in bits. 105390075Sobrien 105490075Sobrien@findex BIGGEST_ALIGNMENT 105590075Sobrien@item BIGGEST_ALIGNMENT 105690075SobrienBiggest alignment that any data type can require on this machine, in bits. 105790075Sobrien 105890075Sobrien@findex MINIMUM_ATOMIC_ALIGNMENT 105990075Sobrien@item MINIMUM_ATOMIC_ALIGNMENT 106090075SobrienIf defined, the smallest alignment, in bits, that can be given to an 106190075Sobrienobject that can be referenced in one operation, without disturbing any 106290075Sobriennearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 106390075Sobrienon machines that don't have byte or half-word store operations. 106490075Sobrien 106590075Sobrien@findex BIGGEST_FIELD_ALIGNMENT 106690075Sobrien@item BIGGEST_FIELD_ALIGNMENT 106790075SobrienBiggest alignment that any structure or union field can require on this 106890075Sobrienmachine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 106990075Sobrienstructure and union fields only, unless the field alignment has been set 107090075Sobrienby the @code{__attribute__ ((aligned (@var{n})))} construct. 107190075Sobrien 107290075Sobrien@findex ADJUST_FIELD_ALIGN 107390075Sobrien@item ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 107490075SobrienAn expression for the alignment of a structure field @var{field} if the 1075102780Skanalignment computed in the usual way (including applying of 1076102780Skan@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the 1077102780Skanalignment) is @var{computed}. It overrides alignment only if the 1078102780Skanfield alignment has not been set by the 1079102780Skan@code{__attribute__ ((aligned (@var{n})))} construct. 108090075Sobrien 108190075Sobrien@findex MAX_OFILE_ALIGNMENT 108290075Sobrien@item MAX_OFILE_ALIGNMENT 108390075SobrienBiggest alignment supported by the object file format of this machine. 108490075SobrienUse this macro to limit the alignment which can be specified using the 108590075Sobrien@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 108690075Sobrienthe default value is @code{BIGGEST_ALIGNMENT}. 108790075Sobrien 108890075Sobrien@findex DATA_ALIGNMENT 108990075Sobrien@item DATA_ALIGNMENT (@var{type}, @var{basic-align}) 109090075SobrienIf defined, a C expression to compute the alignment for a variable in 109190075Sobrienthe static store. @var{type} is the data type, and @var{basic-align} is 109290075Sobrienthe alignment that the object would ordinarily have. The value of this 109390075Sobrienmacro is used instead of that alignment to align the object. 109490075Sobrien 109590075SobrienIf this macro is not defined, then @var{basic-align} is used. 109690075Sobrien 109790075Sobrien@findex strcpy 109890075SobrienOne use of this macro is to increase alignment of medium-size data to 109990075Sobrienmake it all fit in fewer cache lines. Another is to cause character 110090075Sobrienarrays to be word-aligned so that @code{strcpy} calls that copy 110190075Sobrienconstants to character arrays can be done inline. 110290075Sobrien 110390075Sobrien@findex CONSTANT_ALIGNMENT 110490075Sobrien@item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 110590075SobrienIf defined, a C expression to compute the alignment given to a constant 110690075Sobrienthat is being placed in memory. @var{constant} is the constant and 110790075Sobrien@var{basic-align} is the alignment that the object would ordinarily 110890075Sobrienhave. The value of this macro is used instead of that alignment to 110990075Sobrienalign the object. 111090075Sobrien 111190075SobrienIf this macro is not defined, then @var{basic-align} is used. 111290075Sobrien 111390075SobrienThe typical use of this macro is to increase alignment for string 111490075Sobrienconstants to be word aligned so that @code{strcpy} calls that copy 111590075Sobrienconstants can be done inline. 111690075Sobrien 111790075Sobrien@findex LOCAL_ALIGNMENT 111890075Sobrien@item LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 111990075SobrienIf defined, a C expression to compute the alignment for a variable in 112090075Sobrienthe local store. @var{type} is the data type, and @var{basic-align} is 112190075Sobrienthe alignment that the object would ordinarily have. The value of this 112290075Sobrienmacro is used instead of that alignment to align the object. 112390075Sobrien 112490075SobrienIf this macro is not defined, then @var{basic-align} is used. 112590075Sobrien 112690075SobrienOne use of this macro is to increase alignment of medium-size data to 112790075Sobrienmake it all fit in fewer cache lines. 112890075Sobrien 112990075Sobrien@findex EMPTY_FIELD_BOUNDARY 113090075Sobrien@item EMPTY_FIELD_BOUNDARY 113190075SobrienAlignment in bits to be given to a structure bit-field that follows an 113290075Sobrienempty field such as @code{int : 0;}. 113390075Sobrien 113490075SobrienNote that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment 113590075Sobrienthat results from an empty field. 113690075Sobrien 113790075Sobrien@findex STRUCTURE_SIZE_BOUNDARY 113890075Sobrien@item STRUCTURE_SIZE_BOUNDARY 113990075SobrienNumber of bits which any structure or union's size must be a multiple of. 114090075SobrienEach structure or union's size is rounded up to a multiple of this. 114190075Sobrien 114290075SobrienIf you do not define this macro, the default is the same as 114390075Sobrien@code{BITS_PER_UNIT}. 114490075Sobrien 114590075Sobrien@findex STRICT_ALIGNMENT 114690075Sobrien@item STRICT_ALIGNMENT 114790075SobrienDefine this macro to be the value 1 if instructions will fail to work 114890075Sobrienif given data not on the nominal alignment. If instructions will merely 114990075Sobriengo slower in that case, define this macro as 0. 115090075Sobrien 115190075Sobrien@findex PCC_BITFIELD_TYPE_MATTERS 115290075Sobrien@item PCC_BITFIELD_TYPE_MATTERS 115390075SobrienDefine this if you wish to imitate the way many other C compilers handle 115490075Sobrienalignment of bit-fields and the structures that contain them. 115590075Sobrien 115690075SobrienThe behavior is that the type written for a bit-field (@code{int}, 115790075Sobrien@code{short}, or other integer type) imposes an alignment for the 115890075Sobrienentire structure, as if the structure really did contain an ordinary 115990075Sobrienfield of that type. In addition, the bit-field is placed within the 116090075Sobrienstructure so that it would fit within such a field, not crossing a 116190075Sobrienboundary for it. 116290075Sobrien 116390075SobrienThus, on most machines, a bit-field whose type is written as @code{int} 116490075Sobrienwould not cross a four-byte boundary, and would force four-byte 116590075Sobrienalignment for the whole structure. (The alignment used may not be four 116690075Sobrienbytes; it is controlled by the other alignment parameters.) 116790075Sobrien 116890075SobrienIf the macro is defined, its definition should be a C expression; 116990075Sobriena nonzero value for the expression enables this behavior. 117090075Sobrien 117190075SobrienNote that if this macro is not defined, or its value is zero, some 117290075Sobrienbit-fields may cross more than one alignment boundary. The compiler can 117390075Sobriensupport such references if there are @samp{insv}, @samp{extv}, and 117490075Sobrien@samp{extzv} insns that can directly reference memory. 117590075Sobrien 117690075SobrienThe other known way of making bit-fields work is to define 117790075Sobrien@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 117890075SobrienThen every structure can be accessed with fullwords. 117990075Sobrien 118090075SobrienUnless the machine has bit-field instructions or you define 118190075Sobrien@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 118290075Sobrien@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 118390075Sobrien 118490075SobrienIf your aim is to make GCC use the same conventions for laying out 118590075Sobrienbit-fields as are used by another compiler, here is how to investigate 118690075Sobrienwhat the other compiler does. Compile and run this program: 118790075Sobrien 118890075Sobrien@example 118990075Sobrienstruct foo1 119090075Sobrien@{ 119190075Sobrien char x; 119290075Sobrien char :0; 119390075Sobrien char y; 119490075Sobrien@}; 119590075Sobrien 119690075Sobrienstruct foo2 119790075Sobrien@{ 119890075Sobrien char x; 119990075Sobrien int :0; 120090075Sobrien char y; 120190075Sobrien@}; 120290075Sobrien 120390075Sobrienmain () 120490075Sobrien@{ 120590075Sobrien printf ("Size of foo1 is %d\n", 120690075Sobrien sizeof (struct foo1)); 120790075Sobrien printf ("Size of foo2 is %d\n", 120890075Sobrien sizeof (struct foo2)); 120990075Sobrien exit (0); 121090075Sobrien@} 121190075Sobrien@end example 121290075Sobrien 121390075SobrienIf this prints 2 and 5, then the compiler's behavior is what you would 121490075Sobrienget from @code{PCC_BITFIELD_TYPE_MATTERS}. 121590075Sobrien 121690075Sobrien@findex BITFIELD_NBYTES_LIMITED 121790075Sobrien@item BITFIELD_NBYTES_LIMITED 121896263SobrienLike @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 121996263Sobriento aligning a bit-field within the structure. 122090075Sobrien 122190075Sobrien@findex MEMBER_TYPE_FORCES_BLK 122290075Sobrien@item MEMBER_TYPE_FORCES_BLK (@var{field}) 122390075SobrienReturn 1 if a structure or array containing @var{field} should be accessed using 122490075Sobrien@code{BLKMODE}. 122590075Sobrien 122690075SobrienNormally, this is not needed. See the file @file{c4x.h} for an example 122790075Sobrienof how to use this macro to prevent a structure having a floating point 122890075Sobrienfield from being accessed in an integer mode. 122990075Sobrien 123090075Sobrien@findex ROUND_TYPE_SIZE 123190075Sobrien@item ROUND_TYPE_SIZE (@var{type}, @var{computed}, @var{specified}) 123290075SobrienDefine this macro as an expression for the overall size of a type 123390075Sobrien(given by @var{type} as a tree node) when the size computed in the 123490075Sobrienusual way is @var{computed} and the alignment is @var{specified}. 123590075Sobrien 123690075SobrienThe default is to round @var{computed} up to a multiple of @var{specified}. 123790075Sobrien 123890075Sobrien@findex ROUND_TYPE_SIZE_UNIT 123990075Sobrien@item ROUND_TYPE_SIZE_UNIT (@var{type}, @var{computed}, @var{specified}) 124090075SobrienSimilar to @code{ROUND_TYPE_SIZE}, but sizes and alignments are 124190075Sobrienspecified in units (bytes). If you define @code{ROUND_TYPE_SIZE}, 124290075Sobrienyou must also define this macro and they must be defined consistently 124390075Sobrienwith each other. 124490075Sobrien 124590075Sobrien@findex ROUND_TYPE_ALIGN 124690075Sobrien@item ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 124790075SobrienDefine this macro as an expression for the alignment of a type (given 124890075Sobrienby @var{type} as a tree node) if the alignment computed in the usual 124990075Sobrienway is @var{computed} and the alignment explicitly specified was 125090075Sobrien@var{specified}. 125190075Sobrien 125290075SobrienThe default is to use @var{specified} if it is larger; otherwise, use 125390075Sobrienthe smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 125490075Sobrien 125590075Sobrien@findex MAX_FIXED_MODE_SIZE 125690075Sobrien@item MAX_FIXED_MODE_SIZE 125790075SobrienAn integer expression for the size in bits of the largest integer 125890075Sobrienmachine mode that should actually be used. All integer machine modes of 125990075Sobrienthis size or smaller can be used for structures and unions with the 126090075Sobrienappropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 126190075Sobrien(DImode)} is assumed. 126290075Sobrien 126390075Sobrien@findex VECTOR_MODE_SUPPORTED_P 126490075Sobrien@item VECTOR_MODE_SUPPORTED_P(@var{mode}) 126590075SobrienDefine this macro to be nonzero if the port is prepared to handle insns 126690075Sobrieninvolving vector mode @var{mode}. At the very least, it must have move 126790075Sobrienpatterns for this mode. 126890075Sobrien 126990075Sobrien@findex STACK_SAVEAREA_MODE 127090075Sobrien@item STACK_SAVEAREA_MODE (@var{save_level}) 127190075SobrienIf defined, an expression of type @code{enum machine_mode} that 127290075Sobrienspecifies the mode of the save area operand of a 127390075Sobrien@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 127490075Sobrien@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 127590075Sobrien@code{SAVE_NONLOCAL} and selects which of the three named patterns is 127690075Sobrienhaving its mode specified. 127790075Sobrien 127890075SobrienYou need not define this macro if it always returns @code{Pmode}. You 127990075Sobrienwould most commonly define this macro if the 128090075Sobrien@code{save_stack_@var{level}} patterns need to support both a 32- and a 128190075Sobrien64-bit mode. 128290075Sobrien 128390075Sobrien@findex STACK_SIZE_MODE 128490075Sobrien@item STACK_SIZE_MODE 128590075SobrienIf defined, an expression of type @code{enum machine_mode} that 128690075Sobrienspecifies the mode of the size increment operand of an 128790075Sobrien@code{allocate_stack} named pattern (@pxref{Standard Names}). 128890075Sobrien 128990075SobrienYou need not define this macro if it always returns @code{word_mode}. 129090075SobrienYou would most commonly define this macro if the @code{allocate_stack} 129190075Sobrienpattern needs to support both a 32- and a 64-bit mode. 129290075Sobrien 129390075Sobrien@findex CHECK_FLOAT_VALUE 129490075Sobrien@item CHECK_FLOAT_VALUE (@var{mode}, @var{value}, @var{overflow}) 129590075SobrienA C statement to validate the value @var{value} (of type 129690075Sobrien@code{double}) for mode @var{mode}. This means that you check whether 129790075Sobrien@var{value} fits within the possible range of values for mode 129890075Sobrien@var{mode} on this target machine. The mode @var{mode} is always 129990075Sobriena mode of class @code{MODE_FLOAT}. @var{overflow} is nonzero if 130090075Sobrienthe value is already known to be out of range. 130190075Sobrien 130290075SobrienIf @var{value} is not valid or if @var{overflow} is nonzero, you should 130390075Sobrienset @var{overflow} to 1 and then assign some valid value to @var{value}. 130490075SobrienAllowing an invalid value to go through the compiler can produce 130590075Sobrienincorrect assembler code which may even cause Unix assemblers to crash. 130690075Sobrien 130790075SobrienThis macro need not be defined if there is no work for it to do. 130890075Sobrien 130990075Sobrien@findex TARGET_FLOAT_FORMAT 131090075Sobrien@item TARGET_FLOAT_FORMAT 131190075SobrienA code distinguishing the floating point format of the target machine. 131290075SobrienThere are five defined values: 131390075Sobrien 131490075Sobrien@table @code 131590075Sobrien@findex IEEE_FLOAT_FORMAT 131690075Sobrien@item IEEE_FLOAT_FORMAT 131790075SobrienThis code indicates IEEE floating point. It is the default; there is no 131890075Sobrienneed to define this macro when the format is IEEE@. 131990075Sobrien 132090075Sobrien@findex VAX_FLOAT_FORMAT 132190075Sobrien@item VAX_FLOAT_FORMAT 132290075SobrienThis code indicates the ``D float'' format used on the VAX@. 132390075Sobrien 132490075Sobrien@findex IBM_FLOAT_FORMAT 132590075Sobrien@item IBM_FLOAT_FORMAT 132690075SobrienThis code indicates the format used on the IBM System/370. 132790075Sobrien 132890075Sobrien@findex C4X_FLOAT_FORMAT 132990075Sobrien@item C4X_FLOAT_FORMAT 133090075SobrienThis code indicates the format used on the TMS320C3x/C4x. 133190075Sobrien 133290075Sobrien@findex UNKNOWN_FLOAT_FORMAT 133390075Sobrien@item UNKNOWN_FLOAT_FORMAT 133490075SobrienThis code indicates any other format. 133590075Sobrien@end table 133690075Sobrien 133790075SobrienThe value of this macro is compared with @code{HOST_FLOAT_FORMAT}, which 133890075Sobrienis defined by the @command{configure} script, to determine whether the 133990075Sobrientarget machine has the same format as the host machine. If any other 134090075Sobrienformats are actually in use on supported machines, new codes should be 134190075Sobriendefined for them. 134290075Sobrien 134390075SobrienThe ordering of the component words of floating point values stored in 134490075Sobrienmemory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. 134590075Sobrien 134690075Sobrien@end table 134790075Sobrien 134896263Sobrien@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) 134996263SobrienThis target hook returns @code{true} if bit-fields in the given 135096263Sobrien@var{record_type} are to be laid out following the rules of Microsoft 135196263SobrienVisual C/C++, namely: (i) a bit-field won't share the same storage 135296263Sobrienunit with the previous bit-field if their underlying types have 135396263Sobriendifferent sizes, and the bit-field will be aligned to the highest 135496263Sobrienalignment of the underlying types of itself and of the previous 135596263Sobrienbit-field; (ii) a zero-sized bit-field will affect the alignment of 135696263Sobrienthe whole enclosing structure, even if it is unnamed; except that 135796263Sobrien(iii) a zero-sized bit-field will be disregarded unless it follows 135896263Sobrienanother bit-field of non-zero size. If this hook returns @code{true}, 135996263Sobrienother macros that control bit-field layout are ignored. 136096263Sobrien@end deftypefn 136196263Sobrien 136290075Sobrien@node Type Layout 136390075Sobrien@section Layout of Source Language Data Types 136490075Sobrien 136590075SobrienThese macros define the sizes and other characteristics of the standard 136690075Sobrienbasic data types used in programs being compiled. Unlike the macros in 136790075Sobrienthe previous section, these apply to specific features of C and related 136890075Sobrienlanguages, rather than to fundamental aspects of storage layout. 136990075Sobrien 137090075Sobrien@table @code 137190075Sobrien@findex INT_TYPE_SIZE 137290075Sobrien@item INT_TYPE_SIZE 137390075SobrienA C expression for the size in bits of the type @code{int} on the 137490075Sobrientarget machine. If you don't define this, the default is one word. 137590075Sobrien 137690075Sobrien@findex SHORT_TYPE_SIZE 137790075Sobrien@item SHORT_TYPE_SIZE 137890075SobrienA C expression for the size in bits of the type @code{short} on the 137990075Sobrientarget machine. If you don't define this, the default is half a word. 138090075Sobrien(If this would be less than one storage unit, it is rounded up to one 138190075Sobrienunit.) 138290075Sobrien 138390075Sobrien@findex LONG_TYPE_SIZE 138490075Sobrien@item LONG_TYPE_SIZE 138590075SobrienA C expression for the size in bits of the type @code{long} on the 138690075Sobrientarget machine. If you don't define this, the default is one word. 138790075Sobrien 138890075Sobrien@findex ADA_LONG_TYPE_SIZE 138990075Sobrien@item ADA_LONG_TYPE_SIZE 139090075SobrienOn some machines, the size used for the Ada equivalent of the type 139190075Sobrien@code{long} by a native Ada compiler differs from that used by C. In 139290075Sobrienthat situation, define this macro to be a C expression to be used for 139390075Sobrienthe size of that type. If you don't define this, the default is the 139490075Sobrienvalue of @code{LONG_TYPE_SIZE}. 139590075Sobrien 139690075Sobrien@findex MAX_LONG_TYPE_SIZE 139790075Sobrien@item MAX_LONG_TYPE_SIZE 139890075SobrienMaximum number for the size in bits of the type @code{long} on the 139990075Sobrientarget machine. If this is undefined, the default is 140090075Sobrien@code{LONG_TYPE_SIZE}. Otherwise, it is the constant value that is the 140190075Sobrienlargest value that @code{LONG_TYPE_SIZE} can have at run-time. This is 140290075Sobrienused in @code{cpp}. 140390075Sobrien 140490075Sobrien@findex LONG_LONG_TYPE_SIZE 140590075Sobrien@item LONG_LONG_TYPE_SIZE 140690075SobrienA C expression for the size in bits of the type @code{long long} on the 140790075Sobrientarget machine. If you don't define this, the default is two 140890075Sobrienwords. If you want to support GNU Ada on your machine, the value of this 140990075Sobrienmacro must be at least 64. 141090075Sobrien 141190075Sobrien@findex CHAR_TYPE_SIZE 141290075Sobrien@item CHAR_TYPE_SIZE 141390075SobrienA C expression for the size in bits of the type @code{char} on the 141490075Sobrientarget machine. If you don't define this, the default is 141590075Sobrien@code{BITS_PER_UNIT}. 141690075Sobrien 141790075Sobrien@findex MAX_CHAR_TYPE_SIZE 141890075Sobrien@item MAX_CHAR_TYPE_SIZE 141990075SobrienMaximum number for the size in bits of the type @code{char} on the 142090075Sobrientarget machine. If this is undefined, the default is 142190075Sobrien@code{CHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the 142290075Sobrienlargest value that @code{CHAR_TYPE_SIZE} can have at run-time. This is 142390075Sobrienused in @code{cpp}. 142490075Sobrien 142590075Sobrien@findex BOOL_TYPE_SIZE 142690075Sobrien@item BOOL_TYPE_SIZE 142796263SobrienA C expression for the size in bits of the C++ type @code{bool} and 142896263SobrienC99 type @code{_Bool} on the target machine. If you don't define 142996263Sobrienthis, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 143090075Sobrien 143190075Sobrien@findex FLOAT_TYPE_SIZE 143290075Sobrien@item FLOAT_TYPE_SIZE 143390075SobrienA C expression for the size in bits of the type @code{float} on the 143490075Sobrientarget machine. If you don't define this, the default is one word. 143590075Sobrien 143690075Sobrien@findex DOUBLE_TYPE_SIZE 143790075Sobrien@item DOUBLE_TYPE_SIZE 143890075SobrienA C expression for the size in bits of the type @code{double} on the 143990075Sobrientarget machine. If you don't define this, the default is two 144090075Sobrienwords. 144190075Sobrien 144290075Sobrien@findex LONG_DOUBLE_TYPE_SIZE 144390075Sobrien@item LONG_DOUBLE_TYPE_SIZE 144490075SobrienA C expression for the size in bits of the type @code{long double} on 144590075Sobrienthe target machine. If you don't define this, the default is two 144690075Sobrienwords. 144790075Sobrien 144890075Sobrien@findex MAX_LONG_DOUBLE_TYPE_SIZE 144990075SobrienMaximum number for the size in bits of the type @code{long double} on the 145090075Sobrientarget machine. If this is undefined, the default is 145190075Sobrien@code{LONG_DOUBLE_TYPE_SIZE}. Otherwise, it is the constant value that is 145290075Sobrienthe largest value that @code{LONG_DOUBLE_TYPE_SIZE} can have at run-time. 145390075SobrienThis is used in @code{cpp}. 145490075Sobrien 145590075Sobrien@findex INTEL_EXTENDED_IEEE_FORMAT 145690075SobrienDefine this macro to be 1 if the target machine uses 80-bit floating-point 145790075Sobrienvalues with 128-bit size and alignment. This is used in @file{real.c}. 145890075Sobrien 145990075Sobrien@findex WIDEST_HARDWARE_FP_SIZE 146090075Sobrien@item WIDEST_HARDWARE_FP_SIZE 146190075SobrienA C expression for the size in bits of the widest floating-point format 146290075Sobriensupported by the hardware. If you define this macro, you must specify a 146390075Sobrienvalue less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 146490075SobrienIf you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 146590075Sobrienis the default. 146690075Sobrien 146790075Sobrien@findex DEFAULT_SIGNED_CHAR 146890075Sobrien@item DEFAULT_SIGNED_CHAR 146990075SobrienAn expression whose value is 1 or 0, according to whether the type 147090075Sobrien@code{char} should be signed or unsigned by default. The user can 147190075Sobrienalways override this default with the options @option{-fsigned-char} 147290075Sobrienand @option{-funsigned-char}. 147390075Sobrien 147490075Sobrien@findex DEFAULT_SHORT_ENUMS 147590075Sobrien@item DEFAULT_SHORT_ENUMS 147690075SobrienA C expression to determine whether to give an @code{enum} type 147790075Sobrienonly as many bytes as it takes to represent the range of possible values 147890075Sobrienof that type. A nonzero value means to do that; a zero value means all 147990075Sobrien@code{enum} types should be allocated like @code{int}. 148090075Sobrien 148190075SobrienIf you don't define the macro, the default is 0. 148290075Sobrien 148390075Sobrien@findex SIZE_TYPE 148490075Sobrien@item SIZE_TYPE 148590075SobrienA C expression for a string describing the name of the data type to use 148690075Sobrienfor size values. The typedef name @code{size_t} is defined using the 148790075Sobriencontents of the string. 148890075Sobrien 148990075SobrienThe string can contain more than one keyword. If so, separate them with 149090075Sobrienspaces, and write first any length keyword, then @code{unsigned} if 149190075Sobrienappropriate, and finally @code{int}. The string must exactly match one 149290075Sobrienof the data type names defined in the function 149390075Sobrien@code{init_decl_processing} in the file @file{c-decl.c}. You may not 149490075Sobrienomit @code{int} or change the order---that would cause the compiler to 149590075Sobriencrash on startup. 149690075Sobrien 149790075SobrienIf you don't define this macro, the default is @code{"long unsigned 149890075Sobrienint"}. 149990075Sobrien 150090075Sobrien@findex PTRDIFF_TYPE 150190075Sobrien@item PTRDIFF_TYPE 150290075SobrienA C expression for a string describing the name of the data type to use 150390075Sobrienfor the result of subtracting two pointers. The typedef name 150490075Sobrien@code{ptrdiff_t} is defined using the contents of the string. See 150590075Sobrien@code{SIZE_TYPE} above for more information. 150690075Sobrien 150790075SobrienIf you don't define this macro, the default is @code{"long int"}. 150890075Sobrien 150990075Sobrien@findex WCHAR_TYPE 151090075Sobrien@item WCHAR_TYPE 151190075SobrienA C expression for a string describing the name of the data type to use 151290075Sobrienfor wide characters. The typedef name @code{wchar_t} is defined using 151390075Sobrienthe contents of the string. See @code{SIZE_TYPE} above for more 151490075Sobrieninformation. 151590075Sobrien 151690075SobrienIf you don't define this macro, the default is @code{"int"}. 151790075Sobrien 151890075Sobrien@findex WCHAR_TYPE_SIZE 151990075Sobrien@item WCHAR_TYPE_SIZE 152090075SobrienA C expression for the size in bits of the data type for wide 152190075Sobriencharacters. This is used in @code{cpp}, which cannot make use of 152290075Sobrien@code{WCHAR_TYPE}. 152390075Sobrien 152490075Sobrien@findex MAX_WCHAR_TYPE_SIZE 152590075Sobrien@item MAX_WCHAR_TYPE_SIZE 152690075SobrienMaximum number for the size in bits of the data type for wide 152790075Sobriencharacters. If this is undefined, the default is 152890075Sobrien@code{WCHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the 152990075Sobrienlargest value that @code{WCHAR_TYPE_SIZE} can have at run-time. This is 153090075Sobrienused in @code{cpp}. 153190075Sobrien 153290075Sobrien@findex GCOV_TYPE_SIZE 153390075Sobrien@item GCOV_TYPE_SIZE 153490075SobrienA C expression for the size in bits of the type used for gcov counters on the 153590075Sobrientarget machine. If you don't define this, the default is one 153690075Sobrien@code{LONG_TYPE_SIZE} in case it is greater or equal to 64-bit and 153790075Sobrien@code{LONG_LONG_TYPE_SIZE} otherwise. You may want to re-define the type to 153890075Sobrienensure atomicity for counters in multithreaded programs. 153990075Sobrien 154090075Sobrien@findex WINT_TYPE 154190075Sobrien@item WINT_TYPE 154290075SobrienA C expression for a string describing the name of the data type to 154390075Sobrienuse for wide characters passed to @code{printf} and returned from 154490075Sobrien@code{getwc}. The typedef name @code{wint_t} is defined using the 154590075Sobriencontents of the string. See @code{SIZE_TYPE} above for more 154690075Sobrieninformation. 154790075Sobrien 154890075SobrienIf you don't define this macro, the default is @code{"unsigned int"}. 154990075Sobrien 155090075Sobrien@findex INTMAX_TYPE 155190075Sobrien@item INTMAX_TYPE 155290075SobrienA C expression for a string describing the name of the data type that 155390075Sobriencan represent any value of any standard or extended signed integer type. 155490075SobrienThe typedef name @code{intmax_t} is defined using the contents of the 155590075Sobrienstring. See @code{SIZE_TYPE} above for more information. 155690075Sobrien 155790075SobrienIf you don't define this macro, the default is the first of 155890075Sobrien@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 155990075Sobrienmuch precision as @code{long long int}. 156090075Sobrien 156190075Sobrien@findex UINTMAX_TYPE 156290075Sobrien@item UINTMAX_TYPE 156390075SobrienA C expression for a string describing the name of the data type that 156490075Sobriencan represent any value of any standard or extended unsigned integer 156590075Sobrientype. The typedef name @code{uintmax_t} is defined using the contents 156690075Sobrienof the string. See @code{SIZE_TYPE} above for more information. 156790075Sobrien 156890075SobrienIf you don't define this macro, the default is the first of 156990075Sobrien@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 157090075Sobrienunsigned int"} that has as much precision as @code{long long unsigned 157190075Sobrienint}. 157290075Sobrien 157390075Sobrien@findex TARGET_PTRMEMFUNC_VBIT_LOCATION 157490075Sobrien@item TARGET_PTRMEMFUNC_VBIT_LOCATION 157590075SobrienThe C++ compiler represents a pointer-to-member-function with a struct 157690075Sobrienthat looks like: 157790075Sobrien 157890075Sobrien@example 157990075Sobrien struct @{ 158090075Sobrien union @{ 158190075Sobrien void (*fn)(); 158290075Sobrien ptrdiff_t vtable_index; 158390075Sobrien @}; 158490075Sobrien ptrdiff_t delta; 158590075Sobrien @}; 158690075Sobrien@end example 158790075Sobrien 158890075Sobrien@noindent 158990075SobrienThe C++ compiler must use one bit to indicate whether the function that 159090075Sobrienwill be called through a pointer-to-member-function is virtual. 159190075SobrienNormally, we assume that the low-order bit of a function pointer must 159290075Sobrienalways be zero. Then, by ensuring that the vtable_index is odd, we can 159390075Sobriendistinguish which variant of the union is in use. But, on some 159490075Sobrienplatforms function pointers can be odd, and so this doesn't work. In 159590075Sobrienthat case, we use the low-order bit of the @code{delta} field, and shift 159690075Sobrienthe remainder of the @code{delta} field to the left. 159790075Sobrien 159890075SobrienGCC will automatically make the right selection about where to store 159990075Sobrienthis bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 160090075SobrienHowever, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 160190075Sobrienset such that functions always start at even addresses, but the lowest 160290075Sobrienbit of pointers to functions indicate whether the function at that 160390075Sobrienaddress is in ARM or Thumb mode. If this is the case of your 160490075Sobrienarchitecture, you should define this macro to 160590075Sobrien@code{ptrmemfunc_vbit_in_delta}. 160690075Sobrien 160790075SobrienIn general, you should not have to define this macro. On architectures 160890075Sobrienin which function addresses are always even, according to 160990075Sobrien@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 161090075Sobrien@code{ptrmemfunc_vbit_in_pfn}. 161190075Sobrien 161290075Sobrien@findex TARGET_VTABLE_USES_DESCRIPTORS 161390075Sobrien@item TARGET_VTABLE_USES_DESCRIPTORS 161490075SobrienNormally, the C++ compiler uses function pointers in vtables. This 161596263Sobrienmacro allows the target to change to use ``function descriptors'' 161690075Sobrieninstead. Function descriptors are found on targets for whom a 161790075Sobrienfunction pointer is actually a small data structure. Normally the 161896263Sobriendata structure consists of the actual code address plus a data 161990075Sobrienpointer to which the function's data is relative. 162090075Sobrien 162190075SobrienIf vtables are used, the value of this macro should be the number 162290075Sobrienof words that the function descriptor occupies. 162390075Sobrien@end table 162490075Sobrien 162590075Sobrien@node Escape Sequences 162690075Sobrien@section Target Character Escape Sequences 162790075Sobrien@cindex escape sequences 162890075Sobrien 162990075SobrienBy default, GCC assumes that the C character escape sequences take on 163090075Sobrientheir ASCII values for the target. If this is not correct, you must 163190075Sobrienexplicitly define all of the macros below. 163290075Sobrien 163390075Sobrien@table @code 163490075Sobrien@findex TARGET_BELL 163590075Sobrien@item TARGET_BELL 163690075SobrienA C constant expression for the integer value for escape sequence 163790075Sobrien@samp{\a}. 163890075Sobrien 163990075Sobrien@findex TARGET_ESC 164090075Sobrien@item TARGET_ESC 164190075SobrienA C constant expression for the integer value of the target escape 164290075Sobriencharacter. As an extension, GCC evaluates the escape sequences 164390075Sobrien@samp{\e} and @samp{\E} to this. 164490075Sobrien 164590075Sobrien@findex TARGET_TAB 164690075Sobrien@findex TARGET_BS 164790075Sobrien@findex TARGET_NEWLINE 164890075Sobrien@item TARGET_BS 164990075Sobrien@itemx TARGET_TAB 165090075Sobrien@itemx TARGET_NEWLINE 165190075SobrienC constant expressions for the integer values for escape sequences 165290075Sobrien@samp{\b}, @samp{\t} and @samp{\n}. 165390075Sobrien 165490075Sobrien@findex TARGET_VT 165590075Sobrien@findex TARGET_FF 165690075Sobrien@findex TARGET_CR 165790075Sobrien@item TARGET_VT 165890075Sobrien@itemx TARGET_FF 165990075Sobrien@itemx TARGET_CR 166090075SobrienC constant expressions for the integer values for escape sequences 166190075Sobrien@samp{\v}, @samp{\f} and @samp{\r}. 166290075Sobrien@end table 166390075Sobrien 166490075Sobrien@node Registers 166590075Sobrien@section Register Usage 166690075Sobrien@cindex register usage 166790075Sobrien 166890075SobrienThis section explains how to describe what registers the target machine 166990075Sobrienhas, and how (in general) they can be used. 167090075Sobrien 167190075SobrienThe description of which registers a specific instruction can use is 167290075Sobriendone with register classes; see @ref{Register Classes}. For information 167390075Sobrienon using registers to access a stack frame, see @ref{Frame Registers}. 167490075SobrienFor passing values in registers, see @ref{Register Arguments}. 167590075SobrienFor returning values in registers, see @ref{Scalar Return}. 167690075Sobrien 167790075Sobrien@menu 167890075Sobrien* Register Basics:: Number and kinds of registers. 167990075Sobrien* Allocation Order:: Order in which registers are allocated. 168090075Sobrien* Values in Registers:: What kinds of values each reg can hold. 168190075Sobrien* Leaf Functions:: Renumbering registers for leaf functions. 168290075Sobrien* Stack Registers:: Handling a register stack such as 80387. 168390075Sobrien@end menu 168490075Sobrien 168590075Sobrien@node Register Basics 168690075Sobrien@subsection Basic Characteristics of Registers 168790075Sobrien 168890075Sobrien@c prevent bad page break with this line 168990075SobrienRegisters have various characteristics. 169090075Sobrien 169190075Sobrien@table @code 169290075Sobrien@findex FIRST_PSEUDO_REGISTER 169390075Sobrien@item FIRST_PSEUDO_REGISTER 169490075SobrienNumber of hardware registers known to the compiler. They receive 169590075Sobriennumbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 169690075Sobrienpseudo register's number really is assigned the number 169790075Sobrien@code{FIRST_PSEUDO_REGISTER}. 169890075Sobrien 169990075Sobrien@item FIXED_REGISTERS 170090075Sobrien@findex FIXED_REGISTERS 170190075Sobrien@cindex fixed register 170290075SobrienAn initializer that says which registers are used for fixed purposes 170390075Sobrienall throughout the compiled code and are therefore not available for 170490075Sobriengeneral allocation. These would include the stack pointer, the frame 170590075Sobrienpointer (except on machines where that can be used as a general 170690075Sobrienregister when no frame pointer is needed), the program counter on 170790075Sobrienmachines where that is considered one of the addressable registers, 170890075Sobrienand any other numbered register with a standard use. 170990075Sobrien 171090075SobrienThis information is expressed as a sequence of numbers, separated by 171190075Sobriencommas and surrounded by braces. The @var{n}th number is 1 if 171290075Sobrienregister @var{n} is fixed, 0 otherwise. 171390075Sobrien 171490075SobrienThe table initialized from this macro, and the table initialized by 171590075Sobrienthe following one, may be overridden at run time either automatically, 171690075Sobrienby the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 171790075Sobrienthe user with the command options @option{-ffixed-@var{reg}}, 171890075Sobrien@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. 171990075Sobrien 172090075Sobrien@findex CALL_USED_REGISTERS 172190075Sobrien@item CALL_USED_REGISTERS 172290075Sobrien@cindex call-used register 172390075Sobrien@cindex call-clobbered register 172490075Sobrien@cindex call-saved register 172590075SobrienLike @code{FIXED_REGISTERS} but has 1 for each register that is 172690075Sobrienclobbered (in general) by function calls as well as for fixed 172790075Sobrienregisters. This macro therefore identifies the registers that are not 172890075Sobrienavailable for general allocation of values that must live across 172990075Sobrienfunction calls. 173090075Sobrien 173190075SobrienIf a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 173290075Sobrienautomatically saves it on function entry and restores it on function 173390075Sobrienexit, if the register is used within the function. 173490075Sobrien 173590075Sobrien@findex CALL_REALLY_USED_REGISTERS 173690075Sobrien@item CALL_REALLY_USED_REGISTERS 173790075Sobrien@cindex call-used register 173890075Sobrien@cindex call-clobbered register 173990075Sobrien@cindex call-saved register 174096263SobrienLike @code{CALL_USED_REGISTERS} except this macro doesn't require 174196263Sobrienthat the entire set of @code{FIXED_REGISTERS} be included. 174290075Sobrien(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). 174396263SobrienThis macro is optional. If not specified, it defaults to the value 174490075Sobrienof @code{CALL_USED_REGISTERS}. 174590075Sobrien 174690075Sobrien@findex HARD_REGNO_CALL_PART_CLOBBERED 174790075Sobrien@item HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) 174890075Sobrien@cindex call-used register 174990075Sobrien@cindex call-clobbered register 175090075Sobrien@cindex call-saved register 175190075SobrienA C expression that is nonzero if it is not permissible to store a 175290075Sobrienvalue of mode @var{mode} in hard register number @var{regno} across a 175390075Sobriencall without some part of it being clobbered. For most machines this 175490075Sobrienmacro need not be defined. It is only required for machines that do not 175590075Sobrienpreserve the entire contents of a register across a call. 175690075Sobrien 175790075Sobrien@findex CONDITIONAL_REGISTER_USAGE 175890075Sobrien@findex fixed_regs 175990075Sobrien@findex call_used_regs 176090075Sobrien@item CONDITIONAL_REGISTER_USAGE 176190075SobrienZero or more C statements that may conditionally modify five variables 176290075Sobrien@code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, 176390075Sobrien@code{reg_names}, and @code{reg_class_contents}, to take into account 176490075Sobrienany dependence of these register sets on target flags. The first three 176590075Sobrienof these are of type @code{char []} (interpreted as Boolean vectors). 176690075Sobrien@code{global_regs} is a @code{const char *[]}, and 176790075Sobrien@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is 176890075Sobriencalled, @code{fixed_regs}, @code{call_used_regs}, 176990075Sobrien@code{reg_class_contents}, and @code{reg_names} have been initialized 177090075Sobrienfrom @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, 177190075Sobrien@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. 177290075Sobrien@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, 177390075Sobrien@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} 177490075Sobriencommand options have been applied. 177590075Sobrien 177690075SobrienYou need not define this macro if it has no work to do. 177790075Sobrien 177890075Sobrien@cindex disabling certain registers 177990075Sobrien@cindex controlling register usage 178090075SobrienIf the usage of an entire class of registers depends on the target 178190075Sobrienflags, you may indicate this to GCC by using this macro to modify 178290075Sobrien@code{fixed_regs} and @code{call_used_regs} to 1 for each of the 178390075Sobrienregisters in the classes which should not be used by GCC@. Also define 178490075Sobrienthe macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it 178590075Sobrienis called with a letter for a class that shouldn't be used. 178690075Sobrien 178790075Sobrien(However, if this class is not included in @code{GENERAL_REGS} and all 178890075Sobrienof the insn patterns whose constraints permit this class are 178990075Sobriencontrolled by target switches, then GCC will automatically avoid using 179090075Sobrienthese registers when the target switches are opposed to them.) 179190075Sobrien 179290075Sobrien@findex NON_SAVING_SETJMP 179390075Sobrien@item NON_SAVING_SETJMP 179490075SobrienIf this macro is defined and has a nonzero value, it means that 179590075Sobrien@code{setjmp} and related functions fail to save the registers, or that 179690075Sobrien@code{longjmp} fails to restore them. To compensate, the compiler 179790075Sobrienavoids putting variables in registers in functions that use 179890075Sobrien@code{setjmp}. 179990075Sobrien 180090075Sobrien@findex INCOMING_REGNO 180190075Sobrien@item INCOMING_REGNO (@var{out}) 180290075SobrienDefine this macro if the target machine has register windows. This C 180390075Sobrienexpression returns the register number as seen by the called function 180490075Sobriencorresponding to the register number @var{out} as seen by the calling 180590075Sobrienfunction. Return @var{out} if register number @var{out} is not an 180690075Sobrienoutbound register. 180790075Sobrien 180890075Sobrien@findex OUTGOING_REGNO 180990075Sobrien@item OUTGOING_REGNO (@var{in}) 181090075SobrienDefine this macro if the target machine has register windows. This C 181190075Sobrienexpression returns the register number as seen by the calling function 181290075Sobriencorresponding to the register number @var{in} as seen by the called 181390075Sobrienfunction. Return @var{in} if register number @var{in} is not an inbound 181490075Sobrienregister. 181590075Sobrien 181690075Sobrien@findex LOCAL_REGNO 181790075Sobrien@item LOCAL_REGNO (@var{regno}) 181890075SobrienDefine this macro if the target machine has register windows. This C 181990075Sobrienexpression returns true if the register is call-saved but is in the 182090075Sobrienregister window. Unlike most call-saved registers, such registers 182190075Sobrienneed not be explicitly restored on function exit or during non-local 182290075Sobriengotos. 182390075Sobrien 182490075Sobrien@ignore 182590075Sobrien@findex PC_REGNUM 182690075Sobrien@item PC_REGNUM 182790075SobrienIf the program counter has a register number, define this as that 182890075Sobrienregister number. Otherwise, do not define it. 182990075Sobrien@end ignore 183090075Sobrien@end table 183190075Sobrien 183290075Sobrien@node Allocation Order 183390075Sobrien@subsection Order of Allocation of Registers 183490075Sobrien@cindex order of register allocation 183590075Sobrien@cindex register allocation order 183690075Sobrien 183790075Sobrien@c prevent bad page break with this line 183890075SobrienRegisters are allocated in order. 183990075Sobrien 184090075Sobrien@table @code 184190075Sobrien@findex REG_ALLOC_ORDER 184290075Sobrien@item REG_ALLOC_ORDER 184390075SobrienIf defined, an initializer for a vector of integers, containing the 184490075Sobriennumbers of hard registers in the order in which GCC should prefer 184590075Sobriento use them (from most preferred to least). 184690075Sobrien 184790075SobrienIf this macro is not defined, registers are used lowest numbered first 184890075Sobrien(all else being equal). 184990075Sobrien 185090075SobrienOne use of this macro is on machines where the highest numbered 185190075Sobrienregisters must always be saved and the save-multiple-registers 185290075Sobrieninstruction supports only sequences of consecutive registers. On such 185390075Sobrienmachines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 185490075Sobrienthe highest numbered allocable register first. 185590075Sobrien 185690075Sobrien@findex ORDER_REGS_FOR_LOCAL_ALLOC 185790075Sobrien@item ORDER_REGS_FOR_LOCAL_ALLOC 185890075SobrienA C statement (sans semicolon) to choose the order in which to allocate 185990075Sobrienhard registers for pseudo-registers local to a basic block. 186090075Sobrien 186190075SobrienStore the desired register order in the array @code{reg_alloc_order}. 186290075SobrienElement 0 should be the register to allocate first; element 1, the next 186390075Sobrienregister; and so on. 186490075Sobrien 186590075SobrienThe macro body should not assume anything about the contents of 186690075Sobrien@code{reg_alloc_order} before execution of the macro. 186790075Sobrien 186890075SobrienOn most machines, it is not necessary to define this macro. 186990075Sobrien@end table 187090075Sobrien 187190075Sobrien@node Values in Registers 187290075Sobrien@subsection How Values Fit in Registers 187390075Sobrien 187490075SobrienThis section discusses the macros that describe which kinds of values 187590075Sobrien(specifically, which machine modes) each register can hold, and how many 187690075Sobrienconsecutive registers are needed for a given mode. 187790075Sobrien 187890075Sobrien@table @code 187990075Sobrien@findex HARD_REGNO_NREGS 188090075Sobrien@item HARD_REGNO_NREGS (@var{regno}, @var{mode}) 188190075SobrienA C expression for the number of consecutive hard registers, starting 188290075Sobrienat register number @var{regno}, required to hold a value of mode 188390075Sobrien@var{mode}. 188490075Sobrien 188590075SobrienOn a machine where all registers are exactly one word, a suitable 188690075Sobriendefinition of this macro is 188790075Sobrien 188890075Sobrien@smallexample 188990075Sobrien#define HARD_REGNO_NREGS(REGNO, MODE) \ 189090075Sobrien ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 189190075Sobrien / UNITS_PER_WORD) 189290075Sobrien@end smallexample 189390075Sobrien 189490075Sobrien@findex HARD_REGNO_MODE_OK 189590075Sobrien@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 189690075SobrienA C expression that is nonzero if it is permissible to store a value 189790075Sobrienof mode @var{mode} in hard register number @var{regno} (or in several 189890075Sobrienregisters starting with that one). For a machine where all registers 189990075Sobrienare equivalent, a suitable definition is 190090075Sobrien 190190075Sobrien@smallexample 190290075Sobrien#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 190390075Sobrien@end smallexample 190490075Sobrien 190590075SobrienYou need not include code to check for the numbers of fixed registers, 190690075Sobrienbecause the allocation mechanism considers them to be always occupied. 190790075Sobrien 190890075Sobrien@cindex register pairs 190990075SobrienOn some machines, double-precision values must be kept in even/odd 191090075Sobrienregister pairs. You can implement that by defining this macro to reject 191190075Sobrienodd register numbers for such modes. 191290075Sobrien 191390075SobrienThe minimum requirement for a mode to be OK in a register is that the 191490075Sobrien@samp{mov@var{mode}} instruction pattern support moves between the 191590075Sobrienregister and other hard register in the same class and that moving a 191690075Sobrienvalue into the register and back out not alter it. 191790075Sobrien 191890075SobrienSince the same instruction used to move @code{word_mode} will work for 191990075Sobrienall narrower integer modes, it is not necessary on any machine for 192090075Sobrien@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 192190075Sobrienyou define patterns @samp{movhi}, etc., to take advantage of this. This 192290075Sobrienis useful because of the interaction between @code{HARD_REGNO_MODE_OK} 192390075Sobrienand @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 192490075Sobriento be tieable. 192590075Sobrien 192690075SobrienMany machines have special registers for floating point arithmetic. 192790075SobrienOften people assume that floating point machine modes are allowed only 192890075Sobrienin floating point registers. This is not true. Any registers that 192990075Sobriencan hold integers can safely @emph{hold} a floating point machine 193090075Sobrienmode, whether or not floating arithmetic can be done on it in those 193190075Sobrienregisters. Integer move instructions can be used to move the values. 193290075Sobrien 193390075SobrienOn some machines, though, the converse is true: fixed-point machine 193490075Sobrienmodes may not go in floating registers. This is true if the floating 193590075Sobrienregisters normalize any value stored in them, because storing a 193690075Sobriennon-floating value there would garble it. In this case, 193790075Sobrien@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 193890075Sobrienfloating registers. But if the floating registers do not automatically 193990075Sobriennormalize, if you can store any bit pattern in one and retrieve it 194090075Sobrienunchanged without a trap, then any machine mode may go in a floating 194190075Sobrienregister, so you can define this macro to say so. 194290075Sobrien 194390075SobrienThe primary significance of special floating registers is rather that 194490075Sobrienthey are the registers acceptable in floating point arithmetic 194590075Sobrieninstructions. However, this is of no concern to 194690075Sobrien@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 194790075Sobrienconstraints for those instructions. 194890075Sobrien 194990075SobrienOn some machines, the floating registers are especially slow to access, 195090075Sobrienso that it is better to store a value in a stack frame than in such a 195190075Sobrienregister if floating point arithmetic is not being done. As long as the 195290075Sobrienfloating registers are not in class @code{GENERAL_REGS}, they will not 195390075Sobrienbe used unless some pattern's constraint asks for one. 195490075Sobrien 195590075Sobrien@findex MODES_TIEABLE_P 195690075Sobrien@item MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 195790075SobrienA C expression that is nonzero if a value of mode 195890075Sobrien@var{mode1} is accessible in mode @var{mode2} without copying. 195990075Sobrien 196090075SobrienIf @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 196190075Sobrien@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for 196290075Sobrienany @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})} 196390075Sobrienshould be nonzero. If they differ for any @var{r}, you should define 196490075Sobrienthis macro to return zero unless some other mechanism ensures the 196590075Sobrienaccessibility of the value in a narrower mode. 196690075Sobrien 196790075SobrienYou should define this macro to return nonzero in as many cases as 196890075Sobrienpossible since doing so will allow GCC to perform better register 196990075Sobrienallocation. 197090075Sobrien 197190075Sobrien@findex AVOID_CCMODE_COPIES 197290075Sobrien@item AVOID_CCMODE_COPIES 197390075SobrienDefine this macro if the compiler should avoid copies to/from @code{CCmode} 197490075Sobrienregisters. You should only define this macro if support for copying to/from 197590075Sobrien@code{CCmode} is incomplete. 197690075Sobrien@end table 197790075Sobrien 197890075Sobrien@node Leaf Functions 197990075Sobrien@subsection Handling Leaf Functions 198090075Sobrien 198190075Sobrien@cindex leaf functions 198290075Sobrien@cindex functions, leaf 198390075SobrienOn some machines, a leaf function (i.e., one which makes no calls) can run 198490075Sobrienmore efficiently if it does not make its own register window. Often this 198590075Sobrienmeans it is required to receive its arguments in the registers where they 198690075Sobrienare passed by the caller, instead of the registers where they would 198790075Sobriennormally arrive. 198890075Sobrien 198990075SobrienThe special treatment for leaf functions generally applies only when 199090075Sobrienother conditions are met; for example, often they may use only those 199190075Sobrienregisters for its own variables and temporaries. We use the term ``leaf 199290075Sobrienfunction'' to mean a function that is suitable for this special 199390075Sobrienhandling, so that functions with no calls are not necessarily ``leaf 199490075Sobrienfunctions''. 199590075Sobrien 199690075SobrienGCC assigns register numbers before it knows whether the function is 199790075Sobriensuitable for leaf function treatment. So it needs to renumber the 199890075Sobrienregisters in order to output a leaf function. The following macros 199990075Sobrienaccomplish this. 200090075Sobrien 200190075Sobrien@table @code 200290075Sobrien@findex LEAF_REGISTERS 200390075Sobrien@item LEAF_REGISTERS 200490075SobrienName of a char vector, indexed by hard register number, which 200590075Sobriencontains 1 for a register that is allowable in a candidate for leaf 200690075Sobrienfunction treatment. 200790075Sobrien 200890075SobrienIf leaf function treatment involves renumbering the registers, then the 200990075Sobrienregisters marked here should be the ones before renumbering---those that 201090075SobrienGCC would ordinarily allocate. The registers which will actually be 201190075Sobrienused in the assembler code, after renumbering, should not be marked with 1 201290075Sobrienin this vector. 201390075Sobrien 201490075SobrienDefine this macro only if the target machine offers a way to optimize 201590075Sobrienthe treatment of leaf functions. 201690075Sobrien 201790075Sobrien@findex LEAF_REG_REMAP 201890075Sobrien@item LEAF_REG_REMAP (@var{regno}) 201990075SobrienA C expression whose value is the register number to which @var{regno} 202090075Sobrienshould be renumbered, when a function is treated as a leaf function. 202190075Sobrien 202290075SobrienIf @var{regno} is a register number which should not appear in a leaf 202390075Sobrienfunction before renumbering, then the expression should yield @minus{}1, which 202490075Sobrienwill cause the compiler to abort. 202590075Sobrien 202690075SobrienDefine this macro only if the target machine offers a way to optimize the 202790075Sobrientreatment of leaf functions, and registers need to be renumbered to do 202890075Sobrienthis. 202990075Sobrien@end table 203090075Sobrien 203190075Sobrien@findex current_function_is_leaf 203290075Sobrien@findex current_function_uses_only_leaf_regs 203390075Sobrien@code{TARGET_ASM_FUNCTION_PROLOGUE} and 203490075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions 203590075Sobrienspecially. They can test the C variable @code{current_function_is_leaf} 203690075Sobrienwhich is nonzero for leaf functions. @code{current_function_is_leaf} is 203790075Sobrienset prior to local register allocation and is valid for the remaining 203890075Sobriencompiler passes. They can also test the C variable 203990075Sobrien@code{current_function_uses_only_leaf_regs} which is nonzero for leaf 204090075Sobrienfunctions which only use leaf registers. 204190075Sobrien@code{current_function_uses_only_leaf_regs} is valid after reload and is 204290075Sobrienonly useful if @code{LEAF_REGISTERS} is defined. 204390075Sobrien@c changed this to fix overfull. ALSO: why the "it" at the beginning 204490075Sobrien@c of the next paragraph?! --mew 2feb93 204590075Sobrien 204690075Sobrien@node Stack Registers 204790075Sobrien@subsection Registers That Form a Stack 204890075Sobrien 204990075SobrienThere are special features to handle computers where some of the 205090075Sobrien``registers'' form a stack, as in the 80387 coprocessor for the 80386. 205190075SobrienStack registers are normally written by pushing onto the stack, and are 205290075Sobriennumbered relative to the top of the stack. 205390075Sobrien 205490075SobrienCurrently, GCC can only handle one group of stack-like registers, and 205590075Sobrienthey must be consecutively numbered. 205690075Sobrien 205790075Sobrien@table @code 205890075Sobrien@findex STACK_REGS 205990075Sobrien@item STACK_REGS 206090075SobrienDefine this if the machine has any stack-like registers. 206190075Sobrien 206290075Sobrien@findex FIRST_STACK_REG 206390075Sobrien@item FIRST_STACK_REG 206490075SobrienThe number of the first stack-like register. This one is the top 206590075Sobrienof the stack. 206690075Sobrien 206790075Sobrien@findex LAST_STACK_REG 206890075Sobrien@item LAST_STACK_REG 206990075SobrienThe number of the last stack-like register. This one is the bottom of 207090075Sobrienthe stack. 207190075Sobrien@end table 207290075Sobrien 207390075Sobrien@node Register Classes 207490075Sobrien@section Register Classes 207590075Sobrien@cindex register class definitions 207690075Sobrien@cindex class definitions, register 207790075Sobrien 207890075SobrienOn many machines, the numbered registers are not all equivalent. 207990075SobrienFor example, certain registers may not be allowed for indexed addressing; 208090075Sobriencertain registers may not be allowed in some instructions. These machine 208190075Sobrienrestrictions are described to the compiler using @dfn{register classes}. 208290075Sobrien 208390075SobrienYou define a number of register classes, giving each one a name and saying 208490075Sobrienwhich of the registers belong to it. Then you can specify register classes 208590075Sobrienthat are allowed as operands to particular instruction patterns. 208690075Sobrien 208790075Sobrien@findex ALL_REGS 208890075Sobrien@findex NO_REGS 208990075SobrienIn general, each register will belong to several classes. In fact, one 209090075Sobrienclass must be named @code{ALL_REGS} and contain all the registers. Another 209190075Sobrienclass must be named @code{NO_REGS} and contain no registers. Often the 209290075Sobrienunion of two classes will be another class; however, this is not required. 209390075Sobrien 209490075Sobrien@findex GENERAL_REGS 209590075SobrienOne of the classes must be named @code{GENERAL_REGS}. There is nothing 209690075Sobrienterribly special about the name, but the operand constraint letters 209790075Sobrien@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 209890075Sobrienthe same as @code{ALL_REGS}, just define it as a macro which expands 209990075Sobriento @code{ALL_REGS}. 210090075Sobrien 210190075SobrienOrder the classes so that if class @var{x} is contained in class @var{y} 210290075Sobrienthen @var{x} has a lower class number than @var{y}. 210390075Sobrien 210490075SobrienThe way classes other than @code{GENERAL_REGS} are specified in operand 210590075Sobrienconstraints is through machine-dependent operand constraint letters. 210690075SobrienYou can define such letters to correspond to various classes, then use 210790075Sobrienthem in operand constraints. 210890075Sobrien 210990075SobrienYou should define a class for the union of two classes whenever some 211090075Sobrieninstruction allows both classes. For example, if an instruction allows 211190075Sobrieneither a floating point (coprocessor) register or a general register for a 211290075Sobriencertain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 211390075Sobrienwhich includes both of them. Otherwise you will get suboptimal code. 211490075Sobrien 211590075SobrienYou must also specify certain redundant information about the register 211690075Sobrienclasses: for each class, which classes contain it and which ones are 211790075Sobriencontained in it; for each pair of classes, the largest class contained 211890075Sobrienin their union. 211990075Sobrien 212090075SobrienWhen a value occupying several consecutive registers is expected in a 212190075Sobriencertain class, all the registers used must belong to that class. 212290075SobrienTherefore, register classes cannot be used to enforce a requirement for 212390075Sobriena register pair to start with an even-numbered register. The way to 212490075Sobrienspecify this requirement is with @code{HARD_REGNO_MODE_OK}. 212590075Sobrien 212690075SobrienRegister classes used for input-operands of bitwise-and or shift 212790075Sobrieninstructions have a special requirement: each such class must have, for 212890075Sobrieneach fixed-point machine mode, a subclass whose registers can transfer that 212990075Sobrienmode to or from memory. For example, on some machines, the operations for 213090075Sobriensingle-byte values (@code{QImode}) are limited to certain registers. When 213190075Sobrienthis is so, each register class that is used in a bitwise-and or shift 213290075Sobrieninstruction must have a subclass consisting of registers from which 213390075Sobriensingle-byte values can be loaded or stored. This is so that 213490075Sobrien@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 213590075Sobrien 213690075Sobrien@table @code 213790075Sobrien@findex enum reg_class 213890075Sobrien@item enum reg_class 213990075SobrienAn enumeral type that must be defined with all the register class names 214090075Sobrienas enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS} 214190075Sobrienmust be the last register class, followed by one more enumeral value, 214290075Sobrien@code{LIM_REG_CLASSES}, which is not a register class but rather 214390075Sobrientells how many classes there are. 214490075Sobrien 214590075SobrienEach register class has a number, which is the value of casting 214690075Sobrienthe class name to type @code{int}. The number serves as an index 214790075Sobrienin many of the tables described below. 214890075Sobrien 214990075Sobrien@findex N_REG_CLASSES 215090075Sobrien@item N_REG_CLASSES 215190075SobrienThe number of distinct register classes, defined as follows: 215290075Sobrien 215390075Sobrien@example 215490075Sobrien#define N_REG_CLASSES (int) LIM_REG_CLASSES 215590075Sobrien@end example 215690075Sobrien 215790075Sobrien@findex REG_CLASS_NAMES 215890075Sobrien@item REG_CLASS_NAMES 215990075SobrienAn initializer containing the names of the register classes as C string 216090075Sobrienconstants. These names are used in writing some of the debugging dumps. 216190075Sobrien 216290075Sobrien@findex REG_CLASS_CONTENTS 216390075Sobrien@item REG_CLASS_CONTENTS 216490075SobrienAn initializer containing the contents of the register classes, as integers 216590075Sobrienwhich are bit masks. The @var{n}th integer specifies the contents of class 216690075Sobrien@var{n}. The way the integer @var{mask} is interpreted is that 216790075Sobrienregister @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 216890075Sobrien 216990075SobrienWhen the machine has more than 32 registers, an integer does not suffice. 217090075SobrienThen the integers are replaced by sub-initializers, braced groupings containing 217190075Sobrienseveral integers. Each sub-initializer must be suitable as an initializer 217290075Sobrienfor the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 217390075SobrienIn this situation, the first integer in each sub-initializer corresponds to 217490075Sobrienregisters 0 through 31, the second integer to registers 32 through 63, and 217590075Sobrienso on. 217690075Sobrien 217790075Sobrien@findex REGNO_REG_CLASS 217890075Sobrien@item REGNO_REG_CLASS (@var{regno}) 217990075SobrienA C expression whose value is a register class containing hard register 218090075Sobrien@var{regno}. In general there is more than one such class; choose a class 218190075Sobrienwhich is @dfn{minimal}, meaning that no smaller class also contains the 218290075Sobrienregister. 218390075Sobrien 218490075Sobrien@findex BASE_REG_CLASS 218590075Sobrien@item BASE_REG_CLASS 218690075SobrienA macro whose definition is the name of the class to which a valid 218790075Sobrienbase register must belong. A base register is one used in an address 218890075Sobrienwhich is the register value plus a displacement. 218990075Sobrien 219090075Sobrien@findex MODE_BASE_REG_CLASS 219190075Sobrien@item MODE_BASE_REG_CLASS (@var{mode}) 219290075SobrienThis is a variation of the @code{BASE_REG_CLASS} macro which allows 219390075Sobrienthe selection of a base register in a mode depenedent manner. If 219490075Sobrien@var{mode} is VOIDmode then it should return the same value as 219590075Sobrien@code{BASE_REG_CLASS}. 219690075Sobrien 219790075Sobrien@findex INDEX_REG_CLASS 219890075Sobrien@item INDEX_REG_CLASS 219990075SobrienA macro whose definition is the name of the class to which a valid 220090075Sobrienindex register must belong. An index register is one used in an 220190075Sobrienaddress where its value is either multiplied by a scale factor or 220290075Sobrienadded to another register (as well as added to a displacement). 220390075Sobrien 220490075Sobrien@findex REG_CLASS_FROM_LETTER 220590075Sobrien@item REG_CLASS_FROM_LETTER (@var{char}) 220690075SobrienA C expression which defines the machine-dependent operand constraint 220790075Sobrienletters for register classes. If @var{char} is such a letter, the 220890075Sobrienvalue should be the register class corresponding to it. Otherwise, 220990075Sobrienthe value should be @code{NO_REGS}. The register letter @samp{r}, 221090075Sobriencorresponding to class @code{GENERAL_REGS}, will not be passed 221190075Sobriento this macro; you do not need to handle it. 221290075Sobrien 221390075Sobrien@findex REGNO_OK_FOR_BASE_P 221490075Sobrien@item REGNO_OK_FOR_BASE_P (@var{num}) 221590075SobrienA C expression which is nonzero if register number @var{num} is 221690075Sobriensuitable for use as a base register in operand addresses. It may be 221790075Sobrieneither a suitable hard register or a pseudo register that has been 221890075Sobrienallocated such a hard register. 221990075Sobrien 222090075Sobrien@findex REGNO_MODE_OK_FOR_BASE_P 222190075Sobrien@item REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) 222290075SobrienA C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that 222390075Sobrienthat expression may examine the mode of the memory reference in 222490075Sobrien@var{mode}. You should define this macro if the mode of the memory 222590075Sobrienreference affects whether a register may be used as a base register. If 222690075Sobrienyou define this macro, the compiler will use it instead of 222790075Sobrien@code{REGNO_OK_FOR_BASE_P}. 222890075Sobrien 222990075Sobrien@findex REGNO_OK_FOR_INDEX_P 223090075Sobrien@item REGNO_OK_FOR_INDEX_P (@var{num}) 223190075SobrienA C expression which is nonzero if register number @var{num} is 223290075Sobriensuitable for use as an index register in operand addresses. It may be 223390075Sobrieneither a suitable hard register or a pseudo register that has been 223490075Sobrienallocated such a hard register. 223590075Sobrien 223690075SobrienThe difference between an index register and a base register is that 223790075Sobrienthe index register may be scaled. If an address involves the sum of 223890075Sobrientwo registers, neither one of them scaled, then either one may be 223990075Sobrienlabeled the ``base'' and the other the ``index''; but whichever 224090075Sobrienlabeling is used must fit the machine's constraints of which registers 224190075Sobrienmay serve in each capacity. The compiler will try both labelings, 224290075Sobrienlooking for one that is valid, and will reload one or both registers 224390075Sobrienonly if neither labeling works. 224490075Sobrien 224590075Sobrien@findex PREFERRED_RELOAD_CLASS 224690075Sobrien@item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 224790075SobrienA C expression that places additional restrictions on the register class 224890075Sobriento use when it is necessary to copy value @var{x} into a register in class 224990075Sobrien@var{class}. The value is a register class; perhaps @var{class}, or perhaps 225090075Sobrienanother, smaller class. On many machines, the following definition is 225190075Sobriensafe: 225290075Sobrien 225390075Sobrien@example 225490075Sobrien#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 225590075Sobrien@end example 225690075Sobrien 225790075SobrienSometimes returning a more restrictive class makes better code. For 225890075Sobrienexample, on the 68000, when @var{x} is an integer constant that is in range 225990075Sobrienfor a @samp{moveq} instruction, the value of this macro is always 226090075Sobrien@code{DATA_REGS} as long as @var{class} includes the data registers. 226190075SobrienRequiring a data register guarantees that a @samp{moveq} will be used. 226290075Sobrien 226390075SobrienIf @var{x} is a @code{const_double}, by returning @code{NO_REGS} 226490075Sobrienyou can force @var{x} into a memory constant. This is useful on 226590075Sobriencertain machines where immediate floating values cannot be loaded into 226690075Sobriencertain kinds of registers. 226790075Sobrien 226890075Sobrien@findex PREFERRED_OUTPUT_RELOAD_CLASS 226990075Sobrien@item PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) 227090075SobrienLike @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of 227190075Sobrieninput reloads. If you don't define this macro, the default is to use 227290075Sobrien@var{class}, unchanged. 227390075Sobrien 227490075Sobrien@findex LIMIT_RELOAD_CLASS 227590075Sobrien@item LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 227690075SobrienA C expression that places additional restrictions on the register class 227790075Sobriento use when it is necessary to be able to hold a value of mode 227890075Sobrien@var{mode} in a reload register for which class @var{class} would 227990075Sobrienordinarily be used. 228090075Sobrien 228190075SobrienUnlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 228290075Sobrienthere are certain modes that simply can't go in certain reload classes. 228390075Sobrien 228490075SobrienThe value is a register class; perhaps @var{class}, or perhaps another, 228590075Sobriensmaller class. 228690075Sobrien 228790075SobrienDon't define this macro unless the target machine has limitations which 228890075Sobrienrequire the macro to do something nontrivial. 228990075Sobrien 229090075Sobrien@findex SECONDARY_RELOAD_CLASS 229190075Sobrien@findex SECONDARY_INPUT_RELOAD_CLASS 229290075Sobrien@findex SECONDARY_OUTPUT_RELOAD_CLASS 229390075Sobrien@item SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 229490075Sobrien@itemx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 229590075Sobrien@itemx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 229690075SobrienMany machines have some registers that cannot be copied directly to or 229790075Sobrienfrom memory or even from other types of registers. An example is the 229890075Sobrien@samp{MQ} register, which on most machines, can only be copied to or 229990075Sobrienfrom general registers, but not memory. Some machines allow copying all 230090075Sobrienregisters to and from memory, but require a scratch register for stores 230190075Sobriento some memory locations (e.g., those with symbolic address on the RT, 230290075Sobrienand those with certain symbolic address on the Sparc when compiling 230390075SobrienPIC)@. In some cases, both an intermediate and a scratch register are 230490075Sobrienrequired. 230590075Sobrien 230690075SobrienYou should define these macros to indicate to the reload phase that it may 230790075Sobrienneed to allocate at least one register for a reload in addition to the 230890075Sobrienregister to contain the data. Specifically, if copying @var{x} to a 230990075Sobrienregister @var{class} in @var{mode} requires an intermediate register, 231090075Sobrienyou should define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 231190075Sobrienlargest register class all of whose registers can be used as 231290075Sobrienintermediate registers or scratch registers. 231390075Sobrien 231490075SobrienIf copying a register @var{class} in @var{mode} to @var{x} requires an 231590075Sobrienintermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} 231690075Sobrienshould be defined to return the largest register class required. If the 231790075Sobrienrequirements for input and output reloads are the same, the macro 231890075Sobrien@code{SECONDARY_RELOAD_CLASS} should be used instead of defining both 231990075Sobrienmacros identically. 232090075Sobrien 232190075SobrienThe values returned by these macros are often @code{GENERAL_REGS}. 232290075SobrienReturn @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 232390075Sobriencan be directly copied to or from a register of @var{class} in 232490075Sobrien@var{mode} without requiring a scratch register. Do not define this 232590075Sobrienmacro if it would always return @code{NO_REGS}. 232690075Sobrien 232790075SobrienIf a scratch register is required (either with or without an 232890075Sobrienintermediate register), you should define patterns for 232990075Sobrien@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 233090075Sobrien(@pxref{Standard Names}. These patterns, which will normally be 233190075Sobrienimplemented with a @code{define_expand}, should be similar to the 233290075Sobrien@samp{mov@var{m}} patterns, except that operand 2 is the scratch 233390075Sobrienregister. 233490075Sobrien 233590075SobrienDefine constraints for the reload register and scratch register that 233690075Sobriencontain a single register class. If the original reload register (whose 233790075Sobrienclass is @var{class}) can meet the constraint given in the pattern, the 233890075Sobrienvalue returned by these macros is used for the class of the scratch 233990075Sobrienregister. Otherwise, two additional reload registers are required. 234090075SobrienTheir classes are obtained from the constraints in the insn pattern. 234190075Sobrien 234290075Sobrien@var{x} might be a pseudo-register or a @code{subreg} of a 234390075Sobrienpseudo-register, which could either be in a hard register or in memory. 234490075SobrienUse @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 234590075Sobrienin memory and the hard register number if it is in a register. 234690075Sobrien 234790075SobrienThese macros should not be used in the case where a particular class of 234890075Sobrienregisters can only be copied to memory and not to another class of 234990075Sobrienregisters. In that case, secondary reload registers are not needed and 235090075Sobrienwould not be helpful. Instead, a stack location must be used to perform 235190075Sobrienthe copy and the @code{mov@var{m}} pattern should use memory as an 235290075Sobrienintermediate storage. This case often occurs between floating-point and 235390075Sobriengeneral registers. 235490075Sobrien 235590075Sobrien@findex SECONDARY_MEMORY_NEEDED 235690075Sobrien@item SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 235790075SobrienCertain machines have the property that some registers cannot be copied 235890075Sobriento some other registers without using memory. Define this macro on 235990075Sobrienthose machines to be a C expression that is nonzero if objects of mode 236090075Sobrien@var{m} in registers of @var{class1} can only be copied to registers of 236190075Sobrienclass @var{class2} by storing a register of @var{class1} into memory 236290075Sobrienand loading that memory location into a register of @var{class2}. 236390075Sobrien 236490075SobrienDo not define this macro if its value would always be zero. 236590075Sobrien 236690075Sobrien@findex SECONDARY_MEMORY_NEEDED_RTX 236790075Sobrien@item SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) 236890075SobrienNormally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler 236990075Sobrienallocates a stack slot for a memory location needed for register copies. 237090075SobrienIf this macro is defined, the compiler instead uses the memory location 237190075Sobriendefined by this macro. 237290075Sobrien 237390075SobrienDo not define this macro if you do not define 237490075Sobrien@code{SECONDARY_MEMORY_NEEDED}. 237590075Sobrien 237690075Sobrien@findex SECONDARY_MEMORY_NEEDED_MODE 237790075Sobrien@item SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) 237890075SobrienWhen the compiler needs a secondary memory location to copy between two 237990075Sobrienregisters of mode @var{mode}, it normally allocates sufficient memory to 238090075Sobrienhold a quantity of @code{BITS_PER_WORD} bits and performs the store and 238190075Sobrienload operations in a mode that many bits wide and whose class is the 238290075Sobriensame as that of @var{mode}. 238390075Sobrien 238490075SobrienThis is right thing to do on most machines because it ensures that all 238590075Sobrienbits of the register are copied and prevents accesses to the registers 238690075Sobrienin a narrower mode, which some machines prohibit for floating-point 238790075Sobrienregisters. 238890075Sobrien 238990075SobrienHowever, this default behavior is not correct on some machines, such as 239090075Sobrienthe DEC Alpha, that store short integers in floating-point registers 239190075Sobriendifferently than in integer registers. On those machines, the default 239290075Sobrienwidening will not work correctly and you must define this macro to 239390075Sobriensuppress that widening in some cases. See the file @file{alpha.h} for 239490075Sobriendetails. 239590075Sobrien 239690075SobrienDo not define this macro if you do not define 239790075Sobrien@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that 239890075Sobrienis @code{BITS_PER_WORD} bits wide is correct for your machine. 239990075Sobrien 240090075Sobrien@findex SMALL_REGISTER_CLASSES 240190075Sobrien@item SMALL_REGISTER_CLASSES 240290075SobrienOn some machines, it is risky to let hard registers live across arbitrary 240390075Sobrieninsns. Typically, these machines have instructions that require values 240490075Sobriento be in specific registers (like an accumulator), and reload will fail 240590075Sobrienif the required hard register is used for another purpose across such an 240690075Sobrieninsn. 240790075Sobrien 240890075SobrienDefine @code{SMALL_REGISTER_CLASSES} to be an expression with a nonzero 240990075Sobrienvalue on these machines. When this macro has a nonzero value, the 241090075Sobriencompiler will try to minimize the lifetime of hard registers. 241190075Sobrien 241290075SobrienIt is always safe to define this macro with a nonzero value, but if you 241390075Sobrienunnecessarily define it, you will reduce the amount of optimizations 241490075Sobrienthat can be performed in some cases. If you do not define this macro 241590075Sobrienwith a nonzero value when it is required, the compiler will run out of 241690075Sobrienspill registers and print a fatal error message. For most machines, you 241790075Sobrienshould not define this macro at all. 241890075Sobrien 241990075Sobrien@findex CLASS_LIKELY_SPILLED_P 242090075Sobrien@item CLASS_LIKELY_SPILLED_P (@var{class}) 242190075SobrienA C expression whose value is nonzero if pseudos that have been assigned 242290075Sobriento registers of class @var{class} would likely be spilled because 242390075Sobrienregisters of @var{class} are needed for spill registers. 242490075Sobrien 242590075SobrienThe default value of this macro returns 1 if @var{class} has exactly one 242690075Sobrienregister and zero otherwise. On most machines, this default should be 242790075Sobrienused. Only define this macro to some other expression if pseudos 242890075Sobrienallocated by @file{local-alloc.c} end up in memory because their hard 242990075Sobrienregisters were needed for spill registers. If this macro returns nonzero 243090075Sobrienfor those classes, those pseudos will only be allocated by 243190075Sobrien@file{global.c}, which knows how to reallocate the pseudo to another 243290075Sobrienregister. If there would not be another register available for 243390075Sobrienreallocation, you should not change the definition of this macro since 243490075Sobrienthe only effect of such a definition would be to slow down register 243590075Sobrienallocation. 243690075Sobrien 243790075Sobrien@findex CLASS_MAX_NREGS 243890075Sobrien@item CLASS_MAX_NREGS (@var{class}, @var{mode}) 243990075SobrienA C expression for the maximum number of consecutive registers 244090075Sobrienof class @var{class} needed to hold a value of mode @var{mode}. 244190075Sobrien 244290075SobrienThis is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 244390075Sobrienthe value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 244490075Sobrienshould be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, 244590075Sobrien@var{mode})} for all @var{regno} values in the class @var{class}. 244690075Sobrien 244790075SobrienThis macro helps control the handling of multiple-word values 244890075Sobrienin the reload pass. 244990075Sobrien 245090075Sobrien@item CLASS_CANNOT_CHANGE_MODE 245190075SobrienIf defined, a C expression for a class that contains registers for 245290075Sobrienwhich the compiler may not change modes arbitrarily. 245390075Sobrien 245490075Sobrien@item CLASS_CANNOT_CHANGE_MODE_P(@var{from}, @var{to}) 245590075SobrienA C expression that is true if, for a register in 245690075Sobrien@code{CLASS_CANNOT_CHANGE_MODE}, the requested mode punning is invalid. 245790075Sobrien 245890075SobrienFor the example, loading 32-bit integer or floating-point objects into 2459102780Skanfloating-point registers on the Alpha extends them to 64 bits. 246090075SobrienTherefore loading a 64-bit object and then storing it as a 32-bit object 2461102780Skandoes not store the low-order 32 bits, as would be the case for a normal 246290075Sobrienregister. Therefore, @file{alpha.h} defines @code{CLASS_CANNOT_CHANGE_MODE} 246390075Sobrienas @code{FLOAT_REGS} and @code{CLASS_CANNOT_CHANGE_MODE_P} restricts 246490075Sobrienmode changes to same-size modes. 246590075Sobrien 2466102780SkanCompare this to IA-64, which extends floating-point values to 82 bits, 246790075Sobrienand stores 64-bit integers in a different format than 64-bit doubles. 246890075SobrienTherefore @code{CLASS_CANNOT_CHANGE_MODE_P} is always true. 246990075Sobrien@end table 247090075Sobrien 247190075SobrienThree other special macros describe which operands fit which constraint 247290075Sobrienletters. 247390075Sobrien 247490075Sobrien@table @code 247590075Sobrien@findex CONST_OK_FOR_LETTER_P 247690075Sobrien@item CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 247790075SobrienA C expression that defines the machine-dependent operand constraint 247890075Sobrienletters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify 247990075Sobrienparticular ranges of integer values. If @var{c} is one of those 248090075Sobrienletters, the expression should check that @var{value}, an integer, is in 248190075Sobrienthe appropriate range and return 1 if so, 0 otherwise. If @var{c} is 248290075Sobriennot one of those letters, the value should be 0 regardless of 248390075Sobrien@var{value}. 248490075Sobrien 248590075Sobrien@findex CONST_DOUBLE_OK_FOR_LETTER_P 248690075Sobrien@item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 248790075SobrienA C expression that defines the machine-dependent operand constraint 248890075Sobrienletters that specify particular ranges of @code{const_double} values 248990075Sobrien(@samp{G} or @samp{H}). 249090075Sobrien 249190075SobrienIf @var{c} is one of those letters, the expression should check that 249290075Sobrien@var{value}, an RTX of code @code{const_double}, is in the appropriate 249390075Sobrienrange and return 1 if so, 0 otherwise. If @var{c} is not one of those 249490075Sobrienletters, the value should be 0 regardless of @var{value}. 249590075Sobrien 249690075Sobrien@code{const_double} is used for all floating-point constants and for 249790075Sobrien@code{DImode} fixed-point constants. A given letter can accept either 249890075Sobrienor both kinds of values. It can use @code{GET_MODE} to distinguish 249990075Sobrienbetween these kinds. 250090075Sobrien 250190075Sobrien@findex EXTRA_CONSTRAINT 250290075Sobrien@item EXTRA_CONSTRAINT (@var{value}, @var{c}) 250390075SobrienA C expression that defines the optional machine-dependent constraint 250490075Sobrienletters that can be used to segregate specific types of operands, usually 250590075Sobrienmemory references, for the target machine. Any letter that is not 250690075Sobrienelsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} 250790075Sobrienmay be used. Normally this macro will not be defined. 250890075Sobrien 250990075SobrienIf it is required for a particular target machine, it should return 1 251090075Sobrienif @var{value} corresponds to the operand type represented by the 251190075Sobrienconstraint letter @var{c}. If @var{c} is not defined as an extra 251290075Sobrienconstraint, the value returned should be 0 regardless of @var{value}. 251390075Sobrien 251490075SobrienFor example, on the ROMP, load instructions cannot have their output 251590075Sobrienin r0 if the memory reference contains a symbolic address. Constraint 251690075Sobrienletter @samp{Q} is defined as representing a memory address that does 251790075Sobrien@emph{not} contain a symbolic address. An alternative is specified with 251890075Sobriena @samp{Q} constraint on the input and @samp{r} on the output. The next 251990075Sobrienalternative specifies @samp{m} on the input and a register class that 252090075Sobriendoes not include r0 on the output. 252190075Sobrien@end table 252290075Sobrien 252390075Sobrien@node Stack and Calling 252490075Sobrien@section Stack Layout and Calling Conventions 252590075Sobrien@cindex calling conventions 252690075Sobrien 252790075Sobrien@c prevent bad page break with this line 252890075SobrienThis describes the stack layout and calling conventions. 252990075Sobrien 253090075Sobrien@menu 253190075Sobrien* Frame Layout:: 253290075Sobrien* Exception Handling:: 253390075Sobrien* Stack Checking:: 253490075Sobrien* Frame Registers:: 253590075Sobrien* Elimination:: 253690075Sobrien* Stack Arguments:: 253790075Sobrien* Register Arguments:: 253890075Sobrien* Scalar Return:: 253990075Sobrien* Aggregate Return:: 254090075Sobrien* Caller Saves:: 254190075Sobrien* Function Entry:: 254290075Sobrien* Profiling:: 254390075Sobrien* Tail Calls:: 254490075Sobrien@end menu 254590075Sobrien 254690075Sobrien@node Frame Layout 254790075Sobrien@subsection Basic Stack Layout 254890075Sobrien@cindex stack frame layout 254990075Sobrien@cindex frame layout 255090075Sobrien 255190075Sobrien@c prevent bad page break with this line 255290075SobrienHere is the basic stack layout. 255390075Sobrien 255490075Sobrien@table @code 255590075Sobrien@findex STACK_GROWS_DOWNWARD 255690075Sobrien@item STACK_GROWS_DOWNWARD 255790075SobrienDefine this macro if pushing a word onto the stack moves the stack 255890075Sobrienpointer to a smaller address. 255990075Sobrien 256090075SobrienWhen we say, ``define this macro if @dots{},'' it means that the 256190075Sobriencompiler checks this macro only with @code{#ifdef} so the precise 256290075Sobriendefinition used does not matter. 256390075Sobrien 256490075Sobrien@findex STACK_PUSH_CODE 256590075Sobrien@item STACK_PUSH_CODE 256690075Sobrien 256790075SobrienThis macro defines the operation used when something is pushed 256890075Sobrienon the stack. In RTL, a push operation will be 256990075Sobrien@code{(set (mem (STACK_PUSH_CODE (reg sp))) ...)} 257090075Sobrien 257190075SobrienThe choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, 257290075Sobrienand @code{POST_INC}. Which of these is correct depends on 257390075Sobrienthe stack direction and on whether the stack pointer points 257490075Sobriento the last item on the stack or whether it points to the 257590075Sobrienspace for the next item on the stack. 257690075Sobrien 257790075SobrienThe default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is 257890075Sobriendefined, which is almost always right, and @code{PRE_INC} otherwise, 257990075Sobrienwhich is often wrong. 258090075Sobrien 258190075Sobrien@findex FRAME_GROWS_DOWNWARD 258290075Sobrien@item FRAME_GROWS_DOWNWARD 258390075SobrienDefine this macro if the addresses of local variable slots are at negative 258490075Sobrienoffsets from the frame pointer. 258590075Sobrien 258690075Sobrien@findex ARGS_GROW_DOWNWARD 258790075Sobrien@item ARGS_GROW_DOWNWARD 258890075SobrienDefine this macro if successive arguments to a function occupy decreasing 258990075Sobrienaddresses on the stack. 259090075Sobrien 259190075Sobrien@findex STARTING_FRAME_OFFSET 259290075Sobrien@item STARTING_FRAME_OFFSET 259390075SobrienOffset from the frame pointer to the first local variable slot to be allocated. 259490075Sobrien 259590075SobrienIf @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by 259690075Sobriensubtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. 259790075SobrienOtherwise, it is found by adding the length of the first slot to the 259890075Sobrienvalue @code{STARTING_FRAME_OFFSET}. 259990075Sobrien@c i'm not sure if the above is still correct.. had to change it to get 260090075Sobrien@c rid of an overfull. --mew 2feb93 260190075Sobrien 260290075Sobrien@findex STACK_POINTER_OFFSET 260390075Sobrien@item STACK_POINTER_OFFSET 260490075SobrienOffset from the stack pointer register to the first location at which 260590075Sobrienoutgoing arguments are placed. If not specified, the default value of 260690075Sobrienzero is used. This is the proper value for most machines. 260790075Sobrien 260890075SobrienIf @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 260990075Sobrienthe first location at which outgoing arguments are placed. 261090075Sobrien 261190075Sobrien@findex FIRST_PARM_OFFSET 261290075Sobrien@item FIRST_PARM_OFFSET (@var{fundecl}) 261390075SobrienOffset from the argument pointer register to the first argument's 261490075Sobrienaddress. On some machines it may depend on the data type of the 261590075Sobrienfunction. 261690075Sobrien 261790075SobrienIf @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 261890075Sobrienthe first argument's address. 261990075Sobrien 262090075Sobrien@findex STACK_DYNAMIC_OFFSET 262190075Sobrien@item STACK_DYNAMIC_OFFSET (@var{fundecl}) 262290075SobrienOffset from the stack pointer register to an item dynamically allocated 262390075Sobrienon the stack, e.g., by @code{alloca}. 262490075Sobrien 262590075SobrienThe default value for this macro is @code{STACK_POINTER_OFFSET} plus the 262690075Sobrienlength of the outgoing arguments. The default is correct for most 262790075Sobrienmachines. See @file{function.c} for details. 262890075Sobrien 262990075Sobrien@findex DYNAMIC_CHAIN_ADDRESS 263090075Sobrien@item DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 263190075SobrienA C expression whose value is RTL representing the address in a stack 263290075Sobrienframe where the pointer to the caller's frame is stored. Assume that 263390075Sobrien@var{frameaddr} is an RTL expression for the address of the stack frame 263490075Sobrienitself. 263590075Sobrien 263690075SobrienIf you don't define this macro, the default is to return the value 263790075Sobrienof @var{frameaddr}---that is, the stack frame address is also the 263890075Sobrienaddress of the stack word that points to the previous frame. 263990075Sobrien 264090075Sobrien@findex SETUP_FRAME_ADDRESSES 264190075Sobrien@item SETUP_FRAME_ADDRESSES 264290075SobrienIf defined, a C expression that produces the machine-specific code to 264390075Sobriensetup the stack so that arbitrary frames can be accessed. For example, 264490075Sobrienon the Sparc, we must flush all of the register windows to the stack 264590075Sobrienbefore we can access arbitrary stack frames. You will seldom need to 264690075Sobriendefine this macro. 264790075Sobrien 264890075Sobrien@findex BUILTIN_SETJMP_FRAME_VALUE 264990075Sobrien@item BUILTIN_SETJMP_FRAME_VALUE 265090075SobrienIf defined, a C expression that contains an rtx that is used to store 265190075Sobrienthe address of the current frame into the built in @code{setjmp} buffer. 265290075SobrienThe default value, @code{virtual_stack_vars_rtx}, is correct for most 265390075Sobrienmachines. One reason you may need to define this macro is if 265490075Sobrien@code{hard_frame_pointer_rtx} is the appropriate value on your machine. 265590075Sobrien 265690075Sobrien@findex RETURN_ADDR_RTX 265790075Sobrien@item RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) 265890075SobrienA C expression whose value is RTL representing the value of the return 265990075Sobrienaddress for the frame @var{count} steps up from the current frame, after 266090075Sobrienthe prologue. @var{frameaddr} is the frame pointer of the @var{count} 266190075Sobrienframe, or the frame pointer of the @var{count} @minus{} 1 frame if 266290075Sobrien@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. 266390075Sobrien 266490075SobrienThe value of the expression must always be the correct address when 266590075Sobrien@var{count} is zero, but may be @code{NULL_RTX} if there is not way to 266690075Sobriendetermine the return address of other frames. 266790075Sobrien 266890075Sobrien@findex RETURN_ADDR_IN_PREVIOUS_FRAME 266990075Sobrien@item RETURN_ADDR_IN_PREVIOUS_FRAME 267090075SobrienDefine this if the return address of a particular stack frame is accessed 267190075Sobrienfrom the frame pointer of the previous stack frame. 267290075Sobrien 267390075Sobrien@findex INCOMING_RETURN_ADDR_RTX 267490075Sobrien@item INCOMING_RETURN_ADDR_RTX 267590075SobrienA C expression whose value is RTL representing the location of the 267690075Sobrienincoming return address at the beginning of any function, before the 267790075Sobrienprologue. This RTL is either a @code{REG}, indicating that the return 267890075Sobrienvalue is saved in @samp{REG}, or a @code{MEM} representing a location in 267990075Sobrienthe stack. 268090075Sobrien 268190075SobrienYou only need to define this macro if you want to support call frame 268290075Sobriendebugging information like that provided by DWARF 2. 268390075Sobrien 268490075SobrienIf this RTL is a @code{REG}, you should also define 268590075Sobrien@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. 268690075Sobrien 268790075Sobrien@findex INCOMING_FRAME_SP_OFFSET 268890075Sobrien@item INCOMING_FRAME_SP_OFFSET 268990075SobrienA C expression whose value is an integer giving the offset, in bytes, 269090075Sobrienfrom the value of the stack pointer register to the top of the stack 269190075Sobrienframe at the beginning of any function, before the prologue. The top of 269290075Sobrienthe frame is defined to be the value of the stack pointer in the 269390075Sobrienprevious frame, just before the call instruction. 269490075Sobrien 269590075SobrienYou only need to define this macro if you want to support call frame 269690075Sobriendebugging information like that provided by DWARF 2. 269790075Sobrien 269890075Sobrien@findex ARG_POINTER_CFA_OFFSET 269990075Sobrien@item ARG_POINTER_CFA_OFFSET (@var{fundecl}) 270090075SobrienA C expression whose value is an integer giving the offset, in bytes, 270190075Sobrienfrom the argument pointer to the canonical frame address (cfa). The 270290075Sobrienfinal value should coincide with that calculated by 270390075Sobrien@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable 270490075Sobrienduring virtual register instantiation. 270590075Sobrien 270690075SobrienThe default value for this macro is @code{FIRST_PARM_OFFSET (fundecl)}, 270790075Sobrienwhich is correct for most machines; in general, the arguments are found 270890075Sobrienimmediately before the stack frame. Note that this is not the case on 270990075Sobriensome targets that save registers into the caller's frame, such as SPARC 271090075Sobrienand rs6000, and so such targets need to define this macro. 271190075Sobrien 271290075SobrienYou only need to define this macro if the default is incorrect, and you 271390075Sobrienwant to support call frame debugging information like that provided by 271490075SobrienDWARF 2. 271590075Sobrien 271690075Sobrien@findex SMALL_STACK 271790075Sobrien@item SMALL_STACK 271890075SobrienDefine this macro if the stack size for the target is very small. This 271990075Sobrienhas the effect of disabling gcc's built-in @samp{alloca}, though 272090075Sobrien@samp{__builtin_alloca} is not affected. 272190075Sobrien@end table 272290075Sobrien 272390075Sobrien@node Exception Handling 272490075Sobrien@subsection Exception Handling Support 272590075Sobrien@cindex exception handling 272690075Sobrien 272790075Sobrien@table @code 272890075Sobrien@findex EH_RETURN_DATA_REGNO 272990075Sobrien@item EH_RETURN_DATA_REGNO (@var{N}) 273090075SobrienA C expression whose value is the @var{N}th register number used for 273190075Sobriendata by exception handlers, or @code{INVALID_REGNUM} if fewer than 273290075Sobrien@var{N} registers are usable. 273390075Sobrien 273490075SobrienThe exception handling library routines communicate with the exception 273590075Sobrienhandlers via a set of agreed upon registers. Ideally these registers 273690075Sobrienshould be call-clobbered; it is possible to use call-saved registers, 273790075Sobrienbut may negatively impact code size. The target must support at least 273890075Sobrien2 data registers, but should define 4 if there are enough free registers. 273990075Sobrien 274090075SobrienYou must define this macro if you want to support call frame exception 274190075Sobrienhandling like that provided by DWARF 2. 274290075Sobrien 274390075Sobrien@findex EH_RETURN_STACKADJ_RTX 274490075Sobrien@item EH_RETURN_STACKADJ_RTX 274590075SobrienA C expression whose value is RTL representing a location in which 274690075Sobriento store a stack adjustment to be applied before function return. 274790075SobrienThis is used to unwind the stack to an exception handler's call frame. 274890075SobrienIt will be assigned zero on code paths that return normally. 274990075Sobrien 275090075SobrienTypically this is a call-clobbered hard register that is otherwise 275190075Sobrienuntouched by the epilogue, but could also be a stack slot. 275290075Sobrien 275390075SobrienYou must define this macro if you want to support call frame exception 275490075Sobrienhandling like that provided by DWARF 2. 275590075Sobrien 275690075Sobrien@findex EH_RETURN_HANDLER_RTX 275790075Sobrien@item EH_RETURN_HANDLER_RTX 275890075SobrienA C expression whose value is RTL representing a location in which 275990075Sobriento store the address of an exception handler to which we should 276090075Sobrienreturn. It will not be assigned on code paths that return normally. 276190075Sobrien 276290075SobrienTypically this is the location in the call frame at which the normal 276390075Sobrienreturn address is stored. For targets that return by popping an 276490075Sobrienaddress off the stack, this might be a memory address just below 276590075Sobrienthe @emph{target} call frame rather than inside the current call 276690075Sobrienframe. @code{EH_RETURN_STACKADJ_RTX} will have already been assigned, 276790075Sobrienso it may be used to calculate the location of the target call frame. 276890075Sobrien 276990075SobrienSome targets have more complex requirements than storing to an 277090075Sobrienaddress calculable during initial code generation. In that case 277190075Sobrienthe @code{eh_return} instruction pattern should be used instead. 277290075Sobrien 277390075SobrienIf you want to support call frame exception handling, you must 277490075Sobriendefine either this macro or the @code{eh_return} instruction pattern. 277590075Sobrien 277690075Sobrien@findex ASM_PREFERRED_EH_DATA_FORMAT 277790075Sobrien@item ASM_PREFERRED_EH_DATA_FORMAT(@var{code}, @var{global}) 277890075SobrienThis macro chooses the encoding of pointers embedded in the exception 277990075Sobrienhandling sections. If at all possible, this should be defined such 278090075Sobrienthat the exception handling section will not require dynamic relocations, 278190075Sobrienand so may be read-only. 278290075Sobrien 278390075Sobrien@var{code} is 0 for data, 1 for code labels, 2 for function pointers. 278490075Sobrien@var{global} is true if the symbol may be affected by dynamic relocations. 278590075SobrienThe macro should return a combination of the @code{DW_EH_PE_*} defines 278690075Sobrienas found in @file{dwarf2.h}. 278790075Sobrien 278890075SobrienIf this macro is not defined, pointers will not be encoded but 278990075Sobrienrepresented directly. 279090075Sobrien 279190075Sobrien@findex ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX 279290075Sobrien@item ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) 279390075SobrienThis macro allows the target to emit whatever special magic is required 279490075Sobriento represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. 279590075SobrienGeneric code takes care of pc-relative and indirect encodings; this must 279690075Sobrienbe defined if the target uses text-relative or data-relative encodings. 279790075Sobrien 279890075SobrienThis is a C statement that branches to @var{done} if the format was 279990075Sobrienhandled. @var{encoding} is the format chosen, @var{size} is the number 280090075Sobrienof bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} 280190075Sobriento be emitted. 280290075Sobrien 280390075Sobrien@findex MD_FALLBACK_FRAME_STATE_FOR 280490075Sobrien@item MD_FALLBACK_FRAME_STATE_FOR(@var{context}, @var{fs}, @var{success}) 280590075SobrienThis macro allows the target to add cpu and operating system specific 280690075Sobriencode to the call-frame unwinder for use when there is no unwind data 280790075Sobrienavailable. The most common reason to implement this macro is to unwind 280890075Sobrienthrough signal frames. 280990075Sobrien 281090075SobrienThis macro is called from @code{uw_frame_state_for} in @file{unwind-dw2.c} 281190075Sobrienand @file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; 281290075Sobrien@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} 281390075Sobrienfor the address of the code being executed and @code{context->cfa} for 281490075Sobrienthe stack pointer value. If the frame can be decoded, the register save 281590075Sobrienaddresses should be updated in @var{fs} and the macro should branch to 281696263Sobrien@var{success}. If the frame cannot be decoded, the macro should do 281790075Sobriennothing. 281890075Sobrien@end table 281990075Sobrien 282090075Sobrien@node Stack Checking 282190075Sobrien@subsection Specifying How Stack Checking is Done 282290075Sobrien 282390075SobrienGCC will check that stack references are within the boundaries of 282490075Sobrienthe stack, if the @option{-fstack-check} is specified, in one of three ways: 282590075Sobrien 282690075Sobrien@enumerate 282790075Sobrien@item 282890075SobrienIf the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC 282990075Sobrienwill assume that you have arranged for stack checking to be done at 283090075Sobrienappropriate places in the configuration files, e.g., in 283190075Sobrien@code{TARGET_ASM_FUNCTION_PROLOGUE}. GCC will do not other special 283290075Sobrienprocessing. 283390075Sobrien 283490075Sobrien@item 283590075SobrienIf @code{STACK_CHECK_BUILTIN} is zero and you defined a named pattern 283690075Sobriencalled @code{check_stack} in your @file{md} file, GCC will call that 283790075Sobrienpattern with one argument which is the address to compare the stack 283890075Sobrienvalue against. You must arrange for this pattern to report an error if 283990075Sobrienthe stack pointer is out of range. 284090075Sobrien 284190075Sobrien@item 284290075SobrienIf neither of the above are true, GCC will generate code to periodically 284390075Sobrien``probe'' the stack pointer using the values of the macros defined below. 284490075Sobrien@end enumerate 284590075Sobrien 284690075SobrienNormally, you will use the default values of these macros, so GCC 284790075Sobrienwill use the third approach. 284890075Sobrien 284990075Sobrien@table @code 285090075Sobrien@findex STACK_CHECK_BUILTIN 285190075Sobrien@item STACK_CHECK_BUILTIN 285290075SobrienA nonzero value if stack checking is done by the configuration files in a 285390075Sobrienmachine-dependent manner. You should define this macro if stack checking 285490075Sobrienis require by the ABI of your machine or if you would like to have to stack 285590075Sobrienchecking in some more efficient way than GCC's portable approach. 285690075SobrienThe default value of this macro is zero. 285790075Sobrien 285890075Sobrien@findex STACK_CHECK_PROBE_INTERVAL 285990075Sobrien@item STACK_CHECK_PROBE_INTERVAL 286090075SobrienAn integer representing the interval at which GCC must generate stack 286190075Sobrienprobe instructions. You will normally define this macro to be no larger 286290075Sobrienthan the size of the ``guard pages'' at the end of a stack area. The 286390075Sobriendefault value of 4096 is suitable for most systems. 286490075Sobrien 286590075Sobrien@findex STACK_CHECK_PROBE_LOAD 286690075Sobrien@item STACK_CHECK_PROBE_LOAD 286790075SobrienA integer which is nonzero if GCC should perform the stack probe 286890075Sobrienas a load instruction and zero if GCC should use a store instruction. 286990075SobrienThe default is zero, which is the most efficient choice on most systems. 287090075Sobrien 287190075Sobrien@findex STACK_CHECK_PROTECT 287290075Sobrien@item STACK_CHECK_PROTECT 287390075SobrienThe number of bytes of stack needed to recover from a stack overflow, 287490075Sobrienfor languages where such a recovery is supported. The default value of 287590075Sobrien75 words should be adequate for most machines. 287690075Sobrien 287790075Sobrien@findex STACK_CHECK_MAX_FRAME_SIZE 287890075Sobrien@item STACK_CHECK_MAX_FRAME_SIZE 287990075SobrienThe maximum size of a stack frame, in bytes. GCC will generate probe 288090075Sobrieninstructions in non-leaf functions to ensure at least this many bytes of 288190075Sobrienstack are available. If a stack frame is larger than this size, stack 288290075Sobrienchecking will not be reliable and GCC will issue a warning. The 288390075Sobriendefault is chosen so that GCC only generates one instruction on most 288490075Sobriensystems. You should normally not change the default value of this macro. 288590075Sobrien 288690075Sobrien@findex STACK_CHECK_FIXED_FRAME_SIZE 288790075Sobrien@item STACK_CHECK_FIXED_FRAME_SIZE 288890075SobrienGCC uses this value to generate the above warning message. It 288990075Sobrienrepresents the amount of fixed frame used by a function, not including 289090075Sobrienspace for any callee-saved registers, temporaries and user variables. 289190075SobrienYou need only specify an upper bound for this amount and will normally 289290075Sobrienuse the default of four words. 289390075Sobrien 289490075Sobrien@findex STACK_CHECK_MAX_VAR_SIZE 289590075Sobrien@item STACK_CHECK_MAX_VAR_SIZE 289690075SobrienThe maximum size, in bytes, of an object that GCC will place in the 289790075Sobrienfixed area of the stack frame when the user specifies 289890075Sobrien@option{-fstack-check}. 289990075SobrienGCC computed the default from the values of the above macros and you will 290090075Sobriennormally not need to override that default. 290190075Sobrien@end table 290290075Sobrien 290390075Sobrien@need 2000 290490075Sobrien@node Frame Registers 290590075Sobrien@subsection Registers That Address the Stack Frame 290690075Sobrien 290790075Sobrien@c prevent bad page break with this line 290890075SobrienThis discusses registers that address the stack frame. 290990075Sobrien 291090075Sobrien@table @code 291190075Sobrien@findex STACK_POINTER_REGNUM 291290075Sobrien@item STACK_POINTER_REGNUM 291390075SobrienThe register number of the stack pointer register, which must also be a 291490075Sobrienfixed register according to @code{FIXED_REGISTERS}. On most machines, 291590075Sobrienthe hardware determines which register this is. 291690075Sobrien 291790075Sobrien@findex FRAME_POINTER_REGNUM 291890075Sobrien@item FRAME_POINTER_REGNUM 291990075SobrienThe register number of the frame pointer register, which is used to 292090075Sobrienaccess automatic variables in the stack frame. On some machines, the 292190075Sobrienhardware determines which register this is. On other machines, you can 292290075Sobrienchoose any register you wish for this purpose. 292390075Sobrien 292490075Sobrien@findex HARD_FRAME_POINTER_REGNUM 292590075Sobrien@item HARD_FRAME_POINTER_REGNUM 292690075SobrienOn some machines the offset between the frame pointer and starting 292790075Sobrienoffset of the automatic variables is not known until after register 292890075Sobrienallocation has been done (for example, because the saved registers are 292990075Sobrienbetween these two locations). On those machines, define 293090075Sobrien@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to 293190075Sobrienbe used internally until the offset is known, and define 293290075Sobrien@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number 293390075Sobrienused for the frame pointer. 293490075Sobrien 293590075SobrienYou should define this macro only in the very rare circumstances when it 293690075Sobrienis not possible to calculate the offset between the frame pointer and 293790075Sobrienthe automatic variables until after register allocation has been 293890075Sobriencompleted. When this macro is defined, you must also indicate in your 293990075Sobriendefinition of @code{ELIMINABLE_REGS} how to eliminate 294090075Sobrien@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} 294190075Sobrienor @code{STACK_POINTER_REGNUM}. 294290075Sobrien 294390075SobrienDo not define this macro if it would be the same as 294490075Sobrien@code{FRAME_POINTER_REGNUM}. 294590075Sobrien 294690075Sobrien@findex ARG_POINTER_REGNUM 294790075Sobrien@item ARG_POINTER_REGNUM 294890075SobrienThe register number of the arg pointer register, which is used to access 294990075Sobrienthe function's argument list. On some machines, this is the same as the 295090075Sobrienframe pointer register. On some machines, the hardware determines which 295190075Sobrienregister this is. On other machines, you can choose any register you 295290075Sobrienwish for this purpose. If this is not the same register as the frame 295390075Sobrienpointer register, then you must mark it as a fixed register according to 295490075Sobrien@code{FIXED_REGISTERS}, or arrange to be able to eliminate it 295590075Sobrien(@pxref{Elimination}). 295690075Sobrien 295790075Sobrien@findex RETURN_ADDRESS_POINTER_REGNUM 295890075Sobrien@item RETURN_ADDRESS_POINTER_REGNUM 295990075SobrienThe register number of the return address pointer register, which is used to 296090075Sobrienaccess the current function's return address from the stack. On some 296190075Sobrienmachines, the return address is not at a fixed offset from the frame 296290075Sobrienpointer or stack pointer or argument pointer. This register can be defined 296390075Sobriento point to the return address on the stack, and then be converted by 296490075Sobrien@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. 296590075Sobrien 296690075SobrienDo not define this macro unless there is no other way to get the return 296790075Sobrienaddress from the stack. 296890075Sobrien 296990075Sobrien@findex STATIC_CHAIN_REGNUM 297090075Sobrien@findex STATIC_CHAIN_INCOMING_REGNUM 297190075Sobrien@item STATIC_CHAIN_REGNUM 297290075Sobrien@itemx STATIC_CHAIN_INCOMING_REGNUM 297390075SobrienRegister numbers used for passing a function's static chain pointer. If 297490075Sobrienregister windows are used, the register number as seen by the called 297590075Sobrienfunction is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register 297690075Sobriennumber as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If 297790075Sobrienthese registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need 297890075Sobriennot be defined. 297990075Sobrien 298090075SobrienThe static chain register need not be a fixed register. 298190075Sobrien 298290075SobrienIf the static chain is passed in memory, these macros should not be 298390075Sobriendefined; instead, the next two macros should be defined. 298490075Sobrien 298590075Sobrien@findex STATIC_CHAIN 298690075Sobrien@findex STATIC_CHAIN_INCOMING 298790075Sobrien@item STATIC_CHAIN 298890075Sobrien@itemx STATIC_CHAIN_INCOMING 298990075SobrienIf the static chain is passed in memory, these macros provide rtx giving 299090075Sobrien@code{mem} expressions that denote where they are stored. 299190075Sobrien@code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations 299290075Sobrienas seen by the calling and called functions, respectively. Often the former 299390075Sobrienwill be at an offset from the stack pointer and the latter at an offset from 299490075Sobrienthe frame pointer. 299590075Sobrien 299690075Sobrien@findex stack_pointer_rtx 299790075Sobrien@findex frame_pointer_rtx 299890075Sobrien@findex arg_pointer_rtx 299990075SobrienThe variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 300090075Sobrien@code{arg_pointer_rtx} will have been initialized prior to the use of these 300190075Sobrienmacros and should be used to refer to those items. 300290075Sobrien 300390075SobrienIf the static chain is passed in a register, the two previous macros should 300490075Sobrienbe defined instead. 300590075Sobrien 300690075Sobrien@findex DWARF_FRAME_REGISTERS 300790075Sobrien@item DWARF_FRAME_REGISTERS 300890075SobrienThis macro specifies the maximum number of hard registers that can be 300990075Sobriensaved in a call frame. This is used to size data structures used in 301090075SobrienDWARF2 exception handling. 301190075Sobrien 301290075SobrienPrior to GCC 3.0, this macro was needed in order to establish a stable 301390075Sobrienexception handling ABI in the face of adding new hard registers for ISA 301490075Sobrienextensions. In GCC 3.0 and later, the EH ABI is insulated from changes 301590075Sobrienin the number of hard registers. Nevertheless, this macro can still be 301690075Sobrienused to reduce the runtime memory requirements of the exception handling 301790075Sobrienroutines, which can be substantial if the ISA contains a lot of 301890075Sobrienregisters that are not call-saved. 301990075Sobrien 302090075SobrienIf this macro is not defined, it defaults to 302190075Sobrien@code{FIRST_PSEUDO_REGISTER}. 302290075Sobrien 302390075Sobrien@findex PRE_GCC3_DWARF_FRAME_REGISTERS 302490075Sobrien@item PRE_GCC3_DWARF_FRAME_REGISTERS 302590075Sobrien 302690075SobrienThis macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided 302790075Sobrienfor backward compatibility in pre GCC 3.0 compiled code. 302890075Sobrien 302990075SobrienIf this macro is not defined, it defaults to 303090075Sobrien@code{DWARF_FRAME_REGISTERS}. 303190075Sobrien 303290075Sobrien@end table 303390075Sobrien 303490075Sobrien@node Elimination 303590075Sobrien@subsection Eliminating Frame Pointer and Arg Pointer 303690075Sobrien 303790075Sobrien@c prevent bad page break with this line 303890075SobrienThis is about eliminating the frame pointer and arg pointer. 303990075Sobrien 304090075Sobrien@table @code 304190075Sobrien@findex FRAME_POINTER_REQUIRED 304290075Sobrien@item FRAME_POINTER_REQUIRED 304390075SobrienA C expression which is nonzero if a function must have and use a frame 304490075Sobrienpointer. This expression is evaluated in the reload pass. If its value is 304590075Sobriennonzero the function will have a frame pointer. 304690075Sobrien 304790075SobrienThe expression can in principle examine the current function and decide 304890075Sobrienaccording to the facts, but on most machines the constant 0 or the 304990075Sobrienconstant 1 suffices. Use 0 when the machine allows code to be generated 305090075Sobrienwith no frame pointer, and doing so saves some time or space. Use 1 305190075Sobrienwhen there is no possible advantage to avoiding a frame pointer. 305290075Sobrien 305390075SobrienIn certain cases, the compiler does not know how to produce valid code 305490075Sobrienwithout a frame pointer. The compiler recognizes those cases and 305590075Sobrienautomatically gives the function a frame pointer regardless of what 305690075Sobrien@code{FRAME_POINTER_REQUIRED} says. You don't need to worry about 305790075Sobrienthem. 305890075Sobrien 305990075SobrienIn a function that does not require a frame pointer, the frame pointer 306090075Sobrienregister can be allocated for ordinary usage, unless you mark it as a 306190075Sobrienfixed register. See @code{FIXED_REGISTERS} for more information. 306290075Sobrien 306390075Sobrien@findex INITIAL_FRAME_POINTER_OFFSET 306490075Sobrien@findex get_frame_size 306590075Sobrien@item INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 306690075SobrienA C statement to store in the variable @var{depth-var} the difference 306790075Sobrienbetween the frame pointer and the stack pointer values immediately after 306890075Sobrienthe function prologue. The value would be computed from information 306990075Sobriensuch as the result of @code{get_frame_size ()} and the tables of 307090075Sobrienregisters @code{regs_ever_live} and @code{call_used_regs}. 307190075Sobrien 307290075SobrienIf @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 307390075Sobrienneed not be defined. Otherwise, it must be defined even if 307490075Sobrien@code{FRAME_POINTER_REQUIRED} is defined to always be true; in that 307590075Sobriencase, you may set @var{depth-var} to anything. 307690075Sobrien 307790075Sobrien@findex ELIMINABLE_REGS 307890075Sobrien@item ELIMINABLE_REGS 307990075SobrienIf defined, this macro specifies a table of register pairs used to 308090075Sobrieneliminate unneeded registers that point into the stack frame. If it is not 308190075Sobriendefined, the only elimination attempted by the compiler is to replace 308290075Sobrienreferences to the frame pointer with references to the stack pointer. 308390075Sobrien 308490075SobrienThe definition of this macro is a list of structure initializations, each 308590075Sobrienof which specifies an original and replacement register. 308690075Sobrien 308790075SobrienOn some machines, the position of the argument pointer is not known until 308890075Sobrienthe compilation is completed. In such a case, a separate hard register 308990075Sobrienmust be used for the argument pointer. This register can be eliminated by 309090075Sobrienreplacing it with either the frame pointer or the argument pointer, 309190075Sobriendepending on whether or not the frame pointer has been eliminated. 309290075Sobrien 309390075SobrienIn this case, you might specify: 309490075Sobrien@example 309590075Sobrien#define ELIMINABLE_REGS \ 309690075Sobrien@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 309790075Sobrien @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 309890075Sobrien @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 309990075Sobrien@end example 310090075Sobrien 310190075SobrienNote that the elimination of the argument pointer with the stack pointer is 310290075Sobrienspecified first since that is the preferred elimination. 310390075Sobrien 310490075Sobrien@findex CAN_ELIMINATE 310590075Sobrien@item CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) 310690075SobrienA C expression that returns nonzero if the compiler is allowed to try 310790075Sobriento replace register number @var{from-reg} with register number 310890075Sobrien@var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} 310990075Sobrienis defined, and will usually be the constant 1, since most of the cases 311090075Sobrienpreventing register elimination are things that the compiler already 311190075Sobrienknows about. 311290075Sobrien 311390075Sobrien@findex INITIAL_ELIMINATION_OFFSET 311490075Sobrien@item INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 311590075SobrienThis macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 311690075Sobrienspecifies the initial difference between the specified pair of 311790075Sobrienregisters. This macro must be defined if @code{ELIMINABLE_REGS} is 311890075Sobriendefined. 311990075Sobrien@end table 312090075Sobrien 312190075Sobrien@node Stack Arguments 312290075Sobrien@subsection Passing Function Arguments on the Stack 312390075Sobrien@cindex arguments on stack 312490075Sobrien@cindex stack arguments 312590075Sobrien 312690075SobrienThe macros in this section control how arguments are passed 312790075Sobrienon the stack. See the following section for other macros that 312890075Sobriencontrol passing certain arguments in registers. 312990075Sobrien 313090075Sobrien@table @code 313190075Sobrien@findex PROMOTE_PROTOTYPES 313290075Sobrien@item PROMOTE_PROTOTYPES 313390075SobrienA C expression whose value is nonzero if an argument declared in 313490075Sobriena prototype as an integral type smaller than @code{int} should 313590075Sobrienactually be passed as an @code{int}. In addition to avoiding 313690075Sobrienerrors in certain cases of mismatch, it also makes for better 313790075Sobriencode on certain machines. If the macro is not defined in target 313890075Sobrienheader files, it defaults to 0. 313990075Sobrien 314090075Sobrien@findex PUSH_ARGS 314190075Sobrien@item PUSH_ARGS 314290075SobrienA C expression. If nonzero, push insns will be used to pass 314390075Sobrienoutgoing arguments. 314490075SobrienIf the target machine does not have a push instruction, set it to zero. 314590075SobrienThat directs GCC to use an alternate strategy: to 314690075Sobrienallocate the entire argument block and then store the arguments into 314790075Sobrienit. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. 314890075SobrienOn some machines, the definition 314990075Sobrien 315090075Sobrien@findex PUSH_ROUNDING 315190075Sobrien@item PUSH_ROUNDING (@var{npushed}) 315290075SobrienA C expression that is the number of bytes actually pushed onto the 315390075Sobrienstack when an instruction attempts to push @var{npushed} bytes. 315490075Sobrien 315590075SobrienOn some machines, the definition 315690075Sobrien 315790075Sobrien@example 315890075Sobrien#define PUSH_ROUNDING(BYTES) (BYTES) 315990075Sobrien@end example 316090075Sobrien 316190075Sobrien@noindent 316290075Sobrienwill suffice. But on other machines, instructions that appear 316390075Sobriento push one byte actually push two bytes in an attempt to maintain 316490075Sobrienalignment. Then the definition should be 316590075Sobrien 316690075Sobrien@example 316790075Sobrien#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 316890075Sobrien@end example 316990075Sobrien 317090075Sobrien@findex ACCUMULATE_OUTGOING_ARGS 317190075Sobrien@findex current_function_outgoing_args_size 317290075Sobrien@item ACCUMULATE_OUTGOING_ARGS 317390075SobrienA C expression. If nonzero, the maximum amount of space required for outgoing arguments 317490075Sobrienwill be computed and placed into the variable 317590075Sobrien@code{current_function_outgoing_args_size}. No space will be pushed 317690075Sobrienonto the stack for each call; instead, the function prologue should 317790075Sobrienincrease the stack frame size by this amount. 317890075Sobrien 317990075SobrienSetting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 318090075Sobrienis not proper. 318190075Sobrien 318290075Sobrien@findex REG_PARM_STACK_SPACE 318390075Sobrien@item REG_PARM_STACK_SPACE (@var{fndecl}) 318490075SobrienDefine this macro if functions should assume that stack space has been 318590075Sobrienallocated for arguments even when their values are passed in 318690075Sobrienregisters. 318790075Sobrien 318890075SobrienThe value of this macro is the size, in bytes, of the area reserved for 318990075Sobrienarguments passed in registers for the function represented by @var{fndecl}, 319090075Sobrienwhich can be zero if GCC is calling a library function. 319190075Sobrien 319290075SobrienThis space can be allocated by the caller, or be a part of the 319390075Sobrienmachine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 319490075Sobrienwhich. 319590075Sobrien@c above is overfull. not sure what to do. --mew 5feb93 did 319690075Sobrien@c something, not sure if it looks good. --mew 10feb93 319790075Sobrien 319890075Sobrien@findex MAYBE_REG_PARM_STACK_SPACE 319990075Sobrien@findex FINAL_REG_PARM_STACK_SPACE 320090075Sobrien@item MAYBE_REG_PARM_STACK_SPACE 320190075Sobrien@itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) 320290075SobrienDefine these macros in addition to the one above if functions might 320390075Sobrienallocate stack space for arguments even when their values are passed 320490075Sobrienin registers. These should be used when the stack space allocated 320590075Sobrienfor arguments in registers is not a simple constant independent of the 320690075Sobrienfunction declaration. 320790075Sobrien 320890075SobrienThe value of the first macro is the size, in bytes, of the area that 320990075Sobrienwe should initially assume would be reserved for arguments passed in registers. 321090075Sobrien 321190075SobrienThe value of the second macro is the actual size, in bytes, of the area 321290075Sobrienthat will be reserved for arguments passed in registers. This takes two 321390075Sobrienarguments: an integer representing the number of bytes of fixed sized 321490075Sobrienarguments on the stack, and a tree representing the number of bytes of 321590075Sobrienvariable sized arguments on the stack. 321690075Sobrien 321790075SobrienWhen these macros are defined, @code{REG_PARM_STACK_SPACE} will only be 321890075Sobriencalled for libcall functions, the current function, or for a function 321990075Sobrienbeing called when it is known that such stack space must be allocated. 322090075SobrienIn each case this value can be easily computed. 322190075Sobrien 322290075SobrienWhen deciding whether a called function needs such stack space, and how 322390075Sobrienmuch space to reserve, GCC uses these two macros instead of 322490075Sobrien@code{REG_PARM_STACK_SPACE}. 322590075Sobrien 322690075Sobrien@findex OUTGOING_REG_PARM_STACK_SPACE 322790075Sobrien@item OUTGOING_REG_PARM_STACK_SPACE 322890075SobrienDefine this if it is the responsibility of the caller to allocate the area 322990075Sobrienreserved for arguments passed in registers. 323090075Sobrien 323190075SobrienIf @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 323290075Sobrienwhether the space for these arguments counts in the value of 323390075Sobrien@code{current_function_outgoing_args_size}. 323490075Sobrien 323590075Sobrien@findex STACK_PARMS_IN_REG_PARM_AREA 323690075Sobrien@item STACK_PARMS_IN_REG_PARM_AREA 323790075SobrienDefine this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 323890075Sobrienstack parameters don't skip the area specified by it. 323990075Sobrien@c i changed this, makes more sens and it should have taken care of the 324090075Sobrien@c overfull.. not as specific, tho. --mew 5feb93 324190075Sobrien 324290075SobrienNormally, when a parameter is not passed in registers, it is placed on the 324390075Sobrienstack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 324490075Sobriensuppresses this behavior and causes the parameter to be passed on the 324590075Sobrienstack in its natural location. 324690075Sobrien 324790075Sobrien@findex RETURN_POPS_ARGS 324890075Sobrien@item RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) 324990075SobrienA C expression that should indicate the number of bytes of its own 325090075Sobrienarguments that a function pops on returning, or 0 if the 325190075Sobrienfunction pops no arguments and the caller must therefore pop them all 325290075Sobrienafter the function returns. 325390075Sobrien 325490075Sobrien@var{fundecl} is a C variable whose value is a tree node that describes 325590075Sobrienthe function in question. Normally it is a node of type 325690075Sobrien@code{FUNCTION_DECL} that describes the declaration of the function. 325790075SobrienFrom this you can obtain the @code{DECL_ATTRIBUTES} of the function. 325890075Sobrien 325990075Sobrien@var{funtype} is a C variable whose value is a tree node that 326090075Sobriendescribes the function in question. Normally it is a node of type 326190075Sobrien@code{FUNCTION_TYPE} that describes the data type of the function. 326290075SobrienFrom this it is possible to obtain the data types of the value and 326390075Sobrienarguments (if known). 326490075Sobrien 326590075SobrienWhen a call to a library function is being considered, @var{fundecl} 326690075Sobrienwill contain an identifier node for the library function. Thus, if 326790075Sobrienyou need to distinguish among various library functions, you can do so 326890075Sobrienby their names. Note that ``library function'' in this context means 326990075Sobriena function used to perform arithmetic, whose name is known specially 327090075Sobrienin the compiler and was not mentioned in the C code being compiled. 327190075Sobrien 327290075Sobrien@var{stack-size} is the number of bytes of arguments passed on the 327390075Sobrienstack. If a variable number of bytes is passed, it is zero, and 327490075Sobrienargument popping will always be the responsibility of the calling function. 327590075Sobrien 327690075SobrienOn the VAX, all functions always pop their arguments, so the definition 327790075Sobrienof this macro is @var{stack-size}. On the 68000, using the standard 327890075Sobriencalling convention, no functions pop their arguments, so the value of 327990075Sobrienthe macro is always 0 in this case. But an alternative calling 328090075Sobrienconvention is available in which functions that take a fixed number of 328190075Sobrienarguments pop them but other functions (such as @code{printf}) pop 328290075Sobriennothing (the caller pops all). When this convention is in use, 328390075Sobrien@var{funtype} is examined to determine whether a function takes a fixed 328490075Sobriennumber of arguments. 328596263Sobrien 328696263Sobrien@findex CALL_POPS_ARGS 328796263Sobrien@item CALL_POPS_ARGS (@var{cum}) 328896263SobrienA C expression that should indicate the number of bytes a call sequence 328996263Sobrienpops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 329096263Sobrienwhen compiling a function call. 329196263Sobrien 329296263Sobrien@var{cum} is the variable in which all arguments to the called function 329396263Sobrienhave been accumulated. 329496263Sobrien 329596263SobrienOn certain architectures, such as the SH5, a call trampoline is used 329696263Sobrienthat pops certain registers off the stack, depending on the arguments 329796263Sobrienthat have been passed to the function. Since this is a property of the 329896263Sobriencall site, not of the called function, @code{RETURN_POPS_ARGS} is not 329996263Sobrienappropriate. 330096263Sobrien 330190075Sobrien@end table 330290075Sobrien 330390075Sobrien@node Register Arguments 330490075Sobrien@subsection Passing Arguments in Registers 330590075Sobrien@cindex arguments in registers 330690075Sobrien@cindex registers arguments 330790075Sobrien 330890075SobrienThis section describes the macros which let you control how various 330990075Sobrientypes of arguments are passed in registers or how they are arranged in 331090075Sobrienthe stack. 331190075Sobrien 331290075Sobrien@table @code 331390075Sobrien@findex FUNCTION_ARG 331490075Sobrien@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 331590075SobrienA C expression that controls whether a function argument is passed 331690075Sobrienin a register, and which register. 331790075Sobrien 331890075SobrienThe arguments are @var{cum}, which summarizes all the previous 331990075Sobrienarguments; @var{mode}, the machine mode of the argument; @var{type}, 332090075Sobrienthe data type of the argument as a tree node or 0 if that is not known 332190075Sobrien(which happens for C support library functions); and @var{named}, 332290075Sobrienwhich is 1 for an ordinary argument and 0 for nameless arguments that 332390075Sobriencorrespond to @samp{@dots{}} in the called function's prototype. 332490075Sobrien@var{type} can be an incomplete type if a syntax error has previously 332590075Sobrienoccurred. 332690075Sobrien 332790075SobrienThe value of the expression is usually either a @code{reg} RTX for the 332890075Sobrienhard register in which to pass the argument, or zero to pass the 332990075Sobrienargument on the stack. 333090075Sobrien 333190075SobrienFor machines like the VAX and 68000, where normally all arguments are 333290075Sobrienpushed, zero suffices as a definition. 333390075Sobrien 333490075SobrienThe value of the expression can also be a @code{parallel} RTX@. This is 333590075Sobrienused when an argument is passed in multiple locations. The mode of the 333690075Sobrienof the @code{parallel} should be the mode of the entire argument. The 333790075Sobrien@code{parallel} holds any number of @code{expr_list} pairs; each one 333890075Sobriendescribes where part of the argument is passed. In each 333990075Sobrien@code{expr_list} the first operand must be a @code{reg} RTX for the hard 334090075Sobrienregister in which to pass this part of the argument, and the mode of the 334190075Sobrienregister RTX indicates how large this part of the argument is. The 334290075Sobriensecond operand of the @code{expr_list} is a @code{const_int} which gives 334390075Sobrienthe offset in bytes into the entire argument of where this part starts. 334490075SobrienAs a special exception the first @code{expr_list} in the @code{parallel} 334590075SobrienRTX may have a first operand of zero. This indicates that the entire 334690075Sobrienargument is also stored on the stack. 334790075Sobrien 334890075SobrienThe last time this macro is called, it is called with @code{MODE == 334990075SobrienVOIDmode}, and its result is passed to the @code{call} or @code{call_value} 335090075Sobrienpattern as operands 2 and 3 respectively. 335190075Sobrien 335290075Sobrien@cindex @file{stdarg.h} and register arguments 335390075SobrienThe usual way to make the ISO library @file{stdarg.h} work on a machine 335490075Sobrienwhere some arguments are usually passed in registers, is to cause 335590075Sobriennameless arguments to be passed on the stack instead. This is done 335690075Sobrienby making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. 335790075Sobrien 335890075Sobrien@cindex @code{MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} 335990075Sobrien@cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} 336090075SobrienYou may use the macro @code{MUST_PASS_IN_STACK (@var{mode}, @var{type})} 336190075Sobrienin the definition of this macro to determine if this argument is of a 336290075Sobrientype that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 336390075Sobrienis not defined and @code{FUNCTION_ARG} returns nonzero for such an 336490075Sobrienargument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 336590075Sobriendefined, the argument will be computed in the stack and then loaded into 336690075Sobriena register. 336790075Sobrien 336890075Sobrien@findex MUST_PASS_IN_STACK 336990075Sobrien@item MUST_PASS_IN_STACK (@var{mode}, @var{type}) 337090075SobrienDefine as a C expression that evaluates to nonzero if we do not know how 337190075Sobriento pass TYPE solely in registers. The file @file{expr.h} defines a 337290075Sobriendefinition that is usually appropriate, refer to @file{expr.h} for additional 337390075Sobriendocumentation. 337490075Sobrien 337590075Sobrien@findex FUNCTION_INCOMING_ARG 337690075Sobrien@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 337790075SobrienDefine this macro if the target machine has ``register windows'', so 337890075Sobrienthat the register in which a function sees an arguments is not 337990075Sobriennecessarily the same as the one in which the caller passed the 338090075Sobrienargument. 338190075Sobrien 338290075SobrienFor such machines, @code{FUNCTION_ARG} computes the register in which 338390075Sobrienthe caller passes the value, and @code{FUNCTION_INCOMING_ARG} should 338490075Sobrienbe defined in a similar fashion to tell the function being called 338590075Sobrienwhere the arguments will arrive. 338690075Sobrien 338790075SobrienIf @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} 338890075Sobrienserves both purposes. 338990075Sobrien 339090075Sobrien@findex FUNCTION_ARG_PARTIAL_NREGS 339190075Sobrien@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) 339290075SobrienA C expression for the number of words, at the beginning of an 339390075Sobrienargument, that must be put in registers. The value must be zero for 339490075Sobrienarguments that are passed entirely in registers or that are entirely 339590075Sobrienpushed on the stack. 339690075Sobrien 339790075SobrienOn some machines, certain arguments must be passed partially in 339890075Sobrienregisters and partially in memory. On these machines, typically the 339990075Sobrienfirst @var{n} words of arguments are passed in registers, and the rest 340090075Sobrienon the stack. If a multi-word argument (a @code{double} or a 340190075Sobrienstructure) crosses that boundary, its first few words must be passed 340290075Sobrienin registers and the rest must be pushed. This macro tells the 340390075Sobriencompiler when this occurs, and how many of the words should go in 340490075Sobrienregisters. 340590075Sobrien 340690075Sobrien@code{FUNCTION_ARG} for these arguments should return the first 340790075Sobrienregister to be used by the caller for this argument; likewise 340890075Sobrien@code{FUNCTION_INCOMING_ARG}, for the called function. 340990075Sobrien 341090075Sobrien@findex FUNCTION_ARG_PASS_BY_REFERENCE 341190075Sobrien@item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 341290075SobrienA C expression that indicates when an argument must be passed by reference. 341390075SobrienIf nonzero for an argument, a copy of that argument is made in memory and a 341490075Sobrienpointer to the argument is passed instead of the argument itself. 341590075SobrienThe pointer is passed in whatever way is appropriate for passing a pointer 341690075Sobriento that type. 341790075Sobrien 341890075SobrienOn machines where @code{REG_PARM_STACK_SPACE} is not defined, a suitable 341990075Sobriendefinition of this macro might be 342090075Sobrien@smallexample 342190075Sobrien#define FUNCTION_ARG_PASS_BY_REFERENCE\ 342290075Sobrien(CUM, MODE, TYPE, NAMED) \ 342390075Sobrien MUST_PASS_IN_STACK (MODE, TYPE) 342490075Sobrien@end smallexample 342590075Sobrien@c this is *still* too long. --mew 5feb93 342690075Sobrien 342790075Sobrien@findex FUNCTION_ARG_CALLEE_COPIES 342890075Sobrien@item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) 342990075SobrienIf defined, a C expression that indicates when it is the called function's 343090075Sobrienresponsibility to make a copy of arguments passed by invisible reference. 343190075SobrienNormally, the caller makes a copy and passes the address of the copy to the 343290075Sobrienroutine being called. When @code{FUNCTION_ARG_CALLEE_COPIES} is defined and is 343390075Sobriennonzero, the caller does not make a copy. Instead, it passes a pointer to the 343490075Sobrien``live'' value. The called function must not modify this value. If it can be 343590075Sobriendetermined that the value won't be modified, it need not make a copy; 343690075Sobrienotherwise a copy must be made. 343790075Sobrien 343890075Sobrien@findex FUNCTION_ARG_REG_LITTLE_ENDIAN 343990075Sobrien@item FUNCTION_ARG_REG_LITTLE_ENDIAN 344090075SobrienIf defined TRUE on a big-endian system then structure arguments passed 344190075Sobrien(and returned) in registers are passed in a little-endian manner instead of 344290075Sobrienthe big-endian manner. On the HP-UX IA64 and PA64 platforms structures are 344390075Sobrienaligned differently then integral values and setting this value to true will 344490075Sobrienallow for the special handling of structure arguments and return values. 344590075Sobrien 344690075Sobrien@findex CUMULATIVE_ARGS 344790075Sobrien@item CUMULATIVE_ARGS 344890075SobrienA C type for declaring a variable that is used as the first argument of 344990075Sobrien@code{FUNCTION_ARG} and other related values. For some target machines, 345090075Sobrienthe type @code{int} suffices and can hold the number of bytes of 345190075Sobrienargument so far. 345290075Sobrien 345390075SobrienThere is no need to record in @code{CUMULATIVE_ARGS} anything about the 345490075Sobrienarguments that have been passed on the stack. The compiler has other 345590075Sobrienvariables to keep track of that. For target machines on which all 345690075Sobrienarguments are passed on the stack, there is no need to store anything in 345790075Sobrien@code{CUMULATIVE_ARGS}; however, the data structure must exist and 345890075Sobrienshould not be empty, so use @code{int}. 345990075Sobrien 346090075Sobrien@findex INIT_CUMULATIVE_ARGS 346190075Sobrien@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{indirect}) 346290075SobrienA C statement (sans semicolon) for initializing the variable @var{cum} 346390075Sobrienfor the state at the beginning of the argument list. The variable has 346490075Sobrientype @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node 346590075Sobrienfor the data type of the function which will receive the args, or 0 346690075Sobrienif the args are to a compiler support library function. The value of 346790075Sobrien@var{indirect} is nonzero when processing an indirect call, for example 346890075Sobriena call through a function pointer. The value of @var{indirect} is zero 346990075Sobrienfor a call to an explicitly named function, a library function call, or when 347090075Sobrien@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 347190075Sobrienbeing compiled. 347290075Sobrien 347390075SobrienWhen processing a call to a compiler support library function, 347490075Sobrien@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 347590075Sobriencontains the name of the function, as a string. @var{libname} is 0 when 347690075Sobrienan ordinary C function call is being processed. Thus, each time this 347790075Sobrienmacro is called, either @var{libname} or @var{fntype} is nonzero, but 347890075Sobriennever both of them at once. 347990075Sobrien 348090075Sobrien@findex INIT_CUMULATIVE_LIBCALL_ARGS 348190075Sobrien@item INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 348290075SobrienLike @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 348390075Sobrienit gets a @code{MODE} argument instead of @var{fntype}, that would be 348490075Sobrien@code{NULL}. @var{indirect} would always be zero, too. If this macro 348590075Sobrienis not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 348690075Sobrien0)} is used instead. 348790075Sobrien 348890075Sobrien@findex INIT_CUMULATIVE_INCOMING_ARGS 348990075Sobrien@item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 349090075SobrienLike @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 349190075Sobrienfinding the arguments for the function being compiled. If this macro is 349290075Sobrienundefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 349390075Sobrien 349490075SobrienThe value passed for @var{libname} is always 0, since library routines 349590075Sobrienwith special calling conventions are never compiled with GCC@. The 349690075Sobrienargument @var{libname} exists for symmetry with 349790075Sobrien@code{INIT_CUMULATIVE_ARGS}. 349890075Sobrien@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 349990075Sobrien@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 350090075Sobrien 350190075Sobrien@findex FUNCTION_ARG_ADVANCE 350290075Sobrien@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 350390075SobrienA C statement (sans semicolon) to update the summarizer variable 350490075Sobrien@var{cum} to advance past an argument in the argument list. The 350590075Sobrienvalues @var{mode}, @var{type} and @var{named} describe that argument. 350690075SobrienOnce this is done, the variable @var{cum} is suitable for analyzing 350790075Sobrienthe @emph{following} argument with @code{FUNCTION_ARG}, etc. 350890075Sobrien 350990075SobrienThis macro need not do anything if the argument in question was passed 351090075Sobrienon the stack. The compiler knows how to track the amount of stack space 351190075Sobrienused for arguments without any special help. 351290075Sobrien 351390075Sobrien@findex FUNCTION_ARG_PADDING 351490075Sobrien@item FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 351590075SobrienIf defined, a C expression which determines whether, and in which direction, 351690075Sobriento pad out an argument with extra space. The value should be of type 351790075Sobrien@code{enum direction}: either @code{upward} to pad above the argument, 351890075Sobrien@code{downward} to pad below, or @code{none} to inhibit padding. 351990075Sobrien 352090075SobrienThe @emph{amount} of padding is always just enough to reach the next 352190075Sobrienmultiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control 352290075Sobrienit. 352390075Sobrien 352490075SobrienThis macro has a default definition which is right for most systems. 352590075SobrienFor little-endian machines, the default is to pad upward. For 352690075Sobrienbig-endian machines, the default is to pad downward for an argument of 352790075Sobrienconstant size shorter than an @code{int}, and upward otherwise. 352890075Sobrien 352990075Sobrien@findex PAD_VARARGS_DOWN 353090075Sobrien@item PAD_VARARGS_DOWN 353190075SobrienIf defined, a C expression which determines whether the default 353290075Sobrienimplementation of va_arg will attempt to pad down before reading the 353390075Sobriennext argument, if that argument is smaller than its aligned space as 353490075Sobriencontrolled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 353590075Sobrienarguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 353690075Sobrien 353790075Sobrien@findex FUNCTION_ARG_BOUNDARY 353890075Sobrien@item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) 353990075SobrienIf defined, a C expression that gives the alignment boundary, in bits, 354090075Sobrienof an argument with the specified mode and type. If it is not defined, 354190075Sobrien@code{PARM_BOUNDARY} is used for all arguments. 354290075Sobrien 354390075Sobrien@findex FUNCTION_ARG_REGNO_P 354490075Sobrien@item FUNCTION_ARG_REGNO_P (@var{regno}) 354590075SobrienA C expression that is nonzero if @var{regno} is the number of a hard 354690075Sobrienregister in which function arguments are sometimes passed. This does 354790075Sobrien@emph{not} include implicit arguments such as the static chain and 354890075Sobrienthe structure-value address. On many machines, no registers can be 354990075Sobrienused for this purpose since all function arguments are pushed on the 355090075Sobrienstack. 355190075Sobrien 355290075Sobrien@findex LOAD_ARGS_REVERSED 355390075Sobrien@item LOAD_ARGS_REVERSED 355490075SobrienIf defined, the order in which arguments are loaded into their 355590075Sobrienrespective argument registers is reversed so that the last 355690075Sobrienargument is loaded first. This macro only affects arguments 355790075Sobrienpassed in registers. 355890075Sobrien 355990075Sobrien@end table 356090075Sobrien 356190075Sobrien@node Scalar Return 356290075Sobrien@subsection How Scalar Function Values Are Returned 356390075Sobrien@cindex return values in registers 356490075Sobrien@cindex values, returned by functions 356590075Sobrien@cindex scalars, returned as values 356690075Sobrien 356790075SobrienThis section discusses the macros that control returning scalars as 356890075Sobrienvalues---values that can fit in registers. 356990075Sobrien 357090075Sobrien@table @code 357190075Sobrien@findex TRADITIONAL_RETURN_FLOAT 357290075Sobrien@item TRADITIONAL_RETURN_FLOAT 357390075SobrienDefine this macro if @option{-traditional} should not cause functions 357490075Sobriendeclared to return @code{float} to convert the value to @code{double}. 357590075Sobrien 357690075Sobrien@findex FUNCTION_VALUE 357790075Sobrien@item FUNCTION_VALUE (@var{valtype}, @var{func}) 357890075SobrienA C expression to create an RTX representing the place where a 357990075Sobrienfunction returns a value of data type @var{valtype}. @var{valtype} is 358090075Sobriena tree node representing a data type. Write @code{TYPE_MODE 358190075Sobrien(@var{valtype})} to get the machine mode used to represent that type. 358290075SobrienOn many machines, only the mode is relevant. (Actually, on most 358390075Sobrienmachines, scalar values are returned in the same place regardless of 358490075Sobrienmode). 358590075Sobrien 358690075SobrienThe value of the expression is usually a @code{reg} RTX for the hard 358790075Sobrienregister where the return value is stored. The value can also be a 358890075Sobrien@code{parallel} RTX, if the return value is in multiple places. See 358990075Sobrien@code{FUNCTION_ARG} for an explanation of the @code{parallel} form. 359090075Sobrien 359190075SobrienIf @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same 359290075Sobrienpromotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a 359390075Sobrienscalar type. 359490075Sobrien 359590075SobrienIf the precise function being called is known, @var{func} is a tree 359690075Sobriennode (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 359790075Sobrienpointer. This makes it possible to use a different value-returning 359890075Sobrienconvention for specific functions when all their calls are 359990075Sobrienknown. 360090075Sobrien 360190075Sobrien@code{FUNCTION_VALUE} is not used for return vales with aggregate data 360290075Sobrientypes, because these are returned in another way. See 360390075Sobrien@code{STRUCT_VALUE_REGNUM} and related macros, below. 360490075Sobrien 360590075Sobrien@findex FUNCTION_OUTGOING_VALUE 360690075Sobrien@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) 360790075SobrienDefine this macro if the target machine has ``register windows'' 360890075Sobrienso that the register in which a function returns its value is not 360990075Sobrienthe same as the one in which the caller sees the value. 361090075Sobrien 361190075SobrienFor such machines, @code{FUNCTION_VALUE} computes the register in which 361290075Sobrienthe caller will see the value. @code{FUNCTION_OUTGOING_VALUE} should be 361390075Sobriendefined in a similar fashion to tell the function where to put the 361490075Sobrienvalue. 361590075Sobrien 361690075SobrienIf @code{FUNCTION_OUTGOING_VALUE} is not defined, 361790075Sobrien@code{FUNCTION_VALUE} serves both purposes. 361890075Sobrien 361990075Sobrien@code{FUNCTION_OUTGOING_VALUE} is not used for return vales with 362090075Sobrienaggregate data types, because these are returned in another way. See 362190075Sobrien@code{STRUCT_VALUE_REGNUM} and related macros, below. 362290075Sobrien 362390075Sobrien@findex LIBCALL_VALUE 362490075Sobrien@item LIBCALL_VALUE (@var{mode}) 362590075SobrienA C expression to create an RTX representing the place where a library 362690075Sobrienfunction returns a value of mode @var{mode}. If the precise function 362790075Sobrienbeing called is known, @var{func} is a tree node 362890075Sobrien(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 362990075Sobrienpointer. This makes it possible to use a different value-returning 363090075Sobrienconvention for specific functions when all their calls are 363190075Sobrienknown. 363290075Sobrien 363390075SobrienNote that ``library function'' in this context means a compiler 363490075Sobriensupport routine, used to perform arithmetic, whose name is known 363590075Sobrienspecially by the compiler and was not mentioned in the C code being 363690075Sobriencompiled. 363790075Sobrien 363890075SobrienThe definition of @code{LIBRARY_VALUE} need not be concerned aggregate 363990075Sobriendata types, because none of the library functions returns such types. 364090075Sobrien 364190075Sobrien@findex FUNCTION_VALUE_REGNO_P 364290075Sobrien@item FUNCTION_VALUE_REGNO_P (@var{regno}) 364390075SobrienA C expression that is nonzero if @var{regno} is the number of a hard 364490075Sobrienregister in which the values of called function may come back. 364590075Sobrien 364690075SobrienA register whose use for returning values is limited to serving as the 364790075Sobriensecond of a pair (for a value of type @code{double}, say) need not be 364890075Sobrienrecognized by this macro. So for most machines, this definition 364990075Sobriensuffices: 365090075Sobrien 365190075Sobrien@example 365290075Sobrien#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 365390075Sobrien@end example 365490075Sobrien 365590075SobrienIf the machine has register windows, so that the caller and the called 365690075Sobrienfunction use different registers for the return value, this macro 365790075Sobrienshould recognize only the caller's register numbers. 365890075Sobrien 365990075Sobrien@findex APPLY_RESULT_SIZE 366090075Sobrien@item APPLY_RESULT_SIZE 366190075SobrienDefine this macro if @samp{untyped_call} and @samp{untyped_return} 366290075Sobrienneed more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 366390075Sobriensaving and restoring an arbitrary return value. 366490075Sobrien@end table 366590075Sobrien 366690075Sobrien@node Aggregate Return 366790075Sobrien@subsection How Large Values Are Returned 366890075Sobrien@cindex aggregates as return values 366990075Sobrien@cindex large return values 367090075Sobrien@cindex returning aggregate values 367190075Sobrien@cindex structure value address 367290075Sobrien 367390075SobrienWhen a function value's mode is @code{BLKmode} (and in some other 367490075Sobriencases), the value is not returned according to @code{FUNCTION_VALUE} 367590075Sobrien(@pxref{Scalar Return}). Instead, the caller passes the address of a 367690075Sobrienblock of memory in which the value should be stored. This address 367790075Sobrienis called the @dfn{structure value address}. 367890075Sobrien 367990075SobrienThis section describes how to control returning structure values in 368090075Sobrienmemory. 368190075Sobrien 368290075Sobrien@table @code 368390075Sobrien@findex RETURN_IN_MEMORY 368490075Sobrien@item RETURN_IN_MEMORY (@var{type}) 368590075SobrienA C expression which can inhibit the returning of certain function 368690075Sobrienvalues in registers, based on the type of value. A nonzero value says 368790075Sobriento return the function value in memory, just as large structures are 368890075Sobrienalways returned. Here @var{type} will be a C expression of type 368990075Sobrien@code{tree}, representing the data type of the value. 369090075Sobrien 369190075SobrienNote that values of mode @code{BLKmode} must be explicitly handled 369290075Sobrienby this macro. Also, the option @option{-fpcc-struct-return} 369390075Sobrientakes effect regardless of this macro. On most systems, it is 369490075Sobrienpossible to leave the macro undefined; this causes a default 369590075Sobriendefinition to be used, whose value is the constant 1 for @code{BLKmode} 369690075Sobrienvalues, and 0 otherwise. 369790075Sobrien 369890075SobrienDo not use this macro to indicate that structures and unions should always 369990075Sobrienbe returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 370090075Sobriento indicate this. 370190075Sobrien 370290075Sobrien@findex DEFAULT_PCC_STRUCT_RETURN 370390075Sobrien@item DEFAULT_PCC_STRUCT_RETURN 370490075SobrienDefine this macro to be 1 if all structure and union return values must be 370590075Sobrienin memory. Since this results in slower code, this should be defined 370690075Sobrienonly if needed for compatibility with other compilers or with an ABI@. 370790075SobrienIf you define this macro to be 0, then the conventions used for structure 370890075Sobrienand union return values are decided by the @code{RETURN_IN_MEMORY} macro. 370990075Sobrien 371090075SobrienIf not defined, this defaults to the value 1. 371190075Sobrien 371290075Sobrien@findex STRUCT_VALUE_REGNUM 371390075Sobrien@item STRUCT_VALUE_REGNUM 371490075SobrienIf the structure value address is passed in a register, then 371590075Sobrien@code{STRUCT_VALUE_REGNUM} should be the number of that register. 371690075Sobrien 371790075Sobrien@findex STRUCT_VALUE 371890075Sobrien@item STRUCT_VALUE 371990075SobrienIf the structure value address is not passed in a register, define 372090075Sobrien@code{STRUCT_VALUE} as an expression returning an RTX for the place 372190075Sobrienwhere the address is passed. If it returns 0, the address is passed as 372290075Sobrienan ``invisible'' first argument. 372390075Sobrien 372490075Sobrien@findex STRUCT_VALUE_INCOMING_REGNUM 372590075Sobrien@item STRUCT_VALUE_INCOMING_REGNUM 372690075SobrienOn some architectures the place where the structure value address 372790075Sobrienis found by the called function is not the same place that the 372890075Sobriencaller put it. This can be due to register windows, or it could 372990075Sobrienbe because the function prologue moves it to a different place. 373090075Sobrien 373190075SobrienIf the incoming location of the structure value address is in a 373290075Sobrienregister, define this macro as the register number. 373390075Sobrien 373490075Sobrien@findex STRUCT_VALUE_INCOMING 373590075Sobrien@item STRUCT_VALUE_INCOMING 373690075SobrienIf the incoming location is not a register, then you should define 373790075Sobrien@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the 373890075Sobriencalled function should find the value. If it should find the value on 373990075Sobrienthe stack, define this to create a @code{mem} which refers to the frame 374090075Sobrienpointer. A definition of 0 means that the address is passed as an 374190075Sobrien``invisible'' first argument. 374290075Sobrien 374390075Sobrien@findex PCC_STATIC_STRUCT_RETURN 374490075Sobrien@item PCC_STATIC_STRUCT_RETURN 374590075SobrienDefine this macro if the usual system convention on the target machine 374690075Sobrienfor returning structures and unions is for the called function to return 374790075Sobrienthe address of a static variable containing the value. 374890075Sobrien 374990075SobrienDo not define this if the usual system convention is for the caller to 375090075Sobrienpass an address to the subroutine. 375190075Sobrien 375290075SobrienThis macro has effect in @option{-fpcc-struct-return} mode, but it does 375390075Sobriennothing when you use @option{-freg-struct-return} mode. 375490075Sobrien@end table 375590075Sobrien 375690075Sobrien@node Caller Saves 375790075Sobrien@subsection Caller-Saves Register Allocation 375890075Sobrien 375990075SobrienIf you enable it, GCC can save registers around function calls. This 376090075Sobrienmakes it possible to use call-clobbered registers to hold variables that 376190075Sobrienmust live across calls. 376290075Sobrien 376390075Sobrien@table @code 376490075Sobrien@findex DEFAULT_CALLER_SAVES 376590075Sobrien@item DEFAULT_CALLER_SAVES 376690075SobrienDefine this macro if function calls on the target machine do not preserve 376790075Sobrienany registers; in other words, if @code{CALL_USED_REGISTERS} has 1 376890075Sobrienfor all registers. When defined, this macro enables @option{-fcaller-saves} 376990075Sobrienby default for all optimization levels. It has no effect for optimization 377090075Sobrienlevels 2 and higher, where @option{-fcaller-saves} is the default. 377190075Sobrien 377290075Sobrien@findex CALLER_SAVE_PROFITABLE 377390075Sobrien@item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 377490075SobrienA C expression to determine whether it is worthwhile to consider placing 377590075Sobriena pseudo-register in a call-clobbered hard register and saving and 377690075Sobrienrestoring it around each function call. The expression should be 1 when 377790075Sobrienthis is worth doing, and 0 otherwise. 377890075Sobrien 377990075SobrienIf you don't define this macro, a default is used which is good on most 378090075Sobrienmachines: @code{4 * @var{calls} < @var{refs}}. 378190075Sobrien 378290075Sobrien@findex HARD_REGNO_CALLER_SAVE_MODE 378390075Sobrien@item HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 378490075SobrienA C expression specifying which mode is required for saving @var{nregs} 378590075Sobrienof a pseudo-register in call-clobbered hard register @var{regno}. If 378690075Sobrien@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 378790075Sobrienreturned. For most machines this macro need not be defined since GCC 378890075Sobrienwill select the smallest suitable mode. 378990075Sobrien@end table 379090075Sobrien 379190075Sobrien@node Function Entry 379290075Sobrien@subsection Function Entry and Exit 379390075Sobrien@cindex function entry and exit 379490075Sobrien@cindex prologue 379590075Sobrien@cindex epilogue 379690075Sobrien 379790075SobrienThis section describes the macros that output function entry 379890075Sobrien(@dfn{prologue}) and exit (@dfn{epilogue}) code. 379990075Sobrien 380090075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 380190075SobrienIf defined, a function that outputs the assembler code for entry to a 380290075Sobrienfunction. The prologue is responsible for setting up the stack frame, 380390075Sobrieninitializing the frame pointer register, saving registers that must be 380490075Sobriensaved, and allocating @var{size} additional bytes of storage for the 380590075Sobrienlocal variables. @var{size} is an integer. @var{file} is a stdio 380690075Sobrienstream to which the assembler code should be output. 380790075Sobrien 380890075SobrienThe label for the beginning of the function need not be output by this 380990075Sobrienmacro. That has already been done when the macro is run. 381090075Sobrien 381190075Sobrien@findex regs_ever_live 381290075SobrienTo determine which registers to save, the macro can refer to the array 381390075Sobrien@code{regs_ever_live}: element @var{r} is nonzero if hard register 381490075Sobrien@var{r} is used anywhere within the function. This implies the function 381590075Sobrienprologue should save register @var{r}, provided it is not one of the 381690075Sobriencall-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 381790075Sobrien@code{regs_ever_live}.) 381890075Sobrien 381990075SobrienOn machines that have ``register windows'', the function entry code does 382090075Sobriennot save on the stack the registers that are in the windows, even if 382190075Sobrienthey are supposed to be preserved by function calls; instead it takes 382290075Sobrienappropriate steps to ``push'' the register stack, if any non-call-used 382390075Sobrienregisters are used in the function. 382490075Sobrien 382590075Sobrien@findex frame_pointer_needed 382690075SobrienOn machines where functions may or may not have frame-pointers, the 382790075Sobrienfunction entry code must vary accordingly; it must set up the frame 382890075Sobrienpointer if one is wanted, and not otherwise. To determine whether a 382990075Sobrienframe pointer is in wanted, the macro can refer to the variable 383090075Sobrien@code{frame_pointer_needed}. The variable's value will be 1 at run 383190075Sobrientime in a function that needs a frame pointer. @xref{Elimination}. 383290075Sobrien 383390075SobrienThe function entry code is responsible for allocating any stack space 383490075Sobrienrequired for the function. This stack space consists of the regions 383590075Sobrienlisted below. In most cases, these regions are allocated in the 383690075Sobrienorder listed, with the last listed region closest to the top of the 383790075Sobrienstack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 383890075Sobrienthe highest address if it is not defined). You can use a different order 383990075Sobrienfor a machine if doing so is more convenient or required for 384090075Sobriencompatibility reasons. Except in cases where required by standard 384190075Sobrienor by a debugger, there is no reason why the stack layout used by GCC 384290075Sobrienneed agree with that used by other compilers for a machine. 384390075Sobrien@end deftypefn 384490075Sobrien 384590075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 384690075SobrienIf defined, a function that outputs assembler code at the end of a 384790075Sobrienprologue. This should be used when the function prologue is being 384890075Sobrienemitted as RTL, and you have some extra assembler that needs to be 384990075Sobrienemitted. @xref{prologue instruction pattern}. 385090075Sobrien@end deftypefn 385190075Sobrien 385290075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 385390075SobrienIf defined, a function that outputs assembler code at the start of an 385490075Sobrienepilogue. This should be used when the function epilogue is being 385590075Sobrienemitted as RTL, and you have some extra assembler that needs to be 385690075Sobrienemitted. @xref{epilogue instruction pattern}. 385790075Sobrien@end deftypefn 385890075Sobrien 385990075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 386090075SobrienIf defined, a function that outputs the assembler code for exit from a 386190075Sobrienfunction. The epilogue is responsible for restoring the saved 386290075Sobrienregisters and stack pointer to their values when the function was 386390075Sobriencalled, and returning control to the caller. This macro takes the 386490075Sobriensame arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 386590075Sobrienregisters to restore are determined from @code{regs_ever_live} and 386690075Sobrien@code{CALL_USED_REGISTERS} in the same way. 386790075Sobrien 386890075SobrienOn some machines, there is a single instruction that does all the work 386990075Sobrienof returning from the function. On these machines, give that 387090075Sobrieninstruction the name @samp{return} and do not define the macro 387190075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 387290075Sobrien 387390075SobrienDo not define a pattern named @samp{return} if you want the 387490075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 387590075Sobrienswitches to control whether return instructions or epilogues are used, 387690075Sobriendefine a @samp{return} pattern with a validity condition that tests the 387790075Sobrientarget switches appropriately. If the @samp{return} pattern's validity 387890075Sobriencondition is false, epilogues will be used. 387990075Sobrien 388090075SobrienOn machines where functions may or may not have frame-pointers, the 388190075Sobrienfunction exit code must vary accordingly. Sometimes the code for these 388290075Sobrientwo cases is completely different. To determine whether a frame pointer 388390075Sobrienis wanted, the macro can refer to the variable 388490075Sobrien@code{frame_pointer_needed}. The variable's value will be 1 when compiling 388590075Sobriena function that needs a frame pointer. 388690075Sobrien 388790075SobrienNormally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 388890075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 388990075SobrienThe C variable @code{current_function_is_leaf} is nonzero for such a 389090075Sobrienfunction. @xref{Leaf Functions}. 389190075Sobrien 389290075SobrienOn some machines, some functions pop their arguments on exit while 389390075Sobrienothers leave that for the caller to do. For example, the 68020 when 389490075Sobriengiven @option{-mrtd} pops arguments in functions that take a fixed 389590075Sobriennumber of arguments. 389690075Sobrien 389790075Sobrien@findex current_function_pops_args 389890075SobrienYour definition of the macro @code{RETURN_POPS_ARGS} decides which 389990075Sobrienfunctions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 390090075Sobrienneeds to know what was decided. The variable that is called 390190075Sobrien@code{current_function_pops_args} is the number of bytes of its 390290075Sobrienarguments that a function should pop. @xref{Scalar Return}. 390390075Sobrien@c what is the "its arguments" in the above sentence referring to, pray 390490075Sobrien@c tell? --mew 5feb93 390590075Sobrien@end deftypefn 390690075Sobrien 390790075Sobrien@table @code 390890075Sobrien 390990075Sobrien@itemize @bullet 391090075Sobrien@item 391190075Sobrien@findex current_function_pretend_args_size 391290075SobrienA region of @code{current_function_pretend_args_size} bytes of 391390075Sobrienuninitialized space just underneath the first argument arriving on the 391490075Sobrienstack. (This may not be at the very start of the allocated stack region 391590075Sobrienif the calling sequence has pushed anything else since pushing the stack 391690075Sobrienarguments. But usually, on such machines, nothing else has been pushed 391790075Sobrienyet, because the function prologue itself does all the pushing.) This 391890075Sobrienregion is used on machines where an argument may be passed partly in 391990075Sobrienregisters and partly in memory, and, in some cases to support the 392090075Sobrienfeatures in @code{<varargs.h>} and @code{<stdarg.h>}. 392190075Sobrien 392290075Sobrien@item 392390075SobrienAn area of memory used to save certain registers used by the function. 392490075SobrienThe size of this area, which may also include space for such things as 392590075Sobrienthe return address and pointers to previous stack frames, is 392690075Sobrienmachine-specific and usually depends on which registers have been used 392790075Sobrienin the function. Machines with register windows often do not require 392890075Sobriena save area. 392990075Sobrien 393090075Sobrien@item 393190075SobrienA region of at least @var{size} bytes, possibly rounded up to an allocation 393290075Sobrienboundary, to contain the local variables of the function. On some machines, 393390075Sobrienthis region and the save area may occur in the opposite order, with the 393490075Sobriensave area closer to the top of the stack. 393590075Sobrien 393690075Sobrien@item 393790075Sobrien@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 393890075SobrienOptionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 393990075Sobrien@code{current_function_outgoing_args_size} bytes to be used for outgoing 394090075Sobrienargument lists of the function. @xref{Stack Arguments}. 394190075Sobrien@end itemize 394290075Sobrien 394390075SobrienNormally, it is necessary for the macros 394490075Sobrien@code{TARGET_ASM_FUNCTION_PROLOGUE} and 394590075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} to treat leaf functions specially. 394690075SobrienThe C variable @code{current_function_is_leaf} is nonzero for such a 394790075Sobrienfunction. 394890075Sobrien 394990075Sobrien@findex EXIT_IGNORE_STACK 395090075Sobrien@item EXIT_IGNORE_STACK 395190075SobrienDefine this macro as a C expression that is nonzero if the return 395290075Sobrieninstruction or the function epilogue ignores the value of the stack 395390075Sobrienpointer; in other words, if it is safe to delete an instruction to 395490075Sobrienadjust the stack pointer before a return from the function. 395590075Sobrien 395690075SobrienNote that this macro's value is relevant only for functions for which 395790075Sobrienframe pointers are maintained. It is never safe to delete a final 395890075Sobrienstack adjustment in a function that has no frame pointer, and the 395990075Sobriencompiler knows this regardless of @code{EXIT_IGNORE_STACK}. 396090075Sobrien 396190075Sobrien@findex EPILOGUE_USES 396290075Sobrien@item EPILOGUE_USES (@var{regno}) 396390075SobrienDefine this macro as a C expression that is nonzero for registers that are 396490075Sobrienused by the epilogue or the @samp{return} pattern. The stack and frame 396590075Sobrienpointer registers are already be assumed to be used as needed. 396690075Sobrien 396796263Sobrien@findex EH_USES 396896263Sobrien@item EH_USES (@var{regno}) 396996263SobrienDefine this macro as a C expression that is nonzero for registers that are 397096263Sobrienused by the exception handling mechanism, and so should be considered live 397196263Sobrienon entry to an exception edge. 397296263Sobrien 397390075Sobrien@findex DELAY_SLOTS_FOR_EPILOGUE 397490075Sobrien@item DELAY_SLOTS_FOR_EPILOGUE 397590075SobrienDefine this macro if the function epilogue contains delay slots to which 397690075Sobrieninstructions from the rest of the function can be ``moved''. The 397790075Sobriendefinition should be a C expression whose value is an integer 397890075Sobrienrepresenting the number of delay slots there. 397990075Sobrien 398090075Sobrien@findex ELIGIBLE_FOR_EPILOGUE_DELAY 398190075Sobrien@item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 398290075SobrienA C expression that returns 1 if @var{insn} can be placed in delay 398390075Sobrienslot number @var{n} of the epilogue. 398490075Sobrien 398590075SobrienThe argument @var{n} is an integer which identifies the delay slot now 398690075Sobrienbeing considered (since different slots may have different rules of 398790075Sobrieneligibility). It is never negative and is always less than the number 398890075Sobrienof epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 398990075SobrienIf you reject a particular insn for a given delay slot, in principle, it 399090075Sobrienmay be reconsidered for a subsequent delay slot. Also, other insns may 399190075Sobrien(at least in principle) be considered for the so far unfilled delay 399290075Sobrienslot. 399390075Sobrien 399490075Sobrien@findex current_function_epilogue_delay_list 399590075Sobrien@findex final_scan_insn 399690075SobrienThe insns accepted to fill the epilogue delay slots are put in an RTL 399790075Sobrienlist made with @code{insn_list} objects, stored in the variable 399890075Sobrien@code{current_function_epilogue_delay_list}. The insn for the first 399990075Sobriendelay slot comes first in the list. Your definition of the macro 400090075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 400190075Sobrienoutputting the insns in this list, usually by calling 400290075Sobrien@code{final_scan_insn}. 400390075Sobrien 400490075SobrienYou need not define this macro if you did not define 400590075Sobrien@code{DELAY_SLOTS_FOR_EPILOGUE}. 400690075Sobrien 400790075Sobrien@findex ASM_OUTPUT_MI_THUNK 400890075Sobrien@item ASM_OUTPUT_MI_THUNK (@var{file}, @var{thunk_fndecl}, @var{delta}, @var{function}) 400990075SobrienA C compound statement that outputs the assembler code for a thunk 401090075Sobrienfunction, used to implement C++ virtual function calls with multiple 401190075Sobrieninheritance. The thunk acts as a wrapper around a virtual function, 401290075Sobrienadjusting the implicit object parameter before handing control off to 401390075Sobrienthe real function. 401490075Sobrien 401590075SobrienFirst, emit code to add the integer @var{delta} to the location that 401690075Sobriencontains the incoming first argument. Assume that this argument 401790075Sobriencontains a pointer, and is the one used to pass the @code{this} pointer 401890075Sobrienin C++. This is the incoming argument @emph{before} the function prologue, 401990075Sobriene.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 402090075Sobrienall other incoming arguments. 402190075Sobrien 402290075SobrienAfter the addition, emit code to jump to @var{function}, which is a 402390075Sobrien@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 402490075Sobriennot touch the return address. Hence returning from @var{FUNCTION} will 402590075Sobrienreturn to whoever called the current @samp{thunk}. 402690075Sobrien 402790075SobrienThe effect must be as if @var{function} had been called directly with 402890075Sobrienthe adjusted first argument. This macro is responsible for emitting all 402990075Sobrienof the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 403090075Sobrienand @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 403190075Sobrien 403290075SobrienThe @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 403390075Sobrienhave already been extracted from it.) It might possibly be useful on 403490075Sobriensome targets, but probably not. 403590075Sobrien 403690075SobrienIf you do not define this macro, the target-independent code in the C++ 403790075Sobrienfront end will generate a less efficient heavyweight thunk that calls 403890075Sobrien@var{function} instead of jumping to it. The generic approach does 403990075Sobriennot support varargs. 404090075Sobrien@end table 404190075Sobrien 404290075Sobrien@node Profiling 404390075Sobrien@subsection Generating Code for Profiling 404490075Sobrien@cindex profiling, code generation 404590075Sobrien 404690075SobrienThese macros will help you generate code for profiling. 404790075Sobrien 404890075Sobrien@table @code 404990075Sobrien@findex FUNCTION_PROFILER 405090075Sobrien@item FUNCTION_PROFILER (@var{file}, @var{labelno}) 405190075SobrienA C statement or compound statement to output to @var{file} some 405290075Sobrienassembler code to call the profiling subroutine @code{mcount}. 405390075Sobrien 405490075Sobrien@findex mcount 405590075SobrienThe details of how @code{mcount} expects to be called are determined by 405690075Sobrienyour operating system environment, not by GCC@. To figure them out, 405790075Sobriencompile a small program for profiling using the system's installed C 405890075Sobriencompiler and look at the assembler code that results. 405990075Sobrien 406090075SobrienOlder implementations of @code{mcount} expect the address of a counter 406190075Sobrienvariable to be loaded into some register. The name of this variable is 406290075Sobrien@samp{LP} followed by the number @var{labelno}, so you would generate 406390075Sobrienthe name using @samp{LP%d} in a @code{fprintf}. 406490075Sobrien 406590075Sobrien@findex PROFILE_HOOK 406690075Sobrien@item PROFILE_HOOK 406790075SobrienA C statement or compound statement to output to @var{file} some assembly 406890075Sobriencode to call the profiling subroutine @code{mcount} even the target does 406990075Sobriennot support profiling. 407090075Sobrien 407190075Sobrien@findex NO_PROFILE_COUNTERS 407290075Sobrien@item NO_PROFILE_COUNTERS 407390075SobrienDefine this macro if the @code{mcount} subroutine on your system does 407490075Sobriennot need a counter variable allocated for each function. This is true 407590075Sobrienfor almost all modern implementations. If you define this macro, you 407690075Sobrienmust not use the @var{labelno} argument to @code{FUNCTION_PROFILER}. 407790075Sobrien 407890075Sobrien@findex PROFILE_BEFORE_PROLOGUE 407990075Sobrien@item PROFILE_BEFORE_PROLOGUE 408090075SobrienDefine this macro if the code for function profiling should come before 408190075Sobrienthe function prologue. Normally, the profiling code comes after. 408290075Sobrien 408390075Sobrien 408490075Sobrien@findex TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER 408590075Sobrien@item TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER 408690075SobrienOn some targets, it is impossible to use profiling when the frame 408790075Sobrienpointer has been omitted. For example, on x86 GNU/Linux systems, 408890075Sobrienthe @code{mcount} routine provided by the GNU C Library finds the 408990075Sobrienaddress of the routine that called the routine that called @code{mcount} 409090075Sobrienby looking in the immediate caller's stack frame. If the immediate 409190075Sobriencaller has no frame pointer, this lookup will fail. 409290075Sobrien 409390075SobrienBy default, GCC assumes that the target does allow profiling when the 409490075Sobrienframe pointer is omitted. This macro should be defined to a C 409590075Sobrienexpression that evaluates to @code{false} if the target does not allow 409690075Sobrienprofiling when the frame pointer is omitted. 409790075Sobrien 409890075Sobrien@end table 409990075Sobrien 410090075Sobrien@node Tail Calls 410190075Sobrien@subsection Permitting tail calls 410290075Sobrien@cindex tail calls 410390075Sobrien 410490075Sobrien@table @code 410590075Sobrien@findex FUNCTION_OK_FOR_SIBCALL 410690075Sobrien@item FUNCTION_OK_FOR_SIBCALL (@var{decl}) 410790075SobrienA C expression that evaluates to true if it is ok to perform a sibling 410890075Sobriencall to @var{decl} from the current function. 410990075Sobrien 411090075SobrienIt is not uncommon for limitations of calling conventions to prevent 411190075Sobrientail calls to functions outside the current unit of translation, or 411290075Sobrienduring PIC compilation. Use this macro to enforce these restrictions, 411390075Sobrienas the @code{sibcall} md pattern can not fail, or fall over to a 411490075Sobrien``normal'' call. 411590075Sobrien@end table 411690075Sobrien 411790075Sobrien@node Varargs 411890075Sobrien@section Implementing the Varargs Macros 411990075Sobrien@cindex varargs implementation 412090075Sobrien 412190075SobrienGCC comes with an implementation of @code{<varargs.h>} and 412290075Sobrien@code{<stdarg.h>} that work without change on machines that pass arguments 412390075Sobrienon the stack. Other machines require their own implementations of 412490075Sobrienvarargs, and the two machine independent header files must have 412590075Sobrienconditionals to include it. 412690075Sobrien 412790075SobrienISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 412890075Sobrienthe calling convention for @code{va_start}. The traditional 412990075Sobrienimplementation takes just one argument, which is the variable in which 413090075Sobriento store the argument pointer. The ISO implementation of 413190075Sobrien@code{va_start} takes an additional second argument. The user is 413290075Sobriensupposed to write the last named argument of the function here. 413390075Sobrien 413490075SobrienHowever, @code{va_start} should not use this argument. The way to find 413590075Sobrienthe end of the named arguments is with the built-in functions described 413690075Sobrienbelow. 413790075Sobrien 413890075Sobrien@table @code 413990075Sobrien@findex __builtin_saveregs 414090075Sobrien@item __builtin_saveregs () 414190075SobrienUse this built-in function to save the argument registers in memory so 414290075Sobrienthat the varargs mechanism can access them. Both ISO and traditional 414390075Sobrienversions of @code{va_start} must use @code{__builtin_saveregs}, unless 414490075Sobrienyou use @code{SETUP_INCOMING_VARARGS} (see below) instead. 414590075Sobrien 414690075SobrienOn some machines, @code{__builtin_saveregs} is open-coded under the 414790075Sobriencontrol of the macro @code{EXPAND_BUILTIN_SAVEREGS}. On other machines, 414890075Sobrienit calls a routine written in assembler language, found in 414990075Sobrien@file{libgcc2.c}. 415090075Sobrien 415190075SobrienCode generated for the call to @code{__builtin_saveregs} appears at the 415290075Sobrienbeginning of the function, as opposed to where the call to 415390075Sobrien@code{__builtin_saveregs} is written, regardless of what the code is. 415490075SobrienThis is because the registers must be saved before the function starts 415590075Sobriento use them for its own purposes. 415690075Sobrien@c i rewrote the first sentence above to fix an overfull hbox. --mew 415790075Sobrien@c 10feb93 415890075Sobrien 415990075Sobrien@findex __builtin_args_info 416090075Sobrien@item __builtin_args_info (@var{category}) 416190075SobrienUse this built-in function to find the first anonymous arguments in 416290075Sobrienregisters. 416390075Sobrien 416490075SobrienIn general, a machine may have several categories of registers used for 416590075Sobrienarguments, each for a particular category of data types. (For example, 416690075Sobrienon some machines, floating-point registers are used for floating-point 416790075Sobrienarguments while other arguments are passed in the general registers.) 416890075SobrienTo make non-varargs functions use the proper calling convention, you 416990075Sobrienhave defined the @code{CUMULATIVE_ARGS} data type to record how many 417090075Sobrienregisters in each category have been used so far 417190075Sobrien 417290075Sobrien@code{__builtin_args_info} accesses the same data structure of type 417390075Sobrien@code{CUMULATIVE_ARGS} after the ordinary argument layout is finished 417490075Sobrienwith it, with @var{category} specifying which word to access. Thus, the 417590075Sobrienvalue indicates the first unused register in a given category. 417690075Sobrien 417790075SobrienNormally, you would use @code{__builtin_args_info} in the implementation 417890075Sobrienof @code{va_start}, accessing each category just once and storing the 417990075Sobrienvalue in the @code{va_list} object. This is because @code{va_list} will 418090075Sobrienhave to update the values, and there is no way to alter the 418190075Sobrienvalues accessed by @code{__builtin_args_info}. 418290075Sobrien 418390075Sobrien@findex __builtin_next_arg 418490075Sobrien@item __builtin_next_arg (@var{lastarg}) 418590075SobrienThis is the equivalent of @code{__builtin_args_info}, for stack 418690075Sobrienarguments. It returns the address of the first anonymous stack 418790075Sobrienargument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 418890075Sobrienreturns the address of the location above the first anonymous stack 418990075Sobrienargument. Use it in @code{va_start} to initialize the pointer for 419090075Sobrienfetching arguments from the stack. Also use it in @code{va_start} to 419190075Sobrienverify that the second parameter @var{lastarg} is the last named argument 419290075Sobrienof the current function. 419390075Sobrien 419490075Sobrien@findex __builtin_classify_type 419590075Sobrien@item __builtin_classify_type (@var{object}) 419690075SobrienSince each machine has its own conventions for which data types are 419790075Sobrienpassed in which kind of register, your implementation of @code{va_arg} 419890075Sobrienhas to embody these conventions. The easiest way to categorize the 419990075Sobrienspecified data type is to use @code{__builtin_classify_type} together 420090075Sobrienwith @code{sizeof} and @code{__alignof__}. 420190075Sobrien 420290075Sobrien@code{__builtin_classify_type} ignores the value of @var{object}, 420390075Sobrienconsidering only its data type. It returns an integer describing what 420490075Sobrienkind of type that is---integer, floating, pointer, structure, and so on. 420590075Sobrien 420690075SobrienThe file @file{typeclass.h} defines an enumeration that you can use to 420790075Sobrieninterpret the values of @code{__builtin_classify_type}. 420890075Sobrien@end table 420990075Sobrien 421090075SobrienThese machine description macros help implement varargs: 421190075Sobrien 421290075Sobrien@table @code 421390075Sobrien@findex EXPAND_BUILTIN_SAVEREGS 421490075Sobrien@item EXPAND_BUILTIN_SAVEREGS () 421590075SobrienIf defined, is a C expression that produces the machine-specific code 421690075Sobrienfor a call to @code{__builtin_saveregs}. This code will be moved to the 421790075Sobrienvery beginning of the function, before any parameter access are made. 421890075SobrienThe return value of this function should be an RTX that contains the 421990075Sobrienvalue to use as the return of @code{__builtin_saveregs}. 422090075Sobrien 422190075Sobrien@findex SETUP_INCOMING_VARARGS 422290075Sobrien@item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type}, @var{pretend_args_size}, @var{second_time}) 422390075SobrienThis macro offers an alternative to using @code{__builtin_saveregs} and 422490075Sobriendefining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the 422590075Sobrienanonymous register arguments into the stack so that all the arguments 422690075Sobrienappear to have been passed consecutively on the stack. Once this is 422790075Sobriendone, you can use the standard implementation of varargs that works for 422890075Sobrienmachines that pass all their arguments on the stack. 422990075Sobrien 423090075SobrienThe argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data 423190075Sobrienstructure, containing the values that are obtained after processing the 423290075Sobriennamed arguments. The arguments @var{mode} and @var{type} describe the 423390075Sobrienlast named argument---its machine mode and its data type as a tree node. 423490075Sobrien 423590075SobrienThe macro implementation should do two things: first, push onto the 423690075Sobrienstack all the argument registers @emph{not} used for the named 423790075Sobrienarguments, and second, store the size of the data thus pushed into the 423890075Sobrien@code{int}-valued variable whose name is supplied as the argument 423990075Sobrien@var{pretend_args_size}. The value that you store here will serve as 424090075Sobrienadditional offset for setting up the stack frame. 424190075Sobrien 424290075SobrienBecause you must generate code to push the anonymous arguments at 424390075Sobriencompile time without knowing their data types, 424490075Sobrien@code{SETUP_INCOMING_VARARGS} is only useful on machines that have just 424590075Sobriena single category of argument register and use it uniformly for all data 424690075Sobrientypes. 424790075Sobrien 424890075SobrienIf the argument @var{second_time} is nonzero, it means that the 424990075Sobrienarguments of the function are being analyzed for the second time. This 425090075Sobrienhappens for an inline function, which is not actually compiled until the 425190075Sobrienend of the source file. The macro @code{SETUP_INCOMING_VARARGS} should 425290075Sobriennot generate any instructions in this case. 425390075Sobrien 425490075Sobrien@findex STRICT_ARGUMENT_NAMING 425590075Sobrien@item STRICT_ARGUMENT_NAMING 425690075SobrienDefine this macro to be a nonzero value if the location where a function 425790075Sobrienargument is passed depends on whether or not it is a named argument. 425890075Sobrien 425990075SobrienThis macro controls how the @var{named} argument to @code{FUNCTION_ARG} 426090075Sobrienis set for varargs and stdarg functions. If this macro returns a 426190075Sobriennonzero value, the @var{named} argument is always true for named 426290075Sobrienarguments, and false for unnamed arguments. If it returns a value of 426390075Sobrienzero, but @code{SETUP_INCOMING_VARARGS} is defined, then all arguments 426490075Sobrienare treated as named. Otherwise, all named arguments except the last 426590075Sobrienare treated as named. 426690075Sobrien 426790075SobrienYou need not define this macro if it always returns zero. 426890075Sobrien 426990075Sobrien@findex PRETEND_OUTGOING_VARARGS_NAMED 427090075Sobrien@item PRETEND_OUTGOING_VARARGS_NAMED 427190075SobrienIf you need to conditionally change ABIs so that one works with 427290075Sobrien@code{SETUP_INCOMING_VARARGS}, but the other works like neither 427390075Sobrien@code{SETUP_INCOMING_VARARGS} nor @code{STRICT_ARGUMENT_NAMING} was 427490075Sobriendefined, then define this macro to return nonzero if 427590075Sobrien@code{SETUP_INCOMING_VARARGS} is used, zero otherwise. 427690075SobrienOtherwise, you should not define this macro. 427790075Sobrien@end table 427890075Sobrien 427990075Sobrien@node Trampolines 428090075Sobrien@section Trampolines for Nested Functions 428190075Sobrien@cindex trampolines for nested functions 428290075Sobrien@cindex nested functions, trampolines for 428390075Sobrien 428490075SobrienA @dfn{trampoline} is a small piece of code that is created at run time 428590075Sobrienwhen the address of a nested function is taken. It normally resides on 428690075Sobrienthe stack, in the stack frame of the containing function. These macros 428790075Sobrientell GCC how to generate code to allocate and initialize a 428890075Sobrientrampoline. 428990075Sobrien 429090075SobrienThe instructions in the trampoline must do two things: load a constant 429190075Sobrienaddress into the static chain register, and jump to the real address of 429290075Sobrienthe nested function. On CISC machines such as the m68k, this requires 429390075Sobrientwo instructions, a move immediate and a jump. Then the two addresses 429490075Sobrienexist in the trampoline as word-long immediate operands. On RISC 429590075Sobrienmachines, it is often necessary to load each address into a register in 429690075Sobrientwo parts. Then pieces of each address form separate immediate 429790075Sobrienoperands. 429890075Sobrien 429990075SobrienThe code generated to initialize the trampoline must store the variable 430090075Sobrienparts---the static chain value and the function address---into the 430190075Sobrienimmediate operands of the instructions. On a CISC machine, this is 430290075Sobriensimply a matter of copying each address to a memory reference at the 430390075Sobrienproper offset from the start of the trampoline. On a RISC machine, it 430490075Sobrienmay be necessary to take out pieces of the address and store them 430590075Sobrienseparately. 430690075Sobrien 430790075Sobrien@table @code 430890075Sobrien@findex TRAMPOLINE_TEMPLATE 430990075Sobrien@item TRAMPOLINE_TEMPLATE (@var{file}) 431090075SobrienA C statement to output, on the stream @var{file}, assembler code for a 431190075Sobrienblock of data that contains the constant parts of a trampoline. This 431290075Sobriencode should not include a label---the label is taken care of 431390075Sobrienautomatically. 431490075Sobrien 431590075SobrienIf you do not define this macro, it means no template is needed 431690075Sobrienfor the target. Do not define this macro on systems where the block move 431790075Sobriencode to copy the trampoline into place would be larger than the code 431890075Sobriento generate it on the spot. 431990075Sobrien 432090075Sobrien@findex TRAMPOLINE_SECTION 432190075Sobrien@item TRAMPOLINE_SECTION 432290075SobrienThe name of a subroutine to switch to the section in which the 432390075Sobrientrampoline template is to be placed (@pxref{Sections}). The default is 432490075Sobriena value of @samp{readonly_data_section}, which places the trampoline in 432590075Sobrienthe section containing read-only data. 432690075Sobrien 432790075Sobrien@findex TRAMPOLINE_SIZE 432890075Sobrien@item TRAMPOLINE_SIZE 432990075SobrienA C expression for the size in bytes of the trampoline, as an integer. 433090075Sobrien 433190075Sobrien@findex TRAMPOLINE_ALIGNMENT 433290075Sobrien@item TRAMPOLINE_ALIGNMENT 433390075SobrienAlignment required for trampolines, in bits. 433490075Sobrien 433590075SobrienIf you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} 433690075Sobrienis used for aligning trampolines. 433790075Sobrien 433890075Sobrien@findex INITIALIZE_TRAMPOLINE 433990075Sobrien@item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) 434090075SobrienA C statement to initialize the variable parts of a trampoline. 434190075Sobrien@var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is 434290075Sobrienan RTX for the address of the nested function; @var{static_chain} is an 434390075SobrienRTX for the static chain value that should be passed to the function 434490075Sobrienwhen it is called. 434590075Sobrien 434690075Sobrien@findex TRAMPOLINE_ADJUST_ADDRESS 434790075Sobrien@item TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) 434890075SobrienA C statement that should perform any machine-specific adjustment in 434990075Sobrienthe address of the trampoline. Its argument contains the address that 435090075Sobrienwas passed to @code{INITIALIZE_TRAMPOLINE}. In case the address to be 435190075Sobrienused for a function call should be different from the address in which 435290075Sobrienthe template was stored, the different address should be assigned to 435390075Sobrien@var{addr}. If this macro is not defined, @var{addr} will be used for 435490075Sobrienfunction calls. 435590075Sobrien 435690075Sobrien@findex ALLOCATE_TRAMPOLINE 435790075Sobrien@item ALLOCATE_TRAMPOLINE (@var{fp}) 435890075SobrienA C expression to allocate run-time space for a trampoline. The 435990075Sobrienexpression value should be an RTX representing a memory reference to the 436090075Sobrienspace for the trampoline. 436190075Sobrien 436290075Sobrien@cindex @code{TARGET_ASM_FUNCTION_EPILOGUE} and trampolines 436390075Sobrien@cindex @code{TARGET_ASM_FUNCTION_PROLOGUE} and trampolines 436490075SobrienIf this macro is not defined, by default the trampoline is allocated as 436590075Sobriena stack slot. This default is right for most machines. The exceptions 436690075Sobrienare machines where it is impossible to execute instructions in the stack 436790075Sobrienarea. On such machines, you may have to implement a separate stack, 436890075Sobrienusing this macro in conjunction with @code{TARGET_ASM_FUNCTION_PROLOGUE} 436990075Sobrienand @code{TARGET_ASM_FUNCTION_EPILOGUE}. 437090075Sobrien 437190075Sobrien@var{fp} points to a data structure, a @code{struct function}, which 437290075Sobriendescribes the compilation status of the immediate containing function of 437390075Sobrienthe function which the trampoline is for. Normally (when 437490075Sobrien@code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the 437590075Sobrientrampoline is in the stack frame of this containing function. Other 437690075Sobrienallocation strategies probably must do something analogous with this 437790075Sobrieninformation. 437890075Sobrien@end table 437990075Sobrien 438090075SobrienImplementing trampolines is difficult on many machines because they have 438190075Sobrienseparate instruction and data caches. Writing into a stack location 438290075Sobrienfails to clear the memory in the instruction cache, so when the program 438390075Sobrienjumps to that location, it executes the old contents. 438490075Sobrien 438590075SobrienHere are two possible solutions. One is to clear the relevant parts of 438690075Sobrienthe instruction cache whenever a trampoline is set up. The other is to 438790075Sobrienmake all trampolines identical, by having them jump to a standard 438890075Sobriensubroutine. The former technique makes trampoline execution faster; the 438990075Sobrienlatter makes initialization faster. 439090075Sobrien 439190075SobrienTo clear the instruction cache when a trampoline is initialized, define 439290075Sobrienthe following macros which describe the shape of the cache. 439390075Sobrien 439490075Sobrien@table @code 439590075Sobrien@findex INSN_CACHE_SIZE 439690075Sobrien@item INSN_CACHE_SIZE 439790075SobrienThe total size in bytes of the cache. 439890075Sobrien 439990075Sobrien@findex INSN_CACHE_LINE_WIDTH 440090075Sobrien@item INSN_CACHE_LINE_WIDTH 440190075SobrienThe length in bytes of each cache line. The cache is divided into cache 440290075Sobrienlines which are disjoint slots, each holding a contiguous chunk of data 440390075Sobrienfetched from memory. Each time data is brought into the cache, an 440490075Sobrienentire line is read at once. The data loaded into a cache line is 440590075Sobrienalways aligned on a boundary equal to the line size. 440690075Sobrien 440790075Sobrien@findex INSN_CACHE_DEPTH 440890075Sobrien@item INSN_CACHE_DEPTH 440990075SobrienThe number of alternative cache lines that can hold any particular memory 441090075Sobrienlocation. 441190075Sobrien@end table 441290075Sobrien 441390075SobrienAlternatively, if the machine has system calls or instructions to clear 441490075Sobrienthe instruction cache directly, you can define the following macro. 441590075Sobrien 441690075Sobrien@table @code 441790075Sobrien@findex CLEAR_INSN_CACHE 441890075Sobrien@item CLEAR_INSN_CACHE (@var{beg}, @var{end}) 441990075SobrienIf defined, expands to a C expression clearing the @emph{instruction 442090075Sobriencache} in the specified interval. If it is not defined, and the macro 442190075Sobrien@code{INSN_CACHE_SIZE} is defined, some generic code is generated to clear the 442290075Sobriencache. The definition of this macro would typically be a series of 442390075Sobrien@code{asm} statements. Both @var{beg} and @var{end} are both pointer 442490075Sobrienexpressions. 442590075Sobrien@end table 442690075Sobrien 442790075SobrienTo use a standard subroutine, define the following macro. In addition, 442890075Sobrienyou must make sure that the instructions in a trampoline fill an entire 442990075Sobriencache line with identical instructions, or else ensure that the 443090075Sobrienbeginning of the trampoline code is always aligned at the same point in 443190075Sobrienits cache line. Look in @file{m68k.h} as a guide. 443290075Sobrien 443390075Sobrien@table @code 443490075Sobrien@findex TRANSFER_FROM_TRAMPOLINE 443590075Sobrien@item TRANSFER_FROM_TRAMPOLINE 443690075SobrienDefine this macro if trampolines need a special subroutine to do their 443790075Sobrienwork. The macro should expand to a series of @code{asm} statements 443890075Sobrienwhich will be compiled with GCC@. They go in a library function named 443990075Sobrien@code{__transfer_from_trampoline}. 444090075Sobrien 444190075SobrienIf you need to avoid executing the ordinary prologue code of a compiled 444290075SobrienC function when you jump to the subroutine, you can do so by placing a 444390075Sobrienspecial label of your own in the assembler code. Use one @code{asm} 444490075Sobrienstatement to generate an assembler label, and another to make the label 444590075Sobrienglobal. Then trampolines can use that label to jump directly to your 444690075Sobrienspecial assembler code. 444790075Sobrien@end table 444890075Sobrien 444990075Sobrien@node Library Calls 445090075Sobrien@section Implicit Calls to Library Routines 445190075Sobrien@cindex library subroutine names 445290075Sobrien@cindex @file{libgcc.a} 445390075Sobrien 445490075Sobrien@c prevent bad page break with this line 445590075SobrienHere is an explanation of implicit calls to library routines. 445690075Sobrien 445790075Sobrien@table @code 445890075Sobrien@findex MULSI3_LIBCALL 445990075Sobrien@item MULSI3_LIBCALL 446090075SobrienA C string constant giving the name of the function to call for 446190075Sobrienmultiplication of one signed full-word by another. If you do not 446290075Sobriendefine this macro, the default name is used, which is @code{__mulsi3}, 446390075Sobriena function defined in @file{libgcc.a}. 446490075Sobrien 446590075Sobrien@findex DIVSI3_LIBCALL 446690075Sobrien@item DIVSI3_LIBCALL 446790075SobrienA C string constant giving the name of the function to call for 446890075Sobriendivision of one signed full-word by another. If you do not define 446990075Sobrienthis macro, the default name is used, which is @code{__divsi3}, a 447090075Sobrienfunction defined in @file{libgcc.a}. 447190075Sobrien 447290075Sobrien@findex UDIVSI3_LIBCALL 447390075Sobrien@item UDIVSI3_LIBCALL 447490075SobrienA C string constant giving the name of the function to call for 447590075Sobriendivision of one unsigned full-word by another. If you do not define 447690075Sobrienthis macro, the default name is used, which is @code{__udivsi3}, a 447790075Sobrienfunction defined in @file{libgcc.a}. 447890075Sobrien 447990075Sobrien@findex MODSI3_LIBCALL 448090075Sobrien@item MODSI3_LIBCALL 448190075SobrienA C string constant giving the name of the function to call for the 448290075Sobrienremainder in division of one signed full-word by another. If you do 448390075Sobriennot define this macro, the default name is used, which is 448490075Sobrien@code{__modsi3}, a function defined in @file{libgcc.a}. 448590075Sobrien 448690075Sobrien@findex UMODSI3_LIBCALL 448790075Sobrien@item UMODSI3_LIBCALL 448890075SobrienA C string constant giving the name of the function to call for the 448990075Sobrienremainder in division of one unsigned full-word by another. If you do 449090075Sobriennot define this macro, the default name is used, which is 449190075Sobrien@code{__umodsi3}, a function defined in @file{libgcc.a}. 449290075Sobrien 449390075Sobrien@findex MULDI3_LIBCALL 449490075Sobrien@item MULDI3_LIBCALL 449590075SobrienA C string constant giving the name of the function to call for 449690075Sobrienmultiplication of one signed double-word by another. If you do not 449790075Sobriendefine this macro, the default name is used, which is @code{__muldi3}, 449890075Sobriena function defined in @file{libgcc.a}. 449990075Sobrien 450090075Sobrien@findex DIVDI3_LIBCALL 450190075Sobrien@item DIVDI3_LIBCALL 450290075SobrienA C string constant giving the name of the function to call for 450390075Sobriendivision of one signed double-word by another. If you do not define 450490075Sobrienthis macro, the default name is used, which is @code{__divdi3}, a 450590075Sobrienfunction defined in @file{libgcc.a}. 450690075Sobrien 450790075Sobrien@findex UDIVDI3_LIBCALL 450890075Sobrien@item UDIVDI3_LIBCALL 450990075SobrienA C string constant giving the name of the function to call for 451090075Sobriendivision of one unsigned full-word by another. If you do not define 451190075Sobrienthis macro, the default name is used, which is @code{__udivdi3}, a 451290075Sobrienfunction defined in @file{libgcc.a}. 451390075Sobrien 451490075Sobrien@findex MODDI3_LIBCALL 451590075Sobrien@item MODDI3_LIBCALL 451690075SobrienA C string constant giving the name of the function to call for the 451790075Sobrienremainder in division of one signed double-word by another. If you do 451890075Sobriennot define this macro, the default name is used, which is 451990075Sobrien@code{__moddi3}, a function defined in @file{libgcc.a}. 452090075Sobrien 452190075Sobrien@findex UMODDI3_LIBCALL 452290075Sobrien@item UMODDI3_LIBCALL 452390075SobrienA C string constant giving the name of the function to call for the 452490075Sobrienremainder in division of one unsigned full-word by another. If you do 452590075Sobriennot define this macro, the default name is used, which is 452690075Sobrien@code{__umoddi3}, a function defined in @file{libgcc.a}. 452790075Sobrien 452890075Sobrien@findex INIT_TARGET_OPTABS 452990075Sobrien@item INIT_TARGET_OPTABS 453090075SobrienDefine this macro as a C statement that declares additional library 453190075Sobrienroutines renames existing ones. @code{init_optabs} calls this macro after 453290075Sobrieninitializing all the normal library routines. 453390075Sobrien 453490075Sobrien@findex FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 453590075Sobrien@item FLOAT_LIB_COMPARE_RETURNS_BOOL 453690075SobrienDefine this macro as a C statement that returns nonzero if a call to 453790075Sobrienthe floating point comparison library function will return a boolean 453890075Sobrienvalue that indicates the result of the comparison. It should return 453990075Sobrienzero if one of gcc's own libgcc functions is called. 454090075Sobrien 454190075SobrienMost ports don't need to define this macro. 454290075Sobrien 454390075Sobrien@findex TARGET_EDOM 454490075Sobrien@cindex @code{EDOM}, implicit usage 454590075Sobrien@item TARGET_EDOM 454690075SobrienThe value of @code{EDOM} on the target machine, as a C integer constant 454790075Sobrienexpression. If you don't define this macro, GCC does not attempt to 454890075Sobriendeposit the value of @code{EDOM} into @code{errno} directly. Look in 454990075Sobrien@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 455090075Sobriensystem. 455190075Sobrien 455290075SobrienIf you do not define @code{TARGET_EDOM}, then compiled code reports 455390075Sobriendomain errors by calling the library function and letting it report the 455490075Sobrienerror. If mathematical functions on your system use @code{matherr} when 455590075Sobrienthere is an error, then you should leave @code{TARGET_EDOM} undefined so 455690075Sobrienthat @code{matherr} is used normally. 455790075Sobrien 455890075Sobrien@findex GEN_ERRNO_RTX 455990075Sobrien@cindex @code{errno}, implicit usage 456090075Sobrien@item GEN_ERRNO_RTX 456190075SobrienDefine this macro as a C expression to create an rtl expression that 456290075Sobrienrefers to the global ``variable'' @code{errno}. (On certain systems, 456390075Sobrien@code{errno} may not actually be a variable.) If you don't define this 456490075Sobrienmacro, a reasonable default is used. 456590075Sobrien 456690075Sobrien@findex TARGET_MEM_FUNCTIONS 456790075Sobrien@cindex @code{bcopy}, implicit usage 456890075Sobrien@cindex @code{memcpy}, implicit usage 456990075Sobrien@cindex @code{memmove}, implicit usage 457090075Sobrien@cindex @code{bzero}, implicit usage 457190075Sobrien@cindex @code{memset}, implicit usage 457290075Sobrien@item TARGET_MEM_FUNCTIONS 457390075SobrienDefine this macro if GCC should generate calls to the ISO C 457490075Sobrien(and System V) library functions @code{memcpy}, @code{memmove} and 457590075Sobrien@code{memset} rather than the BSD functions @code{bcopy} and @code{bzero}. 457690075Sobrien 457790075Sobrien@findex LIBGCC_NEEDS_DOUBLE 457890075Sobrien@item LIBGCC_NEEDS_DOUBLE 457990075SobrienDefine this macro if @code{float} arguments cannot be passed to library 458090075Sobrienroutines (so they must be converted to @code{double}). This macro 458190075Sobrienaffects both how library calls are generated and how the library 458290075Sobrienroutines in @file{libgcc.a} accept their arguments. It is useful on 458390075Sobrienmachines where floating and fixed point arguments are passed 458490075Sobriendifferently, such as the i860. 458590075Sobrien 458690075Sobrien@findex NEXT_OBJC_RUNTIME 458790075Sobrien@item NEXT_OBJC_RUNTIME 458890075SobrienDefine this macro to generate code for Objective-C message sending using 458990075Sobrienthe calling convention of the NeXT system. This calling convention 459090075Sobrieninvolves passing the object, the selector and the method arguments all 459190075Sobrienat once to the method-lookup library function. 459290075Sobrien 459390075SobrienThe default calling convention passes just the object and the selector 459490075Sobriento the lookup function, which returns a pointer to the method. 459590075Sobrien@end table 459690075Sobrien 459790075Sobrien@node Addressing Modes 459890075Sobrien@section Addressing Modes 459990075Sobrien@cindex addressing modes 460090075Sobrien 460190075Sobrien@c prevent bad page break with this line 460290075SobrienThis is about addressing modes. 460390075Sobrien 460490075Sobrien@table @code 460590075Sobrien@findex HAVE_PRE_INCREMENT 460690075Sobrien@findex HAVE_PRE_DECREMENT 460790075Sobrien@findex HAVE_POST_INCREMENT 460890075Sobrien@findex HAVE_POST_DECREMENT 460990075Sobrien@item HAVE_PRE_INCREMENT 461090075Sobrien@itemx HAVE_PRE_DECREMENT 461190075Sobrien@itemx HAVE_POST_INCREMENT 461290075Sobrien@itemx HAVE_POST_DECREMENT 461390075SobrienA C expression that is nonzero if the machine supports pre-increment, 461490075Sobrienpre-decrement, post-increment, or post-decrement addressing respectively. 461590075Sobrien 461690075Sobrien@findex HAVE_POST_MODIFY_DISP 461790075Sobrien@findex HAVE_PRE_MODIFY_DISP 461890075Sobrien@item HAVE_PRE_MODIFY_DISP 461990075Sobrien@itemx HAVE_POST_MODIFY_DISP 462090075SobrienA C expression that is nonzero if the machine supports pre- or 462190075Sobrienpost-address side-effect generation involving constants other than 462290075Sobrienthe size of the memory operand. 462390075Sobrien 462490075Sobrien@findex HAVE_POST_MODIFY_REG 462590075Sobrien@findex HAVE_PRE_MODIFY_REG 462690075Sobrien@item HAVE_PRE_MODIFY_REG 462790075Sobrien@itemx HAVE_POST_MODIFY_REG 462890075SobrienA C expression that is nonzero if the machine supports pre- or 462990075Sobrienpost-address side-effect generation involving a register displacement. 463090075Sobrien 463190075Sobrien@findex CONSTANT_ADDRESS_P 463290075Sobrien@item CONSTANT_ADDRESS_P (@var{x}) 463390075SobrienA C expression that is 1 if the RTX @var{x} is a constant which 463490075Sobrienis a valid address. On most machines, this can be defined as 463590075Sobrien@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive 463690075Sobrienin which constant addresses are supported. 463790075Sobrien 463890075Sobrien@findex CONSTANT_P 463990075Sobrien@code{CONSTANT_P} accepts integer-values expressions whose values are 464090075Sobriennot explicitly known, such as @code{symbol_ref}, @code{label_ref}, and 464190075Sobrien@code{high} expressions and @code{const} arithmetic expressions, in 464290075Sobrienaddition to @code{const_int} and @code{const_double} expressions. 464390075Sobrien 464490075Sobrien@findex MAX_REGS_PER_ADDRESS 464590075Sobrien@item MAX_REGS_PER_ADDRESS 464690075SobrienA number, the maximum number of registers that can appear in a valid 464790075Sobrienmemory address. Note that it is up to you to specify a value equal to 464890075Sobrienthe maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever 464990075Sobrienaccept. 465090075Sobrien 465190075Sobrien@findex GO_IF_LEGITIMATE_ADDRESS 465290075Sobrien@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 465390075SobrienA C compound statement with a conditional @code{goto @var{label};} 465490075Sobrienexecuted if @var{x} (an RTX) is a legitimate memory address on the 465590075Sobrientarget machine for a memory operand of mode @var{mode}. 465690075Sobrien 465790075SobrienIt usually pays to define several simpler macros to serve as 465890075Sobriensubroutines for this one. Otherwise it may be too complicated to 465990075Sobrienunderstand. 466090075Sobrien 466190075SobrienThis macro must exist in two variants: a strict variant and a 466290075Sobriennon-strict one. The strict variant is used in the reload pass. It 466390075Sobrienmust be defined so that any pseudo-register that has not been 466490075Sobrienallocated a hard register is considered a memory reference. In 466590075Sobriencontexts where some kind of register is required, a pseudo-register 466690075Sobrienwith no hard register must be rejected. 466790075Sobrien 466890075SobrienThe non-strict variant is used in other passes. It must be defined to 466990075Sobrienaccept all pseudo-registers in every context where some kind of 467090075Sobrienregister is required. 467190075Sobrien 467290075Sobrien@findex REG_OK_STRICT 467390075SobrienCompiler source files that want to use the strict variant of this 467490075Sobrienmacro define the macro @code{REG_OK_STRICT}. You should use an 467590075Sobrien@code{#ifdef REG_OK_STRICT} conditional to define the strict variant 467690075Sobrienin that case and the non-strict variant otherwise. 467790075Sobrien 467890075SobrienSubroutines to check for acceptable registers for various purposes (one 467990075Sobrienfor base registers, one for index registers, and so on) are typically 468090075Sobrienamong the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. 468190075SobrienThen only these subroutine macros need have two variants; the higher 468290075Sobrienlevels of macros may be the same whether strict or not. 468390075Sobrien 468490075SobrienNormally, constant addresses which are the sum of a @code{symbol_ref} 468590075Sobrienand an integer are stored inside a @code{const} RTX to mark them as 468690075Sobrienconstant. Therefore, there is no need to recognize such sums 468790075Sobrienspecifically as legitimate addresses. Normally you would simply 468890075Sobrienrecognize any @code{const} as legitimate. 468990075Sobrien 469090075SobrienUsually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 469190075Sobriensums that are not marked with @code{const}. It assumes that a naked 469290075Sobrien@code{plus} indicates indexing. If so, then you @emph{must} reject such 469390075Sobriennaked constant sums as illegitimate addresses, so that none of them will 469490075Sobrienbe given to @code{PRINT_OPERAND_ADDRESS}. 469590075Sobrien 469690075Sobrien@cindex @code{ENCODE_SECTION_INFO} and address validation 469790075SobrienOn some machines, whether a symbolic address is legitimate depends on 469890075Sobrienthe section that the address refers to. On these machines, define the 469990075Sobrienmacro @code{ENCODE_SECTION_INFO} to store the information into the 470090075Sobrien@code{symbol_ref}, and then check for it here. When you see a 470190075Sobrien@code{const}, you will have to look inside it to find the 470290075Sobrien@code{symbol_ref} in order to determine the section. @xref{Assembler 470390075SobrienFormat}. 470490075Sobrien 470590075Sobrien@findex saveable_obstack 470690075SobrienThe best way to modify the name string is by adding text to the 470790075Sobrienbeginning, with suitable punctuation to prevent any ambiguity. Allocate 470890075Sobrienthe new name in @code{saveable_obstack}. You will have to modify 470990075Sobrien@code{ASM_OUTPUT_LABELREF} to remove and decode the added text and 471090075Sobrienoutput the name accordingly, and define @code{STRIP_NAME_ENCODING} to 471190075Sobrienaccess the original name string. 471290075Sobrien 471390075SobrienYou can check the information stored here into the @code{symbol_ref} in 471490075Sobrienthe definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and 471590075Sobrien@code{PRINT_OPERAND_ADDRESS}. 471690075Sobrien 471790075Sobrien@findex REG_OK_FOR_BASE_P 471890075Sobrien@item REG_OK_FOR_BASE_P (@var{x}) 471990075SobrienA C expression that is nonzero if @var{x} (assumed to be a @code{reg} 472090075SobrienRTX) is valid for use as a base register. For hard registers, it 472190075Sobrienshould always accept those which the hardware permits and reject the 472290075Sobrienothers. Whether the macro accepts or rejects pseudo registers must be 472390075Sobriencontrolled by @code{REG_OK_STRICT} as described above. This usually 472490075Sobrienrequires two variant definitions, of which @code{REG_OK_STRICT} 472590075Sobriencontrols the one actually used. 472690075Sobrien 472790075Sobrien@findex REG_MODE_OK_FOR_BASE_P 472890075Sobrien@item REG_MODE_OK_FOR_BASE_P (@var{x}, @var{mode}) 472990075SobrienA C expression that is just like @code{REG_OK_FOR_BASE_P}, except that 473090075Sobrienthat expression may examine the mode of the memory reference in 473190075Sobrien@var{mode}. You should define this macro if the mode of the memory 473290075Sobrienreference affects whether a register may be used as a base register. If 473390075Sobrienyou define this macro, the compiler will use it instead of 473490075Sobrien@code{REG_OK_FOR_BASE_P}. 473590075Sobrien 473690075Sobrien@findex REG_OK_FOR_INDEX_P 473790075Sobrien@item REG_OK_FOR_INDEX_P (@var{x}) 473890075SobrienA C expression that is nonzero if @var{x} (assumed to be a @code{reg} 473990075SobrienRTX) is valid for use as an index register. 474090075Sobrien 474190075SobrienThe difference between an index register and a base register is that 474290075Sobrienthe index register may be scaled. If an address involves the sum of 474390075Sobrientwo registers, neither one of them scaled, then either one may be 474490075Sobrienlabeled the ``base'' and the other the ``index''; but whichever 474590075Sobrienlabeling is used must fit the machine's constraints of which registers 474690075Sobrienmay serve in each capacity. The compiler will try both labelings, 474790075Sobrienlooking for one that is valid, and will reload one or both registers 474890075Sobrienonly if neither labeling works. 474990075Sobrien 475090075Sobrien@findex FIND_BASE_TERM 475190075Sobrien@item FIND_BASE_TERM (@var{x}) 475290075SobrienA C expression to determine the base term of address @var{x}. 475390075SobrienThis macro is used in only one place: `find_base_term' in alias.c. 475490075Sobrien 475590075SobrienIt is always safe for this macro to not be defined. It exists so 475690075Sobrienthat alias analysis can understand machine-dependent addresses. 475790075Sobrien 475890075SobrienThe typical use of this macro is to handle addresses containing 475990075Sobriena label_ref or symbol_ref within an UNSPEC@. 476090075Sobrien 476190075Sobrien@findex LEGITIMIZE_ADDRESS 476290075Sobrien@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) 476390075SobrienA C compound statement that attempts to replace @var{x} with a valid 476490075Sobrienmemory address for an operand of mode @var{mode}. @var{win} will be a 476590075SobrienC statement label elsewhere in the code; the macro definition may use 476690075Sobrien 476790075Sobrien@example 476890075SobrienGO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); 476990075Sobrien@end example 477090075Sobrien 477190075Sobrien@noindent 477290075Sobriento avoid further processing if the address has become legitimate. 477390075Sobrien 477490075Sobrien@findex break_out_memory_refs 477590075Sobrien@var{x} will always be the result of a call to @code{break_out_memory_refs}, 477690075Sobrienand @var{oldx} will be the operand that was given to that function to produce 477790075Sobrien@var{x}. 477890075Sobrien 477990075SobrienThe code generated by this macro should not alter the substructure of 478090075Sobrien@var{x}. If it transforms @var{x} into a more legitimate form, it 478190075Sobrienshould assign @var{x} (which will always be a C variable) a new value. 478290075Sobrien 478390075SobrienIt is not necessary for this macro to come up with a legitimate 478490075Sobrienaddress. The compiler has standard ways of doing so in all cases. In 478590075Sobrienfact, it is safe for this macro to do nothing. But often a 478690075Sobrienmachine-dependent strategy can generate better code. 478790075Sobrien 478890075Sobrien@findex LEGITIMIZE_RELOAD_ADDRESS 478990075Sobrien@item LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 479090075SobrienA C compound statement that attempts to replace @var{x}, which is an address 479190075Sobrienthat needs reloading, with a valid memory address for an operand of mode 479290075Sobrien@var{mode}. @var{win} will be a C statement label elsewhere in the code. 479390075SobrienIt is not necessary to define this macro, but it might be useful for 479490075Sobrienperformance reasons. 479590075Sobrien 479690075SobrienFor example, on the i386, it is sometimes possible to use a single 479790075Sobrienreload register instead of two by reloading a sum of two pseudo 479890075Sobrienregisters into a register. On the other hand, for number of RISC 479990075Sobrienprocessors offsets are limited so that often an intermediate address 480090075Sobrienneeds to be generated in order to address a stack slot. By defining 480190075Sobrien@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 480290075Sobriengenerated for adjacent some stack slots can be made identical, and thus 480390075Sobrienbe shared. 480490075Sobrien 480590075Sobrien@emph{Note}: This macro should be used with caution. It is necessary 480690075Sobriento know something of how reload works in order to effectively use this, 480790075Sobrienand it is quite easy to produce macros that build in too much knowledge 480890075Sobrienof reload internals. 480990075Sobrien 481090075Sobrien@emph{Note}: This macro must be able to reload an address created by a 481190075Sobrienprevious invocation of this macro. If it fails to handle such addresses 481290075Sobrienthen the compiler may generate incorrect code or abort. 481390075Sobrien 481490075Sobrien@findex push_reload 481590075SobrienThe macro definition should use @code{push_reload} to indicate parts that 481690075Sobrienneed reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 481790075Sobriensuitable to be passed unaltered to @code{push_reload}. 481890075Sobrien 481990075SobrienThe code generated by this macro must not alter the substructure of 482090075Sobrien@var{x}. If it transforms @var{x} into a more legitimate form, it 482190075Sobrienshould assign @var{x} (which will always be a C variable) a new value. 482290075SobrienThis also applies to parts that you change indirectly by calling 482390075Sobrien@code{push_reload}. 482490075Sobrien 482590075Sobrien@findex strict_memory_address_p 482690075SobrienThe macro definition may use @code{strict_memory_address_p} to test if 482790075Sobrienthe address has become legitimate. 482890075Sobrien 482990075Sobrien@findex copy_rtx 483090075SobrienIf you want to change only a part of @var{x}, one standard way of doing 483190075Sobrienthis is to use @code{copy_rtx}. Note, however, that is unshares only a 483290075Sobriensingle level of rtl. Thus, if the part to be changed is not at the 483390075Sobrientop level, you'll need to replace first the top level. 483490075SobrienIt is not necessary for this macro to come up with a legitimate 483590075Sobrienaddress; but often a machine-dependent strategy can generate better code. 483690075Sobrien 483790075Sobrien@findex GO_IF_MODE_DEPENDENT_ADDRESS 483890075Sobrien@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 483990075SobrienA C statement or compound statement with a conditional @code{goto 484090075Sobrien@var{label};} executed if memory address @var{x} (an RTX) can have 484190075Sobriendifferent meanings depending on the machine mode of the memory 484290075Sobrienreference it is used for or if the address is valid for some modes 484390075Sobrienbut not others. 484490075Sobrien 484590075SobrienAutoincrement and autodecrement addresses typically have mode-dependent 484690075Sobrieneffects because the amount of the increment or decrement is the size 484790075Sobrienof the operand being addressed. Some machines have other mode-dependent 484890075Sobrienaddresses. Many RISC machines have no mode-dependent addresses. 484990075Sobrien 485090075SobrienYou may assume that @var{addr} is a valid address for the machine. 485190075Sobrien 485290075Sobrien@findex LEGITIMATE_CONSTANT_P 485390075Sobrien@item LEGITIMATE_CONSTANT_P (@var{x}) 485490075SobrienA C expression that is nonzero if @var{x} is a legitimate constant for 485590075Sobrienan immediate operand on the target machine. You can assume that 485690075Sobrien@var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, 485790075Sobrien@samp{1} is a suitable definition for this macro on machines where 485890075Sobrienanything @code{CONSTANT_P} is valid. 485990075Sobrien@end table 486090075Sobrien 486190075Sobrien@node Condition Code 486290075Sobrien@section Condition Code Status 486390075Sobrien@cindex condition code status 486490075Sobrien 486590075Sobrien@c prevent bad page break with this line 486690075SobrienThis describes the condition code status. 486790075Sobrien 486890075Sobrien@findex cc_status 486990075SobrienThe file @file{conditions.h} defines a variable @code{cc_status} to 487090075Sobriendescribe how the condition code was computed (in case the interpretation of 487190075Sobrienthe condition code depends on the instruction that it was set by). This 487290075Sobrienvariable contains the RTL expressions on which the condition code is 487390075Sobriencurrently based, and several standard flags. 487490075Sobrien 487590075SobrienSometimes additional machine-specific flags must be defined in the machine 487690075Sobriendescription header file. It can also add additional machine-specific 487790075Sobrieninformation by defining @code{CC_STATUS_MDEP}. 487890075Sobrien 487990075Sobrien@table @code 488090075Sobrien@findex CC_STATUS_MDEP 488190075Sobrien@item CC_STATUS_MDEP 488290075SobrienC code for a data type which is used for declaring the @code{mdep} 488390075Sobriencomponent of @code{cc_status}. It defaults to @code{int}. 488490075Sobrien 488590075SobrienThis macro is not used on machines that do not use @code{cc0}. 488690075Sobrien 488790075Sobrien@findex CC_STATUS_MDEP_INIT 488890075Sobrien@item CC_STATUS_MDEP_INIT 488990075SobrienA C expression to initialize the @code{mdep} field to ``empty''. 489090075SobrienThe default definition does nothing, since most machines don't use 489190075Sobrienthe field anyway. If you want to use the field, you should probably 489290075Sobriendefine this macro to initialize it. 489390075Sobrien 489490075SobrienThis macro is not used on machines that do not use @code{cc0}. 489590075Sobrien 489690075Sobrien@findex NOTICE_UPDATE_CC 489790075Sobrien@item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 489890075SobrienA C compound statement to set the components of @code{cc_status} 489990075Sobrienappropriately for an insn @var{insn} whose body is @var{exp}. It is 490090075Sobrienthis macro's responsibility to recognize insns that set the condition 490190075Sobriencode as a byproduct of other activity as well as those that explicitly 490290075Sobrienset @code{(cc0)}. 490390075Sobrien 490490075SobrienThis macro is not used on machines that do not use @code{cc0}. 490590075Sobrien 490690075SobrienIf there are insns that do not set the condition code but do alter 490790075Sobrienother machine registers, this macro must check to see whether they 490890075Sobrieninvalidate the expressions that the condition code is recorded as 490990075Sobrienreflecting. For example, on the 68000, insns that store in address 491090075Sobrienregisters do not set the condition code, which means that usually 491190075Sobrien@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 491290075Sobrieninsns. But suppose that the previous insn set the condition code 491390075Sobrienbased on location @samp{a4@@(102)} and the current insn stores a new 491490075Sobrienvalue in @samp{a4}. Although the condition code is not changed by 491590075Sobrienthis, it will no longer be true that it reflects the contents of 491690075Sobrien@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 491790075Sobrien@code{cc_status} in this case to say that nothing is known about the 491890075Sobriencondition code value. 491990075Sobrien 492090075SobrienThe definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 492190075Sobrienwith the results of peephole optimization: insns whose patterns are 492290075Sobrien@code{parallel} RTXs containing various @code{reg}, @code{mem} or 492390075Sobrienconstants which are just the operands. The RTL structure of these 492490075Sobrieninsns is not sufficient to indicate what the insns actually do. What 492590075Sobrien@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 492690075Sobrien@code{CC_STATUS_INIT}. 492790075Sobrien 492890075SobrienA possible definition of @code{NOTICE_UPDATE_CC} is to call a function 492990075Sobrienthat looks at an attribute (@pxref{Insn Attributes}) named, for example, 493090075Sobrien@samp{cc}. This avoids having detailed information about patterns in 493190075Sobrientwo places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 493290075Sobrien 493390075Sobrien@findex EXTRA_CC_MODES 493490075Sobrien@item EXTRA_CC_MODES 493590075SobrienA list of additional modes for condition code values in registers 493690075Sobrien(@pxref{Jump Patterns}). This macro should expand to a sequence of 493790075Sobriencalls of the macro @code{CC} separated by white space. @code{CC} takes 493890075Sobrientwo arguments. The first is the enumeration name of the mode, which 493990075Sobrienshould begin with @samp{CC} and end with @samp{mode}. The second is a C 494090075Sobrienstring giving the printable name of the mode; it should be the same as 494190075Sobrienthe first argument, but with the trailing @samp{mode} removed. 494290075Sobrien 494390075SobrienYou should only define this macro if additional modes are required. 494490075Sobrien 494590075SobrienA sample definition of @code{EXTRA_CC_MODES} is: 494690075Sobrien@smallexample 494790075Sobrien#define EXTRA_CC_MODES \ 494890075Sobrien CC(CC_NOOVmode, "CC_NOOV") \ 494990075Sobrien CC(CCFPmode, "CCFP") \ 495090075Sobrien CC(CCFPEmode, "CCFPE") 495190075Sobrien@end smallexample 495290075Sobrien 495390075Sobrien@findex SELECT_CC_MODE 495490075Sobrien@item SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 495590075SobrienReturns a mode from class @code{MODE_CC} to be used when comparison 495690075Sobrienoperation code @var{op} is applied to rtx @var{x} and @var{y}. For 495790075Sobrienexample, on the Sparc, @code{SELECT_CC_MODE} is defined as (see 495890075Sobrien@pxref{Jump Patterns} for a description of the reason for this 495990075Sobriendefinition) 496090075Sobrien 496190075Sobrien@smallexample 496290075Sobrien#define SELECT_CC_MODE(OP,X,Y) \ 496390075Sobrien (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 496490075Sobrien ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 496590075Sobrien : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 496690075Sobrien || GET_CODE (X) == NEG) \ 496790075Sobrien ? CC_NOOVmode : CCmode)) 496890075Sobrien@end smallexample 496990075Sobrien 497090075SobrienYou need not define this macro if @code{EXTRA_CC_MODES} is not defined. 497190075Sobrien 497290075Sobrien@findex CANONICALIZE_COMPARISON 497390075Sobrien@item CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 497490075SobrienOn some machines not all possible comparisons are defined, but you can 497590075Sobrienconvert an invalid comparison into a valid one. For example, the Alpha 497690075Sobriendoes not have a @code{GT} comparison, but you can use an @code{LT} 497790075Sobriencomparison instead and swap the order of the operands. 497890075Sobrien 497990075SobrienOn such machines, define this macro to be a C statement to do any 498090075Sobrienrequired conversions. @var{code} is the initial comparison code 498190075Sobrienand @var{op0} and @var{op1} are the left and right operands of the 498290075Sobriencomparison, respectively. You should modify @var{code}, @var{op0}, and 498390075Sobrien@var{op1} as required. 498490075Sobrien 498590075SobrienGCC will not assume that the comparison resulting from this macro is 498690075Sobrienvalid but will see if the resulting insn matches a pattern in the 498790075Sobrien@file{md} file. 498890075Sobrien 498990075SobrienYou need not define this macro if it would never change the comparison 499090075Sobriencode or operands. 499190075Sobrien 499290075Sobrien@findex REVERSIBLE_CC_MODE 499390075Sobrien@item REVERSIBLE_CC_MODE (@var{mode}) 499490075SobrienA C expression whose value is one if it is always safe to reverse a 499590075Sobriencomparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 499690075Sobriencan ever return @var{mode} for a floating-point inequality comparison, 499790075Sobrienthen @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 499890075Sobrien 499990075SobrienYou need not define this macro if it would always returns zero or if the 500090075Sobrienfloating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 500190075SobrienFor example, here is the definition used on the Sparc, where floating-point 500290075Sobrieninequality comparisons are always given @code{CCFPEmode}: 500390075Sobrien 500490075Sobrien@smallexample 500590075Sobrien#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 500690075Sobrien@end smallexample 500790075Sobrien 500890075Sobrien@findex REVERSE_CONDITION (@var{code}, @var{mode}) 500990075SobrienA C expression whose value is reversed condition code of the @var{code} for 501090075Sobriencomparison done in CC_MODE @var{mode}. The macro is used only in case 501190075Sobrien@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 501290075Sobrienmachine has some non-standard way how to reverse certain conditionals. For 501390075Sobrieninstance in case all floating point conditions are non-trapping, compiler may 501490075Sobrienfreely convert unordered compares to ordered one. Then definition may look 501590075Sobrienlike: 501690075Sobrien 501790075Sobrien@smallexample 501890075Sobrien#define REVERSE_CONDITION(CODE, MODE) \ 501990075Sobrien ((MODE) != CCFPmode ? reverse_condition (CODE) \ 502090075Sobrien : reverse_condition_maybe_unordered (CODE)) 502190075Sobrien@end smallexample 502290075Sobrien 502390075Sobrien@findex REVERSE_CONDEXEC_PREDICATES_P 502490075Sobrien@item REVERSE_CONDEXEC_PREDICATES_P (@var{code1}, @var{code2}) 502590075SobrienA C expression that returns true if the conditional execution predicate 502690075Sobrien@var{code1} is the inverse of @var{code2} and vice versa. Define this to 502790075Sobrienreturn 0 if the target has conditional execution predicates that cannot be 502890075Sobrienreversed safely. If no expansion is specified, this macro is defined as 502990075Sobrienfollows: 503090075Sobrien 503190075Sobrien@smallexample 503290075Sobrien#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 503390075Sobrien ((x) == reverse_condition (y)) 503490075Sobrien@end smallexample 503590075Sobrien 503690075Sobrien@end table 503790075Sobrien 503890075Sobrien@node Costs 503990075Sobrien@section Describing Relative Costs of Operations 504090075Sobrien@cindex costs of instructions 504190075Sobrien@cindex relative costs 504290075Sobrien@cindex speed of instructions 504390075Sobrien 504490075SobrienThese macros let you describe the relative speed of various operations 504590075Sobrienon the target machine. 504690075Sobrien 504790075Sobrien@table @code 504890075Sobrien@findex CONST_COSTS 504990075Sobrien@item CONST_COSTS (@var{x}, @var{code}, @var{outer_code}) 505090075SobrienA part of a C @code{switch} statement that describes the relative costs 505190075Sobrienof constant RTL expressions. It must contain @code{case} labels for 505290075Sobrienexpression codes @code{const_int}, @code{const}, @code{symbol_ref}, 505390075Sobrien@code{label_ref} and @code{const_double}. Each case must ultimately 505490075Sobrienreach a @code{return} statement to return the relative cost of the use 505590075Sobrienof that kind of constant value in an expression. The cost may depend on 505690075Sobrienthe precise value of the constant, which is available for examination in 505790075Sobrien@var{x}, and the rtx code of the expression in which it is contained, 505890075Sobrienfound in @var{outer_code}. 505990075Sobrien 506090075Sobrien@var{code} is the expression code---redundant, since it can be 506190075Sobrienobtained with @code{GET_CODE (@var{x})}. 506290075Sobrien 506390075Sobrien@findex RTX_COSTS 506490075Sobrien@findex COSTS_N_INSNS 506590075Sobrien@item RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 506690075SobrienLike @code{CONST_COSTS} but applies to nonconstant RTL expressions. 506790075SobrienThis can be used, for example, to indicate how costly a multiply 506890075Sobrieninstruction is. In writing this macro, you can use the construct 506990075Sobrien@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 507090075Sobrieninstructions. @var{outer_code} is the code of the expression in which 507190075Sobrien@var{x} is contained. 507290075Sobrien 507390075SobrienThis macro is optional; do not define it if the default cost assumptions 507490075Sobrienare adequate for the target machine. 507590075Sobrien 507690075Sobrien@findex DEFAULT_RTX_COSTS 507790075Sobrien@item DEFAULT_RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 507890075SobrienThis macro, if defined, is called for any case not handled by the 507990075Sobrien@code{RTX_COSTS} or @code{CONST_COSTS} macros. This eliminates the need 508090075Sobriento put case labels into the macro, but the code, or any functions it 508190075Sobriencalls, must assume that the RTL in @var{x} could be of any type that has 508290075Sobriennot already been handled. The arguments are the same as for 508390075Sobrien@code{RTX_COSTS}, and the macro should execute a return statement giving 508490075Sobrienthe cost of any RTL expressions that it can handle. The default cost 508590075Sobriencalculation is used for any RTL for which this macro does not return a 508690075Sobrienvalue. 508790075Sobrien 508890075SobrienThis macro is optional; do not define it if the default cost assumptions 508990075Sobrienare adequate for the target machine. 509090075Sobrien 509190075Sobrien@findex ADDRESS_COST 509290075Sobrien@item ADDRESS_COST (@var{address}) 509390075SobrienAn expression giving the cost of an addressing mode that contains 509490075Sobrien@var{address}. If not defined, the cost is computed from 509590075Sobrienthe @var{address} expression and the @code{CONST_COSTS} values. 509690075Sobrien 509790075SobrienFor most CISC machines, the default cost is a good approximation of the 509890075Sobrientrue cost of the addressing mode. However, on RISC machines, all 509990075Sobrieninstructions normally have the same length and execution time. Hence 510090075Sobrienall addresses will have equal costs. 510190075Sobrien 510290075SobrienIn cases where more than one form of an address is known, the form with 510390075Sobrienthe lowest cost will be used. If multiple forms have the same, lowest, 510490075Sobriencost, the one that is the most complex will be used. 510590075Sobrien 510690075SobrienFor example, suppose an address that is equal to the sum of a register 510790075Sobrienand a constant is used twice in the same basic block. When this macro 510890075Sobrienis not defined, the address will be computed in a register and memory 510990075Sobrienreferences will be indirect through that register. On machines where 511090075Sobrienthe cost of the addressing mode containing the sum is no higher than 511190075Sobrienthat of a simple indirect reference, this will produce an additional 511290075Sobrieninstruction and possibly require an additional register. Proper 511390075Sobrienspecification of this macro eliminates this overhead for such machines. 511490075Sobrien 511590075SobrienSimilar use of this macro is made in strength reduction of loops. 511690075Sobrien 511790075Sobrien@var{address} need not be valid as an address. In such a case, the cost 511890075Sobrienis not relevant and can be any value; invalid addresses need not be 511990075Sobrienassigned a different cost. 512090075Sobrien 512190075SobrienOn machines where an address involving more than one register is as 512290075Sobriencheap as an address computation involving only one register, defining 512390075Sobrien@code{ADDRESS_COST} to reflect this can cause two registers to be live 512490075Sobrienover a region of code where only one would have been if 512590075Sobrien@code{ADDRESS_COST} were not defined in that manner. This effect should 512690075Sobrienbe considered in the definition of this macro. Equivalent costs should 512790075Sobrienprobably only be given to addresses with different numbers of registers 512890075Sobrienon machines with lots of registers. 512990075Sobrien 513090075SobrienThis macro will normally either not be defined or be defined as a 513190075Sobrienconstant. 513290075Sobrien 513390075Sobrien@findex REGISTER_MOVE_COST 513490075Sobrien@item REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 513590075SobrienA C expression for the cost of moving data of mode @var{mode} from a 513690075Sobrienregister in class @var{from} to one in class @var{to}. The classes are 513790075Sobrienexpressed using the enumeration values such as @code{GENERAL_REGS}. A 513890075Sobrienvalue of 2 is the default; other values are interpreted relative to 513990075Sobrienthat. 514090075Sobrien 514190075SobrienIt is not required that the cost always equal 2 when @var{from} is the 514290075Sobriensame as @var{to}; on some machines it is expensive to move between 514390075Sobrienregisters if they are not general registers. 514490075Sobrien 514590075SobrienIf reload sees an insn consisting of a single @code{set} between two 514690075Sobrienhard registers, and if @code{REGISTER_MOVE_COST} applied to their 514790075Sobrienclasses returns a value of 2, reload does not check to ensure that the 514890075Sobrienconstraints of the insn are met. Setting a cost of other than 2 will 514990075Sobrienallow reload to verify that the constraints are met. You should do this 515090075Sobrienif the @samp{mov@var{m}} pattern's constraints do not allow such copying. 515190075Sobrien 515290075Sobrien@findex MEMORY_MOVE_COST 515390075Sobrien@item MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 515490075SobrienA C expression for the cost of moving data of mode @var{mode} between a 515590075Sobrienregister of class @var{class} and memory; @var{in} is zero if the value 515690075Sobrienis to be written to memory, nonzero if it is to be read in. This cost 515790075Sobrienis relative to those in @code{REGISTER_MOVE_COST}. If moving between 515890075Sobrienregisters and memory is more expensive than between two registers, you 515990075Sobrienshould define this macro to express the relative cost. 516090075Sobrien 516190075SobrienIf you do not define this macro, GCC uses a default cost of 4 plus 516290075Sobrienthe cost of copying via a secondary reload register, if one is 516390075Sobrienneeded. If your machine requires a secondary reload register to copy 516490075Sobrienbetween memory and a register of @var{class} but the reload mechanism is 516590075Sobrienmore complex than copying via an intermediate, define this macro to 516690075Sobrienreflect the actual cost of the move. 516790075Sobrien 516890075SobrienGCC defines the function @code{memory_move_secondary_cost} if 516990075Sobriensecondary reloads are needed. It computes the costs due to copying via 517090075Sobriena secondary register. If your machine copies from memory using a 517190075Sobriensecondary register in the conventional way but the default base value of 517290075Sobrien4 is not correct for your machine, define this macro to add some other 517390075Sobrienvalue to the result of that function. The arguments to that function 517490075Sobrienare the same as to this macro. 517590075Sobrien 517690075Sobrien@findex BRANCH_COST 517790075Sobrien@item BRANCH_COST 517890075SobrienA C expression for the cost of a branch instruction. A value of 1 is 517990075Sobrienthe default; other values are interpreted relative to that. 518090075Sobrien@end table 518190075Sobrien 518290075SobrienHere are additional macros which do not specify precise relative costs, 518390075Sobrienbut only that certain actions are more expensive than GCC would 518490075Sobrienordinarily expect. 518590075Sobrien 518690075Sobrien@table @code 518790075Sobrien@findex SLOW_BYTE_ACCESS 518890075Sobrien@item SLOW_BYTE_ACCESS 518990075SobrienDefine this macro as a C expression which is nonzero if accessing less 519090075Sobrienthan a word of memory (i.e.@: a @code{char} or a @code{short}) is no 519190075Sobrienfaster than accessing a word of memory, i.e., if such access 519290075Sobrienrequire more than one instruction or if there is no difference in cost 519390075Sobrienbetween byte and (aligned) word loads. 519490075Sobrien 519590075SobrienWhen this macro is not defined, the compiler will access a field by 519690075Sobrienfinding the smallest containing object; when it is defined, a fullword 519790075Sobrienload will be used if alignment permits. Unless bytes accesses are 519890075Sobrienfaster than word accesses, using word accesses is preferable since it 519990075Sobrienmay eliminate subsequent memory access if subsequent accesses occur to 520090075Sobrienother fields in the same word of the structure, but to different bytes. 520190075Sobrien 520290075Sobrien@findex SLOW_UNALIGNED_ACCESS 520390075Sobrien@item SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 520490075SobrienDefine this macro to be the value 1 if memory accesses described by the 520590075Sobrien@var{mode} and @var{alignment} parameters have a cost many times greater 520690075Sobrienthan aligned accesses, for example if they are emulated in a trap 520790075Sobrienhandler. 520890075Sobrien 520990075SobrienWhen this macro is nonzero, the compiler will act as if 521090075Sobrien@code{STRICT_ALIGNMENT} were nonzero when generating code for block 521190075Sobrienmoves. This can cause significantly more instructions to be produced. 521290075SobrienTherefore, do not set this macro nonzero if unaligned accesses only add a 521390075Sobriencycle or two to the time for a memory access. 521490075Sobrien 521590075SobrienIf the value of this macro is always zero, it need not be defined. If 521690075Sobrienthis macro is defined, it should produce a nonzero value when 521790075Sobrien@code{STRICT_ALIGNMENT} is nonzero. 521890075Sobrien 521990075Sobrien@findex DONT_REDUCE_ADDR 522090075Sobrien@item DONT_REDUCE_ADDR 522190075SobrienDefine this macro to inhibit strength reduction of memory addresses. 522290075Sobrien(On some machines, such strength reduction seems to do harm rather 522390075Sobrienthan good.) 522490075Sobrien 522590075Sobrien@findex MOVE_RATIO 522690075Sobrien@item MOVE_RATIO 522790075SobrienThe threshold of number of scalar memory-to-memory move insns, @emph{below} 522890075Sobrienwhich a sequence of insns should be generated instead of a 522990075Sobrienstring move insn or a library call. Increasing the value will always 523090075Sobrienmake code faster, but eventually incurs high cost in increased code size. 523190075Sobrien 523290075SobrienNote that on machines where the corresponding move insn is a 523390075Sobrien@code{define_expand} that emits a sequence of insns, this macro counts 523490075Sobrienthe number of such sequences. 523590075Sobrien 523690075SobrienIf you don't define this, a reasonable default is used. 523790075Sobrien 523890075Sobrien@findex MOVE_BY_PIECES_P 523990075Sobrien@item MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 524090075SobrienA C expression used to determine whether @code{move_by_pieces} will be used to 524190075Sobriencopy a chunk of memory, or whether some other block move mechanism 524290075Sobrienwill be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 524390075Sobrienthan @code{MOVE_RATIO}. 524490075Sobrien 524590075Sobrien@findex MOVE_MAX_PIECES 524690075Sobrien@item MOVE_MAX_PIECES 524790075SobrienA C expression used by @code{move_by_pieces} to determine the largest unit 524890075Sobriena load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 524990075Sobrien 525090075Sobrien@findex USE_LOAD_POST_INCREMENT 525190075Sobrien@item USE_LOAD_POST_INCREMENT (@var{mode}) 525290075SobrienA C expression used to determine whether a load postincrement is a good 525390075Sobrienthing to use for a given mode. Defaults to the value of 525490075Sobrien@code{HAVE_POST_INCREMENT}. 525590075Sobrien 525690075Sobrien@findex USE_LOAD_POST_DECREMENT 525790075Sobrien@item USE_LOAD_POST_DECREMENT (@var{mode}) 525890075SobrienA C expression used to determine whether a load postdecrement is a good 525990075Sobrienthing to use for a given mode. Defaults to the value of 526090075Sobrien@code{HAVE_POST_DECREMENT}. 526190075Sobrien 526290075Sobrien@findex USE_LOAD_PRE_INCREMENT 526390075Sobrien@item USE_LOAD_PRE_INCREMENT (@var{mode}) 526490075SobrienA C expression used to determine whether a load preincrement is a good 526590075Sobrienthing to use for a given mode. Defaults to the value of 526690075Sobrien@code{HAVE_PRE_INCREMENT}. 526790075Sobrien 526890075Sobrien@findex USE_LOAD_PRE_DECREMENT 526990075Sobrien@item USE_LOAD_PRE_DECREMENT (@var{mode}) 527090075SobrienA C expression used to determine whether a load predecrement is a good 527190075Sobrienthing to use for a given mode. Defaults to the value of 527290075Sobrien@code{HAVE_PRE_DECREMENT}. 527390075Sobrien 527490075Sobrien@findex USE_STORE_POST_INCREMENT 527590075Sobrien@item USE_STORE_POST_INCREMENT (@var{mode}) 527690075SobrienA C expression used to determine whether a store postincrement is a good 527790075Sobrienthing to use for a given mode. Defaults to the value of 527890075Sobrien@code{HAVE_POST_INCREMENT}. 527990075Sobrien 528090075Sobrien@findex USE_STORE_POST_DECREMENT 528190075Sobrien@item USE_STORE_POST_DECREMENT (@var{mode}) 528290075SobrienA C expression used to determine whether a store postdecrement is a good 528390075Sobrienthing to use for a given mode. Defaults to the value of 528490075Sobrien@code{HAVE_POST_DECREMENT}. 528590075Sobrien 528690075Sobrien@findex USE_STORE_PRE_INCREMENT 528790075Sobrien@item USE_STORE_PRE_INCREMENT (@var{mode}) 528890075SobrienThis macro is used to determine whether a store preincrement is a good 528990075Sobrienthing to use for a given mode. Defaults to the value of 529090075Sobrien@code{HAVE_PRE_INCREMENT}. 529190075Sobrien 529290075Sobrien@findex USE_STORE_PRE_DECREMENT 529390075Sobrien@item USE_STORE_PRE_DECREMENT (@var{mode}) 529490075SobrienThis macro is used to determine whether a store predecrement is a good 529590075Sobrienthing to use for a given mode. Defaults to the value of 529690075Sobrien@code{HAVE_PRE_DECREMENT}. 529790075Sobrien 529890075Sobrien@findex NO_FUNCTION_CSE 529990075Sobrien@item NO_FUNCTION_CSE 530090075SobrienDefine this macro if it is as good or better to call a constant 530190075Sobrienfunction address than to call an address kept in a register. 530290075Sobrien 530390075Sobrien@findex NO_RECURSIVE_FUNCTION_CSE 530490075Sobrien@item NO_RECURSIVE_FUNCTION_CSE 530590075SobrienDefine this macro if it is as good or better for a function to call 530690075Sobrienitself with an explicit address than to call an address kept in a 530790075Sobrienregister. 530890075Sobrien@end table 530990075Sobrien 531090075Sobrien@node Scheduling 531190075Sobrien@section Adjusting the Instruction Scheduler 531290075Sobrien 531390075SobrienThe instruction scheduler may need a fair amount of machine-specific 531490075Sobrienadjustment in order to produce good code. GCC provides several target 531590075Sobrienhooks for this purpose. It is usually enough to define just a few of 531690075Sobrienthem: try the first ones in this list first. 531790075Sobrien 531890075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 531990075SobrienThis hook returns the maximum number of instructions that can ever issue 532090075Sobrienat the same time on the target machine. The default is one. This value 532190075Sobrienmust be constant over the entire compilation. If you need it to vary 532290075Sobriendepending on what the instructions are, you must use 532390075Sobrien@samp{TARGET_SCHED_VARIABLE_ISSUE}. 532490075Sobrien@end deftypefn 532590075Sobrien 532690075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 532790075SobrienThis hook is executed by the scheduler after it has scheduled an insn 532890075Sobrienfrom the ready list. It should return the number of insns which can 532990075Sobrienstill be issued in the current cycle. Normally this is 533090075Sobrien@samp{@w{@var{more} - 1}}. You should define this hook if some insns 533190075Sobrientake more machine resources than others, so that fewer insns can follow 533290075Sobrienthem in the same cycle. @var{file} is either a null pointer, or a stdio 533390075Sobrienstream to write any debug output to. @var{verbose} is the verbose level 533490075Sobrienprovided by @option{-fsched-verbose-@var{n}}. @var{insn} is the 533590075Sobrieninstruction that was scheduled. 533690075Sobrien@end deftypefn 533790075Sobrien 533890075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 533990075SobrienThis function corrects the value of @var{cost} based on the relationship 534090075Sobrienbetween @var{insn} and @var{dep_insn} through the dependence @var{link}. 534190075SobrienIt should return the new value. The default is to make no adjustment to 534290075Sobrien@var{cost}. This can be used for example to specify to the scheduler 534390075Sobrienthat an output- or anti-dependence does not incur the same cost as a 534490075Sobriendata-dependence. 534590075Sobrien@end deftypefn 534690075Sobrien 534790075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 534890075SobrienThis hook adjusts the integer scheduling priority @var{priority} of 534990075Sobrien@var{insn}. It should return the new priority. Reduce the priority to 535090075Sobrienexecute @var{insn} earlier, increase the priority to execute @var{insn} 535190075Sobrienlater. Do not define this hook if you do not need to adjust the 535290075Sobrienscheduling priorities of insns. 535390075Sobrien@end deftypefn 535490075Sobrien 535590075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 535690075SobrienThis hook is executed by the scheduler after it has scheduled the ready 535790075Sobrienlist, to allow the machine description to reorder it (for example to 535890075Sobriencombine two small instructions together on @samp{VLIW} machines). 535990075Sobrien@var{file} is either a null pointer, or a stdio stream to write any 536090075Sobriendebug output to. @var{verbose} is the verbose level provided by 536190075Sobrien@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 536290075Sobrienlist of instructions that are ready to be scheduled. @var{n_readyp} is 536390075Sobriena pointer to the number of elements in the ready list. The scheduler 536490075Sobrienreads the ready list in reverse order, starting with 536590075Sobrien@var{ready}[@var{*n_readyp}-1] and going to @var{ready}[0]. @var{clock} 536690075Sobrienis the timer tick of the scheduler. You may modify the ready list and 536790075Sobrienthe number of ready insns. The return value is the number of insns that 536890075Sobriencan issue this cycle; normally this is just @code{issue_rate}. See also 536990075Sobrien@samp{TARGET_SCHED_REORDER2}. 537090075Sobrien@end deftypefn 537190075Sobrien 537290075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_ready}, @var{clock}) 537390075SobrienLike @samp{TARGET_SCHED_REORDER}, but called at a different time. That 537490075Sobrienfunction is called whenever the scheduler starts a new cycle. This one 537590075Sobrienis called once per iteration over a cycle, immediately after 537690075Sobrien@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 537790075Sobrienreturn the number of insns to be scheduled in the same cycle. Defining 537890075Sobrienthis hook can be useful if there are frequent situations where 537990075Sobrienscheduling one insn causes other insns to become ready in the same 538090075Sobriencycle. These other insns can then be taken into account properly. 538190075Sobrien@end deftypefn 538290075Sobrien 538390075Sobrien@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 538490075SobrienThis hook is executed by the scheduler at the beginning of each block of 538590075Sobrieninstructions that are to be scheduled. @var{file} is either a null 538690075Sobrienpointer, or a stdio stream to write any debug output to. @var{verbose} 538790075Sobrienis the verbose level provided by @option{-fsched-verbose-@var{n}}. 538890075Sobrien@var{max_ready} is the maximum number of insns in the current scheduling 538990075Sobrienregion that can be live at the same time. This can be used to allocate 539090075Sobrienscratch space if it is needed, e.g. by @samp{TARGET_SCHED_REORDER}. 539190075Sobrien@end deftypefn 539290075Sobrien 539390075Sobrien@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 539490075SobrienThis hook is executed by the scheduler at the end of each block of 539590075Sobrieninstructions that are to be scheduled. It can be used to perform 539690075Sobriencleanup of any actions done by the other scheduling hooks. @var{file} 539790075Sobrienis either a null pointer, or a stdio stream to write any debug output 539890075Sobriento. @var{verbose} is the verbose level provided by 539990075Sobrien@option{-fsched-verbose-@var{n}}. 540090075Sobrien@end deftypefn 540190075Sobrien 540290075Sobrien@deftypefn {Target Hook} rtx TARGET_SCHED_CYCLE_DISPLAY (int @var{clock}, rtx @var{last}) 540390075SobrienThis hook is called in verbose mode only, at the beginning of each pass 540490075Sobrienover a basic block. It should insert an insn into the chain after 540590075Sobrien@var{last}, which has no effect, but records the value @var{clock} in 540690075SobrienRTL dumps and assembly output. Define this hook only if you need this 540790075Sobrienlevel of detail about what the scheduler is doing. 540890075Sobrien@end deftypefn 540990075Sobrien 541090075Sobrien@node Sections 541190075Sobrien@section Dividing the Output into Sections (Texts, Data, @dots{}) 541290075Sobrien@c the above section title is WAY too long. maybe cut the part between 541390075Sobrien@c the (...)? --mew 10feb93 541490075Sobrien 541590075SobrienAn object file is divided into sections containing different types of 541690075Sobriendata. In the most common case, there are three sections: the @dfn{text 541790075Sobriensection}, which holds instructions and read-only data; the @dfn{data 541890075Sobriensection}, which holds initialized writable data; and the @dfn{bss 541990075Sobriensection}, which holds uninitialized data. Some systems have other kinds 542090075Sobrienof sections. 542190075Sobrien 542290075SobrienThe compiler must tell the assembler when to switch sections. These 542390075Sobrienmacros control what commands to output to tell the assembler this. You 542490075Sobriencan also define additional sections. 542590075Sobrien 542690075Sobrien@table @code 542790075Sobrien@findex TEXT_SECTION_ASM_OP 542890075Sobrien@item TEXT_SECTION_ASM_OP 542990075SobrienA C expression whose value is a string, including spacing, containing the 543090075Sobrienassembler operation that should precede instructions and read-only data. 543190075SobrienNormally @code{"\t.text"} is right. 543290075Sobrien 543390075Sobrien@findex TEXT_SECTION 543490075Sobrien@item TEXT_SECTION 543590075SobrienA C statement that switches to the default section containing instructions. 543690075SobrienNormally this is not needed, as simply defining @code{TEXT_SECTION_ASM_OP} 543790075Sobrienis enough. The MIPS port uses this to sort all functions after all data 543890075Sobriendeclarations. 543990075Sobrien 544090075Sobrien@findex DATA_SECTION_ASM_OP 544190075Sobrien@item DATA_SECTION_ASM_OP 544290075SobrienA C expression whose value is a string, including spacing, containing the 544390075Sobrienassembler operation to identify the following data as writable initialized 544490075Sobriendata. Normally @code{"\t.data"} is right. 544590075Sobrien 544690075Sobrien@findex SHARED_SECTION_ASM_OP 544790075Sobrien@item SHARED_SECTION_ASM_OP 544890075SobrienIf defined, a C expression whose value is a string, including spacing, 544990075Sobriencontaining the assembler operation to identify the following data as 545090075Sobrienshared data. If not defined, @code{DATA_SECTION_ASM_OP} will be used. 545190075Sobrien 545290075Sobrien@findex BSS_SECTION_ASM_OP 545390075Sobrien@item BSS_SECTION_ASM_OP 545490075SobrienIf defined, a C expression whose value is a string, including spacing, 545590075Sobriencontaining the assembler operation to identify the following data as 545690075Sobrienuninitialized global data. If not defined, and neither 545790075Sobrien@code{ASM_OUTPUT_BSS} nor @code{ASM_OUTPUT_ALIGNED_BSS} are defined, 545890075Sobrienuninitialized global data will be output in the data section if 545990075Sobrien@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 546090075Sobrienused. 546190075Sobrien 546290075Sobrien@findex SHARED_BSS_SECTION_ASM_OP 546390075Sobrien@item SHARED_BSS_SECTION_ASM_OP 546490075SobrienIf defined, a C expression whose value is a string, including spacing, 546590075Sobriencontaining the assembler operation to identify the following data as 546690075Sobrienuninitialized global shared data. If not defined, and 546790075Sobrien@code{BSS_SECTION_ASM_OP} is, the latter will be used. 546890075Sobrien 546990075Sobrien@findex INIT_SECTION_ASM_OP 547090075Sobrien@item INIT_SECTION_ASM_OP 547190075SobrienIf defined, a C expression whose value is a string, including spacing, 547290075Sobriencontaining the assembler operation to identify the following data as 547390075Sobrieninitialization code. If not defined, GCC will assume such a section does 547490075Sobriennot exist. 547590075Sobrien 547690075Sobrien@findex FINI_SECTION_ASM_OP 547790075Sobrien@item FINI_SECTION_ASM_OP 547890075SobrienIf defined, a C expression whose value is a string, including spacing, 547990075Sobriencontaining the assembler operation to identify the following data as 548090075Sobrienfinalization code. If not defined, GCC will assume such a section does 548190075Sobriennot exist. 548290075Sobrien 548390075Sobrien@findex CRT_CALL_STATIC_FUNCTION 548490075Sobrien@item CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 548590075SobrienIf defined, an ASM statement that switches to a different section 548690075Sobrienvia @var{section_op}, calls @var{function}, and switches back to 548790075Sobrienthe text section. This is used in @file{crtstuff.c} if 548890075Sobrien@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 548990075Sobriento initialization and finalization functions from the init and fini 549090075Sobriensections. By default, this macro uses a simple function call. Some 549190075Sobrienports need hand-crafted assembly code to avoid dependencies on 549290075Sobrienregisters initialized in the function prologue or to ensure that 549390075Sobrienconstant pools don't end up too far way in the text section. 549490075Sobrien 549590075Sobrien@findex FORCE_CODE_SECTION_ALIGN 549690075Sobrien@item FORCE_CODE_SECTION_ALIGN 549790075SobrienIf defined, an ASM statement that aligns a code section to some 549890075Sobrienarbitrary boundary. This is used to force all fragments of the 549990075Sobrien@code{.init} and @code{.fini} sections to have to same alignment 550090075Sobrienand thus prevent the linker from having to add any padding. 550190075Sobrien 550290075Sobrien@findex EXTRA_SECTIONS 550390075Sobrien@findex in_text 550490075Sobrien@findex in_data 550590075Sobrien@item EXTRA_SECTIONS 550690075SobrienA list of names for sections other than the standard two, which are 550790075Sobrien@code{in_text} and @code{in_data}. You need not define this macro 550890075Sobrienon a system with no other sections (that GCC needs to use). 550990075Sobrien 551090075Sobrien@findex EXTRA_SECTION_FUNCTIONS 551190075Sobrien@findex text_section 551290075Sobrien@findex data_section 551390075Sobrien@item EXTRA_SECTION_FUNCTIONS 551490075SobrienOne or more functions to be defined in @file{varasm.c}. These 551590075Sobrienfunctions should do jobs analogous to those of @code{text_section} and 551690075Sobrien@code{data_section}, for your additional sections. Do not define this 551790075Sobrienmacro if you do not define @code{EXTRA_SECTIONS}. 551890075Sobrien 551990075Sobrien@findex READONLY_DATA_SECTION 552090075Sobrien@item READONLY_DATA_SECTION 552190075SobrienOn most machines, read-only variables, constants, and jump tables are 552290075Sobrienplaced in the text section. If this is not the case on your machine, 552390075Sobrienthis macro should be defined to be the name of a function (either 552490075Sobrien@code{data_section} or a function defined in @code{EXTRA_SECTIONS}) that 552590075Sobrienswitches to the section to be used for read-only items. 552690075Sobrien 552790075SobrienIf these items should be placed in the text section, this macro should 552890075Sobriennot be defined. 552990075Sobrien 553090075Sobrien@findex SELECT_SECTION 553190075Sobrien@item SELECT_SECTION (@var{exp}, @var{reloc}, @var{align}) 553290075SobrienA C statement or statements to switch to the appropriate section for 553390075Sobrienoutput of @var{exp}. You can assume that @var{exp} is either a 553490075Sobrien@code{VAR_DECL} node or a constant of some sort. @var{reloc} 553590075Sobrienindicates whether the initial value of @var{exp} requires link-time 553690075Sobrienrelocations. Bit 1 is set when variable contains local relocations 553790075Sobrienonly, while bit 2 is set for global relocations. 553890075SobrienSelect the section by calling @code{text_section} or one 553990075Sobrienof the alternatives for other sections. @var{align} is the constant 554090075Sobrienalignment in bits. 554190075Sobrien 554290075SobrienDo not define this macro if you put all read-only variables and 554390075Sobrienconstants in the read-only data section (usually the text section). 554490075Sobrien 554590075Sobrien@findex SELECT_RTX_SECTION 554690075Sobrien@item SELECT_RTX_SECTION (@var{mode}, @var{rtx}, @var{align}) 554790075SobrienA C statement or statements to switch to the appropriate section for 554890075Sobrienoutput of @var{rtx} in mode @var{mode}. You can assume that @var{rtx} 554990075Sobrienis some kind of constant in RTL@. The argument @var{mode} is redundant 555090075Sobrienexcept in the case of a @code{const_int} rtx. Select the section by 555190075Sobriencalling @code{text_section} or one of the alternatives for other 555290075Sobriensections. @var{align} is the constant alignment in bits. 555390075Sobrien 555490075SobrienDo not define this macro if you put all constants in the read-only 555590075Sobriendata section. 555690075Sobrien 555790075Sobrien@findex JUMP_TABLES_IN_TEXT_SECTION 555890075Sobrien@item JUMP_TABLES_IN_TEXT_SECTION 555990075SobrienDefine this macro to be an expression with a nonzero value if jump 556090075Sobrientables (for @code{tablejump} insns) should be output in the text 556190075Sobriensection, along with the assembler instructions. Otherwise, the 556290075Sobrienreadonly data section is used. 556390075Sobrien 556490075SobrienThis macro is irrelevant if there is no separate readonly data section. 556590075Sobrien 556690075Sobrien@findex ENCODE_SECTION_INFO 556790075Sobrien@item ENCODE_SECTION_INFO (@var{decl}) 556890075SobrienDefine this macro if references to a symbol or a constant must be 556990075Sobrientreated differently depending on something about the variable or 557090075Sobrienfunction named by the symbol (such as what section it is in). 557190075Sobrien 557290075SobrienThe macro definition, if any, is executed under two circumstances. One 557390075Sobrienis immediately after the rtl for @var{decl} that represents a variable 557490075Sobrienor a function has been created and stored in @code{DECL_RTL 557590075Sobrien(@var{decl})}. The value of the rtl will be a @code{mem} whose address 557690075Sobrienis a @code{symbol_ref}. The other is immediately after the rtl for 557790075Sobrien@var{decl} that represents a constant has been created and stored in 557890075Sobrien@code{TREE_CST_RTL (@var{decl})}. The macro is called once for each 557990075Sobriendistinct constant in a source file. 558090075Sobrien 558190075Sobrien@cindex @code{SYMBOL_REF_FLAG}, in @code{ENCODE_SECTION_INFO} 558290075SobrienThe usual thing for this macro to do is to record a flag in the 558390075Sobrien@code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a 558490075Sobrienmodified name string in the @code{symbol_ref} (if one bit is not enough 558590075Sobrieninformation). 558690075Sobrien 558790075Sobrien@findex STRIP_NAME_ENCODING 558890075Sobrien@item STRIP_NAME_ENCODING (@var{var}, @var{sym_name}) 558990075SobrienDecode @var{sym_name} and store the real name part in @var{var}, sans 559090075Sobrienthe characters that encode section info. Define this macro if 559190075Sobrien@code{ENCODE_SECTION_INFO} alters the symbol's name string. 559290075Sobrien 559390075Sobrien@findex UNIQUE_SECTION 559490075Sobrien@item UNIQUE_SECTION (@var{decl}, @var{reloc}) 559590075SobrienA C statement to build up a unique section name, expressed as a 559690075Sobrien@code{STRING_CST} node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 559790075Sobrien@var{reloc} indicates whether the initial value of @var{exp} requires 559890075Sobrienlink-time relocations. If you do not define this macro, GCC will use 559990075Sobrienthe symbol name prefixed by @samp{.} as the section name. Note - this 560090075Sobrienmacro can now be called for uninitialized data items as well as 560190075Sobrieninitialized data and functions. 560290075Sobrien@end table 560390075Sobrien 560490075Sobrien@node PIC 560590075Sobrien@section Position Independent Code 560690075Sobrien@cindex position independent code 560790075Sobrien@cindex PIC 560890075Sobrien 560990075SobrienThis section describes macros that help implement generation of position 561090075Sobrienindependent code. Simply defining these macros is not enough to 561190075Sobriengenerate valid PIC; you must also add support to the macros 561290075Sobrien@code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as 561390075Sobrienwell as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of 561490075Sobrien@samp{movsi} to do something appropriate when the source operand 561590075Sobriencontains a symbolic address. You may also need to alter the handling of 561690075Sobrienswitch statements so that they use relative addresses. 561790075Sobrien@c i rearranged the order of the macros above to try to force one of 561890075Sobrien@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 561990075Sobrien 562090075Sobrien@table @code 562190075Sobrien@findex PIC_OFFSET_TABLE_REGNUM 562290075Sobrien@item PIC_OFFSET_TABLE_REGNUM 562390075SobrienThe register number of the register used to address a table of static 562490075Sobriendata addresses in memory. In some cases this register is defined by a 562590075Sobrienprocessor's ``application binary interface'' (ABI)@. When this macro 562690075Sobrienis defined, RTL is generated for this register once, as with the stack 562790075Sobrienpointer and frame pointer registers. If this macro is not defined, it 562890075Sobrienis up to the machine-dependent files to allocate such a register (if 562990075Sobriennecessary). Note that this register must be fixed when in use (e.g.@: 563090075Sobrienwhen @code{flag_pic} is true). 563190075Sobrien 563290075Sobrien@findex PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 563390075Sobrien@item PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 563490075SobrienDefine this macro if the register defined by 563590075Sobrien@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define 563690075Sobrienthis macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 563790075Sobrien 563890075Sobrien@findex FINALIZE_PIC 563990075Sobrien@item FINALIZE_PIC 564090075SobrienBy generating position-independent code, when two different programs (A 564190075Sobrienand B) share a common library (libC.a), the text of the library can be 564290075Sobrienshared whether or not the library is linked at the same address for both 564390075Sobrienprograms. In some of these environments, position-independent code 564490075Sobrienrequires not only the use of different addressing modes, but also 564590075Sobrienspecial code to enable the use of these addressing modes. 564690075Sobrien 564790075SobrienThe @code{FINALIZE_PIC} macro serves as a hook to emit these special 564890075Sobriencodes once the function is being compiled into assembly code, but not 564990075Sobrienbefore. (It is not done before, because in the case of compiling an 565090075Sobrieninline function, it would lead to multiple PIC prologues being 565190075Sobrienincluded in functions which used inline functions and were compiled to 565290075Sobrienassembly language.) 565390075Sobrien 565490075Sobrien@findex LEGITIMATE_PIC_OPERAND_P 565590075Sobrien@item LEGITIMATE_PIC_OPERAND_P (@var{x}) 565690075SobrienA C expression that is nonzero if @var{x} is a legitimate immediate 565790075Sobrienoperand on the target machine when generating position independent code. 565890075SobrienYou can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 565990075Sobriencheck this. You can also assume @var{flag_pic} is true, so you need not 566090075Sobriencheck it either. You need not define this macro if all constants 566190075Sobrien(including @code{SYMBOL_REF}) can be immediate operands when generating 566290075Sobrienposition independent code. 566390075Sobrien@end table 566490075Sobrien 566590075Sobrien@node Assembler Format 566690075Sobrien@section Defining the Output Assembler Language 566790075Sobrien 566890075SobrienThis section describes macros whose principal purpose is to describe how 566990075Sobriento write instructions in assembler language---rather than what the 567090075Sobrieninstructions do. 567190075Sobrien 567290075Sobrien@menu 567390075Sobrien* File Framework:: Structural information for the assembler file. 567490075Sobrien* Data Output:: Output of constants (numbers, strings, addresses). 567590075Sobrien* Uninitialized Data:: Output of uninitialized variables. 567690075Sobrien* Label Output:: Output and generation of labels. 567790075Sobrien* Initialization:: General principles of initialization 567890075Sobrien and termination routines. 567990075Sobrien* Macros for Initialization:: 568090075Sobrien Specific macros that control the handling of 568190075Sobrien initialization and termination routines. 568290075Sobrien* Instruction Output:: Output of actual instructions. 568390075Sobrien* Dispatch Tables:: Output of jump tables. 568490075Sobrien* Exception Region Output:: Output of exception region code. 568590075Sobrien* Alignment Output:: Pseudo ops for alignment and skipping data. 568690075Sobrien@end menu 568790075Sobrien 568890075Sobrien@node File Framework 568990075Sobrien@subsection The Overall Framework of an Assembler File 569090075Sobrien@cindex assembler format 569190075Sobrien@cindex output of assembler code 569290075Sobrien 569390075Sobrien@c prevent bad page break with this line 569490075SobrienThis describes the overall framework of an assembler file. 569590075Sobrien 569690075Sobrien@table @code 569790075Sobrien@findex ASM_FILE_START 569890075Sobrien@item ASM_FILE_START (@var{stream}) 569990075SobrienA C expression which outputs to the stdio stream @var{stream} 570090075Sobriensome appropriate text to go at the start of an assembler file. 570190075Sobrien 570290075SobrienNormally this macro is defined to output a line containing 570390075Sobrien@samp{#NO_APP}, which is a comment that has no effect on most 570490075Sobrienassemblers but tells the GNU assembler that it can save time by not 570590075Sobrienchecking for certain assembler constructs. 570690075Sobrien 570790075SobrienOn systems that use SDB, it is necessary to output certain commands; 570890075Sobriensee @file{attasm.h}. 570990075Sobrien 571090075Sobrien@findex ASM_FILE_END 571190075Sobrien@item ASM_FILE_END (@var{stream}) 571290075SobrienA C expression which outputs to the stdio stream @var{stream} 571390075Sobriensome appropriate text to go at the end of an assembler file. 571490075Sobrien 571590075SobrienIf this macro is not defined, the default is to output nothing 571690075Sobrienspecial at the end of the file. Most systems don't require any 571790075Sobriendefinition. 571890075Sobrien 571990075SobrienOn systems that use SDB, it is necessary to output certain commands; 572090075Sobriensee @file{attasm.h}. 572190075Sobrien 572290075Sobrien@findex ASM_COMMENT_START 572390075Sobrien@item ASM_COMMENT_START 572490075SobrienA C string constant describing how to begin a comment in the target 572590075Sobrienassembler language. The compiler assumes that the comment will end at 572690075Sobrienthe end of the line. 572790075Sobrien 572890075Sobrien@findex ASM_APP_ON 572990075Sobrien@item ASM_APP_ON 573090075SobrienA C string constant for text to be output before each @code{asm} 573190075Sobrienstatement or group of consecutive ones. Normally this is 573290075Sobrien@code{"#APP"}, which is a comment that has no effect on most 573390075Sobrienassemblers but tells the GNU assembler that it must check the lines 573490075Sobrienthat follow for all valid assembler constructs. 573590075Sobrien 573690075Sobrien@findex ASM_APP_OFF 573790075Sobrien@item ASM_APP_OFF 573890075SobrienA C string constant for text to be output after each @code{asm} 573990075Sobrienstatement or group of consecutive ones. Normally this is 574090075Sobrien@code{"#NO_APP"}, which tells the GNU assembler to resume making the 574190075Sobrientime-saving assumptions that are valid for ordinary compiler output. 574290075Sobrien 574390075Sobrien@findex ASM_OUTPUT_SOURCE_FILENAME 574490075Sobrien@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 574590075SobrienA C statement to output COFF information or DWARF debugging information 574690075Sobrienwhich indicates that filename @var{name} is the current source file to 574790075Sobrienthe stdio stream @var{stream}. 574890075Sobrien 574990075SobrienThis macro need not be defined if the standard form of output 575090075Sobrienfor the file format in use is appropriate. 575190075Sobrien 575290075Sobrien@findex OUTPUT_QUOTED_STRING 575390075Sobrien@item OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 575490075SobrienA C statement to output the string @var{string} to the stdio stream 575590075Sobrien@var{stream}. If you do not call the function @code{output_quoted_string} 575690075Sobrienin your config files, GCC will only call it to output filenames to 575790075Sobrienthe assembler source. So you can use it to canonicalize the format 575890075Sobrienof the filename using this macro. 575990075Sobrien 576090075Sobrien@findex ASM_OUTPUT_SOURCE_LINE 576190075Sobrien@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 576290075SobrienA C statement to output DBX or SDB debugging information before code 576390075Sobrienfor line number @var{line} of the current source file to the 576490075Sobrienstdio stream @var{stream}. 576590075Sobrien 576690075SobrienThis macro need not be defined if the standard form of debugging 576790075Sobrieninformation for the debugger in use is appropriate. 576890075Sobrien 576990075Sobrien@findex ASM_OUTPUT_IDENT 577090075Sobrien@item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 577190075SobrienA C statement to output something to the assembler file to handle a 577290075Sobrien@samp{#ident} directive containing the text @var{string}. If this 577390075Sobrienmacro is not defined, nothing is output for a @samp{#ident} directive. 577490075Sobrien 577590075Sobrien@findex OBJC_PROLOGUE 577690075Sobrien@item OBJC_PROLOGUE 577790075SobrienA C statement to output any assembler statements which are required to 577890075Sobrienprecede any Objective-C object definitions or message sending. The 577990075Sobrienstatement is executed only when compiling an Objective-C program. 578090075Sobrien@end table 578190075Sobrien 578290075Sobrien@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, unsigned int @var{align}) 578390075SobrienOutput assembly directives to switch to section @var{name}. The section 578490075Sobrienshould have attributes as specified by @var{flags}, which is a bit mask 578590075Sobrienof the @code{SECTION_*} flags defined in @file{output.h}. If @var{align} 578690075Sobrienis nonzero, it contains an alignment in bytes to be used for the section, 578796263Sobrienotherwise some target default should be used. Only targets that must 578890075Sobrienspecify an alignment within the section directive need pay attention to 578990075Sobrien@var{align} -- we will still use @code{ASM_OUTPUT_ALIGN}. 579090075Sobrien@end deftypefn 579190075Sobrien 579290075Sobrien@deftypefn {Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 579390075SobrienThis flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 579490075Sobrien@end deftypefn 579590075Sobrien 579690075Sobrien@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 579790075SobrienChoose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 579890075Sobrienbased on a variable or function decl, a section name, and whether or not the 579990075Sobriendeclaration's initializer may contain runtime relocations. @var{decl} may be 580090075Sobrien null, in which case read-write data should be assumed. 580190075Sobrien 580290075SobrienThe default version if this function handles choosing code vs data, 580390075Sobrienread-only vs read-write data, and @code{flag_pic}. You should only 580490075Sobrienneed to override this if your target has special flags that might be 580590075Sobrienset via @code{__attribute__}. 580690075Sobrien@end deftypefn 580790075Sobrien 580890075Sobrien@need 2000 580990075Sobrien@node Data Output 581090075Sobrien@subsection Output of Data 581190075Sobrien 581290075Sobrien 581390075Sobrien@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 581490075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 581590075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 581690075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 581790075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 581890075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 581990075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 582090075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 582190075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 582290075SobrienThese hooks specify assembly directives for creating certain kinds 582390075Sobrienof integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 582490075Sobrienbyte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 582590075Sobrienaligned two-byte object, and so on. Any of the hooks may be 582690075Sobrien@code{NULL}, indicating that no suitable directive is available. 582790075Sobrien 582890075SobrienThe compiler will print these strings at the start of a new line, 582990075Sobrienfollowed immediately by the object's initial value. In most cases, 583090075Sobrienthe string should contain a tab, a pseudo-op, and then another tab. 583190075Sobrien@end deftypevr 583290075Sobrien 583390075Sobrien@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 583490075SobrienThe @code{assemble_integer} function uses this hook to output an 583590075Sobrieninteger object. @var{x} is the object's value, @var{size} is its size 583690075Sobrienin bytes and @var{aligned_p} indicates whether it is aligned. The 583790075Sobrienfunction should return @code{true} if it was able to output the 583890075Sobrienobject. If it returns false, @code{assemble_integer} will try to 583990075Sobriensplit the object into smaller parts. 584090075Sobrien 584190075SobrienThe default implementation of this hook will use the 584290075Sobrien@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 584390075Sobrienwhen the relevant string is @code{NULL}. 584490075Sobrien@end deftypefn 584590075Sobrien 584690075Sobrien@table @code 584790075Sobrien@findex OUTPUT_ADDR_CONST_EXTRA 584890075Sobrien@item OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) 584990075SobrienA C statement to recognize @var{rtx} patterns that 585090075Sobrien@code{output_addr_const} can't deal with, and output assembly code to 585190075Sobrien@var{stream} corresponding to the pattern @var{x}. This may be used to 585290075Sobrienallow machine-dependent @code{UNSPEC}s to appear within constants. 585390075Sobrien 585490075SobrienIf @code{OUTPUT_ADDR_CONST_EXTRA} fails to recognize a pattern, it must 585590075Sobrien@code{goto fail}, so that a standard error message is printed. If it 585690075Sobrienprints an error message itself, by calling, for example, 585790075Sobrien@code{output_operand_lossage}, it may just complete normally. 585890075Sobrien 585990075Sobrien@findex ASM_OUTPUT_ASCII 586090075Sobrien@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 586190075SobrienA C statement to output to the stdio stream @var{stream} an assembler 586290075Sobrieninstruction to assemble a string constant containing the @var{len} 586390075Sobrienbytes at @var{ptr}. @var{ptr} will be a C expression of type 586490075Sobrien@code{char *} and @var{len} a C expression of type @code{int}. 586590075Sobrien 586690075SobrienIf the assembler has a @code{.ascii} pseudo-op as found in the 586790075SobrienBerkeley Unix assembler, do not define the macro 586890075Sobrien@code{ASM_OUTPUT_ASCII}. 586990075Sobrien 587090075Sobrien@findex ASM_OUTPUT_FDESC 587190075Sobrien@item ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 587290075SobrienA C statement to output word @var{n} of a function descriptor for 587390075Sobrien@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 587490075Sobrienis defined, and is otherwise unused. 587590075Sobrien 587690075Sobrien@findex CONSTANT_POOL_BEFORE_FUNCTION 587790075Sobrien@item CONSTANT_POOL_BEFORE_FUNCTION 587890075SobrienYou may define this macro as a C expression. You should define the 587990075Sobrienexpression to have a nonzero value if GCC should output the constant 588090075Sobrienpool for a function before the code for the function, or a zero value if 588190075SobrienGCC should output the constant pool after the function. If you do 588290075Sobriennot define this macro, the usual case, GCC will output the constant 588390075Sobrienpool before the function. 588490075Sobrien 588590075Sobrien@findex ASM_OUTPUT_POOL_PROLOGUE 588690075Sobrien@item ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 588790075SobrienA C statement to output assembler commands to define the start of the 588890075Sobrienconstant pool for a function. @var{funname} is a string giving 588990075Sobrienthe name of the function. Should the return type of the function 589090075Sobrienbe required, it can be obtained via @var{fundecl}. @var{size} 589190075Sobrienis the size, in bytes, of the constant pool that will be written 589290075Sobrienimmediately after this call. 589390075Sobrien 589490075SobrienIf no constant-pool prefix is required, the usual case, this macro need 589590075Sobriennot be defined. 589690075Sobrien 589790075Sobrien@findex ASM_OUTPUT_SPECIAL_POOL_ENTRY 589890075Sobrien@item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 589990075SobrienA C statement (with or without semicolon) to output a constant in the 590090075Sobrienconstant pool, if it needs special treatment. (This macro need not do 590190075Sobrienanything for RTL expressions that can be output normally.) 590290075Sobrien 590390075SobrienThe argument @var{file} is the standard I/O stream to output the 590490075Sobrienassembler code on. @var{x} is the RTL expression for the constant to 590590075Sobrienoutput, and @var{mode} is the machine mode (in case @var{x} is a 590690075Sobrien@samp{const_int}). @var{align} is the required alignment for the value 590790075Sobrien@var{x}; you should output an assembler directive to force this much 590890075Sobrienalignment. 590990075Sobrien 591090075SobrienThe argument @var{labelno} is a number to use in an internal label for 591190075Sobrienthe address of this pool entry. The definition of this macro is 591290075Sobrienresponsible for outputting the label definition at the proper place. 591390075SobrienHere is how to do this: 591490075Sobrien 591590075Sobrien@example 591690075SobrienASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno}); 591790075Sobrien@end example 591890075Sobrien 591990075SobrienWhen you output a pool entry specially, you should end with a 592090075Sobrien@code{goto} to the label @var{jumpto}. This will prevent the same pool 592190075Sobrienentry from being output a second time in the usual manner. 592290075Sobrien 592390075SobrienYou need not define this macro if it would do nothing. 592490075Sobrien 592590075Sobrien@findex CONSTANT_AFTER_FUNCTION_P 592690075Sobrien@item CONSTANT_AFTER_FUNCTION_P (@var{exp}) 592790075SobrienDefine this macro as a C expression which is nonzero if the constant 592890075Sobrien@var{exp}, of type @code{tree}, should be output after the code for a 592990075Sobrienfunction. The compiler will normally output all constants before the 593090075Sobrienfunction; you need not define this macro if this is OK@. 593190075Sobrien 593290075Sobrien@findex ASM_OUTPUT_POOL_EPILOGUE 593390075Sobrien@item ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 593490075SobrienA C statement to output assembler commands to at the end of the constant 593590075Sobrienpool for a function. @var{funname} is a string giving the name of the 593690075Sobrienfunction. Should the return type of the function be required, you can 593790075Sobrienobtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 593890075Sobrienconstant pool that GCC wrote immediately before this call. 593990075Sobrien 594090075SobrienIf no constant-pool epilogue is required, the usual case, you need not 594190075Sobriendefine this macro. 594290075Sobrien 594390075Sobrien@findex IS_ASM_LOGICAL_LINE_SEPARATOR 594490075Sobrien@item IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) 594590075SobrienDefine this macro as a C expression which is nonzero if @var{C} is 594690075Sobrienused as a logical line separator by the assembler. 594790075Sobrien 594890075SobrienIf you do not define this macro, the default is that only 594990075Sobrienthe character @samp{;} is treated as a logical line separator. 595090075Sobrien@end table 595190075Sobrien 595290075Sobrien@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 595390075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 595490075SobrienThese target hooks are C string constants, describing the syntax in the 595590075Sobrienassembler for grouping arithmetic expressions. If not overridden, they 595690075Sobriendefault to normal parentheses, which is correct for most assemblers. 595790075Sobrien@end deftypevr 595890075Sobrien 595990075Sobrien These macros are provided by @file{real.h} for writing the definitions 596090075Sobrienof @code{ASM_OUTPUT_DOUBLE} and the like: 596190075Sobrien 596290075Sobrien@table @code 596390075Sobrien@item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 596490075Sobrien@itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 596590075Sobrien@itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 596690075Sobrien@findex REAL_VALUE_TO_TARGET_SINGLE 596790075Sobrien@findex REAL_VALUE_TO_TARGET_DOUBLE 596890075Sobrien@findex REAL_VALUE_TO_TARGET_LONG_DOUBLE 596990075SobrienThese translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's 597090075Sobrienfloating point representation, and store its bit pattern in the array of 597190075Sobrien@code{long int} whose address is @var{l}. The number of elements in the 597290075Sobrienoutput array is determined by the size of the desired target floating 597390075Sobrienpoint data type: 32 bits of it go in each @code{long int} array 597490075Sobrienelement. Each array element holds 32 bits of the result, even if 597590075Sobrien@code{long int} is wider than 32 bits on the host machine. 597690075Sobrien 597790075SobrienThe array element values are designed so that you can print them out 597890075Sobrienusing @code{fprintf} in the order they should appear in the target 597990075Sobrienmachine's memory. 598090075Sobrien 598190075Sobrien@item REAL_VALUE_TO_DECIMAL (@var{x}, @var{format}, @var{string}) 598290075Sobrien@findex REAL_VALUE_TO_DECIMAL 598390075SobrienThis macro converts @var{x}, of type @code{REAL_VALUE_TYPE}, to a 598490075Sobriendecimal number and stores it as a string into @var{string}. 598590075SobrienYou must pass, as @var{string}, the address of a long enough block 598690075Sobrienof space to hold the result. 598790075Sobrien 598890075SobrienThe argument @var{format} is a @code{printf}-specification that serves 598990075Sobrienas a suggestion for how to format the output string. 599090075Sobrien@end table 599190075Sobrien 599290075Sobrien@node Uninitialized Data 599390075Sobrien@subsection Output of Uninitialized Variables 599490075Sobrien 599590075SobrienEach of the macros in this section is used to do the whole job of 599690075Sobrienoutputting a single uninitialized variable. 599790075Sobrien 599890075Sobrien@table @code 599990075Sobrien@findex ASM_OUTPUT_COMMON 600090075Sobrien@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 600190075SobrienA C statement (sans semicolon) to output to the stdio stream 600290075Sobrien@var{stream} the assembler definition of a common-label named 600390075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 600490075Sobrienis the size rounded up to whatever alignment the caller wants. 600590075Sobrien 600690075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 600790075Sobrienoutput the name itself; before and after that, output the additional 600890075Sobrienassembler syntax for defining the name, and a newline. 600990075Sobrien 601090075SobrienThis macro controls how the assembler definitions of uninitialized 601190075Sobriencommon global variables are output. 601290075Sobrien 601390075Sobrien@findex ASM_OUTPUT_ALIGNED_COMMON 601490075Sobrien@item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 601590075SobrienLike @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 601690075Sobrienseparate, explicit argument. If you define this macro, it is used in 601790075Sobrienplace of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 601890075Sobrienhandling the required alignment of the variable. The alignment is specified 601990075Sobrienas the number of bits. 602090075Sobrien 602190075Sobrien@findex ASM_OUTPUT_ALIGNED_DECL_COMMON 602290075Sobrien@item ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 602390075SobrienLike @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 602490075Sobrienvariable to be output, if there is one, or @code{NULL_TREE} if there 602590075Sobrienis no corresponding variable. If you define this macro, GCC will use it 602690075Sobrienin place of both @code{ASM_OUTPUT_COMMON} and 602790075Sobrien@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 602890075Sobrienthe variable's decl in order to chose what to output. 602990075Sobrien 603090075Sobrien@findex ASM_OUTPUT_SHARED_COMMON 603190075Sobrien@item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 603290075SobrienIf defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it 603390075Sobrienis used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON} 603490075Sobrienwill be used. 603590075Sobrien 603690075Sobrien@findex ASM_OUTPUT_BSS 603790075Sobrien@item ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 603890075SobrienA C statement (sans semicolon) to output to the stdio stream 603990075Sobrien@var{stream} the assembler definition of uninitialized global @var{decl} named 604090075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 604190075Sobrienis the size rounded up to whatever alignment the caller wants. 604290075Sobrien 604390075SobrienTry to use function @code{asm_output_bss} defined in @file{varasm.c} when 604490075Sobriendefining this macro. If unable, use the expression 604590075Sobrien@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 604690075Sobrienbefore and after that, output the additional assembler syntax for defining 604790075Sobrienthe name, and a newline. 604890075Sobrien 604990075SobrienThis macro controls how the assembler definitions of uninitialized global 605090075Sobrienvariables are output. This macro exists to properly support languages like 605190075SobrienC++ which do not have @code{common} data. However, this macro currently 605290075Sobrienis not defined for all targets. If this macro and 605390075Sobrien@code{ASM_OUTPUT_ALIGNED_BSS} are not defined then @code{ASM_OUTPUT_COMMON} 605490075Sobrienor @code{ASM_OUTPUT_ALIGNED_COMMON} or 605590075Sobrien@code{ASM_OUTPUT_ALIGNED_DECL_COMMON} is used. 605690075Sobrien 605790075Sobrien@findex ASM_OUTPUT_ALIGNED_BSS 605890075Sobrien@item ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 605990075SobrienLike @code{ASM_OUTPUT_BSS} except takes the required alignment as a 606090075Sobrienseparate, explicit argument. If you define this macro, it is used in 606190075Sobrienplace of @code{ASM_OUTPUT_BSS}, and gives you more flexibility in 606290075Sobrienhandling the required alignment of the variable. The alignment is specified 606390075Sobrienas the number of bits. 606490075Sobrien 606590075SobrienTry to use function @code{asm_output_aligned_bss} defined in file 606690075Sobrien@file{varasm.c} when defining this macro. 606790075Sobrien 606890075Sobrien@findex ASM_OUTPUT_SHARED_BSS 606990075Sobrien@item ASM_OUTPUT_SHARED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 607090075SobrienIf defined, it is similar to @code{ASM_OUTPUT_BSS}, except that it 607190075Sobrienis used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_BSS} 607290075Sobrienwill be used. 607390075Sobrien 607490075Sobrien@findex ASM_OUTPUT_LOCAL 607590075Sobrien@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 607690075SobrienA C statement (sans semicolon) to output to the stdio stream 607790075Sobrien@var{stream} the assembler definition of a local-common-label named 607890075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 607990075Sobrienis the size rounded up to whatever alignment the caller wants. 608090075Sobrien 608190075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 608290075Sobrienoutput the name itself; before and after that, output the additional 608390075Sobrienassembler syntax for defining the name, and a newline. 608490075Sobrien 608590075SobrienThis macro controls how the assembler definitions of uninitialized 608690075Sobrienstatic variables are output. 608790075Sobrien 608890075Sobrien@findex ASM_OUTPUT_ALIGNED_LOCAL 608990075Sobrien@item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 609090075SobrienLike @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 609190075Sobrienseparate, explicit argument. If you define this macro, it is used in 609290075Sobrienplace of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 609390075Sobrienhandling the required alignment of the variable. The alignment is specified 609490075Sobrienas the number of bits. 609590075Sobrien 609690075Sobrien@findex ASM_OUTPUT_ALIGNED_DECL_LOCAL 609790075Sobrien@item ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 609890075SobrienLike @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 609990075Sobrienvariable to be output, if there is one, or @code{NULL_TREE} if there 610090075Sobrienis no corresponding variable. If you define this macro, GCC will use it 610190075Sobrienin place of both @code{ASM_OUTPUT_DECL} and 610290075Sobrien@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 610390075Sobrienthe variable's decl in order to chose what to output. 610490075Sobrien 610590075Sobrien@findex ASM_OUTPUT_SHARED_LOCAL 610690075Sobrien@item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 610790075SobrienIf defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it 610890075Sobrienis used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL} 610990075Sobrienwill be used. 611090075Sobrien@end table 611190075Sobrien 611290075Sobrien@node Label Output 611390075Sobrien@subsection Output and Generation of Labels 611490075Sobrien 611590075Sobrien@c prevent bad page break with this line 611690075SobrienThis is about outputting labels. 611790075Sobrien 611890075Sobrien@table @code 611990075Sobrien@findex ASM_OUTPUT_LABEL 612090075Sobrien@findex assemble_name 612190075Sobrien@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 612290075SobrienA C statement (sans semicolon) to output to the stdio stream 612390075Sobrien@var{stream} the assembler definition of a label named @var{name}. 612490075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 612590075Sobrienoutput the name itself; before and after that, output the additional 612690075Sobrienassembler syntax for defining the name, and a newline. 612790075Sobrien 612890075Sobrien@findex ASM_DECLARE_FUNCTION_NAME 612990075Sobrien@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 613090075SobrienA C statement (sans semicolon) to output to the stdio stream 613190075Sobrien@var{stream} any text necessary for declaring the name @var{name} of a 613290075Sobrienfunction which is being defined. This macro is responsible for 613390075Sobrienoutputting the label definition (perhaps using 613490075Sobrien@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the 613590075Sobrien@code{FUNCTION_DECL} tree node representing the function. 613690075Sobrien 613790075SobrienIf this macro is not defined, then the function name is defined in the 613890075Sobrienusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 613990075Sobrien 614090075Sobrien@findex ASM_DECLARE_FUNCTION_SIZE 614190075Sobrien@item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 614290075SobrienA C statement (sans semicolon) to output to the stdio stream 614390075Sobrien@var{stream} any text necessary for declaring the size of a function 614490075Sobrienwhich is being defined. The argument @var{name} is the name of the 614590075Sobrienfunction. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 614690075Sobrienrepresenting the function. 614790075Sobrien 614890075SobrienIf this macro is not defined, then the function size is not defined. 614990075Sobrien 615090075Sobrien@findex ASM_DECLARE_OBJECT_NAME 615190075Sobrien@item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 615290075SobrienA C statement (sans semicolon) to output to the stdio stream 615390075Sobrien@var{stream} any text necessary for declaring the name @var{name} of an 615490075Sobrieninitialized variable which is being defined. This macro must output the 615590075Sobrienlabel definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 615690075Sobrien@var{decl} is the @code{VAR_DECL} tree node representing the variable. 615790075Sobrien 615890075SobrienIf this macro is not defined, then the variable name is defined in the 615990075Sobrienusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 616090075Sobrien 616190075Sobrien@findex ASM_DECLARE_REGISTER_GLOBAL 616290075Sobrien@item ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 616390075SobrienA C statement (sans semicolon) to output to the stdio stream 616490075Sobrien@var{stream} any text necessary for claiming a register @var{regno} 616590075Sobrienfor a global variable @var{decl} with name @var{name}. 616690075Sobrien 616790075SobrienIf you don't define this macro, that is equivalent to defining it to do 616890075Sobriennothing. 616990075Sobrien 617090075Sobrien@findex ASM_FINISH_DECLARE_OBJECT 617190075Sobrien@item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 617290075SobrienA C statement (sans semicolon) to finish up declaring a variable name 617390075Sobrienonce the compiler has processed its initializer fully and thus has had a 617490075Sobrienchance to determine the size of an array when controlled by an 617590075Sobrieninitializer. This is used on systems where it's necessary to declare 617690075Sobriensomething about the size of the object. 617790075Sobrien 617890075SobrienIf you don't define this macro, that is equivalent to defining it to do 617990075Sobriennothing. 618090075Sobrien 618190075Sobrien@findex ASM_GLOBALIZE_LABEL 618290075Sobrien@item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name}) 618390075SobrienA C statement (sans semicolon) to output to the stdio stream 618490075Sobrien@var{stream} some commands that will make the label @var{name} global; 618590075Sobrienthat is, available for reference from other files. Use the expression 618690075Sobrien@code{assemble_name (@var{stream}, @var{name})} to output the name 618790075Sobrienitself; before and after that, output the additional assembler syntax 618890075Sobrienfor making that name global, and a newline. 618990075Sobrien 619090075Sobrien@findex ASM_WEAKEN_LABEL 619196263Sobrien@item ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 619290075SobrienA C statement (sans semicolon) to output to the stdio stream 619390075Sobrien@var{stream} some commands that will make the label @var{name} weak; 619490075Sobrienthat is, available for reference from other files but only used if 619590075Sobrienno other definition is available. Use the expression 619690075Sobrien@code{assemble_name (@var{stream}, @var{name})} to output the name 619790075Sobrienitself; before and after that, output the additional assembler syntax 619890075Sobrienfor making that name weak, and a newline. 619990075Sobrien 620096263SobrienIf you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 620196263Sobriensupport weak symbols and you should not define the @code{SUPPORTS_WEAK} 620296263Sobrienmacro. 620390075Sobrien 620496263Sobrien@findex ASM_WEAKEN_DECL 620596263Sobrien@item ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 620696263SobrienCombines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 620796263Sobrien@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 620896263Sobrienor variable decl. If @var{value} is not @code{NULL}, this C statement 620996263Sobrienshould output to the stdio stream @var{stream} assembler code which 621096263Sobriendefines (equates) the weak symbol @var{name} to have the value 621196263Sobrien@var{value}. If @var{value} is @code{NULL}, it should output commands 621296263Sobriento make @var{name} weak. 621396263Sobrien 621490075Sobrien@findex SUPPORTS_WEAK 621590075Sobrien@item SUPPORTS_WEAK 621690075SobrienA C expression which evaluates to true if the target supports weak symbols. 621790075Sobrien 621890075SobrienIf you don't define this macro, @file{defaults.h} provides a default 621996263Sobriendefinition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 622096263Sobrienis defined, the default definition is @samp{1}; otherwise, it is 622196263Sobrien@samp{0}. Define this macro if you want to control weak symbol support 622296263Sobrienwith a compiler flag such as @option{-melf}. 622390075Sobrien 622490075Sobrien@findex MAKE_DECL_ONE_ONLY (@var{decl}) 622590075Sobrien@item MAKE_DECL_ONE_ONLY 622690075SobrienA C statement (sans semicolon) to mark @var{decl} to be emitted as a 622790075Sobrienpublic symbol such that extra copies in multiple translation units will 622890075Sobrienbe discarded by the linker. Define this macro if your object file 622990075Sobrienformat provides support for this concept, such as the @samp{COMDAT} 623090075Sobriensection flags in the Microsoft Windows PE/COFF format, and this support 623190075Sobrienrequires changes to @var{decl}, such as putting it in a separate section. 623290075Sobrien 623390075Sobrien@findex SUPPORTS_ONE_ONLY 623490075Sobrien@item SUPPORTS_ONE_ONLY 623590075SobrienA C expression which evaluates to true if the target supports one-only 623690075Sobriensemantics. 623790075Sobrien 623890075SobrienIf you don't define this macro, @file{varasm.c} provides a default 623990075Sobriendefinition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 624090075Sobriendefinition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 624190075Sobrienyou want to control one-only symbol support with a compiler flag, or if 624290075Sobriensetting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 624390075Sobrienbe emitted as one-only. 624490075Sobrien 624590075Sobrien@findex ASM_OUTPUT_EXTERNAL 624690075Sobrien@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 624790075SobrienA C statement (sans semicolon) to output to the stdio stream 624890075Sobrien@var{stream} any text necessary for declaring the name of an external 624990075Sobriensymbol named @var{name} which is referenced in this compilation but 625090075Sobriennot defined. The value of @var{decl} is the tree node for the 625190075Sobriendeclaration. 625290075Sobrien 625390075SobrienThis macro need not be defined if it does not need to output anything. 625490075SobrienThe GNU assembler and most Unix assemblers don't require anything. 625590075Sobrien 625690075Sobrien@findex ASM_OUTPUT_EXTERNAL_LIBCALL 625790075Sobrien@item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) 625890075SobrienA C statement (sans semicolon) to output on @var{stream} an assembler 625990075Sobrienpseudo-op to declare a library function name external. The name of the 626090075Sobrienlibrary function is given by @var{symref}, which has type @code{rtx} and 626190075Sobrienis a @code{symbol_ref}. 626290075Sobrien 626390075SobrienThis macro need not be defined if it does not need to output anything. 626490075SobrienThe GNU assembler and most Unix assemblers don't require anything. 626590075Sobrien 626690075Sobrien@findex ASM_OUTPUT_LABELREF 626790075Sobrien@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 626890075SobrienA C statement (sans semicolon) to output to the stdio stream 626990075Sobrien@var{stream} a reference in assembler syntax to a label named 627090075Sobrien@var{name}. This should add @samp{_} to the front of the name, if that 627190075Sobrienis customary on your operating system, as it is in most Berkeley Unix 627290075Sobriensystems. This macro is used in @code{assemble_name}. 627390075Sobrien 627490075Sobrien@findex ASM_OUTPUT_SYMBOL_REF 627590075Sobrien@item ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 627690075SobrienA C statement (sans semicolon) to output a reference to 627790075Sobrien@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 627890075Sobrienwill be used to output the name of the symbol. This macro may be used 627990075Sobriento modify the way a symbol is referenced depending on information 628090075Sobrienencoded by @code{ENCODE_SECTION_INFO}. 628190075Sobrien 628290075Sobrien@findex ASM_OUTPUT_LABEL_REF 628390075Sobrien@item ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 628490075SobrienA C statement (sans semicolon) to output a reference to @var{buf}, the 628590075Sobrienresult of ASM_GENERATE_INTERNAL_LABEL. If not defined, 628690075Sobrien@code{assemble_name} will be used to output the name of the symbol. 628790075SobrienThis macro is not used by @code{output_asm_label}, or the @code{%l} 628890075Sobrienspecifier that calls it; the intention is that this macro should be set 628990075Sobrienwhen it is necessary to output a label differently when its address 629090075Sobrienis being taken. 629190075Sobrien 629290075Sobrien@findex ASM_OUTPUT_INTERNAL_LABEL 629390075Sobrien@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) 629490075SobrienA C statement to output to the stdio stream @var{stream} a label whose 629590075Sobrienname is made from the string @var{prefix} and the number @var{num}. 629690075Sobrien 629790075SobrienIt is absolutely essential that these labels be distinct from the labels 629890075Sobrienused for user-level functions and variables. Otherwise, certain programs 629990075Sobrienwill have name conflicts with internal labels. 630090075Sobrien 630190075SobrienIt is desirable to exclude internal labels from the symbol table of the 630290075Sobrienobject file. Most assemblers have a naming convention for labels that 630390075Sobrienshould be excluded; on many systems, the letter @samp{L} at the 630490075Sobrienbeginning of a label has this effect. You should find out what 630590075Sobrienconvention your system uses, and follow it. 630690075Sobrien 630790075SobrienThe usual definition of this macro is as follows: 630890075Sobrien 630990075Sobrien@example 631090075Sobrienfprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) 631190075Sobrien@end example 631290075Sobrien 631390075Sobrien@findex ASM_OUTPUT_DEBUG_LABEL 631490075Sobrien@item ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 631590075SobrienA C statement to output to the stdio stream @var{stream} a debug info 631690075Sobrienlabel whose name is made from the string @var{prefix} and the number 631790075Sobrien@var{num}. This is useful for VLIW targets, where debug info labels 631890075Sobrienmay need to be treated differently than branch target labels. On some 631990075Sobriensystems, branch target labels must be at the beginning of instruction 632090075Sobrienbundles, but debug info labels can occur in the middle of instruction 632190075Sobrienbundles. 632290075Sobrien 632390075SobrienIf this macro is not defined, then @code{ASM_OUTPUT_INTERNAL_LABEL} will be 632490075Sobrienused. 632590075Sobrien 632690075Sobrien@findex ASM_OUTPUT_ALTERNATE_LABEL_NAME 632790075Sobrien@item ASM_OUTPUT_ALTERNATE_LABEL_NAME (@var{stream}, @var{string}) 632890075SobrienA C statement to output to the stdio stream @var{stream} the string 632990075Sobrien@var{string}. 633090075Sobrien 633190075SobrienThe default definition of this macro is as follows: 633290075Sobrien 633390075Sobrien@example 633490075Sobrienfprintf (@var{stream}, "%s:\n", LABEL_ALTERNATE_NAME (INSN)) 633590075Sobrien@end example 633690075Sobrien 633790075Sobrien@findex ASM_GENERATE_INTERNAL_LABEL 633890075Sobrien@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 633990075SobrienA C statement to store into the string @var{string} a label whose name 634090075Sobrienis made from the string @var{prefix} and the number @var{num}. 634190075Sobrien 634290075SobrienThis string, when output subsequently by @code{assemble_name}, should 634390075Sobrienproduce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce 634490075Sobrienwith the same @var{prefix} and @var{num}. 634590075Sobrien 634690075SobrienIf the string begins with @samp{*}, then @code{assemble_name} will 634790075Sobrienoutput the rest of the string unchanged. It is often convenient for 634890075Sobrien@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 634990075Sobrienstring doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 635090075Sobriento output the string, and may change it. (Of course, 635190075Sobrien@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 635290075Sobrienyou should know what it does on your machine.) 635390075Sobrien 635490075Sobrien@findex ASM_FORMAT_PRIVATE_NAME 635590075Sobrien@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 635690075SobrienA C expression to assign to @var{outvar} (which is a variable of type 635790075Sobrien@code{char *}) a newly allocated string made from the string 635890075Sobrien@var{name} and the number @var{number}, with some suitable punctuation 635990075Sobrienadded. Use @code{alloca} to get space for the string. 636090075Sobrien 636190075SobrienThe string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 636290075Sobrienproduce an assembler label for an internal static variable whose name is 636390075Sobrien@var{name}. Therefore, the string must be such as to result in valid 636490075Sobrienassembler code. The argument @var{number} is different each time this 636590075Sobrienmacro is executed; it prevents conflicts between similarly-named 636690075Sobrieninternal static variables in different scopes. 636790075Sobrien 636890075SobrienIdeally this string should not be a valid C identifier, to prevent any 636990075Sobrienconflict with the user's own symbols. Most assemblers allow periods 637090075Sobrienor percent signs in assembler symbols; putting at least one of these 637190075Sobrienbetween the name and the number will suffice. 637290075Sobrien 637390075Sobrien@findex ASM_OUTPUT_DEF 637490075Sobrien@item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 637590075SobrienA C statement to output to the stdio stream @var{stream} assembler code 637690075Sobrienwhich defines (equates) the symbol @var{name} to have the value @var{value}. 637790075Sobrien 637890075Sobrien@findex SET_ASM_OP 637990075SobrienIf @code{SET_ASM_OP} is defined, a default definition is provided which is 638090075Sobriencorrect for most systems. 638190075Sobrien 638290075Sobrien@findex ASM_OUTPUT_DEF_FROM_DECLS 638390075Sobrien@item ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 638490075SobrienA C statement to output to the stdio stream @var{stream} assembler code 638590075Sobrienwhich defines (equates) the symbol whose tree node is @var{decl_of_name} 638690075Sobriento have the value of the tree node @var{decl_of_value}. This macro will 638790075Sobrienbe used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 638890075Sobrienthe tree nodes are available. 638990075Sobrien 639090075Sobrien@findex ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL 639190075Sobrien@item ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL (@var{stream}, @var{symbol}, @var{high}, @var{low}) 639290075SobrienA C statement to output to the stdio stream @var{stream} assembler code 639390075Sobrienwhich defines (equates) the symbol @var{symbol} to have a value equal to 639490075Sobrienthe difference of the two symbols @var{high} and @var{low}, 639590075Sobrieni.e.@: @var{high} minus @var{low}. GCC guarantees that the symbols @var{high} 639690075Sobrienand @var{low} are already known by the assembler so that the difference 639790075Sobrienresolves into a constant. 639890075Sobrien 639990075Sobrien@findex SET_ASM_OP 640090075SobrienIf @code{SET_ASM_OP} is defined, a default definition is provided which is 640190075Sobriencorrect for most systems. 640290075Sobrien 640390075Sobrien@findex ASM_OUTPUT_WEAK_ALIAS 640490075Sobrien@item ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 640590075SobrienA C statement to output to the stdio stream @var{stream} assembler code 640690075Sobrienwhich defines (equates) the weak symbol @var{name} to have the value 640790075Sobrien@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 640890075Sobrienan undefined weak symbol. 640990075Sobrien 641090075SobrienDefine this macro if the target only supports weak aliases; define 641190075Sobrien@code{ASM_OUTPUT_DEF} instead if possible. 641290075Sobrien 641390075Sobrien@findex OBJC_GEN_METHOD_LABEL 641490075Sobrien@item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 641590075SobrienDefine this macro to override the default assembler names used for 641690075SobrienObjective-C methods. 641790075Sobrien 641890075SobrienThe default name is a unique method number followed by the name of the 641990075Sobrienclass (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 642090075Sobrienthe category is also included in the assembler name (e.g.@: 642190075Sobrien@samp{_1_Foo_Bar}). 642290075Sobrien 642390075SobrienThese names are safe on most systems, but make debugging difficult since 642490075Sobrienthe method's selector is not present in the name. Therefore, particular 642590075Sobriensystems define other ways of computing names. 642690075Sobrien 642790075Sobrien@var{buf} is an expression of type @code{char *} which gives you a 642890075Sobrienbuffer in which to store the name; its length is as long as 642990075Sobrien@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 643090075Sobrien50 characters extra. 643190075Sobrien 643290075SobrienThe argument @var{is_inst} specifies whether the method is an instance 643390075Sobrienmethod or a class method; @var{class_name} is the name of the class; 643490075Sobrien@var{cat_name} is the name of the category (or @code{NULL} if the method is not 643590075Sobrienin a category); and @var{sel_name} is the name of the selector. 643690075Sobrien 643790075SobrienOn systems where the assembler can handle quoted names, you can use this 643890075Sobrienmacro to provide more human-readable names. 643990075Sobrien 644090075Sobrien@findex ASM_DECLARE_CLASS_REFERENCE 644190075Sobrien@item ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) 644290075SobrienA C statement (sans semicolon) to output to the stdio stream 644390075Sobrien@var{stream} commands to declare that the label @var{name} is an 644490075SobrienObjective-C class reference. This is only needed for targets whose 644590075Sobrienlinkers have special support for NeXT-style runtimes. 644690075Sobrien 644790075Sobrien@findex ASM_DECLARE_UNRESOLVED_REFERENCE 644890075Sobrien@item ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) 644990075SobrienA C statement (sans semicolon) to output to the stdio stream 645090075Sobrien@var{stream} commands to declare that the label @var{name} is an 645190075Sobrienunresolved Objective-C class reference. This is only needed for targets 645290075Sobrienwhose linkers have special support for NeXT-style runtimes. 645390075Sobrien@end table 645490075Sobrien 645590075Sobrien@node Initialization 645690075Sobrien@subsection How Initialization Functions Are Handled 645790075Sobrien@cindex initialization routines 645890075Sobrien@cindex termination routines 645990075Sobrien@cindex constructors, output of 646090075Sobrien@cindex destructors, output of 646190075Sobrien 646290075SobrienThe compiled code for certain languages includes @dfn{constructors} 646390075Sobrien(also called @dfn{initialization routines})---functions to initialize 646490075Sobriendata in the program when the program is started. These functions need 646590075Sobriento be called before the program is ``started''---that is to say, before 646690075Sobrien@code{main} is called. 646790075Sobrien 646890075SobrienCompiling some languages generates @dfn{destructors} (also called 646990075Sobrien@dfn{termination routines}) that should be called when the program 647090075Sobrienterminates. 647190075Sobrien 647290075SobrienTo make the initialization and termination functions work, the compiler 647390075Sobrienmust output something in the assembler code to cause those functions to 647490075Sobrienbe called at the appropriate time. When you port the compiler to a new 647590075Sobriensystem, you need to specify how to do this. 647690075Sobrien 647790075SobrienThere are two major ways that GCC currently supports the execution of 647890075Sobrieninitialization and termination functions. Each way has two variants. 647990075SobrienMuch of the structure is common to all four variations. 648090075Sobrien 648190075Sobrien@findex __CTOR_LIST__ 648290075Sobrien@findex __DTOR_LIST__ 648390075SobrienThe linker must build two lists of these functions---a list of 648490075Sobrieninitialization functions, called @code{__CTOR_LIST__}, and a list of 648590075Sobrientermination functions, called @code{__DTOR_LIST__}. 648690075Sobrien 648790075SobrienEach list always begins with an ignored function pointer (which may hold 648890075Sobrien0, @minus{}1, or a count of the function pointers after it, depending on 648990075Sobrienthe environment). This is followed by a series of zero or more function 649090075Sobrienpointers to constructors (or destructors), followed by a function 649190075Sobrienpointer containing zero. 649290075Sobrien 649390075SobrienDepending on the operating system and its executable file format, either 649490075Sobrien@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 649590075Sobrientime and exit time. Constructors are called in reverse order of the 649690075Sobrienlist; destructors in forward order. 649790075Sobrien 649890075SobrienThe best way to handle static constructors works only for object file 649990075Sobrienformats which provide arbitrarily-named sections. A section is set 650090075Sobrienaside for a list of constructors, and another for a list of destructors. 650190075SobrienTraditionally these are called @samp{.ctors} and @samp{.dtors}. Each 650290075Sobrienobject file that defines an initialization function also puts a word in 650390075Sobrienthe constructor section to point to that function. The linker 650490075Sobrienaccumulates all these words into one contiguous @samp{.ctors} section. 650590075SobrienTermination functions are handled similarly. 650690075Sobrien 650790075SobrienThis method will be chosen as the default by @file{target-def.h} if 650890075Sobrien@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 650996263Sobriensupport arbitrary sections, but does support special designated 651090075Sobrienconstructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 651190075Sobrienand @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 651290075Sobrien 651390075SobrienWhen arbitrary sections are available, there are two variants, depending 651490075Sobrienupon how the code in @file{crtstuff.c} is called. On systems that 651590075Sobriensupport a @dfn{.init} section which is executed at program startup, 651690075Sobrienparts of @file{crtstuff.c} are compiled into that section. The 651790075Sobrienprogram is linked by the @code{gcc} driver like this: 651890075Sobrien 651990075Sobrien@example 652090075Sobrienld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 652190075Sobrien@end example 652290075Sobrien 652390075SobrienThe prologue of a function (@code{__init}) appears in the @code{.init} 652490075Sobriensection of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 652590075Sobrienfor the function @code{__fini} in the @dfn{.fini} section. Normally these 652690075Sobrienfiles are provided by the operating system or by the GNU C library, but 652790075Sobrienare provided by GCC for a few targets. 652890075Sobrien 652990075SobrienThe objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 653090075Sobriencompiled from @file{crtstuff.c}. They contain, among other things, code 653190075Sobrienfragments within the @code{.init} and @code{.fini} sections that branch 653290075Sobriento routines in the @code{.text} section. The linker will pull all parts 653390075Sobrienof a section together, which results in a complete @code{__init} function 653490075Sobrienthat invokes the routines we need at startup. 653590075Sobrien 653690075SobrienTo use this variant, you must define the @code{INIT_SECTION_ASM_OP} 653790075Sobrienmacro properly. 653890075Sobrien 653990075SobrienIf no init section is available, when GCC compiles any function called 654090075Sobrien@code{main} (or more accurately, any function designated as a program 654190075Sobrienentry point by the language front end calling @code{expand_main_function}), 654290075Sobrienit inserts a procedure call to @code{__main} as the first executable code 654390075Sobrienafter the function prologue. The @code{__main} function is defined 654490075Sobrienin @file{libgcc2.c} and runs the global constructors. 654590075Sobrien 654690075SobrienIn file formats that don't support arbitrary sections, there are again 654790075Sobrientwo variants. In the simplest variant, the GNU linker (GNU @code{ld}) 654890075Sobrienand an `a.out' format must be used. In this case, 654990075Sobrien@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 655090075Sobrienentry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 655190075Sobrienand with the address of the void function containing the initialization 655290075Sobriencode as its value. The GNU linker recognizes this as a request to add 655390075Sobrienthe value to a @dfn{set}; the values are accumulated, and are eventually 655490075Sobrienplaced in the executable as a vector in the format described above, with 655590075Sobriena leading (ignored) count and a trailing zero element. 655690075Sobrien@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 655790075Sobriensection is available, the absence of @code{INIT_SECTION_ASM_OP} causes 655890075Sobrienthe compilation of @code{main} to call @code{__main} as above, starting 655990075Sobrienthe initialization process. 656090075Sobrien 656190075SobrienThe last variant uses neither arbitrary sections nor the GNU linker. 656290075SobrienThis is preferable when you want to do dynamic linking and when using 656390075Sobrienfile formats which the GNU linker does not support, such as `ECOFF'@. In 656490075Sobrienthis case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 656590075Sobrientermination functions are recognized simply by their names. This requires 656690075Sobrienan extra program in the linkage step, called @command{collect2}. This program 656790075Sobrienpretends to be the linker, for use with GCC; it does its job by running 656890075Sobrienthe ordinary linker, but also arranges to include the vectors of 656990075Sobrieninitialization and termination functions. These functions are called 657090075Sobrienvia @code{__main} as described above. In order to use this method, 657190075Sobrien@code{use_collect2} must be defined in the target in @file{config.gcc}. 657290075Sobrien 657390075Sobrien@ifinfo 657490075SobrienThe following section describes the specific macros that control and 657590075Sobriencustomize the handling of initialization and termination functions. 657690075Sobrien@end ifinfo 657790075Sobrien 657890075Sobrien@node Macros for Initialization 657990075Sobrien@subsection Macros Controlling Initialization Routines 658090075Sobrien 658190075SobrienHere are the macros that control how the compiler handles initialization 658290075Sobrienand termination functions: 658390075Sobrien 658490075Sobrien@table @code 658590075Sobrien@findex INIT_SECTION_ASM_OP 658690075Sobrien@item INIT_SECTION_ASM_OP 658790075SobrienIf defined, a C string constant, including spacing, for the assembler 658890075Sobrienoperation to identify the following data as initialization code. If not 658990075Sobriendefined, GCC will assume such a section does not exist. When you are 659090075Sobrienusing special sections for initialization and termination functions, this 659190075Sobrienmacro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 659290075Sobrienrun the initialization functions. 659390075Sobrien 659490075Sobrien@item HAS_INIT_SECTION 659590075Sobrien@findex HAS_INIT_SECTION 659690075SobrienIf defined, @code{main} will not call @code{__main} as described above. 659790075SobrienThis macro should be defined for systems that control start-up code 659890075Sobrienon a symbol-by-symbol basis, such as OSF/1, and should not 659990075Sobrienbe defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 660090075Sobrien 660190075Sobrien@item LD_INIT_SWITCH 660290075Sobrien@findex LD_INIT_SWITCH 660390075SobrienIf defined, a C string constant for a switch that tells the linker that 660490075Sobrienthe following symbol is an initialization routine. 660590075Sobrien 660690075Sobrien@item LD_FINI_SWITCH 660790075Sobrien@findex LD_FINI_SWITCH 660890075SobrienIf defined, a C string constant for a switch that tells the linker that 660990075Sobrienthe following symbol is a finalization routine. 661090075Sobrien 661190075Sobrien@item COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 661290075SobrienIf defined, a C statement that will write a function that can be 661390075Sobrienautomatically called when a shared library is loaded. The function 661490075Sobrienshould call @var{func}, which takes no arguments. If not defined, and 661590075Sobrienthe object format requires an explicit initialization function, then a 661690075Sobrienfunction called @code{_GLOBAL__DI} will be generated. 661790075Sobrien 661890075SobrienThis function and the following one are used by collect2 when linking a 661996263Sobrienshared library that needs constructors or destructors, or has DWARF2 662090075Sobrienexception tables embedded in the code. 662190075Sobrien 662290075Sobrien@item COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 662390075SobrienIf defined, a C statement that will write a function that can be 662490075Sobrienautomatically called when a shared library is unloaded. The function 662590075Sobrienshould call @var{func}, which takes no arguments. If not defined, and 662690075Sobrienthe object format requires an explicit finalization function, then a 662790075Sobrienfunction called @code{_GLOBAL__DD} will be generated. 662890075Sobrien 662990075Sobrien@item INVOKE__main 663090075Sobrien@findex INVOKE__main 663190075SobrienIf defined, @code{main} will call @code{__main} despite the presence of 663290075Sobrien@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 663390075Sobrienwhere the init section is not actually run automatically, but is still 663490075Sobrienuseful for collecting the lists of constructors and destructors. 663590075Sobrien 663690075Sobrien@item SUPPORTS_INIT_PRIORITY 663790075Sobrien@findex SUPPORTS_INIT_PRIORITY 663890075SobrienIf nonzero, the C++ @code{init_priority} attribute is supported and the 663990075Sobriencompiler should emit instructions to control the order of initialization 664090075Sobrienof objects. If zero, the compiler will issue an error message upon 664190075Sobrienencountering an @code{init_priority} attribute. 664290075Sobrien@end table 664390075Sobrien 664490075Sobrien@deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS 664590075SobrienThis value is true if the target supports some ``native'' method of 664690075Sobriencollecting constructors and destructors to be run at startup and exit. 664790075SobrienIt is false if we must use @command{collect2}. 664890075Sobrien@end deftypefn 664990075Sobrien 665090075Sobrien@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 665190075SobrienIf defined, a function that outputs assembler code to arrange to call 665290075Sobrienthe function referenced by @var{symbol} at initialization time. 665390075Sobrien 665490075SobrienAssume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 665590075Sobrienno arguments and with no return value. If the target supports initialization 665690075Sobrienpriorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 665790075Sobrienotherwise it must be @code{DEFAULT_INIT_PRIORITY}. 665890075Sobrien 665990075SobrienIf this macro is not defined by the target, a suitable default will 666090075Sobrienbe chosen if (1) the target supports arbitrary section names, (2) the 666190075Sobrientarget defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 666290075Sobrienis not defined. 666390075Sobrien@end deftypefn 666490075Sobrien 666590075Sobrien@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 666690075SobrienThis is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 666790075Sobrienfunctions rather than initialization functions. 666890075Sobrien@end deftypefn 666990075Sobrien 667090075SobrienIf @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 667190075Sobriengenerated for the generated object file will have static linkage. 667290075Sobrien 667390075SobrienIf your system uses @command{collect2} as the means of processing 667490075Sobrienconstructors, then that program normally uses @command{nm} to scan 667590075Sobrienan object file for constructor functions to be called. 667690075Sobrien 667790075SobrienOn certain kinds of systems, you can define these macros to make 667890075Sobrien@command{collect2} work faster (and, in some cases, make it work at all): 667990075Sobrien 668090075Sobrien@table @code 668190075Sobrien@findex OBJECT_FORMAT_COFF 668290075Sobrien@item OBJECT_FORMAT_COFF 668390075SobrienDefine this macro if the system uses COFF (Common Object File Format) 668490075Sobrienobject files, so that @command{collect2} can assume this format and scan 668590075Sobrienobject files directly for dynamic constructor/destructor functions. 668690075Sobrien 668790075Sobrien@findex OBJECT_FORMAT_ROSE 668890075Sobrien@item OBJECT_FORMAT_ROSE 668990075SobrienDefine this macro if the system uses ROSE format object files, so that 669090075Sobrien@command{collect2} can assume this format and scan object files directly 669190075Sobrienfor dynamic constructor/destructor functions. 669290075Sobrien 669390075SobrienThese macros are effective only in a native compiler; @command{collect2} as 669490075Sobrienpart of a cross compiler always uses @command{nm} for the target machine. 669590075Sobrien 669690075Sobrien@findex REAL_NM_FILE_NAME 669790075Sobrien@item REAL_NM_FILE_NAME 669890075SobrienDefine this macro as a C string constant containing the file name to use 669990075Sobriento execute @command{nm}. The default is to search the path normally for 670090075Sobrien@command{nm}. 670190075Sobrien 670290075SobrienIf your system supports shared libraries and has a program to list the 670390075Sobriendynamic dependencies of a given library or executable, you can define 670490075Sobrienthese macros to enable support for running initialization and 670590075Sobrientermination functions in shared libraries: 670690075Sobrien 670790075Sobrien@findex LDD_SUFFIX 670890075Sobrien@item LDD_SUFFIX 670990075SobrienDefine this macro to a C string constant containing the name of the program 671090075Sobrienwhich lists dynamic dependencies, like @command{"ldd"} under SunOS 4. 671190075Sobrien 671290075Sobrien@findex PARSE_LDD_OUTPUT 671390075Sobrien@item PARSE_LDD_OUTPUT (@var{ptr}) 671490075SobrienDefine this macro to be C code that extracts filenames from the output 671590075Sobrienof the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 671690075Sobrienof type @code{char *} that points to the beginning of a line of output 671790075Sobrienfrom @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 671890075Sobriencode must advance @var{ptr} to the beginning of the filename on that 671990075Sobrienline. Otherwise, it must set @var{ptr} to @code{NULL}. 672090075Sobrien@end table 672190075Sobrien 672290075Sobrien@node Instruction Output 672390075Sobrien@subsection Output of Assembler Instructions 672490075Sobrien 672590075Sobrien@c prevent bad page break with this line 672690075SobrienThis describes assembler instruction output. 672790075Sobrien 672890075Sobrien@table @code 672990075Sobrien@findex REGISTER_NAMES 673090075Sobrien@item REGISTER_NAMES 673190075SobrienA C initializer containing the assembler's names for the machine 673290075Sobrienregisters, each one as a C string constant. This is what translates 673390075Sobrienregister numbers in the compiler into assembler language. 673490075Sobrien 673590075Sobrien@findex ADDITIONAL_REGISTER_NAMES 673690075Sobrien@item ADDITIONAL_REGISTER_NAMES 673790075SobrienIf defined, a C initializer for an array of structures containing a name 673890075Sobrienand a register number. This macro defines additional names for hard 673990075Sobrienregisters, thus allowing the @code{asm} option in declarations to refer 674090075Sobriento registers using alternate names. 674190075Sobrien 674290075Sobrien@findex ASM_OUTPUT_OPCODE 674390075Sobrien@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 674490075SobrienDefine this macro if you are using an unusual assembler that 674590075Sobrienrequires different names for the machine instructions. 674690075Sobrien 674790075SobrienThe definition is a C statement or statements which output an 674890075Sobrienassembler instruction opcode to the stdio stream @var{stream}. The 674990075Sobrienmacro-operand @var{ptr} is a variable of type @code{char *} which 675090075Sobrienpoints to the opcode name in its ``internal'' form---the form that is 675190075Sobrienwritten in the machine description. The definition should output the 675290075Sobrienopcode name to @var{stream}, performing any translation you desire, and 675390075Sobrienincrement the variable @var{ptr} to point at the end of the opcode 675490075Sobrienso that it will not be output twice. 675590075Sobrien 675690075SobrienIn fact, your macro definition may process less than the entire opcode 675790075Sobrienname, or more than the opcode name; but if you want to process text 675890075Sobrienthat includes @samp{%}-sequences to substitute operands, you must take 675990075Sobriencare of the substitution yourself. Just be sure to increment 676090075Sobrien@var{ptr} over whatever text should not be output normally. 676190075Sobrien 676290075Sobrien@findex recog_data.operand 676390075SobrienIf you need to look at the operand values, they can be found as the 676490075Sobrienelements of @code{recog_data.operand}. 676590075Sobrien 676690075SobrienIf the macro definition does nothing, the instruction is output 676790075Sobrienin the usual way. 676890075Sobrien 676990075Sobrien@findex FINAL_PRESCAN_INSN 677090075Sobrien@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 677190075SobrienIf defined, a C statement to be executed just prior to the output of 677290075Sobrienassembler code for @var{insn}, to modify the extracted operands so 677390075Sobrienthey will be output differently. 677490075Sobrien 677590075SobrienHere the argument @var{opvec} is the vector containing the operands 677690075Sobrienextracted from @var{insn}, and @var{noperands} is the number of 677790075Sobrienelements of the vector which contain meaningful data for this insn. 677890075SobrienThe contents of this vector are what will be used to convert the insn 677990075Sobrientemplate into assembler code, so you can change the assembler output 678090075Sobrienby changing the contents of the vector. 678190075Sobrien 678290075SobrienThis macro is useful when various assembler syntaxes share a single 678390075Sobrienfile of instruction patterns; by defining this macro differently, you 678490075Sobriencan cause a large class of instructions to be output differently (such 678590075Sobrienas with rearranged operands). Naturally, variations in assembler 678690075Sobriensyntax affecting individual insn patterns ought to be handled by 678790075Sobrienwriting conditional output routines in those patterns. 678890075Sobrien 678990075SobrienIf this macro is not defined, it is equivalent to a null statement. 679090075Sobrien 679190075Sobrien@findex FINAL_PRESCAN_LABEL 679290075Sobrien@item FINAL_PRESCAN_LABEL 679390075SobrienIf defined, @code{FINAL_PRESCAN_INSN} will be called on each 679490075Sobrien@code{CODE_LABEL}. In that case, @var{opvec} will be a null pointer and 679590075Sobrien@var{noperands} will be zero. 679690075Sobrien 679790075Sobrien@findex PRINT_OPERAND 679890075Sobrien@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 679990075SobrienA C compound statement to output to stdio stream @var{stream} the 680090075Sobrienassembler syntax for an instruction operand @var{x}. @var{x} is an 680190075SobrienRTL expression. 680290075Sobrien 680390075Sobrien@var{code} is a value that can be used to specify one of several ways 680490075Sobrienof printing the operand. It is used when identical operands must be 680590075Sobrienprinted differently depending on the context. @var{code} comes from 680690075Sobrienthe @samp{%} specification that was used to request printing of the 680790075Sobrienoperand. If the specification was just @samp{%@var{digit}} then 680890075Sobrien@var{code} is 0; if the specification was @samp{%@var{ltr} 680990075Sobrien@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 681090075Sobrien 681190075Sobrien@findex reg_names 681290075SobrienIf @var{x} is a register, this macro should print the register's name. 681390075SobrienThe names can be found in an array @code{reg_names} whose type is 681490075Sobrien@code{char *[]}. @code{reg_names} is initialized from 681590075Sobrien@code{REGISTER_NAMES}. 681690075Sobrien 681790075SobrienWhen the machine description has a specification @samp{%@var{punct}} 681890075Sobrien(a @samp{%} followed by a punctuation character), this macro is called 681990075Sobrienwith a null pointer for @var{x} and the punctuation character for 682090075Sobrien@var{code}. 682190075Sobrien 682290075Sobrien@findex PRINT_OPERAND_PUNCT_VALID_P 682390075Sobrien@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 682490075SobrienA C expression which evaluates to true if @var{code} is a valid 682590075Sobrienpunctuation character for use in the @code{PRINT_OPERAND} macro. If 682690075Sobrien@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 682790075Sobrienpunctuation characters (except for the standard one, @samp{%}) are used 682890075Sobrienin this way. 682990075Sobrien 683090075Sobrien@findex PRINT_OPERAND_ADDRESS 683190075Sobrien@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 683290075SobrienA C compound statement to output to stdio stream @var{stream} the 683390075Sobrienassembler syntax for an instruction operand that is a memory reference 683490075Sobrienwhose address is @var{x}. @var{x} is an RTL expression. 683590075Sobrien 683690075Sobrien@cindex @code{ENCODE_SECTION_INFO} usage 683790075SobrienOn some machines, the syntax for a symbolic address depends on the 683890075Sobriensection that the address refers to. On these machines, define the macro 683990075Sobrien@code{ENCODE_SECTION_INFO} to store the information into the 684090075Sobrien@code{symbol_ref}, and then check for it here. @xref{Assembler Format}. 684190075Sobrien 684290075Sobrien@findex DBR_OUTPUT_SEQEND 684390075Sobrien@findex dbr_sequence_length 684490075Sobrien@item DBR_OUTPUT_SEQEND(@var{file}) 684590075SobrienA C statement, to be executed after all slot-filler instructions have 684690075Sobrienbeen output. If necessary, call @code{dbr_sequence_length} to 684790075Sobriendetermine the number of slots filled in a sequence (zero if not 684890075Sobriencurrently outputting a sequence), to decide how many no-ops to output, 684990075Sobrienor whatever. 685090075Sobrien 685190075SobrienDon't define this macro if it has nothing to do, but it is helpful in 685290075Sobrienreading assembly output if the extent of the delay sequence is made 685390075Sobrienexplicit (e.g.@: with white space). 685490075Sobrien 685590075Sobrien@findex final_sequence 685690075SobrienNote that output routines for instructions with delay slots must be 685790075Sobrienprepared to deal with not being output as part of a sequence 685890075Sobrien(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 685990075Sobrienfound.) The variable @code{final_sequence} is null when not 686090075Sobrienprocessing a sequence, otherwise it contains the @code{sequence} rtx 686190075Sobrienbeing output. 686290075Sobrien 686390075Sobrien@findex REGISTER_PREFIX 686490075Sobrien@findex LOCAL_LABEL_PREFIX 686590075Sobrien@findex USER_LABEL_PREFIX 686690075Sobrien@findex IMMEDIATE_PREFIX 686790075Sobrien@findex asm_fprintf 686890075Sobrien@item REGISTER_PREFIX 686990075Sobrien@itemx LOCAL_LABEL_PREFIX 687090075Sobrien@itemx USER_LABEL_PREFIX 687190075Sobrien@itemx IMMEDIATE_PREFIX 687290075SobrienIf defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 687390075Sobrien@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 687490075Sobrien@file{final.c}). These are useful when a single @file{md} file must 687590075Sobriensupport multiple assembler formats. In that case, the various @file{tm.h} 687690075Sobrienfiles can define these macros differently. 687790075Sobrien 687890075Sobrien@item ASM_FPRINTF_EXTENSIONS(@var{file}, @var{argptr}, @var{format}) 687990075Sobrien@findex ASM_FPRINTF_EXTENSIONS 688090075SobrienIf defined this macro should expand to a series of @code{case} 688190075Sobrienstatements which will be parsed inside the @code{switch} statement of 688290075Sobrienthe @code{asm_fprintf} function. This allows targets to define extra 688390075Sobrienprintf formats which may useful when generating their assembler 688490075Sobrienstatements. Note that upper case letters are reserved for future 688590075Sobriengeneric extensions to asm_fprintf, and so are not available to target 688690075Sobrienspecific code. The output file is given by the parameter @var{file}. 688790075SobrienThe varargs input pointer is @var{argptr} and the rest of the format 688890075Sobrienstring, starting the character after the one that is being switched 688990075Sobrienupon, is pointed to by @var{format}. 689090075Sobrien 689190075Sobrien@findex ASSEMBLER_DIALECT 689290075Sobrien@item ASSEMBLER_DIALECT 689390075SobrienIf your target supports multiple dialects of assembler language (such as 689490075Sobriendifferent opcodes), define this macro as a C expression that gives the 689590075Sobriennumeric index of the assembler language dialect to use, with zero as the 689690075Sobrienfirst variant. 689790075Sobrien 689890075SobrienIf this macro is defined, you may use constructs of the form 689990075Sobrien@smallexample 690096263Sobrien@samp{@{option0|option1|option2@dots{}@}} 690190075Sobrien@end smallexample 690290075Sobrien@noindent 690390075Sobrienin the output templates of patterns (@pxref{Output Template}) or in the 690490075Sobrienfirst argument of @code{asm_fprintf}. This construct outputs 690590075Sobrien@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 690690075Sobrien@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 690790075Sobrienwithin these strings retain their usual meaning. If there are fewer 690890075Sobrienalternatives within the braces than the value of 690990075Sobrien@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 691090075Sobrien 691190075SobrienIf you do not define this macro, the characters @samp{@{}, @samp{|} and 691290075Sobrien@samp{@}} do not have any special meaning when used in templates or 691390075Sobrienoperands to @code{asm_fprintf}. 691490075Sobrien 691590075SobrienDefine the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 691690075Sobrien@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 691790075Sobrienthe variations in assembler language syntax with that mechanism. Define 691890075Sobrien@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 691990075Sobrienif the syntax variant are larger and involve such things as different 692090075Sobrienopcodes or operand order. 692190075Sobrien 692290075Sobrien@findex ASM_OUTPUT_REG_PUSH 692390075Sobrien@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 692490075SobrienA C expression to output to @var{stream} some assembler code 692590075Sobrienwhich will push hard register number @var{regno} onto the stack. 692690075SobrienThe code need not be optimal, since this macro is used only when 692790075Sobrienprofiling. 692890075Sobrien 692990075Sobrien@findex ASM_OUTPUT_REG_POP 693090075Sobrien@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 693190075SobrienA C expression to output to @var{stream} some assembler code 693290075Sobrienwhich will pop hard register number @var{regno} off of the stack. 693390075SobrienThe code need not be optimal, since this macro is used only when 693490075Sobrienprofiling. 693590075Sobrien@end table 693690075Sobrien 693790075Sobrien@node Dispatch Tables 693890075Sobrien@subsection Output of Dispatch Tables 693990075Sobrien 694090075Sobrien@c prevent bad page break with this line 694190075SobrienThis concerns dispatch tables. 694290075Sobrien 694390075Sobrien@table @code 694490075Sobrien@cindex dispatch table 694590075Sobrien@findex ASM_OUTPUT_ADDR_DIFF_ELT 694690075Sobrien@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 694790075SobrienA C statement to output to the stdio stream @var{stream} an assembler 694890075Sobrienpseudo-instruction to generate a difference between two labels. 694990075Sobrien@var{value} and @var{rel} are the numbers of two internal labels. The 695090075Sobriendefinitions of these labels are output using 695190075Sobrien@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same 695290075Sobrienway here. For example, 695390075Sobrien 695490075Sobrien@example 695590075Sobrienfprintf (@var{stream}, "\t.word L%d-L%d\n", 695690075Sobrien @var{value}, @var{rel}) 695790075Sobrien@end example 695890075Sobrien 695990075SobrienYou must provide this macro on machines where the addresses in a 696090075Sobriendispatch table are relative to the table's own address. If defined, GCC 696190075Sobrienwill also use this macro on all machines when producing PIC@. 696290075Sobrien@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 696390075Sobrienmode and flags can be read. 696490075Sobrien 696590075Sobrien@findex ASM_OUTPUT_ADDR_VEC_ELT 696690075Sobrien@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 696790075SobrienThis macro should be provided on machines where the addresses 696890075Sobrienin a dispatch table are absolute. 696990075Sobrien 697090075SobrienThe definition should be a C statement to output to the stdio stream 697190075Sobrien@var{stream} an assembler pseudo-instruction to generate a reference to 697290075Sobriena label. @var{value} is the number of an internal label whose 697390075Sobriendefinition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. 697490075SobrienFor example, 697590075Sobrien 697690075Sobrien@example 697790075Sobrienfprintf (@var{stream}, "\t.word L%d\n", @var{value}) 697890075Sobrien@end example 697990075Sobrien 698090075Sobrien@findex ASM_OUTPUT_CASE_LABEL 698190075Sobrien@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 698290075SobrienDefine this if the label before a jump-table needs to be output 698390075Sobrienspecially. The first three arguments are the same as for 698490075Sobrien@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the 698590075Sobrienjump-table which follows (a @code{jump_insn} containing an 698690075Sobrien@code{addr_vec} or @code{addr_diff_vec}). 698790075Sobrien 698890075SobrienThis feature is used on system V to output a @code{swbeg} statement 698990075Sobrienfor the table. 699090075Sobrien 699190075SobrienIf this macro is not defined, these labels are output with 699290075Sobrien@code{ASM_OUTPUT_INTERNAL_LABEL}. 699390075Sobrien 699490075Sobrien@findex ASM_OUTPUT_CASE_END 699590075Sobrien@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 699690075SobrienDefine this if something special must be output at the end of a 699790075Sobrienjump-table. The definition should be a C statement to be executed 699890075Sobrienafter the assembler code for the table is written. It should write 699990075Sobrienthe appropriate code to stdio stream @var{stream}. The argument 700090075Sobrien@var{table} is the jump-table insn, and @var{num} is the label-number 700190075Sobrienof the preceding label. 700290075Sobrien 700390075SobrienIf this macro is not defined, nothing special is output at the end of 700490075Sobrienthe jump-table. 700590075Sobrien@end table 700690075Sobrien 700790075Sobrien@node Exception Region Output 700890075Sobrien@subsection Assembler Commands for Exception Regions 700990075Sobrien 701090075Sobrien@c prevent bad page break with this line 701190075Sobrien 701290075SobrienThis describes commands marking the start and the end of an exception 701390075Sobrienregion. 701490075Sobrien 701590075Sobrien@table @code 701690075Sobrien@findex EH_FRAME_SECTION_NAME 701790075Sobrien@item EH_FRAME_SECTION_NAME 701890075SobrienIf defined, a C string constant for the name of the section containing 701990075Sobrienexception handling frame unwind information. If not defined, GCC will 702090075Sobrienprovide a default definition if the target supports named sections. 702190075Sobrien@file{crtstuff.c} uses this macro to switch to the appropriate section. 702290075Sobrien 702390075SobrienYou should define this symbol if your target supports DWARF 2 frame 702490075Sobrienunwind information and the default definition does not work. 702590075Sobrien 702690075Sobrien@findex EH_FRAME_IN_DATA_SECTION 702790075Sobrien@item EH_FRAME_IN_DATA_SECTION 702890075SobrienIf defined, DWARF 2 frame unwind information will be placed in the 702990075Sobriendata section even though the target supports named sections. This 703090075Sobrienmight be necessary, for instance, if the system linker does garbage 703190075Sobriencollection and sections cannot be marked as not to be collected. 703290075Sobrien 703390075SobrienDo not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 703490075Sobrienalso defined. 703590075Sobrien 703690075Sobrien@findex MASK_RETURN_ADDR 703790075Sobrien@item MASK_RETURN_ADDR 703890075SobrienAn rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 703990075Sobrienthat it does not contain any extraneous set bits in it. 704090075Sobrien 704190075Sobrien@findex DWARF2_UNWIND_INFO 704290075Sobrien@item DWARF2_UNWIND_INFO 704390075SobrienDefine this macro to 0 if your target supports DWARF 2 frame unwind 704490075Sobrieninformation, but it does not yet work with exception handling. 704590075SobrienOtherwise, if your target supports this information (if it defines 704690075Sobrien@samp{INCOMING_RETURN_ADDR_RTX} and either @samp{UNALIGNED_INT_ASM_OP} 704790075Sobrienor @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 704890075Sobrien1. 704990075Sobrien 705090075SobrienIf this macro is defined to 1, the DWARF 2 unwinder will be the default 705190075Sobrienexception handling mechanism; otherwise, @code{setjmp}/@code{longjmp} will be used by 705290075Sobriendefault. 705390075Sobrien 705490075SobrienIf this macro is defined to anything, the DWARF 2 unwinder will be used 705590075Sobrieninstead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case. 705690075Sobrien 705790075Sobrien@findex DWARF_CIE_DATA_ALIGNMENT 705890075Sobrien@item DWARF_CIE_DATA_ALIGNMENT 705990075SobrienThis macro need only be defined if the target might save registers in the 706090075Sobrienfunction prologue at an offset to the stack pointer that is not aligned to 706190075Sobrien@code{UNITS_PER_WORD}. The definition should be the negative minimum 706290075Sobrienalignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 706390075Sobrienminimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 706490075Sobrienthe target supports DWARF 2 frame unwind information. 706590075Sobrien 706690075Sobrien@end table 706790075Sobrien 706890075Sobrien@deftypefn {Target Hook} void TARGET_ASM_EXCEPTION_SECTION () 706990075SobrienIf defined, a function that switches to the section in which the main 707090075Sobrienexception table is to be placed (@pxref{Sections}). The default is a 707190075Sobrienfunction that switches to a section named @code{.gcc_except_table} on 707290075Sobrienmachines that support named sections via 707390075Sobrien@code{TARGET_ASM_NAMED_SECTION}, otherwise if @option{-fpic} or 707490075Sobrien@option{-fPIC} is in effect, the @code{data_section}, otherwise the 707590075Sobrien@code{readonly_data_section}. 707690075Sobrien@end deftypefn 707790075Sobrien 707890075Sobrien@deftypefn {Target Hook} void TARGET_ASM_EH_FRAME_SECTION () 707990075SobrienIf defined, a function that switches to the section in which the DWARF 2 708090075Sobrienframe unwind information to be placed (@pxref{Sections}). The default 708190075Sobrienis a function that outputs a standard GAS section directive, if 708290075Sobrien@code{EH_FRAME_SECTION_NAME} is defined, or else a data section 708390075Sobriendirective followed by a synthetic label. 708490075Sobrien@end deftypefn 708590075Sobrien 708690075Sobrien@node Alignment Output 708790075Sobrien@subsection Assembler Commands for Alignment 708890075Sobrien 708990075Sobrien@c prevent bad page break with this line 709090075SobrienThis describes commands for alignment. 709190075Sobrien 709290075Sobrien@table @code 709390075Sobrien@findex JUMP_ALIGN 709490075Sobrien@item JUMP_ALIGN (@var{label}) 709590075SobrienThe alignment (log base 2) to put in front of @var{label}, which is 709690075Sobriena common destination of jumps and has no fallthru incoming edge. 709790075Sobrien 709890075SobrienThis macro need not be defined if you don't want any special alignment 709990075Sobriento be done at such a time. Most machine descriptions do not currently 710090075Sobriendefine the macro. 710190075Sobrien 710290075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 710390075Sobriento set the variable @var{align_jumps} in the target's 710490075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 710590075Sobrienselection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 710690075Sobrien 710790075Sobrien@findex LABEL_ALIGN_AFTER_BARRIER 710890075Sobrien@item LABEL_ALIGN_AFTER_BARRIER (@var{label}) 710990075SobrienThe alignment (log base 2) to put in front of @var{label}, which follows 711090075Sobriena @code{BARRIER}. 711190075Sobrien 711290075SobrienThis macro need not be defined if you don't want any special alignment 711390075Sobriento be done at such a time. Most machine descriptions do not currently 711490075Sobriendefine the macro. 711590075Sobrien 711690075Sobrien@findex LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 711790075Sobrien@item LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 711890075SobrienThe maximum number of bytes to skip when applying 711990075Sobrien@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 712090075Sobrien@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 712190075Sobrien 712290075Sobrien@findex LOOP_ALIGN 712390075Sobrien@item LOOP_ALIGN (@var{label}) 712490075SobrienThe alignment (log base 2) to put in front of @var{label}, which follows 712590075Sobriena @code{NOTE_INSN_LOOP_BEG} note. 712690075Sobrien 712790075SobrienThis macro need not be defined if you don't want any special alignment 712890075Sobriento be done at such a time. Most machine descriptions do not currently 712990075Sobriendefine the macro. 713090075Sobrien 713190075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 713290075Sobriento set the variable @code{align_loops} in the target's 713390075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 713490075Sobrienselection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 713590075Sobrien 713690075Sobrien@findex LOOP_ALIGN_MAX_SKIP 713790075Sobrien@item LOOP_ALIGN_MAX_SKIP 713890075SobrienThe maximum number of bytes to skip when applying @code{LOOP_ALIGN}. 713990075SobrienThis works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 714090075Sobrien 714190075Sobrien@findex LABEL_ALIGN 714290075Sobrien@item LABEL_ALIGN (@var{label}) 714390075SobrienThe alignment (log base 2) to put in front of @var{label}. 714490075SobrienIf @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 714590075Sobrienthe maximum of the specified values is used. 714690075Sobrien 714790075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 714890075Sobriento set the variable @code{align_labels} in the target's 714990075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 715090075Sobrienselection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 715190075Sobrien 715290075Sobrien@findex LABEL_ALIGN_MAX_SKIP 715390075Sobrien@item LABEL_ALIGN_MAX_SKIP 715490075SobrienThe maximum number of bytes to skip when applying @code{LABEL_ALIGN}. 715590075SobrienThis works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 715690075Sobrien 715790075Sobrien@findex ASM_OUTPUT_SKIP 715890075Sobrien@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 715990075SobrienA C statement to output to the stdio stream @var{stream} an assembler 716090075Sobrieninstruction to advance the location counter by @var{nbytes} bytes. 716190075SobrienThose bytes should be zero when loaded. @var{nbytes} will be a C 716290075Sobrienexpression of type @code{int}. 716390075Sobrien 716490075Sobrien@findex ASM_NO_SKIP_IN_TEXT 716590075Sobrien@item ASM_NO_SKIP_IN_TEXT 716690075SobrienDefine this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 716790075Sobrientext section because it fails to put zeros in the bytes that are skipped. 716890075SobrienThis is true on many Unix systems, where the pseudo--op to skip bytes 716990075Sobrienproduces no-op instructions rather than zeros when used in the text 717090075Sobriensection. 717190075Sobrien 717290075Sobrien@findex ASM_OUTPUT_ALIGN 717390075Sobrien@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 717490075SobrienA C statement to output to the stdio stream @var{stream} an assembler 717590075Sobriencommand to advance the location counter to a multiple of 2 to the 717690075Sobrien@var{power} bytes. @var{power} will be a C expression of type @code{int}. 717790075Sobrien 717890075Sobrien@findex ASM_OUTPUT_MAX_SKIP_ALIGN 717990075Sobrien@item ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 718090075SobrienA C statement to output to the stdio stream @var{stream} an assembler 718190075Sobriencommand to advance the location counter to a multiple of 2 to the 718290075Sobrien@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 718390075Sobriensatisfy the alignment request. @var{power} and @var{max_skip} will be 718490075Sobriena C expression of type @code{int}. 718590075Sobrien@end table 718690075Sobrien 718790075Sobrien@need 3000 718890075Sobrien@node Debugging Info 718990075Sobrien@section Controlling Debugging Information Format 719090075Sobrien 719190075Sobrien@c prevent bad page break with this line 719290075SobrienThis describes how to specify debugging information. 719390075Sobrien 719490075Sobrien@menu 719590075Sobrien* All Debuggers:: Macros that affect all debugging formats uniformly. 719690075Sobrien* DBX Options:: Macros enabling specific options in DBX format. 719790075Sobrien* DBX Hooks:: Hook macros for varying DBX format. 719890075Sobrien* File Names and DBX:: Macros controlling output of file names in DBX format. 719990075Sobrien* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 720090075Sobrien* VMS Debug:: Macros for VMS debug format. 720190075Sobrien@end menu 720290075Sobrien 720390075Sobrien@node All Debuggers 720490075Sobrien@subsection Macros Affecting All Debugging Formats 720590075Sobrien 720690075Sobrien@c prevent bad page break with this line 720790075SobrienThese macros affect all debugging formats. 720890075Sobrien 720990075Sobrien@table @code 721090075Sobrien@findex DBX_REGISTER_NUMBER 721190075Sobrien@item DBX_REGISTER_NUMBER (@var{regno}) 721290075SobrienA C expression that returns the DBX register number for the compiler 721390075Sobrienregister number @var{regno}. In the default macro provided, the value 721490075Sobrienof this expression will be @var{regno} itself. But sometimes there are 721590075Sobriensome registers that the compiler knows about and DBX does not, or vice 721690075Sobrienversa. In such cases, some register may need to have one number in the 721790075Sobriencompiler and another for DBX@. 721890075Sobrien 721990075SobrienIf two registers have consecutive numbers inside GCC, and they can be 722090075Sobrienused as a pair to hold a multiword value, then they @emph{must} have 722190075Sobrienconsecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 722290075SobrienOtherwise, debuggers will be unable to access such a pair, because they 722390075Sobrienexpect register pairs to be consecutive in their own numbering scheme. 722490075Sobrien 722590075SobrienIf you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 722690075Sobriendoes not preserve register pairs, then what you must do instead is 722790075Sobrienredefine the actual register numbering scheme. 722890075Sobrien 722990075Sobrien@findex DEBUGGER_AUTO_OFFSET 723090075Sobrien@item DEBUGGER_AUTO_OFFSET (@var{x}) 723190075SobrienA C expression that returns the integer offset value for an automatic 723290075Sobrienvariable having address @var{x} (an RTL expression). The default 723390075Sobriencomputation assumes that @var{x} is based on the frame-pointer and 723490075Sobriengives the offset from the frame-pointer. This is required for targets 723590075Sobrienthat produce debugging output for DBX or COFF-style debugging output 723690075Sobrienfor SDB and allow the frame-pointer to be eliminated when the 723790075Sobrien@option{-g} options is used. 723890075Sobrien 723990075Sobrien@findex DEBUGGER_ARG_OFFSET 724090075Sobrien@item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 724190075SobrienA C expression that returns the integer offset value for an argument 724290075Sobrienhaving address @var{x} (an RTL expression). The nominal offset is 724390075Sobrien@var{offset}. 724490075Sobrien 724590075Sobrien@findex PREFERRED_DEBUGGING_TYPE 724690075Sobrien@item PREFERRED_DEBUGGING_TYPE 724790075SobrienA C expression that returns the type of debugging output GCC should 724890075Sobrienproduce when the user specifies just @option{-g}. Define 724990075Sobrienthis if you have arranged for GCC to support more than one format of 725090075Sobriendebugging output. Currently, the allowable values are @code{DBX_DEBUG}, 725190075Sobrien@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 725290075Sobrien@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 725390075Sobrien 725490075SobrienWhen the user specifies @option{-ggdb}, GCC normally also uses the 725590075Sobrienvalue of this macro to select the debugging output format, but with two 725690075Sobrienexceptions. If @code{DWARF2_DEBUGGING_INFO} is defined and 725790075Sobrien@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, GCC uses the 725890075Sobrienvalue @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 725990075Sobriendefined, GCC uses @code{DBX_DEBUG}. 726090075Sobrien 726190075SobrienThe value of this macro only affects the default debugging output; the 726290075Sobrienuser can always get a specific type of output by using @option{-gstabs}, 726390075Sobrien@option{-gcoff}, @option{-gdwarf-1}, @option{-gdwarf-2}, @option{-gxcoff}, 726490075Sobrienor @option{-gvms}. 726590075Sobrien@end table 726690075Sobrien 726790075Sobrien@node DBX Options 726890075Sobrien@subsection Specific Options for DBX Output 726990075Sobrien 727090075Sobrien@c prevent bad page break with this line 727190075SobrienThese are specific options for DBX output. 727290075Sobrien 727390075Sobrien@table @code 727490075Sobrien@findex DBX_DEBUGGING_INFO 727590075Sobrien@item DBX_DEBUGGING_INFO 727690075SobrienDefine this macro if GCC should produce debugging output for DBX 727790075Sobrienin response to the @option{-g} option. 727890075Sobrien 727990075Sobrien@findex XCOFF_DEBUGGING_INFO 728090075Sobrien@item XCOFF_DEBUGGING_INFO 728190075SobrienDefine this macro if GCC should produce XCOFF format debugging output 728290075Sobrienin response to the @option{-g} option. This is a variant of DBX format. 728390075Sobrien 728490075Sobrien@findex DEFAULT_GDB_EXTENSIONS 728590075Sobrien@item DEFAULT_GDB_EXTENSIONS 728690075SobrienDefine this macro to control whether GCC should by default generate 728790075SobrienGDB's extended version of DBX debugging information (assuming DBX-format 728890075Sobriendebugging information is enabled at all). If you don't define the 728990075Sobrienmacro, the default is 1: always generate the extended information 729090075Sobrienif there is any occasion to. 729190075Sobrien 729290075Sobrien@findex DEBUG_SYMS_TEXT 729390075Sobrien@item DEBUG_SYMS_TEXT 729490075SobrienDefine this macro if all @code{.stabs} commands should be output while 729590075Sobrienin the text section. 729690075Sobrien 729790075Sobrien@findex ASM_STABS_OP 729890075Sobrien@item ASM_STABS_OP 729990075SobrienA C string constant, including spacing, naming the assembler pseudo op to 730090075Sobrienuse instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 730190075SobrienIf you don't define this macro, @code{"\t.stabs\t"} is used. This macro 730290075Sobrienapplies only to DBX debugging information format. 730390075Sobrien 730490075Sobrien@findex ASM_STABD_OP 730590075Sobrien@item ASM_STABD_OP 730690075SobrienA C string constant, including spacing, naming the assembler pseudo op to 730790075Sobrienuse instead of @code{"\t.stabd\t"} to define a debugging symbol whose 730890075Sobrienvalue is the current location. If you don't define this macro, 730990075Sobrien@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 731090075Sobrieninformation format. 731190075Sobrien 731290075Sobrien@findex ASM_STABN_OP 731390075Sobrien@item ASM_STABN_OP 731490075SobrienA C string constant, including spacing, naming the assembler pseudo op to 731590075Sobrienuse instead of @code{"\t.stabn\t"} to define a debugging symbol with no 731690075Sobrienname. If you don't define this macro, @code{"\t.stabn\t"} is used. This 731790075Sobrienmacro applies only to DBX debugging information format. 731890075Sobrien 731990075Sobrien@findex DBX_NO_XREFS 732090075Sobrien@item DBX_NO_XREFS 732190075SobrienDefine this macro if DBX on your system does not support the construct 732290075Sobrien@samp{xs@var{tagname}}. On some systems, this construct is used to 732390075Sobriendescribe a forward reference to a structure named @var{tagname}. 732490075SobrienOn other systems, this construct is not supported at all. 732590075Sobrien 732690075Sobrien@findex DBX_CONTIN_LENGTH 732790075Sobrien@item DBX_CONTIN_LENGTH 732890075SobrienA symbol name in DBX-format debugging information is normally 732990075Sobriencontinued (split into two separate @code{.stabs} directives) when it 733090075Sobrienexceeds a certain length (by default, 80 characters). On some 733190075Sobrienoperating systems, DBX requires this splitting; on others, splitting 733290075Sobrienmust not be done. You can inhibit splitting by defining this macro 733390075Sobrienwith the value zero. You can override the default splitting-length by 733490075Sobriendefining this macro as an expression for the length you desire. 733590075Sobrien 733690075Sobrien@findex DBX_CONTIN_CHAR 733790075Sobrien@item DBX_CONTIN_CHAR 733890075SobrienNormally continuation is indicated by adding a @samp{\} character to 733990075Sobrienthe end of a @code{.stabs} string when a continuation follows. To use 734090075Sobriena different character instead, define this macro as a character 734190075Sobrienconstant for the character you want to use. Do not define this macro 734290075Sobrienif backslash is correct for your system. 734390075Sobrien 734490075Sobrien@findex DBX_STATIC_STAB_DATA_SECTION 734590075Sobrien@item DBX_STATIC_STAB_DATA_SECTION 734690075SobrienDefine this macro if it is necessary to go to the data section before 734790075Sobrienoutputting the @samp{.stabs} pseudo-op for a non-global static 734890075Sobrienvariable. 734990075Sobrien 735090075Sobrien@findex DBX_TYPE_DECL_STABS_CODE 735190075Sobrien@item DBX_TYPE_DECL_STABS_CODE 735290075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 735390075Sobrienfor a typedef. The default is @code{N_LSYM}. 735490075Sobrien 735590075Sobrien@findex DBX_STATIC_CONST_VAR_CODE 735690075Sobrien@item DBX_STATIC_CONST_VAR_CODE 735790075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 735890075Sobrienfor a static variable located in the text section. DBX format does not 735990075Sobrienprovide any ``right'' way to do this. The default is @code{N_FUN}. 736090075Sobrien 736190075Sobrien@findex DBX_REGPARM_STABS_CODE 736290075Sobrien@item DBX_REGPARM_STABS_CODE 736390075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 736490075Sobrienfor a parameter passed in registers. DBX format does not provide any 736590075Sobrien``right'' way to do this. The default is @code{N_RSYM}. 736690075Sobrien 736790075Sobrien@findex DBX_REGPARM_STABS_LETTER 736890075Sobrien@item DBX_REGPARM_STABS_LETTER 736990075SobrienThe letter to use in DBX symbol data to identify a symbol as a parameter 737090075Sobrienpassed in registers. DBX format does not customarily provide any way to 737190075Sobriendo this. The default is @code{'P'}. 737290075Sobrien 737390075Sobrien@findex DBX_MEMPARM_STABS_LETTER 737490075Sobrien@item DBX_MEMPARM_STABS_LETTER 737590075SobrienThe letter to use in DBX symbol data to identify a symbol as a stack 737690075Sobrienparameter. The default is @code{'p'}. 737790075Sobrien 737890075Sobrien@findex DBX_FUNCTION_FIRST 737990075Sobrien@item DBX_FUNCTION_FIRST 738090075SobrienDefine this macro if the DBX information for a function and its 738190075Sobrienarguments should precede the assembler code for the function. Normally, 738290075Sobrienin DBX format, the debugging information entirely follows the assembler 738390075Sobriencode. 738490075Sobrien 738590075Sobrien@findex DBX_LBRAC_FIRST 738690075Sobrien@item DBX_LBRAC_FIRST 738790075SobrienDefine this macro if the @code{N_LBRAC} symbol for a block should 738890075Sobrienprecede the debugging information for variables and functions defined in 738990075Sobrienthat block. Normally, in DBX format, the @code{N_LBRAC} symbol comes 739090075Sobrienfirst. 739190075Sobrien 739290075Sobrien@findex DBX_BLOCKS_FUNCTION_RELATIVE 739390075Sobrien@item DBX_BLOCKS_FUNCTION_RELATIVE 739490075SobrienDefine this macro if the value of a symbol describing the scope of a 739590075Sobrienblock (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start 739690075Sobrienof the enclosing function. Normally, GCC uses an absolute address. 739790075Sobrien 739890075Sobrien@findex DBX_USE_BINCL 739990075Sobrien@item DBX_USE_BINCL 740090075SobrienDefine this macro if GCC should generate @code{N_BINCL} and 740190075Sobrien@code{N_EINCL} stabs for included header files, as on Sun systems. This 740290075Sobrienmacro also directs GCC to output a type number as a pair of a file 740390075Sobriennumber and a type number within the file. Normally, GCC does not 740490075Sobriengenerate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 740590075Sobriennumber for a type number. 740690075Sobrien@end table 740790075Sobrien 740890075Sobrien@node DBX Hooks 740990075Sobrien@subsection Open-Ended Hooks for DBX Format 741090075Sobrien 741190075Sobrien@c prevent bad page break with this line 741290075SobrienThese are hooks for DBX format. 741390075Sobrien 741490075Sobrien@table @code 741590075Sobrien@findex DBX_OUTPUT_LBRAC 741690075Sobrien@item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 741790075SobrienDefine this macro to say how to output to @var{stream} the debugging 741890075Sobrieninformation for the start of a scope level for variable names. The 741990075Sobrienargument @var{name} is the name of an assembler symbol (for use with 742090075Sobrien@code{assemble_name}) whose value is the address where the scope begins. 742190075Sobrien 742290075Sobrien@findex DBX_OUTPUT_RBRAC 742390075Sobrien@item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 742490075SobrienLike @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 742590075Sobrien 7426103445Skan@findex DBX_OUTPUT_NFUN 7427103445Skan@item DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 7428103445SkanDefine this macro if the target machine requires special handling to 7429103445Skanoutput an @code{N_FUN} entry for the function @var{decl}. 7430103445Skan 743190075Sobrien@findex DBX_OUTPUT_ENUM 743290075Sobrien@item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) 743390075SobrienDefine this macro if the target machine requires special handling to 743490075Sobrienoutput an enumeration type. The definition should be a C statement 743590075Sobrien(sans semicolon) to output the appropriate information to @var{stream} 743690075Sobrienfor the type @var{type}. 743790075Sobrien 743890075Sobrien@findex DBX_OUTPUT_FUNCTION_END 743990075Sobrien@item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) 744090075SobrienDefine this macro if the target machine requires special output at the 744190075Sobrienend of the debugging information for a function. The definition should 744290075Sobrienbe a C statement (sans semicolon) to output the appropriate information 744390075Sobriento @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for 744490075Sobrienthe function. 744590075Sobrien 744690075Sobrien@findex DBX_OUTPUT_STANDARD_TYPES 744790075Sobrien@item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) 744890075SobrienDefine this macro if you need to control the order of output of the 744990075Sobrienstandard data types at the beginning of compilation. The argument 745090075Sobrien@var{syms} is a @code{tree} which is a chain of all the predefined 745190075Sobrienglobal symbols, including names of data types. 745290075Sobrien 745390075SobrienNormally, DBX output starts with definitions of the types for integers 745490075Sobrienand characters, followed by all the other predefined types of the 745590075Sobrienparticular language in no particular order. 745690075Sobrien 745790075SobrienOn some machines, it is necessary to output different particular types 745890075Sobrienfirst. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output 745990075Sobrienthose symbols in the necessary order. Any predefined types that you 746090075Sobriendon't explicitly output will be output afterward in no particular order. 746190075Sobrien 746290075SobrienBe careful not to define this macro so that it works only for C@. There 746390075Sobrienare no global variables to access most of the built-in types, because 746490075Sobrienanother language may have another set of types. The way to output a 746590075Sobrienparticular type is to look through @var{syms} to see if you can find it. 746690075SobrienHere is an example: 746790075Sobrien 746890075Sobrien@smallexample 746990075Sobrien@{ 747090075Sobrien tree decl; 747190075Sobrien for (decl = syms; decl; decl = TREE_CHAIN (decl)) 747290075Sobrien if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), 747390075Sobrien "long int")) 747490075Sobrien dbxout_symbol (decl); 747590075Sobrien @dots{} 747690075Sobrien@} 747790075Sobrien@end smallexample 747890075Sobrien 747990075Sobrien@noindent 748090075SobrienThis does nothing if the expected type does not exist. 748190075Sobrien 748290075SobrienSee the function @code{init_decl_processing} in @file{c-decl.c} to find 748390075Sobrienthe names to use for all the built-in C types. 748490075Sobrien 748590075SobrienHere is another way of finding a particular type: 748690075Sobrien 748790075Sobrien@c this is still overfull. --mew 10feb93 748890075Sobrien@smallexample 748990075Sobrien@{ 749090075Sobrien tree decl; 749190075Sobrien for (decl = syms; decl; decl = TREE_CHAIN (decl)) 749290075Sobrien if (TREE_CODE (decl) == TYPE_DECL 749390075Sobrien && (TREE_CODE (TREE_TYPE (decl)) 749490075Sobrien == INTEGER_CST) 749590075Sobrien && TYPE_PRECISION (TREE_TYPE (decl)) == 16 749690075Sobrien && TYPE_UNSIGNED (TREE_TYPE (decl))) 749790075Sobrien@group 749890075Sobrien /* @r{This must be @code{unsigned short}.} */ 749990075Sobrien dbxout_symbol (decl); 750090075Sobrien @dots{} 750190075Sobrien@} 750290075Sobrien@end group 750390075Sobrien@end smallexample 750490075Sobrien 750590075Sobrien@findex NO_DBX_FUNCTION_END 750690075Sobrien@item NO_DBX_FUNCTION_END 750790075SobrienSome stabs encapsulation formats (in particular ECOFF), cannot handle the 750890075Sobrien@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 750990075SobrienOn those machines, define this macro to turn this feature off without 751090075Sobriendisturbing the rest of the gdb extensions. 751190075Sobrien 751290075Sobrien@end table 751390075Sobrien 751490075Sobrien@node File Names and DBX 751590075Sobrien@subsection File Names in DBX Format 751690075Sobrien 751790075Sobrien@c prevent bad page break with this line 751890075SobrienThis describes file names in DBX format. 751990075Sobrien 752090075Sobrien@table @code 752190075Sobrien@findex DBX_WORKING_DIRECTORY 752290075Sobrien@item DBX_WORKING_DIRECTORY 752390075SobrienDefine this if DBX wants to have the current directory recorded in each 752490075Sobrienobject file. 752590075Sobrien 752690075SobrienNote that the working directory is always recorded if GDB extensions are 752790075Sobrienenabled. 752890075Sobrien 752990075Sobrien@findex DBX_OUTPUT_MAIN_SOURCE_FILENAME 753090075Sobrien@item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 753190075SobrienA C statement to output DBX debugging information to the stdio stream 753290075Sobrien@var{stream} which indicates that file @var{name} is the main source 753390075Sobrienfile---the file specified as the input file for compilation. 753490075SobrienThis macro is called only once, at the beginning of compilation. 753590075Sobrien 753690075SobrienThis macro need not be defined if the standard form of output 753790075Sobrienfor DBX debugging information is appropriate. 753890075Sobrien 753990075Sobrien@findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY 754090075Sobrien@item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) 754190075SobrienA C statement to output DBX debugging information to the stdio stream 754290075Sobrien@var{stream} which indicates that the current directory during 754390075Sobriencompilation is named @var{name}. 754490075Sobrien 754590075SobrienThis macro need not be defined if the standard form of output 754690075Sobrienfor DBX debugging information is appropriate. 754790075Sobrien 754890075Sobrien@findex DBX_OUTPUT_MAIN_SOURCE_FILE_END 754990075Sobrien@item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 755090075SobrienA C statement to output DBX debugging information at the end of 755190075Sobriencompilation of the main source file @var{name}. 755290075Sobrien 755390075SobrienIf you don't define this macro, nothing special is output at the end 755490075Sobrienof compilation, which is correct for most machines. 755590075Sobrien 755690075Sobrien@findex DBX_OUTPUT_SOURCE_FILENAME 755790075Sobrien@item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 755890075SobrienA C statement to output DBX debugging information to the stdio stream 755990075Sobrien@var{stream} which indicates that file @var{name} is the current source 756090075Sobrienfile. This output is generated each time input shifts to a different 756190075Sobriensource file as a result of @samp{#include}, the end of an included file, 756290075Sobrienor a @samp{#line} command. 756390075Sobrien 756490075SobrienThis macro need not be defined if the standard form of output 756590075Sobrienfor DBX debugging information is appropriate. 756690075Sobrien@end table 756790075Sobrien 756890075Sobrien@need 2000 756990075Sobrien@node SDB and DWARF 757090075Sobrien@subsection Macros for SDB and DWARF Output 757190075Sobrien 757290075Sobrien@c prevent bad page break with this line 757390075SobrienHere are macros for SDB and DWARF output. 757490075Sobrien 757590075Sobrien@table @code 757690075Sobrien@findex SDB_DEBUGGING_INFO 757790075Sobrien@item SDB_DEBUGGING_INFO 757890075SobrienDefine this macro if GCC should produce COFF-style debugging output 757990075Sobrienfor SDB in response to the @option{-g} option. 758090075Sobrien 758190075Sobrien@findex DWARF_DEBUGGING_INFO 758290075Sobrien@item DWARF_DEBUGGING_INFO 758390075SobrienDefine this macro if GCC should produce dwarf format debugging output 758490075Sobrienin response to the @option{-g} option. 758590075Sobrien 758690075Sobrien@findex DWARF2_DEBUGGING_INFO 758790075Sobrien@item DWARF2_DEBUGGING_INFO 758890075SobrienDefine this macro if GCC should produce dwarf version 2 format 758990075Sobriendebugging output in response to the @option{-g} option. 759090075Sobrien 759190075SobrienTo support optional call frame debugging information, you must also 759290075Sobriendefine @code{INCOMING_RETURN_ADDR_RTX} and either set 759390075Sobrien@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 759490075Sobrienprologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 759590075Sobrienas appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 759690075Sobrien 759790075Sobrien@findex DWARF2_FRAME_INFO 759890075Sobrien@item DWARF2_FRAME_INFO 759990075SobrienDefine this macro to a nonzero value if GCC should always output 760090075SobrienDwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} 760190075Sobrien(@pxref{Exception Region Output} is nonzero, GCC will output this 760290075Sobrieninformation not matter how you define @code{DWARF2_FRAME_INFO}. 760390075Sobrien 760490075Sobrien@findex LINKER_DOES_NOT_WORK_WITH_DWARF2 760590075Sobrien@item LINKER_DOES_NOT_WORK_WITH_DWARF2 760690075SobrienDefine this macro if the linker does not work with Dwarf version 2. 760790075SobrienNormally, if the user specifies only @option{-ggdb} GCC will use Dwarf 760890075Sobrienversion 2 if available; this macro disables this. See the description 760990075Sobrienof the @code{PREFERRED_DEBUGGING_TYPE} macro for more details. 761090075Sobrien 761190075Sobrien@findex DWARF2_GENERATE_TEXT_SECTION_LABEL 761290075Sobrien@item DWARF2_GENERATE_TEXT_SECTION_LABEL 761390075SobrienBy default, the Dwarf 2 debugging information generator will generate a 761490075Sobrienlabel to mark the beginning of the text section. If it is better simply 761590075Sobriento use the name of the text section itself, rather than an explicit label, 761690075Sobriento indicate the beginning of the text section, define this macro to zero. 761790075Sobrien 761890075Sobrien@findex DWARF2_ASM_LINE_DEBUG_INFO 761990075Sobrien@item DWARF2_ASM_LINE_DEBUG_INFO 762090075SobrienDefine this macro to be a nonzero value if the assembler can generate Dwarf 2 762190075Sobrienline debug info sections. This will result in much more compact line number 762290075Sobrientables, and hence is desirable if it works. 762390075Sobrien 762490075Sobrien@findex PUT_SDB_@dots{} 762590075Sobrien@item PUT_SDB_@dots{} 762690075SobrienDefine these macros to override the assembler syntax for the special 762790075SobrienSDB assembler directives. See @file{sdbout.c} for a list of these 762890075Sobrienmacros and their arguments. If the standard syntax is used, you need 762990075Sobriennot define them yourself. 763090075Sobrien 763190075Sobrien@findex SDB_DELIM 763290075Sobrien@item SDB_DELIM 763390075SobrienSome assemblers do not support a semicolon as a delimiter, even between 763490075SobrienSDB assembler directives. In that case, define this macro to be the 763590075Sobriendelimiter to use (usually @samp{\n}). It is not necessary to define 763690075Sobriena new set of @code{PUT_SDB_@var{op}} macros if this is the only change 763790075Sobrienrequired. 763890075Sobrien 763990075Sobrien@findex SDB_GENERATE_FAKE 764090075Sobrien@item SDB_GENERATE_FAKE 764190075SobrienDefine this macro to override the usual method of constructing a dummy 764290075Sobrienname for anonymous structure and union types. See @file{sdbout.c} for 764390075Sobrienmore information. 764490075Sobrien 764590075Sobrien@findex SDB_ALLOW_UNKNOWN_REFERENCES 764690075Sobrien@item SDB_ALLOW_UNKNOWN_REFERENCES 764790075SobrienDefine this macro to allow references to unknown structure, 764890075Sobrienunion, or enumeration tags to be emitted. Standard COFF does not 764990075Sobrienallow handling of unknown references, MIPS ECOFF has support for 765090075Sobrienit. 765190075Sobrien 765290075Sobrien@findex SDB_ALLOW_FORWARD_REFERENCES 765390075Sobrien@item SDB_ALLOW_FORWARD_REFERENCES 765490075SobrienDefine this macro to allow references to structure, union, or 765590075Sobrienenumeration tags that have not yet been seen to be handled. Some 765690075Sobrienassemblers choke if forward tags are used, while some require it. 765790075Sobrien@end table 765890075Sobrien 765990075Sobrien@need 2000 766090075Sobrien@node VMS Debug 766190075Sobrien@subsection Macros for VMS Debug Format 766290075Sobrien 766390075Sobrien@c prevent bad page break with this line 766490075SobrienHere are macros for VMS debug format. 766590075Sobrien 766690075Sobrien@table @code 766790075Sobrien@findex VMS_DEBUGGING_INFO 766890075Sobrien@item VMS_DEBUGGING_INFO 766990075SobrienDefine this macro if GCC should produce debugging output for VMS 767090075Sobrienin response to the @option{-g} option. The default behavior for VMS 767190075Sobrienis to generate minimal debug info for a traceback in the absence of 767290075Sobrien@option{-g} unless explicitly overridden with @option{-g0}. This 767390075Sobrienbehavior is controlled by @code{OPTIMIZATION_OPTIONS} and 767490075Sobrien@code{OVERRIDE_OPTIONS}. 767590075Sobrien@end table 767690075Sobrien 767790075Sobrien@node Cross-compilation 767890075Sobrien@section Cross Compilation and Floating Point 767990075Sobrien@cindex cross compilation and floating point 768090075Sobrien@cindex floating point and cross compilation 768190075Sobrien 768290075SobrienWhile all modern machines use 2's complement representation for integers, 768390075Sobrienthere are a variety of representations for floating point numbers. This 768490075Sobrienmeans that in a cross-compiler the representation of floating point numbers 768590075Sobrienin the compiled program may be different from that used in the machine 768690075Sobriendoing the compilation. 768790075Sobrien 768890075Sobrien@findex atof 768990075SobrienBecause different representation systems may offer different amounts of 769090075Sobrienrange and precision, the cross compiler cannot safely use the host 769190075Sobrienmachine's floating point arithmetic. Therefore, floating point constants 769290075Sobrienmust be represented in the target machine's format. This means that the 769390075Sobriencross compiler cannot use @code{atof} to parse a floating point constant; 769490075Sobrienit must have its own special routine to use instead. Also, constant 769590075Sobrienfolding must emulate the target machine's arithmetic (or must not be done 769690075Sobrienat all). 769790075Sobrien 769890075SobrienThe macros in the following table should be defined only if you are cross 769990075Sobriencompiling between different floating point formats. 770090075Sobrien 770190075SobrienOtherwise, don't define them. Then default definitions will be set up which 770290075Sobrienuse @code{double} as the data type, @code{==} to test for equality, etc. 770390075Sobrien 770490075SobrienYou don't need to worry about how many times you use an operand of any 770590075Sobrienof these macros. The compiler never uses operands which have side effects. 770690075Sobrien 770790075Sobrien@table @code 770890075Sobrien@findex REAL_VALUE_TYPE 770990075Sobrien@item REAL_VALUE_TYPE 771090075SobrienA macro for the C data type to be used to hold a floating point value 771190075Sobrienin the target machine's format. Typically this would be a 771290075Sobrien@code{struct} containing an array of @code{int}. 771390075Sobrien 771490075Sobrien@findex REAL_VALUES_EQUAL 771590075Sobrien@item REAL_VALUES_EQUAL (@var{x}, @var{y}) 771690075SobrienA macro for a C expression which compares for equality the two values, 771790075Sobrien@var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}. 771890075Sobrien 771990075Sobrien@findex REAL_VALUES_LESS 772090075Sobrien@item REAL_VALUES_LESS (@var{x}, @var{y}) 772190075SobrienA macro for a C expression which tests whether @var{x} is less than 772290075Sobrien@var{y}, both values being of type @code{REAL_VALUE_TYPE} and 772390075Sobrieninterpreted as floating point numbers in the target machine's 772490075Sobrienrepresentation. 772590075Sobrien 772690075Sobrien@findex REAL_VALUE_LDEXP 772790075Sobrien@findex ldexp 772890075Sobrien@item REAL_VALUE_LDEXP (@var{x}, @var{scale}) 772990075SobrienA macro for a C expression which performs the standard library 773090075Sobrienfunction @code{ldexp}, but using the target machine's floating point 773190075Sobrienrepresentation. Both @var{x} and the value of the expression have 773290075Sobrientype @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an 773390075Sobrieninteger. 773490075Sobrien 773590075Sobrien@findex REAL_VALUE_FIX 773690075Sobrien@item REAL_VALUE_FIX (@var{x}) 773790075SobrienA macro whose definition is a C expression to convert the target-machine 773890075Sobrienfloating point value @var{x} to a signed integer. @var{x} has type 773990075Sobrien@code{REAL_VALUE_TYPE}. 774090075Sobrien 774190075Sobrien@findex REAL_VALUE_UNSIGNED_FIX 774290075Sobrien@item REAL_VALUE_UNSIGNED_FIX (@var{x}) 774390075SobrienA macro whose definition is a C expression to convert the target-machine 774490075Sobrienfloating point value @var{x} to an unsigned integer. @var{x} has type 774590075Sobrien@code{REAL_VALUE_TYPE}. 774690075Sobrien 774790075Sobrien@findex REAL_VALUE_RNDZINT 774890075Sobrien@item REAL_VALUE_RNDZINT (@var{x}) 774990075SobrienA macro whose definition is a C expression to round the target-machine 775090075Sobrienfloating point value @var{x} towards zero to an integer value (but still 775190075Sobrienas a floating point number). @var{x} has type @code{REAL_VALUE_TYPE}, 775290075Sobrienand so does the value. 775390075Sobrien 775490075Sobrien@findex REAL_VALUE_UNSIGNED_RNDZINT 775590075Sobrien@item REAL_VALUE_UNSIGNED_RNDZINT (@var{x}) 775690075SobrienA macro whose definition is a C expression to round the target-machine 775790075Sobrienfloating point value @var{x} towards zero to an unsigned integer value 775890075Sobrien(but still represented as a floating point number). @var{x} has type 775990075Sobrien@code{REAL_VALUE_TYPE}, and so does the value. 776090075Sobrien 776190075Sobrien@findex REAL_VALUE_ATOF 776290075Sobrien@item REAL_VALUE_ATOF (@var{string}, @var{mode}) 776390075SobrienA macro for a C expression which converts @var{string}, an expression of 776490075Sobrientype @code{char *}, into a floating point number in the target machine's 776590075Sobrienrepresentation for mode @var{mode}. The value has type 776690075Sobrien@code{REAL_VALUE_TYPE}. 776790075Sobrien 776890075Sobrien@findex REAL_INFINITY 776990075Sobrien@item REAL_INFINITY 777090075SobrienDefine this macro if infinity is a possible floating point value, and 777190075Sobrientherefore division by 0 is legitimate. 777290075Sobrien 777390075Sobrien@findex REAL_VALUE_ISINF 777490075Sobrien@findex isinf 777590075Sobrien@item REAL_VALUE_ISINF (@var{x}) 777690075SobrienA macro for a C expression which determines whether @var{x}, a floating 777790075Sobrienpoint value, is infinity. The value has type @code{int}. 777890075SobrienBy default, this is defined to call @code{isinf}. 777990075Sobrien 778090075Sobrien@findex REAL_VALUE_ISNAN 778190075Sobrien@findex isnan 778290075Sobrien@item REAL_VALUE_ISNAN (@var{x}) 778390075SobrienA macro for a C expression which determines whether @var{x}, a floating 778490075Sobrienpoint value, is a ``nan'' (not-a-number). The value has type 778590075Sobrien@code{int}. By default, this is defined to call @code{isnan}. 778690075Sobrien@end table 778790075Sobrien 778890075Sobrien@cindex constant folding and floating point 778990075SobrienDefine the following additional macros if you want to make floating 779090075Sobrienpoint constant folding work while cross compiling. If you don't 779190075Sobriendefine them, cross compilation is still possible, but constant folding 779290075Sobrienwill not happen for floating point values. 779390075Sobrien 779490075Sobrien@table @code 779590075Sobrien@findex REAL_ARITHMETIC 779690075Sobrien@item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y}) 779790075SobrienA macro for a C statement which calculates an arithmetic operation of 779890075Sobrienthe two floating point values @var{x} and @var{y}, both of type 779990075Sobrien@code{REAL_VALUE_TYPE} in the target machine's representation, to 780090075Sobrienproduce a result of the same type and representation which is stored 780190075Sobrienin @var{output} (which will be a variable). 780290075Sobrien 780390075SobrienThe operation to be performed is specified by @var{code}, a tree code 780490075Sobrienwhich will always be one of the following: @code{PLUS_EXPR}, 780590075Sobrien@code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR}, 780690075Sobrien@code{MAX_EXPR}, @code{MIN_EXPR}. 780790075Sobrien 780890075Sobrien@cindex overflow while constant folding 780990075SobrienThe expansion of this macro is responsible for checking for overflow. 781090075SobrienIf overflow happens, the macro expansion should execute the statement 781190075Sobrien@code{return 0;}, which indicates the inability to perform the 781290075Sobrienarithmetic operation requested. 781390075Sobrien 781490075Sobrien@findex REAL_VALUE_NEGATE 781590075Sobrien@item REAL_VALUE_NEGATE (@var{x}) 781690075SobrienA macro for a C expression which returns the negative of the floating 781790075Sobrienpoint value @var{x}. Both @var{x} and the value of the expression 781890075Sobrienhave type @code{REAL_VALUE_TYPE} and are in the target machine's 781990075Sobrienfloating point representation. 782090075Sobrien 782190075SobrienThere is no way for this macro to report overflow, since overflow 782290075Sobriencan't happen in the negation operation. 782390075Sobrien 782490075Sobrien@findex REAL_VALUE_TRUNCATE 782590075Sobrien@item REAL_VALUE_TRUNCATE (@var{mode}, @var{x}) 782690075SobrienA macro for a C expression which converts the floating point value 782790075Sobrien@var{x} to mode @var{mode}. 782890075Sobrien 782990075SobrienBoth @var{x} and the value of the expression are in the target machine's 783090075Sobrienfloating point representation and have type @code{REAL_VALUE_TYPE}. 783190075SobrienHowever, the value should have an appropriate bit pattern to be output 783290075Sobrienproperly as a floating constant whose precision accords with mode 783390075Sobrien@var{mode}. 783490075Sobrien 783590075SobrienThere is no way for this macro to report overflow. 783690075Sobrien 783790075Sobrien@findex REAL_VALUE_TO_INT 783890075Sobrien@item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x}) 783990075SobrienA macro for a C expression which converts a floating point value 784090075Sobrien@var{x} into a double-precision integer which is then stored into 784190075Sobrien@var{low} and @var{high}, two variables of type @var{int}. 784290075Sobrien 784390075Sobrien@item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high}, @var{mode}) 784490075Sobrien@findex REAL_VALUE_FROM_INT 784590075SobrienA macro for a C expression which converts a double-precision integer 784690075Sobrienfound in @var{low} and @var{high}, two variables of type @var{int}, 784790075Sobrieninto a floating point value which is then stored into @var{x}. 784890075SobrienThe value is in the target machine's representation for mode @var{mode} 784990075Sobrienand has the type @code{REAL_VALUE_TYPE}. 785090075Sobrien@end table 785190075Sobrien 785290075Sobrien@node Mode Switching 785390075Sobrien@section Mode Switching Instructions 785490075Sobrien@cindex mode switching 785590075SobrienThe following macros control mode switching optimizations: 785690075Sobrien 785790075Sobrien@table @code 785890075Sobrien@findex OPTIMIZE_MODE_SWITCHING 785990075Sobrien@item OPTIMIZE_MODE_SWITCHING (@var{entity}) 786090075SobrienDefine this macro if the port needs extra instructions inserted for mode 786190075Sobrienswitching in an optimizing compilation. 786290075Sobrien 786390075SobrienFor an example, the SH4 can perform both single and double precision 786490075Sobrienfloating point operations, but to perform a single precision operation, 786590075Sobrienthe FPSCR PR bit has to be cleared, while for a double precision 786690075Sobrienoperation, this bit has to be set. Changing the PR bit requires a general 786790075Sobrienpurpose register as a scratch register, hence these FPSCR sets have to 786890075Sobrienbe inserted before reload, i.e.@: you can't put this into instruction emitting 786990075Sobrienor @code{MACHINE_DEPENDENT_REORG}. 787090075Sobrien 787190075SobrienYou can have multiple entities that are mode-switched, and select at run time 787290075Sobrienwhich entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 787390075Sobrienreturn nonzero for any @var{entity} that needs mode-switching. 787490075SobrienIf you define this macro, you also have to define 787590075Sobrien@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 787690075Sobrien@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 787790075Sobrien@code{NORMAL_MODE} is optional. 787890075Sobrien 787990075Sobrien@findex NUM_MODES_FOR_MODE_SWITCHING 788090075Sobrien@item NUM_MODES_FOR_MODE_SWITCHING 788190075SobrienIf you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 788290075Sobrieninitializer for an array of integers. Each initializer element 788390075SobrienN refers to an entity that needs mode switching, and specifies the number 788490075Sobrienof different modes that might need to be set for this entity. 788590075SobrienThe position of the initializer in the initializer - starting counting at 788690075Sobrienzero - determines the integer that is used to refer to the mode-switched 788790075Sobrienentity in question. 788890075SobrienIn macros that take mode arguments / yield a mode result, modes are 788990075Sobrienrepresented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 789090075Sobrienswitch is needed / supplied. 789190075Sobrien 789290075Sobrien@findex MODE_NEEDED 789390075Sobrien@item MODE_NEEDED (@var{entity}, @var{insn}) 789490075Sobrien@var{entity} is an integer specifying a mode-switched entity. If 789590075Sobrien@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 789690075Sobrienreturn an integer value not larger than the corresponding element in 789790075Sobrien@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 789890075Sobrienbe switched into prior to the execution of @var{insn}. 789990075Sobrien 790090075Sobrien@findex NORMAL_MODE 790190075Sobrien@item NORMAL_MODE (@var{entity}) 790290075SobrienIf this macro is defined, it is evaluated for every @var{entity} that needs 790390075Sobrienmode switching. It should evaluate to an integer, which is a mode that 790490075Sobrien@var{entity} is assumed to be switched to at function entry and exit. 790590075Sobrien 790690075Sobrien@findex MODE_PRIORITY_TO_MODE 790790075Sobrien@item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 790890075SobrienThis macro specifies the order in which modes for @var{entity} are processed. 790990075Sobrien0 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 791090075Sobrienlowest. The value of the macro should be an integer designating a mode 791190075Sobrienfor @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 791290075Sobrien(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 791390075Sobrien@code{num_modes_for_mode_switching[@var{entity}] - 1}. 791490075Sobrien 791590075Sobrien@findex EMIT_MODE_SET 791690075Sobrien@item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 791790075SobrienGenerate one or more insns to set @var{entity} to @var{mode}. 791890075Sobrien@var{hard_reg_live} is the set of hard registers live at the point where 791990075Sobrienthe insn(s) are to be inserted. 792090075Sobrien@end table 792190075Sobrien 792290075Sobrien@node Target Attributes 792390075Sobrien@section Defining target-specific uses of @code{__attribute__} 792490075Sobrien@cindex target attributes 792590075Sobrien@cindex machine attributes 792690075Sobrien@cindex attributes, target-specific 792790075Sobrien 792890075SobrienTarget-specific attributes may be defined for functions, data and types. 792990075SobrienThese are described using the following target hooks; they also need to 793090075Sobrienbe documented in @file{extend.texi}. 793190075Sobrien 793290075Sobrien@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 793390075SobrienIf defined, this target hook points to an array of @samp{struct 793490075Sobrienattribute_spec} (defined in @file{tree.h}) specifying the machine 793590075Sobrienspecific attributes for this target and some of the restrictions on the 793690075Sobrienentities to which these attributes are applied and the arguments they 793790075Sobrientake. 793890075Sobrien@end deftypevr 793990075Sobrien 794090075Sobrien@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 794190075SobrienIf defined, this target hook is a function which returns zero if the attributes on 794290075Sobrien@var{type1} and @var{type2} are incompatible, one if they are compatible, 794390075Sobrienand two if they are nearly compatible (which causes a warning to be 794490075Sobriengenerated). If this is not defined, machine-specific attributes are 794590075Sobriensupposed always to be compatible. 794690075Sobrien@end deftypefn 794790075Sobrien 794890075Sobrien@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 794990075SobrienIf defined, this target hook is a function which assigns default attributes to 795090075Sobriennewly defined @var{type}. 795190075Sobrien@end deftypefn 795290075Sobrien 795390075Sobrien@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 795490075SobrienDefine this target hook if the merging of type attributes needs special 795590075Sobrienhandling. If defined, the result is a list of the combined 795690075Sobrien@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 795790075Sobrienthat @code{comptypes} has already been called and returned 1. This 795890075Sobrienfunction may call @code{merge_attributes} to handle machine-independent 795990075Sobrienmerging. 796090075Sobrien@end deftypefn 796190075Sobrien 796290075Sobrien@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 796390075SobrienDefine this target hook if the merging of decl attributes needs special 796490075Sobrienhandling. If defined, the result is a list of the combined 796590075Sobrien@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 796690075Sobrien@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 796790075Sobrienwhen this is needed are when one attribute overrides another, or when an 796890075Sobrienattribute is nullified by a subsequent definition. This function may 796990075Sobriencall @code{merge_attributes} to handle machine-independent merging. 797090075Sobrien 797190075Sobrien@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 797290075SobrienIf the only target-specific handling you require is @samp{dllimport} for 797390075SobrienWindows targets, you should define the macro 797490075Sobrien@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. This links in a function 797590075Sobriencalled @code{merge_dllimport_decl_attributes} which can then be defined 797690075Sobrienas the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. This is done 797790075Sobrienin @file{i386/cygwin.h} and @file{i386/i386.c}, for example. 797890075Sobrien@end deftypefn 797990075Sobrien 798090075Sobrien@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 798190075SobrienDefine this target hook if you want to be able to add attributes to a decl 798290075Sobrienwhen it is being created. This is normally useful for back ends which 798390075Sobrienwish to implement a pragma by using the attributes which correspond to 798490075Sobrienthe pragma's effect. The @var{node} argument is the decl which is being 798590075Sobriencreated. The @var{attr_ptr} argument is a pointer to the attribute list 798690075Sobrienfor this decl. The list itself should not be modified, since it may be 798790075Sobrienshared with other decls, but attributes may be chained on the head of 798890075Sobrienthe list and @code{*@var{attr_ptr}} modified to point to the new 798990075Sobrienattributes, or a copy of the list may be made if further changes are 799090075Sobrienneeded. 799190075Sobrien@end deftypefn 799290075Sobrien 799390075Sobrien@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree @var{fndecl}) 799490075Sobrien@cindex inlining 799590075SobrienThis target hook returns @code{true} if it is ok to inline @var{fndecl} 799690075Sobrieninto the current function, despite its having target-specific 799790075Sobrienattributes, @code{false} otherwise. By default, if a function has a 799890075Sobrientarget specific attribute attached to it, it will not be inlined. 799990075Sobrien@end deftypefn 800090075Sobrien 800190075Sobrien@node Misc 800290075Sobrien@section Miscellaneous Parameters 800390075Sobrien@cindex parameters, miscellaneous 800490075Sobrien 800590075Sobrien@c prevent bad page break with this line 800690075SobrienHere are several miscellaneous parameters. 800790075Sobrien 800890075Sobrien@table @code 800990075Sobrien@item PREDICATE_CODES 801090075Sobrien@findex PREDICATE_CODES 801190075SobrienDefine this if you have defined special-purpose predicates in the file 801290075Sobrien@file{@var{machine}.c}. This macro is called within an initializer of an 801390075Sobrienarray of structures. The first field in the structure is the name of a 801490075Sobrienpredicate and the second field is an array of rtl codes. For each 801590075Sobrienpredicate, list all rtl codes that can be in expressions matched by the 801690075Sobrienpredicate. The list should have a trailing comma. Here is an example 801790075Sobrienof two entries in the list for a typical RISC machine: 801890075Sobrien 801990075Sobrien@smallexample 802090075Sobrien#define PREDICATE_CODES \ 802190075Sobrien @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \ 802290075Sobrien @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@}, 802390075Sobrien@end smallexample 802490075Sobrien 802590075SobrienDefining this macro does not affect the generated code (however, 802690075Sobrienincorrect definitions that omit an rtl code that may be matched by the 802790075Sobrienpredicate can cause the compiler to malfunction). Instead, it allows 802890075Sobrienthe table built by @file{genrecog} to be more compact and efficient, 802990075Sobrienthus speeding up the compiler. The most important predicates to include 803090075Sobrienin the list specified by this macro are those used in the most insn 803190075Sobrienpatterns. 803290075Sobrien 803390075SobrienFor each predicate function named in @code{PREDICATE_CODES}, a 803490075Sobriendeclaration will be generated in @file{insn-codes.h}. 803590075Sobrien 803690075Sobrien@item SPECIAL_MODE_PREDICATES 803790075Sobrien@findex SPECIAL_MODE_PREDICATES 803890075SobrienDefine this if you have special predicates that know special things 803990075Sobrienabout modes. Genrecog will warn about certain forms of 804090075Sobrien@code{match_operand} without a mode; if the operand predicate is 804190075Sobrienlisted in @code{SPECIAL_MODE_PREDICATES}, the warning will be 804290075Sobriensuppressed. 804390075Sobrien 804490075SobrienHere is an example from the IA-32 port (@code{ext_register_operand} 804590075Sobrienspecially checks for @code{HImode} or @code{SImode} in preparation 804690075Sobrienfor a byte extraction from @code{%ah} etc.). 804790075Sobrien 804890075Sobrien@smallexample 804990075Sobrien#define SPECIAL_MODE_PREDICATES \ 805090075Sobrien "ext_register_operand", 805190075Sobrien@end smallexample 805290075Sobrien 805390075Sobrien@findex CASE_VECTOR_MODE 805490075Sobrien@item CASE_VECTOR_MODE 805590075SobrienAn alias for a machine mode name. This is the machine mode that 805690075Sobrienelements of a jump-table should have. 805790075Sobrien 805890075Sobrien@findex CASE_VECTOR_SHORTEN_MODE 805990075Sobrien@item CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 806090075SobrienOptional: return the preferred mode for an @code{addr_diff_vec} 806190075Sobrienwhen the minimum and maximum offset are known. If you define this, 806290075Sobrienit enables extra code in branch shortening to deal with @code{addr_diff_vec}. 806390075SobrienTo make this work, you also have to define INSN_ALIGN and 806490075Sobrienmake the alignment for @code{addr_diff_vec} explicit. 806590075SobrienThe @var{body} argument is provided so that the offset_unsigned and scale 806690075Sobrienflags can be updated. 806790075Sobrien 806890075Sobrien@findex CASE_VECTOR_PC_RELATIVE 806990075Sobrien@item CASE_VECTOR_PC_RELATIVE 807090075SobrienDefine this macro to be a C expression to indicate when jump-tables 807190075Sobrienshould contain relative addresses. If jump-tables never contain 807290075Sobrienrelative addresses, then you need not define this macro. 807390075Sobrien 807490075Sobrien@findex CASE_DROPS_THROUGH 807590075Sobrien@item CASE_DROPS_THROUGH 807690075SobrienDefine this if control falls through a @code{case} insn when the index 807790075Sobrienvalue is out of range. This means the specified default-label is 807890075Sobrienactually ignored by the @code{case} insn proper. 807990075Sobrien 808090075Sobrien@findex CASE_VALUES_THRESHOLD 808190075Sobrien@item CASE_VALUES_THRESHOLD 808290075SobrienDefine this to be the smallest number of different values for which it 808390075Sobrienis best to use a jump-table instead of a tree of conditional branches. 808490075SobrienThe default is four for machines with a @code{casesi} instruction and 808590075Sobrienfive otherwise. This is best for most machines. 808690075Sobrien 808790075Sobrien@findex WORD_REGISTER_OPERATIONS 808890075Sobrien@item WORD_REGISTER_OPERATIONS 808990075SobrienDefine this macro if operations between registers with integral mode 809090075Sobriensmaller than a word are always performed on the entire register. 809190075SobrienMost RISC machines have this property and most CISC machines do not. 809290075Sobrien 809390075Sobrien@findex LOAD_EXTEND_OP 809490075Sobrien@item LOAD_EXTEND_OP (@var{mode}) 809590075SobrienDefine this macro to be a C expression indicating when insns that read 809690075Sobrienmemory in @var{mode}, an integral mode narrower than a word, set the 809790075Sobrienbits outside of @var{mode} to be either the sign-extension or the 809890075Sobrienzero-extension of the data read. Return @code{SIGN_EXTEND} for values 809990075Sobrienof @var{mode} for which the 810090075Sobrieninsn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 810190075Sobrien@code{NIL} for other modes. 810290075Sobrien 810390075SobrienThis macro is not called with @var{mode} non-integral or with a width 810490075Sobriengreater than or equal to @code{BITS_PER_WORD}, so you may return any 810590075Sobrienvalue in this case. Do not define this macro if it would always return 810690075Sobrien@code{NIL}. On machines where this macro is defined, you will normally 810790075Sobriendefine it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 810890075Sobrien 810990075Sobrien@findex SHORT_IMMEDIATES_SIGN_EXTEND 811090075Sobrien@item SHORT_IMMEDIATES_SIGN_EXTEND 811190075SobrienDefine this macro if loading short immediate values into registers sign 811290075Sobrienextends. 811390075Sobrien 811490075Sobrien@findex FIXUNS_TRUNC_LIKE_FIX_TRUNC 811590075Sobrien@item FIXUNS_TRUNC_LIKE_FIX_TRUNC 811690075SobrienDefine this macro if the same instructions that convert a floating 811790075Sobrienpoint number to a signed fixed point number also convert validly to an 811890075Sobrienunsigned one. 811990075Sobrien 812090075Sobrien@findex MOVE_MAX 812190075Sobrien@item MOVE_MAX 812290075SobrienThe maximum number of bytes that a single instruction can move quickly 812390075Sobrienbetween memory and registers or between two memory locations. 812490075Sobrien 812590075Sobrien@findex MAX_MOVE_MAX 812690075Sobrien@item MAX_MOVE_MAX 812790075SobrienThe maximum number of bytes that a single instruction can move quickly 812890075Sobrienbetween memory and registers or between two memory locations. If this 812990075Sobrienis undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 813090075Sobrienconstant value that is the largest value that @code{MOVE_MAX} can have 813190075Sobrienat run-time. 813290075Sobrien 813390075Sobrien@findex SHIFT_COUNT_TRUNCATED 813490075Sobrien@item SHIFT_COUNT_TRUNCATED 813590075SobrienA C expression that is nonzero if on this machine the number of bits 813690075Sobrienactually used for the count of a shift operation is equal to the number 813790075Sobrienof bits needed to represent the size of the object being shifted. When 813890075Sobrienthis macro is nonzero, the compiler will assume that it is safe to omit 813990075Sobriena sign-extend, zero-extend, and certain bitwise `and' instructions that 814090075Sobrientruncates the count of a shift operation. On machines that have 814190075Sobrieninstructions that act on bit-fields at variable positions, which may 814290075Sobrieninclude `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 814390075Sobrienalso enables deletion of truncations of the values that serve as 814490075Sobrienarguments to bit-field instructions. 814590075Sobrien 814690075SobrienIf both types of instructions truncate the count (for shifts) and 814790075Sobrienposition (for bit-field operations), or if no variable-position bit-field 814890075Sobrieninstructions exist, you should define this macro. 814990075Sobrien 815090075SobrienHowever, on some machines, such as the 80386 and the 680x0, truncation 815190075Sobrienonly applies to shift operations and not the (real or pretended) 815290075Sobrienbit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 815390075Sobriensuch machines. Instead, add patterns to the @file{md} file that include 815490075Sobrienthe implied truncation of the shift instructions. 815590075Sobrien 815690075SobrienYou need not define this macro if it would always have the value of zero. 815790075Sobrien 815890075Sobrien@findex TRULY_NOOP_TRUNCATION 815990075Sobrien@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 816090075SobrienA C expression which is nonzero if on this machine it is safe to 816190075Sobrien``convert'' an integer of @var{inprec} bits to one of @var{outprec} 816290075Sobrienbits (where @var{outprec} is smaller than @var{inprec}) by merely 816390075Sobrienoperating on it as if it had only @var{outprec} bits. 816490075Sobrien 816590075SobrienOn many machines, this expression can be 1. 816690075Sobrien 816790075Sobrien@c rearranged this, removed the phrase "it is reported that". this was 816890075Sobrien@c to fix an overfull hbox. --mew 10feb93 816990075SobrienWhen @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 817090075Sobrienmodes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 817190075SobrienIf this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 817290075Sobriensuch cases may improve things. 817390075Sobrien 817490075Sobrien@findex STORE_FLAG_VALUE 817590075Sobrien@item STORE_FLAG_VALUE 817690075SobrienA C expression describing the value returned by a comparison operator 817790075Sobrienwith an integral mode and stored by a store-flag instruction 817890075Sobrien(@samp{s@var{cond}}) when the condition is true. This description must 817990075Sobrienapply to @emph{all} the @samp{s@var{cond}} patterns and all the 818090075Sobriencomparison operators whose results have a @code{MODE_INT} mode. 818190075Sobrien 818290075SobrienA value of 1 or @minus{}1 means that the instruction implementing the 818390075Sobriencomparison operator returns exactly 1 or @minus{}1 when the comparison is true 818490075Sobrienand 0 when the comparison is false. Otherwise, the value indicates 818590075Sobrienwhich bits of the result are guaranteed to be 1 when the comparison is 818690075Sobrientrue. This value is interpreted in the mode of the comparison 818790075Sobrienoperation, which is given by the mode of the first operand in the 818890075Sobrien@samp{s@var{cond}} pattern. Either the low bit or the sign bit of 818990075Sobrien@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 819090075Sobrienthe compiler. 819190075Sobrien 819290075SobrienIf @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 819390075Sobriengenerate code that depends only on the specified bits. It can also 819490075Sobrienreplace comparison operators with equivalent operations if they cause 819590075Sobrienthe required bits to be set, even if the remaining bits are undefined. 819690075SobrienFor example, on a machine whose comparison operators return an 819790075Sobrien@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 819890075Sobrien@samp{0x80000000}, saying that just the sign bit is relevant, the 819990075Sobrienexpression 820090075Sobrien 820190075Sobrien@smallexample 820290075Sobrien(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 820390075Sobrien@end smallexample 820490075Sobrien 820590075Sobrien@noindent 820690075Sobriencan be converted to 820790075Sobrien 820890075Sobrien@smallexample 820990075Sobrien(ashift:SI @var{x} (const_int @var{n})) 821090075Sobrien@end smallexample 821190075Sobrien 821290075Sobrien@noindent 821390075Sobrienwhere @var{n} is the appropriate shift count to move the bit being 821490075Sobrientested into the sign bit. 821590075Sobrien 821690075SobrienThere is no way to describe a machine that always sets the low-order bit 821790075Sobrienfor a true value, but does not guarantee the value of any other bits, 821890075Sobrienbut we do not know of any machine that has such an instruction. If you 821990075Sobrienare trying to port GCC to such a machine, include an instruction to 822090075Sobrienperform a logical-and of the result with 1 in the pattern for the 822190075Sobriencomparison operators and let us know at @email{gcc@@gcc.gnu.org}. 822290075Sobrien 822390075SobrienOften, a machine will have multiple instructions that obtain a value 822490075Sobrienfrom a comparison (or the condition codes). Here are rules to guide the 822590075Sobrienchoice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 822690075Sobriento be used: 822790075Sobrien 822890075Sobrien@itemize @bullet 822990075Sobrien@item 823090075SobrienUse the shortest sequence that yields a valid definition for 823190075Sobrien@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 823290075Sobrien``normalize'' the value (convert it to, e.g., 1 or 0) than for the 823390075Sobriencomparison operators to do so because there may be opportunities to 823490075Sobriencombine the normalization with other operations. 823590075Sobrien 823690075Sobrien@item 823790075SobrienFor equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 823890075Sobrienslightly preferred on machines with expensive jumps and 1 preferred on 823990075Sobrienother machines. 824090075Sobrien 824190075Sobrien@item 824290075SobrienAs a second choice, choose a value of @samp{0x80000001} if instructions 824390075Sobrienexist that set both the sign and low-order bits but do not define the 824490075Sobrienothers. 824590075Sobrien 824690075Sobrien@item 824790075SobrienOtherwise, use a value of @samp{0x80000000}. 824890075Sobrien@end itemize 824990075Sobrien 825090075SobrienMany machines can produce both the value chosen for 825190075Sobrien@code{STORE_FLAG_VALUE} and its negation in the same number of 825290075Sobrieninstructions. On those machines, you should also define a pattern for 825390075Sobrienthose cases, e.g., one matching 825490075Sobrien 825590075Sobrien@smallexample 825690075Sobrien(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 825790075Sobrien@end smallexample 825890075Sobrien 825990075SobrienSome machines can also perform @code{and} or @code{plus} operations on 826090075Sobriencondition code values with less instructions than the corresponding 826190075Sobrien@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those 826290075Sobrienmachines, define the appropriate patterns. Use the names @code{incscc} 826390075Sobrienand @code{decscc}, respectively, for the patterns which perform 826490075Sobrien@code{plus} or @code{minus} operations on condition code values. See 826590075Sobrien@file{rs6000.md} for some examples. The GNU Superoptizer can be used to 826690075Sobrienfind such instruction sequences on other machines. 826790075Sobrien 826890075SobrienYou need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 826990075Sobrieninstructions. 827090075Sobrien 827190075Sobrien@findex FLOAT_STORE_FLAG_VALUE 827290075Sobrien@item FLOAT_STORE_FLAG_VALUE (@var{mode}) 827390075SobrienA C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 827490075Sobrienreturned when comparison operators with floating-point results are true. 827590075SobrienDefine this macro on machine that have comparison operations that return 827690075Sobrienfloating-point values. If there are no such operations, do not define 827790075Sobrienthis macro. 827890075Sobrien 827990075Sobrien@findex Pmode 828090075Sobrien@item Pmode 828190075SobrienAn alias for the machine mode for pointers. On most machines, define 828290075Sobrienthis to be the integer mode corresponding to the width of a hardware 828390075Sobrienpointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 828490075SobrienOn some machines you must define this to be one of the partial integer 828590075Sobrienmodes, such as @code{PSImode}. 828690075Sobrien 828790075SobrienThe width of @code{Pmode} must be at least as large as the value of 828890075Sobrien@code{POINTER_SIZE}. If it is not equal, you must define the macro 828990075Sobrien@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 829090075Sobriento @code{Pmode}. 829190075Sobrien 829290075Sobrien@findex FUNCTION_MODE 829390075Sobrien@item FUNCTION_MODE 829490075SobrienAn alias for the machine mode used for memory references to functions 829590075Sobrienbeing called, in @code{call} RTL expressions. On most machines this 829690075Sobrienshould be @code{QImode}. 829790075Sobrien 829890075Sobrien@findex INTEGRATE_THRESHOLD 829990075Sobrien@item INTEGRATE_THRESHOLD (@var{decl}) 830090075SobrienA C expression for the maximum number of instructions above which the 830190075Sobrienfunction @var{decl} should not be inlined. @var{decl} is a 830290075Sobrien@code{FUNCTION_DECL} node. 830390075Sobrien 830490075SobrienThe default definition of this macro is 64 plus 8 times the number of 830590075Sobrienarguments that the function accepts. Some people think a larger 830690075Sobrienthreshold should be used on RISC machines. 830790075Sobrien 830890075Sobrien@findex STDC_0_IN_SYSTEM_HEADERS 830990075Sobrien@item STDC_0_IN_SYSTEM_HEADERS 831090075SobrienIn normal operation, the preprocessor expands @code{__STDC__} to the 831190075Sobrienconstant 1, to signify that GCC conforms to ISO Standard C@. On some 831290075Sobrienhosts, like Solaris, the system compiler uses a different convention, 831390075Sobrienwhere @code{__STDC__} is normally 0, but is 1 if the user specifies 831490075Sobrienstrict conformance to the C Standard. 831590075Sobrien 831690075SobrienDefining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 831790075Sobrienconvention when processing system header files, but when processing user 831890075Sobrienfiles @code{__STDC__} will always expand to 1. 831990075Sobrien 832090075Sobrien@findex SCCS_DIRECTIVE 832190075Sobrien@item SCCS_DIRECTIVE 832290075SobrienDefine this if the preprocessor should ignore @code{#sccs} directives 832390075Sobrienand print no error message. 832490075Sobrien 832590075Sobrien@findex NO_IMPLICIT_EXTERN_C 832690075Sobrien@item NO_IMPLICIT_EXTERN_C 832790075SobrienDefine this macro if the system header files support C++ as well as C@. 832890075SobrienThis macro inhibits the usual method of using system header files in 832990075SobrienC++, which is to pretend that the file's contents are enclosed in 833090075Sobrien@samp{extern "C" @{@dots{}@}}. 833190075Sobrien 833290075Sobrien@findex HANDLE_PRAGMA 833390075Sobrien@item HANDLE_PRAGMA (@var{getc}, @var{ungetc}, @var{name}) 833490075SobrienThis macro is no longer supported. You must use 833590075Sobrien@code{REGISTER_TARGET_PRAGMAS} instead. 833690075Sobrien 833790075Sobrien@findex REGISTER_TARGET_PRAGMAS 833890075Sobrien@findex #pragma 833990075Sobrien@findex pragma 834090075Sobrien@item REGISTER_TARGET_PRAGMAS (@var{pfile}) 834190075SobrienDefine this macro if you want to implement any target-specific pragmas. 834290075SobrienIf defined, it is a C expression which makes a series of calls to 834390075Sobrien@code{cpp_register_pragma} for each pragma, with @var{pfile} passed as 834490075Sobrienthe first argument to to these functions. The macro may also do any 834590075Sobriensetup required for the pragmas. 834690075Sobrien 834790075SobrienThe primary reason to define this macro is to provide compatibility with 834890075Sobrienother compilers for the same target. In general, we discourage 834990075Sobriendefinition of target-specific pragmas for GCC@. 835090075Sobrien 835190075SobrienIf the pragma can be implemented by attributes then you should consider 835290075Sobriendefining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 835390075Sobrien 835490075SobrienPreprocessor macros that appear on pragma lines are not expanded. All 835590075Sobrien@samp{#pragma} directives that do not match any registered pragma are 835690075Sobriensilently ignored, unless the user specifies @option{-Wunknown-pragmas}. 835790075Sobrien 835890075Sobrien@deftypefun void cpp_register_pragma (cpp_reader *@var{pfile}, const char *@var{space}, const char *@var{name}, void (*@var{callback}) (cpp_reader *)) 835990075Sobrien 836090075SobrienEach call to @code{cpp_register_pragma} establishes one pragma. The 836190075Sobrien@var{callback} routine will be called when the preprocessor encounters a 836290075Sobrienpragma of the form 836390075Sobrien 836490075Sobrien@smallexample 836590075Sobrien#pragma [@var{space}] @var{name} @dots{} 836690075Sobrien@end smallexample 836790075Sobrien 836890075Sobrien@var{space} is the case-sensitive namespace of the pragma, or 836990075Sobrien@code{NULL} to put the pragma in the global namespace. The callback 837090075Sobrienroutine receives @var{pfile} as its first argument, which can be passed 837190075Sobrienon to cpplib's functions if necessary. You can lex tokens after the 837290075Sobrien@var{name} by calling @code{c_lex}. Tokens that are not read by the 837390075Sobriencallback will be silently ignored. The end of the line is indicated by 837490075Sobriena token of type @code{CPP_EOF}. 837590075Sobrien 837690075SobrienFor an example use of this routine, see @file{c4x.h} and the callback 837790075Sobrienroutines defined in @file{c4x-c.c}. 837890075Sobrien 837990075SobrienNote that the use of @code{c_lex} is specific to the C and C++ 838090075Sobriencompilers. It will not work in the Java or Fortran compilers, or any 838190075Sobrienother language compilers for that matter. Thus if @code{c_lex} is going 838290075Sobriento be called from target-specific code, it must only be done so when 838390075Sobrienbuilding the C and C++ compilers. This can be done by defining the 838490075Sobrienvariables @code{c_target_objs} and @code{cxx_target_objs} in the 838590075Sobrientarget entry in the @file{config.gcc} file. These variables should name 838690075Sobrienthe target-specific, language-specific object file which contains the 838790075Sobriencode that uses @code{c_lex}. Note it will also be necessary to add a 838890075Sobrienrule to the makefile fragment pointed to by @code{tmake_file} that shows 838990075Sobrienhow to build this object file. 839090075Sobrien@end deftypefun 839190075Sobrien 839290075Sobrien@findex HANDLE_SYSV_PRAGMA 839390075Sobrien@findex #pragma 839490075Sobrien@findex pragma 839590075Sobrien@item HANDLE_SYSV_PRAGMA 839690075SobrienDefine this macro (to a value of 1) if you want the System V style 839790075Sobrienpragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> 839890075Sobrien[=<value>]} to be supported by gcc. 839990075Sobrien 840090075SobrienThe pack pragma specifies the maximum alignment (in bytes) of fields 840190075Sobrienwithin a structure, in much the same way as the @samp{__aligned__} and 840290075Sobrien@samp{__packed__} @code{__attribute__}s do. A pack value of zero resets 840390075Sobrienthe behavior to the default. 840490075Sobrien 840590075SobrienThe weak pragma only works if @code{SUPPORTS_WEAK} and 840690075Sobrien@code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation 840790075Sobrienof specifically named weak labels, optionally with a value. 840890075Sobrien 840990075Sobrien@findex HANDLE_PRAGMA_PACK_PUSH_POP 841090075Sobrien@findex #pragma 841190075Sobrien@findex pragma 841290075Sobrien@item HANDLE_PRAGMA_PACK_PUSH_POP 841390075SobrienDefine this macro (to a value of 1) if you want to support the Win32 841490075Sobrienstyle pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma 841590075Sobrienpack(pop)}. The @samp{pack(push,@var{n})} pragma specifies the maximum alignment 841690075Sobrien(in bytes) of fields within a structure, in much the same way as the 841790075Sobrien@samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A 841890075Sobrienpack value of zero resets the behavior to the default. Successive 841990075Sobrieninvocations of this pragma cause the previous values to be stacked, so 842090075Sobrienthat invocations of @samp{#pragma pack(pop)} will return to the previous 842190075Sobrienvalue. 842290075Sobrien 842390075Sobrien@findex DOLLARS_IN_IDENTIFIERS 842490075Sobrien@item DOLLARS_IN_IDENTIFIERS 842590075SobrienDefine this macro to control use of the character @samp{$} in identifier 842690075Sobriennames. 0 means @samp{$} is not allowed by default; 1 means it is allowed. 842790075Sobrien1 is the default; there is no need to define this macro in that case. 842890075SobrienThis macro controls the compiler proper; it does not affect the preprocessor. 842990075Sobrien 843090075Sobrien@findex NO_DOLLAR_IN_LABEL 843190075Sobrien@item NO_DOLLAR_IN_LABEL 843290075SobrienDefine this macro if the assembler does not accept the character 843390075Sobrien@samp{$} in label names. By default constructors and destructors in 843490075SobrienG++ have @samp{$} in the identifiers. If this macro is defined, 843590075Sobrien@samp{.} is used instead. 843690075Sobrien 843790075Sobrien@findex NO_DOT_IN_LABEL 843890075Sobrien@item NO_DOT_IN_LABEL 843990075SobrienDefine this macro if the assembler does not accept the character 844090075Sobrien@samp{.} in label names. By default constructors and destructors in G++ 844190075Sobrienhave names that use @samp{.}. If this macro is defined, these names 844290075Sobrienare rewritten to avoid @samp{.}. 844390075Sobrien 844490075Sobrien@findex DEFAULT_MAIN_RETURN 844590075Sobrien@item DEFAULT_MAIN_RETURN 844690075SobrienDefine this macro if the target system expects every program's @code{main} 844790075Sobrienfunction to return a standard ``success'' value by default (if no other 844890075Sobrienvalue is explicitly returned). 844990075Sobrien 845090075SobrienThe definition should be a C statement (sans semicolon) to generate the 845190075Sobrienappropriate rtl instructions. It is used only when compiling the end of 845290075Sobrien@code{main}. 845390075Sobrien 845490075Sobrien@item NEED_ATEXIT 845590075Sobrien@findex NEED_ATEXIT 845690075SobrienDefine this if the target system lacks the function @code{atexit} 845790075Sobrienfrom the ISO C standard. If this macro is defined, a default definition 845890075Sobrienwill be provided to support C++. If @code{ON_EXIT} is not defined, 845990075Sobriena default @code{exit} function will also be provided. 846090075Sobrien 846190075Sobrien@item ON_EXIT 846290075Sobrien@findex ON_EXIT 846390075SobrienDefine this macro if the target has another way to implement atexit 846490075Sobrienfunctionality without replacing @code{exit}. For instance, SunOS 4 has 846590075Sobriena similar @code{on_exit} library function. 846690075Sobrien 846790075SobrienThe definition should be a functional macro which can be used just like 846890075Sobrienthe @code{atexit} function. 846990075Sobrien 847090075Sobrien@item EXIT_BODY 847190075Sobrien@findex EXIT_BODY 847290075SobrienDefine this if your @code{exit} function needs to do something 847390075Sobrienbesides calling an external function @code{_cleanup} before 847490075Sobrienterminating with @code{_exit}. The @code{EXIT_BODY} macro is 847590075Sobrienonly needed if @code{NEED_ATEXIT} is defined and @code{ON_EXIT} is not 847690075Sobriendefined. 847790075Sobrien 847890075Sobrien@findex INSN_SETS_ARE_DELAYED 847990075Sobrien@item INSN_SETS_ARE_DELAYED (@var{insn}) 848090075SobrienDefine this macro as a C expression that is nonzero if it is safe for the 848190075Sobriendelay slot scheduler to place instructions in the delay slot of @var{insn}, 848290075Sobrieneven if they appear to use a resource set or clobbered in @var{insn}. 848390075Sobrien@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 848490075Sobrienevery @code{call_insn} has this behavior. On machines where some @code{insn} 848590075Sobrienor @code{jump_insn} is really a function call and hence has this behavior, 848690075Sobrienyou should define this macro. 848790075Sobrien 848890075SobrienYou need not define this macro if it would always return zero. 848990075Sobrien 849090075Sobrien@findex INSN_REFERENCES_ARE_DELAYED 849190075Sobrien@item INSN_REFERENCES_ARE_DELAYED (@var{insn}) 849290075SobrienDefine this macro as a C expression that is nonzero if it is safe for the 849390075Sobriendelay slot scheduler to place instructions in the delay slot of @var{insn}, 849490075Sobrieneven if they appear to set or clobber a resource referenced in @var{insn}. 849590075Sobrien@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 849690075Sobriensome @code{insn} or @code{jump_insn} is really a function call and its operands 849790075Sobrienare registers whose use is actually in the subroutine it calls, you should 849890075Sobriendefine this macro. Doing so allows the delay slot scheduler to move 849990075Sobrieninstructions which copy arguments into the argument registers into the delay 850090075Sobrienslot of @var{insn}. 850190075Sobrien 850290075SobrienYou need not define this macro if it would always return zero. 850390075Sobrien 850490075Sobrien@findex MACHINE_DEPENDENT_REORG 850590075Sobrien@item MACHINE_DEPENDENT_REORG (@var{insn}) 850690075SobrienIn rare cases, correct code generation requires extra machine 850790075Sobriendependent processing between the second jump optimization pass and 850890075Sobriendelayed branch scheduling. On those machines, define this macro as a C 850990075Sobrienstatement to act on the code starting at @var{insn}. 851090075Sobrien 851190075Sobrien@findex MULTIPLE_SYMBOL_SPACES 851290075Sobrien@item MULTIPLE_SYMBOL_SPACES 851390075SobrienDefine this macro if in some cases global symbols from one translation 851490075Sobrienunit may not be bound to undefined symbols in another translation unit 851590075Sobrienwithout user intervention. For instance, under Microsoft Windows 851690075Sobriensymbols must be explicitly imported from shared libraries (DLLs). 851790075Sobrien 851890075Sobrien@findex MD_ASM_CLOBBERS 851990075Sobrien@item MD_ASM_CLOBBERS (@var{clobbers}) 852090075SobrienA C statement that adds to @var{clobbers} @code{STRING_CST} trees for 852190075Sobrienany hard regs the port wishes to automatically clobber for all asms. 852290075Sobrien 852390075Sobrien@findex MAX_INTEGER_COMPUTATION_MODE 852490075Sobrien@item MAX_INTEGER_COMPUTATION_MODE 852590075SobrienDefine this to the largest integer machine mode which can be used for 852690075Sobrienoperations other than load, store and copy operations. 852790075Sobrien 852890075SobrienYou need only define this macro if the target holds values larger than 852990075Sobrien@code{word_mode} in general purpose registers. Most targets should not define 853090075Sobrienthis macro. 853190075Sobrien 853290075Sobrien@findex MATH_LIBRARY 853390075Sobrien@item MATH_LIBRARY 853490075SobrienDefine this macro as a C string constant for the linker argument to link 853590075Sobrienin the system math library, or @samp{""} if the target does not have a 853690075Sobrienseparate math library. 853790075Sobrien 853890075SobrienYou need only define this macro if the default of @samp{"-lm"} is wrong. 853990075Sobrien 854090075Sobrien@findex LIBRARY_PATH_ENV 854190075Sobrien@item LIBRARY_PATH_ENV 854290075SobrienDefine this macro as a C string constant for the environment variable that 854390075Sobrienspecifies where the linker should look for libraries. 854490075Sobrien 854590075SobrienYou need only define this macro if the default of @samp{"LIBRARY_PATH"} 854690075Sobrienis wrong. 854790075Sobrien 854890075Sobrien@findex TARGET_HAS_F_SETLKW 854990075Sobrien@item TARGET_HAS_F_SETLKW 855090075SobrienDefine this macro if the target supports file locking with fcntl / F_SETLKW@. 855190075SobrienNote that this functionality is part of POSIX@. 855290075SobrienDefining @code{TARGET_HAS_F_SETLKW} will enable the test coverage code 855390075Sobriento use file locking when exiting a program, which avoids race conditions 855490075Sobrienif the program has forked. 855590075Sobrien 855690075Sobrien@findex MAX_CONDITIONAL_EXECUTE 855790075Sobrien@item MAX_CONDITIONAL_EXECUTE 855890075Sobrien 855990075SobrienA C expression for the maximum number of instructions to execute via 856090075Sobrienconditional execution instructions instead of a branch. A value of 856190075Sobrien@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 856290075Sobrien1 if it does use cc0. 856390075Sobrien 856490075Sobrien@findex IFCVT_MODIFY_TESTS 856590075Sobrien@item IFCVT_MODIFY_TESTS 856690075SobrienA C expression to modify the tests in @code{TRUE_EXPR}, and 856790075Sobrien@code{FALSE_EXPR} for use in converting insns in @code{TEST_BB}, 856890075Sobrien@code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB} basic blocks to 856990075Sobrienconditional execution. Set either @code{TRUE_EXPR} or @code{FALSE_EXPR} 857090075Sobriento a null pointer if the tests cannot be converted. 857190075Sobrien 857290075Sobrien@findex IFCVT_MODIFY_INSN 857390075Sobrien@item IFCVT_MODIFY_INSN 857490075SobrienA C expression to modify the @code{PATTERN} of an @code{INSN} that is to 857590075Sobrienbe converted to conditional execution format. 857690075Sobrien 857790075Sobrien@findex IFCVT_MODIFY_FINAL 857890075Sobrien@item IFCVT_MODIFY_FINAL 857990075SobrienA C expression to perform any final machine dependent modifications in 858090075Sobrienconverting code to conditional execution in the basic blocks 858190075Sobrien@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. 858290075Sobrien 858390075Sobrien@findex IFCVT_MODIFY_CANCEL 858490075Sobrien@item IFCVT_MODIFY_CANCEL 858590075SobrienA C expression to cancel any machine dependent modifications in 858690075Sobrienconverting code to conditional execution in the basic blocks 858790075Sobrien@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. 858890075Sobrien@end table 858990075Sobrien 859090075Sobrien@deftypefn {Target Hook} void TARGET_INIT_BUILTINS () 859190075SobrienDefine this hook if you have any machine-specific built-in functions 859290075Sobrienthat need to be defined. It should be a function that performs the 859390075Sobriennecessary setup. 859490075Sobrien 859590075SobrienMachine specific built-in functions can be useful to expand special machine 859690075Sobrieninstructions that would otherwise not normally be generated because 859790075Sobrienthey have no equivalent in the source language (for example, SIMD vector 859890075Sobrieninstructions or prefetch instructions). 859990075Sobrien 860090075SobrienTo create a built-in function, call the function @code{builtin_function} 860190075Sobrienwhich is defined by the language front end. You can use any type nodes set 860290075Sobrienup by @code{build_common_tree_nodes} and @code{build_common_tree_nodes_2}; 860390075Sobrienonly language front ends that use those two functions will call 860490075Sobrien@samp{TARGET_INIT_BUILTINS}. 860590075Sobrien@end deftypefn 860690075Sobrien 860790075Sobrien@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 860890075Sobrien 860990075SobrienExpand a call to a machine specific built-in function that was set up by 861090075Sobrien@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 861190075Sobrienfunction call; the result should go to @var{target} if that is 861290075Sobrienconvenient, and have mode @var{mode} if that is convenient. 861390075Sobrien@var{subtarget} may be used as the target for computing one of 861490075Sobrien@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 861590075Sobrienignored. This function should return the result of the call to the 861690075Sobrienbuilt-in function. 861790075Sobrien@end deftypefn 861890075Sobrien 861990075Sobrien@table @code 862090075Sobrien@findex MD_CAN_REDIRECT_BRANCH 862190075Sobrien@item MD_CAN_REDIRECT_BRANCH(@var{branch1}, @var{branch2}) 862290075Sobrien 862390075SobrienTake a branch insn in @var{branch1} and another in @var{branch2}. 862490075SobrienReturn true if redirecting @var{branch1} to the destination of 862590075Sobrien@var{branch2} is possible. 862690075Sobrien 862790075SobrienOn some targets, branches may have a limited range. Optimizing the 862890075Sobrienfilling of delay slots can result in branches being redirected, and this 862990075Sobrienmay in turn cause a branch offset to overflow. 863090075Sobrien 863190075Sobrien@findex ALLOCATE_INITIAL_VALUE 863290075Sobrien@item ALLOCATE_INITIAL_VALUE(@var{hard_reg}) 863390075Sobrien 863490075SobrienWhen the initial value of a hard register has been copied in a pseudo 863590075Sobrienregister, it is often not necessary to actually allocate another register 863690075Sobriento this pseudo register, because the original hard register or a stack slot 863790075Sobrienit has been saved into can be used. @code{ALLOCATE_INITIAL_VALUE}, if 863890075Sobriendefined, is called at the start of register allocation once for each 863990075Sobrienhard register that had its initial value copied by using 864090075Sobrien@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 864190075SobrienPossible values are @code{NULL_RTX}, if you don't want 864290075Sobriento do any special allocation, a @code{REG} rtx---that would typically be 864390075Sobrienthe hard register itself, if it is known not to be clobbered---or a 864490075Sobrien@code{MEM}. 864590075SobrienIf you are returning a @code{MEM}, this is only a hint for the allocator; 864690075Sobrienit might decide to use another register anyways. 864790075SobrienYou may use @code{current_function_leaf_function} in the definition of the 864890075Sobrienmacro, functions that use @code{REG_N_SETS}, to determine if the hard 864990075Sobrienregister in question will not be clobbered. 865090075Sobrien 865190075Sobrien@findex TARGET_OBJECT_SUFFIX 865290075Sobrien@item TARGET_OBJECT_SUFFIX 865390075SobrienDefine this macro to be a C string representing the suffix for object 865490075Sobrienfiles on your target machine. If you do not define this macro, GCC will 865590075Sobrienuse @samp{.o} as the suffix for object files. 865690075Sobrien 865790075Sobrien@findex TARGET_EXECUTABLE_SUFFIX 865890075Sobrien@item TARGET_EXECUTABLE_SUFFIX 865990075SobrienDefine this macro to be a C string representing the suffix to be 866090075Sobrienautomatically added to executable files on your target machine. If you 866190075Sobriendo not define this macro, GCC will use the null string as the suffix for 866290075Sobrienexecutable files. 866390075Sobrien 866490075Sobrien@findex COLLECT_EXPORT_LIST 866590075Sobrien@item COLLECT_EXPORT_LIST 866690075SobrienIf defined, @code{collect2} will scan the individual object files 866790075Sobrienspecified on its command line and create an export list for the linker. 866890075SobrienDefine this macro for systems like AIX, where the linker discards 866990075Sobrienobject files that are not referenced from @code{main} and uses export 867090075Sobrienlists. 867190075Sobrien 867290075Sobrien@end table 867396263Sobrien 867496263Sobrien@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 867596263SobrienThis target hook returns @code{true} past the point in which new jump 867696263Sobrieninstructions could be created. On machines that require a register for 867796263Sobrienevery jump such as the SHmedia ISA of SH5, this point would typically be 867896263Sobrienreload, so this target hook should be defined to a function such as: 867996263Sobrien 868096263Sobrien@smallexample 868196263Sobrienstatic bool 868296263Sobriencannot_modify_jumps_past_reload_p () 868396263Sobrien@{ 868496263Sobrien return (reload_completed || reload_in_progress); 868596263Sobrien@} 868696263Sobrien@end smallexample 868796263Sobrien@end deftypefn 8688