| @c Copyright (C) 1988-2021 Free Software Foundation, Inc. |
| @c This is part of the GCC manual. |
| @c For copying conditions, see the file gcc.texi. |
| |
| @node Target Macros |
| @chapter Target Description Macros and Functions |
| @cindex machine description macros |
| @cindex target description macros |
| @cindex macros, target description |
| @cindex @file{tm.h} macros |
| |
| In addition to the file @file{@var{machine}.md}, a machine description |
| includes a C header file conventionally given the name |
| @file{@var{machine}.h} and a C source file named @file{@var{machine}.c}. |
| The header file defines numerous macros that convey the information |
| about the target machine that does not fit into the scheme of the |
| @file{.md} file. The file @file{tm.h} should be a link to |
| @file{@var{machine}.h}. The header file @file{config.h} includes |
| @file{tm.h} and most compiler source files include @file{config.h}. The |
| source file defines a variable @code{targetm}, which is a structure |
| containing pointers to functions and data relating to the target |
| machine. @file{@var{machine}.c} should also contain their definitions, |
| if they are not defined elsewhere in GCC, and other functions called |
| through the macros defined in the @file{.h} file. |
| |
| @menu |
| * Target Structure:: The @code{targetm} variable. |
| * Driver:: Controlling how the driver runs the compilation passes. |
| * Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}. |
| * Per-Function Data:: Defining data structures for per-function information. |
| * Storage Layout:: Defining sizes and alignments of data. |
| * Type Layout:: Defining sizes and properties of basic user data types. |
| * Registers:: Naming and describing the hardware registers. |
| * Register Classes:: Defining the classes of hardware registers. |
| * Stack and Calling:: Defining which way the stack grows and by how much. |
| * Varargs:: Defining the varargs macros. |
| * Trampolines:: Code set up at run time to enter a nested function. |
| * Library Calls:: Controlling how library routines are implicitly called. |
| * Addressing Modes:: Defining addressing modes valid for memory operands. |
| * Anchored Addresses:: Defining how @option{-fsection-anchors} should work. |
| * Condition Code:: Defining how insns update the condition code. |
| * Costs:: Defining relative costs of different operations. |
| * Scheduling:: Adjusting the behavior of the instruction scheduler. |
| * Sections:: Dividing storage into text, data, and other sections. |
| * PIC:: Macros for position independent code. |
| * Assembler Format:: Defining how to write insns and pseudo-ops to output. |
| * Debugging Info:: Defining the format of debugging output. |
| * Floating Point:: Handling floating point for cross-compilers. |
| * Mode Switching:: Insertion of mode-switching instructions. |
| * Target Attributes:: Defining target-specific uses of @code{__attribute__}. |
| * Emulated TLS:: Emulated TLS support. |
| * MIPS Coprocessors:: MIPS coprocessor support and how to customize it. |
| * PCH Target:: Validity checking for precompiled headers. |
| * C++ ABI:: Controlling C++ ABI changes. |
| * D Language and ABI:: Controlling D ABI changes. |
| * Named Address Spaces:: Adding support for named address spaces |
| * Misc:: Everything else. |
| @end menu |
| |
| @node Target Structure |
| @section The Global @code{targetm} Variable |
| @cindex target hooks |
| @cindex target functions |
| |
| @deftypevar {struct gcc_target} targetm |
| The target @file{.c} file must define the global @code{targetm} variable |
| which contains pointers to functions and data relating to the target |
| machine. The variable is declared in @file{target.h}; |
| @file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is |
| used to initialize the variable, and macros for the default initializers |
| for elements of the structure. The @file{.c} file should override those |
| macros for which the default definition is inappropriate. For example: |
| @smallexample |
| #include "target.h" |
| #include "target-def.h" |
| |
| /* @r{Initialize the GCC target structure.} */ |
| |
| #undef TARGET_COMP_TYPE_ATTRIBUTES |
| #define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes |
| |
| struct gcc_target targetm = TARGET_INITIALIZER; |
| @end smallexample |
| @end deftypevar |
| |
| Where a macro should be defined in the @file{.c} file in this manner to |
| form part of the @code{targetm} structure, it is documented below as a |
| ``Target Hook'' with a prototype. Many macros will change in future |
| from being defined in the @file{.h} file to being part of the |
| @code{targetm} structure. |
| |
| Similarly, there is a @code{targetcm} variable for hooks that are |
| specific to front ends for C-family languages, documented as ``C |
| Target Hook''. This is declared in @file{c-family/c-target.h}, the |
| initializer @code{TARGETCM_INITIALIZER} in |
| @file{c-family/c-target-def.h}. If targets initialize @code{targetcm} |
| themselves, they should set @code{target_has_targetcm=yes} in |
| @file{config.gcc}; otherwise a default definition is used. |
| |
| Similarly, there is a @code{targetm_common} variable for hooks that |
| are shared between the compiler driver and the compilers proper, |
| documented as ``Common Target Hook''. This is declared in |
| @file{common/common-target.h}, the initializer |
| @code{TARGETM_COMMON_INITIALIZER} in |
| @file{common/common-target-def.h}. If targets initialize |
| @code{targetm_common} themselves, they should set |
| @code{target_has_targetm_common=yes} in @file{config.gcc}; otherwise a |
| default definition is used. |
| |
| Similarly, there is a @code{targetdm} variable for hooks that are |
| specific to the D language front end, documented as ``D Target Hook''. |
| This is declared in @file{d/d-target.h}, the initializer |
| @code{TARGETDM_INITIALIZER} in @file{d/d-target-def.h}. If targets |
| initialize @code{targetdm} themselves, they should set |
| @code{target_has_targetdm=yes} in @file{config.gcc}; otherwise a default |
| definition is used. |
| |
| @node Driver |
| @section Controlling the Compilation Driver, @file{gcc} |
| @cindex driver |
| @cindex controlling the compilation driver |
| |
| @c prevent bad page break with this line |
| You can control the compilation driver. |
| |
| @defmac DRIVER_SELF_SPECS |
| A list of specs for the driver itself. It should be a suitable |
| initializer for an array of strings, with no surrounding braces. |
| |
| The driver applies these specs to its own command line between loading |
| default @file{specs} files (but not command-line specified ones) and |
| choosing the multilib directory or running any subcommands. It |
| applies them in the order given, so each spec can depend on the |
| options added by earlier ones. It is also possible to remove options |
| using @samp{%<@var{option}} in the usual way. |
| |
| This macro can be useful when a port has several interdependent target |
| options. It provides a way of standardizing the command line so |
| that the other specs are easier to write. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac OPTION_DEFAULT_SPECS |
| A list of specs used to support configure-time default options (i.e.@: |
| @option{--with} options) in the driver. It should be a suitable initializer |
| for an array of structures, each containing two strings, without the |
| outermost pair of surrounding braces. |
| |
| The first item in the pair is the name of the default. This must match |
| the code in @file{config.gcc} for the target. The second item is a spec |
| to apply if a default with this name was specified. The string |
| @samp{%(VALUE)} in the spec will be replaced by the value of the default |
| everywhere it occurs. |
| |
| The driver will apply these specs to its own command line between loading |
| default @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using |
| the same mechanism as @code{DRIVER_SELF_SPECS}. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac CPP_SPEC |
| A C string constant that tells the GCC driver program options to |
| pass to CPP@. It can also specify how to translate options you |
| give to GCC into options for GCC to pass to the CPP@. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac CPLUSPLUS_CPP_SPEC |
| This macro is just like @code{CPP_SPEC}, but is used for C++, rather |
| than C@. If you do not define this macro, then the value of |
| @code{CPP_SPEC} (if any) will be used instead. |
| @end defmac |
| |
| @defmac CC1_SPEC |
| A C string constant that tells the GCC driver program options to |
| pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language |
| front ends. |
| It can also specify how to translate options you give to GCC into options |
| for GCC to pass to front ends. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac CC1PLUS_SPEC |
| A C string constant that tells the GCC driver program options to |
| pass to @code{cc1plus}. It can also specify how to translate options you |
| give to GCC into options for GCC to pass to the @code{cc1plus}. |
| |
| Do not define this macro if it does not need to do anything. |
| Note that everything defined in CC1_SPEC is already passed to |
| @code{cc1plus} so there is no need to duplicate the contents of |
| CC1_SPEC in CC1PLUS_SPEC@. |
| @end defmac |
| |
| @defmac ASM_SPEC |
| A C string constant that tells the GCC driver program options to |
| pass to the assembler. It can also specify how to translate options |
| you give to GCC into options for GCC to pass to the assembler. |
| See the file @file{sun3.h} for an example of this. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac ASM_FINAL_SPEC |
| A C string constant that tells the GCC driver program how to |
| run any programs which cleanup after the normal assembler. |
| Normally, this is not needed. See the file @file{mips.h} for |
| an example of this. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac AS_NEEDS_DASH_FOR_PIPED_INPUT |
| Define this macro, with no value, if the driver should give the assembler |
| an argument consisting of a single dash, @option{-}, to instruct it to |
| read from its standard input (which will be a pipe connected to the |
| output of the compiler proper). This argument is given after any |
| @option{-o} option specifying the name of the output file. |
| |
| If you do not define this macro, the assembler is assumed to read its |
| standard input if given no non-option arguments. If your assembler |
| cannot read standard input at all, use a @samp{%@{pipe:%e@}} construct; |
| see @file{mips.h} for instance. |
| @end defmac |
| |
| @defmac LINK_SPEC |
| A C string constant that tells the GCC driver program options to |
| pass to the linker. It can also specify how to translate options you |
| give to GCC into options for GCC to pass to the linker. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac LIB_SPEC |
| Another C string constant used much like @code{LINK_SPEC}. The difference |
| between the two is that @code{LIB_SPEC} is used at the end of the |
| command given to the linker. |
| |
| If this macro is not defined, a default is provided that |
| loads the standard C library from the usual place. See @file{gcc.c}. |
| @end defmac |
| |
| @defmac LIBGCC_SPEC |
| Another C string constant that tells the GCC driver program |
| how and when to place a reference to @file{libgcc.a} into the |
| linker command line. This constant is placed both before and after |
| the value of @code{LIB_SPEC}. |
| |
| If this macro is not defined, the GCC driver provides a default that |
| passes the string @option{-lgcc} to the linker. |
| @end defmac |
| |
| @defmac REAL_LIBGCC_SPEC |
| By default, if @code{ENABLE_SHARED_LIBGCC} is defined, the |
| @code{LIBGCC_SPEC} is not directly used by the driver program but is |
| instead modified to refer to different versions of @file{libgcc.a} |
| depending on the values of the command line flags @option{-static}, |
| @option{-shared}, @option{-static-libgcc}, and @option{-shared-libgcc}. On |
| targets where these modifications are inappropriate, define |
| @code{REAL_LIBGCC_SPEC} instead. @code{REAL_LIBGCC_SPEC} tells the |
| driver how to place a reference to @file{libgcc} on the link command |
| line, but, unlike @code{LIBGCC_SPEC}, it is used unmodified. |
| @end defmac |
| |
| @defmac USE_LD_AS_NEEDED |
| A macro that controls the modifications to @code{LIBGCC_SPEC} |
| mentioned in @code{REAL_LIBGCC_SPEC}. If nonzero, a spec will be |
| generated that uses @option{--as-needed} or equivalent options and the |
| shared @file{libgcc} in place of the |
| static exception handler library, when linking without any of |
| @code{-static}, @code{-static-libgcc}, or @code{-shared-libgcc}. |
| @end defmac |
| |
| @defmac LINK_EH_SPEC |
| If defined, this C string constant is added to @code{LINK_SPEC}. |
| When @code{USE_LD_AS_NEEDED} is zero or undefined, it also affects |
| the modifications to @code{LIBGCC_SPEC} mentioned in |
| @code{REAL_LIBGCC_SPEC}. |
| @end defmac |
| |
| @defmac STARTFILE_SPEC |
| Another C string constant used much like @code{LINK_SPEC}. The |
| difference between the two is that @code{STARTFILE_SPEC} is used at |
| the very beginning of the command given to the linker. |
| |
| If this macro is not defined, a default is provided that loads the |
| standard C startup file from the usual place. See @file{gcc.c}. |
| @end defmac |
| |
| @defmac ENDFILE_SPEC |
| Another C string constant used much like @code{LINK_SPEC}. The |
| difference between the two is that @code{ENDFILE_SPEC} is used at |
| the very end of the command given to the linker. |
| |
| Do not define this macro if it does not need to do anything. |
| @end defmac |
| |
| @defmac THREAD_MODEL_SPEC |
| GCC @code{-v} will print the thread model GCC was configured to use. |
| However, this doesn't work on platforms that are multilibbed on thread |
| models, such as AIX 4.3. On such platforms, define |
| @code{THREAD_MODEL_SPEC} such that it evaluates to a string without |
| blanks that names one of the recognized thread models. @code{%*}, the |
| default value of this macro, will expand to the value of |
| @code{thread_file} set in @file{config.gcc}. |
| @end defmac |
| |
| @defmac SYSROOT_SUFFIX_SPEC |
| Define this macro to add a suffix to the target sysroot when GCC is |
| configured with a sysroot. This will cause GCC to search for usr/lib, |
| et al, within sysroot+suffix. |
| @end defmac |
| |
| @defmac SYSROOT_HEADERS_SUFFIX_SPEC |
| Define this macro to add a headers_suffix to the target sysroot when |
| GCC is configured with a sysroot. This will cause GCC to pass the |
| updated sysroot+headers_suffix to CPP, causing it to search for |
| usr/include, et al, within sysroot+headers_suffix. |
| @end defmac |
| |
| @defmac EXTRA_SPECS |
| Define this macro to provide additional specifications to put in the |
| @file{specs} file that can be used in various specifications like |
| @code{CC1_SPEC}. |
| |
| The definition should be an initializer for an array of structures, |
| containing a string constant, that defines the specification name, and a |
| string constant that provides the specification. |
| |
| Do not define this macro if it does not need to do anything. |
| |
| @code{EXTRA_SPECS} is useful when an architecture contains several |
| related targets, which have various @code{@dots{}_SPECS} which are similar |
| to each other, and the maintainer would like one central place to keep |
| these definitions. |
| |
| For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to |
| define either @code{_CALL_SYSV} when the System V calling sequence is |
| used or @code{_CALL_AIX} when the older AIX-based calling sequence is |
| used. |
| |
| The @file{config/rs6000/rs6000.h} target file defines: |
| |
| @smallexample |
| #define EXTRA_SPECS \ |
| @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, |
| |
| #define CPP_SYS_DEFAULT "" |
| @end smallexample |
| |
| The @file{config/rs6000/sysv.h} target file defines: |
| @smallexample |
| #undef CPP_SPEC |
| #define CPP_SPEC \ |
| "%@{posix: -D_POSIX_SOURCE @} \ |
| %@{mcall-sysv: -D_CALL_SYSV @} \ |
| %@{!mcall-sysv: %(cpp_sysv_default) @} \ |
| %@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" |
| |
| #undef CPP_SYSV_DEFAULT |
| #define CPP_SYSV_DEFAULT "-D_CALL_SYSV" |
| @end smallexample |
| |
| while the @file{config/rs6000/eabiaix.h} target file defines |
| @code{CPP_SYSV_DEFAULT} as: |
| |
| @smallexample |
| #undef CPP_SYSV_DEFAULT |
| #define CPP_SYSV_DEFAULT "-D_CALL_AIX" |
| @end smallexample |
| @end defmac |
| |
| @defmac LINK_LIBGCC_SPECIAL_1 |
| Define this macro if the driver program should find the library |
| @file{libgcc.a}. If you do not define this macro, the driver program will pass |
| the argument @option{-lgcc} to tell the linker to do the search. |
| @end defmac |
| |
| @defmac LINK_GCC_C_SEQUENCE_SPEC |
| The sequence in which libgcc and libc are specified to the linker. |
| By default this is @code{%G %L %G}. |
| @end defmac |
| |
| @defmac POST_LINK_SPEC |
| Define this macro to add additional steps to be executed after linker. |
| The default value of this macro is empty string. |
| @end defmac |
| |
| @defmac LINK_COMMAND_SPEC |
| A C string constant giving the complete command line need to execute the |
| linker. When you do this, you will need to update your port each time a |
| change is made to the link command line within @file{gcc.c}. Therefore, |
| define this macro only if you need to completely redefine the command |
| line for invoking the linker and there is no other way to accomplish |
| the effect you need. Overriding this macro may be avoidable by overriding |
| @code{LINK_GCC_C_SEQUENCE_SPEC} instead. |
| @end defmac |
| |
| @deftypevr {Common Target Hook} bool TARGET_ALWAYS_STRIP_DOTDOT |
| True if @file{..} components should always be removed from directory names |
| computed relative to GCC's internal directories, false (default) if such |
| components should be preserved and directory names containing them passed |
| to other tools such as the linker. |
| @end deftypevr |
| |
| @defmac MULTILIB_DEFAULTS |
| Define this macro as a C expression for the initializer of an array of |
| string to tell the driver program which options are defaults for this |
| target and thus do not need to be handled specially when using |
| @code{MULTILIB_OPTIONS}. |
| |
| Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in |
| the target makefile fragment or if none of the options listed in |
| @code{MULTILIB_OPTIONS} are set by default. |
| @xref{Target Fragment}. |
| @end defmac |
| |
| @defmac RELATIVE_PREFIX_NOT_LINKDIR |
| Define this macro to tell @command{gcc} that it should only translate |
| a @option{-B} prefix into a @option{-L} linker option if the prefix |
| indicates an absolute file name. |
| @end defmac |
| |
| @defmac MD_EXEC_PREFIX |
| If defined, this macro is an additional prefix to try after |
| @code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched |
| when the compiler is built as a cross |
| compiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it |
| to the list of directories used to find the assembler in @file{configure.ac}. |
| @end defmac |
| |
| @defmac STANDARD_STARTFILE_PREFIX |
| Define this macro as a C string constant if you wish to override the |
| standard choice of @code{libdir} as the default prefix to |
| try when searching for startup files such as @file{crt0.o}. |
| @code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler |
| is built as a cross compiler. |
| @end defmac |
| |
| @defmac STANDARD_STARTFILE_PREFIX_1 |
| Define this macro as a C string constant if you wish to override the |
| standard choice of @code{/lib} as a prefix to try after the default prefix |
| when searching for startup files such as @file{crt0.o}. |
| @code{STANDARD_STARTFILE_PREFIX_1} is not searched when the compiler |
| is built as a cross compiler. |
| @end defmac |
| |
| @defmac STANDARD_STARTFILE_PREFIX_2 |
| Define this macro as a C string constant if you wish to override the |
| standard choice of @code{/lib} as yet another prefix to try after the |
| default prefix when searching for startup files such as @file{crt0.o}. |
| @code{STANDARD_STARTFILE_PREFIX_2} is not searched when the compiler |
| is built as a cross compiler. |
| @end defmac |
| |
| @defmac MD_STARTFILE_PREFIX |
| If defined, this macro supplies an additional prefix to try after the |
| standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the |
| compiler is built as a cross compiler. |
| @end defmac |
| |
| @defmac MD_STARTFILE_PREFIX_1 |
| If defined, this macro supplies yet another prefix to try after the |
| standard prefixes. It is not searched when the compiler is built as a |
| cross compiler. |
| @end defmac |
| |
| @defmac INIT_ENVIRONMENT |
| Define this macro as a C string constant if you wish to set environment |
| variables for programs called by the driver, such as the assembler and |
| loader. The driver passes the value of this macro to @code{putenv} to |
| initialize the necessary environment variables. |
| @end defmac |
| |
| @defmac LOCAL_INCLUDE_DIR |
| Define this macro as a C string constant if you wish to override the |
| standard choice of @file{/usr/local/include} as the default prefix to |
| try when searching for local header files. @code{LOCAL_INCLUDE_DIR} |
| comes before @code{NATIVE_SYSTEM_HEADER_DIR} (set in |
| @file{config.gcc}, normally @file{/usr/include}) in the search order. |
| |
| Cross compilers do not search either @file{/usr/local/include} or its |
| replacement. |
| @end defmac |
| |
| @defmac NATIVE_SYSTEM_HEADER_COMPONENT |
| The ``component'' corresponding to @code{NATIVE_SYSTEM_HEADER_DIR}. |
| See @code{INCLUDE_DEFAULTS}, below, for the description of components. |
| If you do not define this macro, no component is used. |
| @end defmac |
| |
| @defmac INCLUDE_DEFAULTS |
| Define this macro if you wish to override the entire default search path |
| for include files. For a native compiler, the default search path |
| usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, |
| @code{GPLUSPLUS_INCLUDE_DIR}, and |
| @code{NATIVE_SYSTEM_HEADER_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} |
| and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, |
| and specify private search areas for GCC@. The directory |
| @code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. |
| |
| The definition should be an initializer for an array of structures. |
| Each array element should have four elements: the directory name (a |
| string constant), the component name (also a string constant), a flag |
| for C++-only directories, |
| and a flag showing that the includes in the directory don't need to be |
| wrapped in @code{extern @samp{C}} when compiling C++. Mark the end of |
| the array with a null element. |
| |
| The component name denotes what GNU package the include file is part of, |
| if any, in all uppercase letters. For example, it might be @samp{GCC} |
| or @samp{BINUTILS}. If the package is part of a vendor-supplied |
| operating system, code the component name as @samp{0}. |
| |
| For example, here is the definition used for VAX/VMS: |
| |
| @smallexample |
| #define INCLUDE_DEFAULTS \ |
| @{ \ |
| @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ |
| @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \ |
| @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \ |
| @{ ".", 0, 0, 0@}, \ |
| @{ 0, 0, 0, 0@} \ |
| @} |
| @end smallexample |
| @end defmac |
| |
| Here is the order of prefixes tried for exec files: |
| |
| @enumerate |
| @item |
| Any prefixes specified by the user with @option{-B}. |
| |
| @item |
| The environment variable @code{GCC_EXEC_PREFIX} or, if @code{GCC_EXEC_PREFIX} |
| is not set and the compiler has not been installed in the configure-time |
| @var{prefix}, the location in which the compiler has actually been installed. |
| |
| @item |
| The directories specified by the environment variable @code{COMPILER_PATH}. |
| |
| @item |
| The macro @code{STANDARD_EXEC_PREFIX}, if the compiler has been installed |
| in the configured-time @var{prefix}. |
| |
| @item |
| The location @file{/usr/libexec/gcc/}, but only if this is a native compiler. |
| |
| @item |
| The location @file{/usr/lib/gcc/}, but only if this is a native compiler. |
| |
| @item |
| The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native |
| compiler. |
| @end enumerate |
| |
| Here is the order of prefixes tried for startfiles: |
| |
| @enumerate |
| @item |
| Any prefixes specified by the user with @option{-B}. |
| |
| @item |
| The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined |
| value based on the installed toolchain location. |
| |
| @item |
| The directories specified by the environment variable @code{LIBRARY_PATH} |
| (or port-specific name; native only, cross compilers do not use this). |
| |
| @item |
| The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed |
| in the configured @var{prefix} or this is a native compiler. |
| |
| @item |
| The location @file{/usr/lib/gcc/}, but only if this is a native compiler. |
| |
| @item |
| The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native |
| compiler. |
| |
| @item |
| The macro @code{MD_STARTFILE_PREFIX}, if defined, but only if this is a |
| native compiler, or we have a target system root. |
| |
| @item |
| The macro @code{MD_STARTFILE_PREFIX_1}, if defined, but only if this is a |
| native compiler, or we have a target system root. |
| |
| @item |
| The macro @code{STANDARD_STARTFILE_PREFIX}, with any sysroot modifications. |
| If this path is relative it will be prefixed by @code{GCC_EXEC_PREFIX} and |
| the machine suffix or @code{STANDARD_EXEC_PREFIX} and the machine suffix. |
| |
| @item |
| The macro @code{STANDARD_STARTFILE_PREFIX_1}, but only if this is a native |
| compiler, or we have a target system root. The default for this macro is |
| @file{/lib/}. |
| |
| @item |
| The macro @code{STANDARD_STARTFILE_PREFIX_2}, but only if this is a native |
| compiler, or we have a target system root. The default for this macro is |
| @file{/usr/lib/}. |
| @end enumerate |
| |
| @node Run-time Target |
| @section Run-time Target Specification |
| @cindex run-time target specification |
| @cindex predefined macros |
| @cindex target specifications |
| |
| @c prevent bad page break with this line |
| Here are run-time target specifications. |
| |
| @defmac TARGET_CPU_CPP_BUILTINS () |
| This function-like macro expands to a block of code that defines |
| built-in preprocessor macros and assertions for the target CPU, using |
| the functions @code{builtin_define}, @code{builtin_define_std} and |
| @code{builtin_assert}. When the front end |
| calls this macro it provides a trailing semicolon, and since it has |
| finished command line option processing your code can use those |
| results freely. |
| |
| @code{builtin_assert} takes a string in the form you pass to the |
| command-line option @option{-A}, such as @code{cpu=mips}, and creates |
| the assertion. @code{builtin_define} takes a string in the form |
| accepted by option @option{-D} and unconditionally defines the macro. |
| |
| @code{builtin_define_std} takes a string representing the name of an |
| object-like macro. If it doesn't lie in the user's namespace, |
| @code{builtin_define_std} defines it unconditionally. Otherwise, it |
| defines a version with two leading underscores, and another version |
| with two leading and trailing underscores, and defines the original |
| only if an ISO standard was not requested on the command line. For |
| example, passing @code{unix} defines @code{__unix}, @code{__unix__} |
| and possibly @code{unix}; passing @code{_mips} defines @code{__mips}, |
| @code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64} |
| defines only @code{_ABI64}. |
| |
| You can also test for the C dialect being compiled. The variable |
| @code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus} |
| or @code{clk_objective_c}. Note that if we are preprocessing |
| assembler, this variable will be @code{clk_c} but the function-like |
| macro @code{preprocessing_asm_p()} will return true, so you might want |
| to check for that first. If you need to check for strict ANSI, the |
| variable @code{flag_iso} can be used. The function-like macro |
| @code{preprocessing_trad_p()} can be used to check for traditional |
| preprocessing. |
| @end defmac |
| |
| @defmac TARGET_OS_CPP_BUILTINS () |
| Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional |
| and is used for the target operating system instead. |
| @end defmac |
| |
| @defmac TARGET_OBJFMT_CPP_BUILTINS () |
| Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional |
| and is used for the target object format. @file{elfos.h} uses this |
| macro to define @code{__ELF__}, so you probably do not need to define |
| it yourself. |
| @end defmac |
| |
| @deftypevar {extern int} target_flags |
| This variable is declared in @file{options.h}, which is included before |
| any target-specific headers. |
| @end deftypevar |
| |
| @deftypevr {Common Target Hook} int TARGET_DEFAULT_TARGET_FLAGS |
| This variable specifies the initial value of @code{target_flags}. |
| Its default setting is 0. |
| @end deftypevr |
| |
| @cindex optional hardware or system features |
| @cindex features, optional, in system conventions |
| |
| @deftypefn {Common Target Hook} bool TARGET_HANDLE_OPTION (struct gcc_options *@var{opts}, struct gcc_options *@var{opts_set}, const struct cl_decoded_option *@var{decoded}, location_t @var{loc}) |
| This hook is called whenever the user specifies one of the |
| target-specific options described by the @file{.opt} definition files |
| (@pxref{Options}). It has the opportunity to do some option-specific |
| processing and should return true if the option is valid. The default |
| definition does nothing but return true. |
| |
| @var{decoded} specifies the option and its arguments. @var{opts} and |
| @var{opts_set} are the @code{gcc_options} structures to be used for |
| storing option state, and @var{loc} is the location at which the |
| option was passed (@code{UNKNOWN_LOCATION} except for options passed |
| via attributes). |
| @end deftypefn |
| |
| @deftypefn {C Target Hook} bool TARGET_HANDLE_C_OPTION (size_t @var{code}, const char *@var{arg}, int @var{value}) |
| This target hook is called whenever the user specifies one of the |
| target-specific C language family options described by the @file{.opt} |
| definition files(@pxref{Options}). It has the opportunity to do some |
| option-specific processing and should return true if the option is |
| valid. The arguments are like for @code{TARGET_HANDLE_OPTION}. The |
| default definition does nothing but return false. |
| |
| In general, you should use @code{TARGET_HANDLE_OPTION} to handle |
| options. However, if processing an option requires routines that are |
| only available in the C (and related language) front ends, then you |
| should use @code{TARGET_HANDLE_C_OPTION} instead. |
| @end deftypefn |
| |
| @deftypefn {C Target Hook} tree TARGET_OBJC_CONSTRUCT_STRING_OBJECT (tree @var{string}) |
| Targets may provide a string object type that can be used within |
| and between C, C++ and their respective Objective-C dialects. |
| A string object might, for example, embed encoding and length information. |
| These objects are considered opaque to the compiler and handled as references. |
| An ideal implementation makes the composition of the string object |
| match that of the Objective-C @code{NSString} (@code{NXString} for GNUStep), |
| allowing efficient interworking between C-only and Objective-C code. |
| If a target implements string objects then this hook should return a |
| reference to such an object constructed from the normal `C' string |
| representation provided in @var{string}. |
| At present, the hook is used by Objective-C only, to obtain a |
| common-format string object when the target provides one. |
| @end deftypefn |
| |
| @deftypefn {C Target Hook} void TARGET_OBJC_DECLARE_UNRESOLVED_CLASS_REFERENCE (const char *@var{classname}) |
| Declare that Objective C class @var{classname} is referenced |
| by the current TU. |
| @end deftypefn |
| |
| @deftypefn {C Target Hook} void TARGET_OBJC_DECLARE_CLASS_DEFINITION (const char *@var{classname}) |
| Declare that Objective C class @var{classname} is defined |
| by the current TU. |
| @end deftypefn |
| |
| @deftypefn {C Target Hook} bool TARGET_STRING_OBJECT_REF_TYPE_P (const_tree @var{stringref}) |
| If a target implements string objects then this hook should return |
| @code{true} if @var{stringref} is a valid reference to such an object. |
| @end deftypefn |
| |
| @deftypefn {C Target Hook} void TARGET_CHECK_STRING_OBJECT_FORMAT_ARG (tree @var{format_arg}, tree @var{args_list}) |
| If a target implements string objects then this hook should should |
| provide a facility to check the function arguments in @var{args_list} |
| against the format specifiers in @var{format_arg} where the type of |
| @var{format_arg} is one recognized as a valid string reference type. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} void TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE (void) |
| This target function is similar to the hook @code{TARGET_OPTION_OVERRIDE} |
| but is called when the optimize level is changed via an attribute or |
| pragma or when it is reset at the end of the code affected by the |
| attribute or pragma. It is not called at the beginning of compilation |
| when @code{TARGET_OPTION_OVERRIDE} is called so if you want to perform these |
| actions then, you should have @code{TARGET_OPTION_OVERRIDE} call |
| @code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}. |
| @end deftypefn |
| |
| @defmac C_COMMON_OVERRIDE_OPTIONS |
| This is similar to the @code{TARGET_OPTION_OVERRIDE} hook |
| but is only used in the C |
| language frontends (C, Objective-C, C++, Objective-C++) and so can be |
| used to alter option flag variables which only exist in those |
| frontends. |
| @end defmac |
| |
| @deftypevr {Common Target Hook} {const struct default_options *} TARGET_OPTION_OPTIMIZATION_TABLE |
| Some machines may desire to change what optimizations are performed for |
| various optimization levels. This variable, if defined, describes |
| options to enable at particular sets of optimization levels. These |
| options are processed once |
| just after the optimization level is determined and before the remainder |
| of the command options have been parsed, so may be overridden by other |
| options passed explicitly. |
| |
| This processing is run once at program startup and when the optimization |
| options are changed via @code{#pragma GCC optimize} or by using the |
| @code{optimize} attribute. |
| @end deftypevr |
| |
| @deftypefn {Common Target Hook} void TARGET_OPTION_INIT_STRUCT (struct gcc_options *@var{opts}) |
| Set target-dependent initial values of fields in @var{opts}. |
| @end deftypefn |
| |
| @defmac SWITCHABLE_TARGET |
| Some targets need to switch between substantially different subtargets |
| during compilation. For example, the MIPS target has one subtarget for |
| the traditional MIPS architecture and another for MIPS16. Source code |
| can switch between these two subarchitectures using the @code{mips16} |
| and @code{nomips16} attributes. |
| |
| Such subtargets can differ in things like the set of available |
| registers, the set of available instructions, the costs of various |
| operations, and so on. GCC caches a lot of this type of information |
| in global variables, and recomputing them for each subtarget takes a |
| significant amount of time. The compiler therefore provides a facility |
| for maintaining several versions of the global variables and quickly |
| switching between them; see @file{target-globals.h} for details. |
| |
| Define this macro to 1 if your target needs this facility. The default |
| is 0. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_FLOAT_EXCEPTIONS_ROUNDING_SUPPORTED_P (void) |
| Returns true if the target supports IEEE 754 floating-point exceptions |
| and rounding modes, false otherwise. This is intended to relate to the |
| @code{float} and @code{double} types, but not necessarily @code{long double}. |
| By default, returns true if the @code{adddf3} instruction pattern is |
| available and false otherwise, on the assumption that hardware floating |
| point supports exceptions and rounding modes but software floating point |
| does not. |
| @end deftypefn |
| |
| @node Per-Function Data |
| @section Defining data structures for per-function information. |
| @cindex per-function data |
| @cindex data structures |
| |
| If the target needs to store information on a per-function basis, GCC |
| provides a macro and a couple of variables to allow this. Note, just |
| using statics to store the information is a bad idea, since GCC supports |
| nested functions, so you can be halfway through encoding one function |
| when another one comes along. |
| |
| GCC defines a data structure called @code{struct function} which |
| contains all of the data specific to an individual function. This |
| structure contains a field called @code{machine} whose type is |
| @code{struct machine_function *}, which can be used by targets to point |
| to their own specific data. |
| |
| If a target needs per-function specific data it should define the type |
| @code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. |
| This macro should be used to initialize the function pointer |
| @code{init_machine_status}. This pointer is explained below. |
| |
| One typical use of per-function, target specific data is to create an |
| RTX to hold the register containing the function's return address. This |
| RTX can then be used to implement the @code{__builtin_return_address} |
| function, for level 0. |
| |
| Note---earlier implementations of GCC used a single data area to hold |
| all of the per-function information. Thus when processing of a nested |
| function began the old per-function data had to be pushed onto a |
| stack, and when the processing was finished, it had to be popped off the |
| stack. GCC used to provide function pointers called |
| @code{save_machine_status} and @code{restore_machine_status} to handle |
| the saving and restoring of the target specific information. Since the |
| single data area approach is no longer used, these pointers are no |
| longer supported. |
| |
| @defmac INIT_EXPANDERS |
| Macro called to initialize any target specific information. This macro |
| is called once per function, before generation of any RTL has begun. |
| The intention of this macro is to allow the initialization of the |
| function pointer @code{init_machine_status}. |
| @end defmac |
| |
| @deftypevar {void (*)(struct function *)} init_machine_status |
| If this function pointer is non-@code{NULL} it will be called once per |
| function, before function compilation starts, in order to allow the |
| target to perform any target specific initialization of the |
| @code{struct function} structure. It is intended that this would be |
| used to initialize the @code{machine} of that structure. |
| |
| @code{struct machine_function} structures are expected to be freed by GC@. |
| Generally, any memory that they reference must be allocated by using |
| GC allocation, including the structure itself. |
| @end deftypevar |
| |
| @node Storage Layout |
| @section Storage Layout |
| @cindex storage layout |
| |
| Note that the definitions of the macros in this table which are sizes or |
| alignments measured in bits do not need to be constant. They can be C |
| expressions that refer to static variables, such as the @code{target_flags}. |
| @xref{Run-time Target}. |
| |
| @defmac BITS_BIG_ENDIAN |
| Define this macro to have the value 1 if the most significant bit in a |
| byte has the lowest number; otherwise define it to have the value zero. |
| This means that bit-field instructions count from the most significant |
| bit. If the machine has no bit-field instructions, then this must still |
| be defined, but it doesn't matter which value it is defined to. This |
| macro need not be a constant. |
| |
| This macro does not affect the way structure fields are packed into |
| bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. |
| @end defmac |
| |
| @defmac BYTES_BIG_ENDIAN |
| Define this macro to have the value 1 if the most significant byte in a |
| word has the lowest number. This macro need not be a constant. |
| @end defmac |
| |
| @defmac WORDS_BIG_ENDIAN |
| Define this macro to have the value 1 if, in a multiword object, the |
| most significant word has the lowest number. This applies to both |
| memory locations and registers; see @code{REG_WORDS_BIG_ENDIAN} if the |
| order of words in memory is not the same as the order in registers. This |
| macro need not be a constant. |
| @end defmac |
| |
| @defmac REG_WORDS_BIG_ENDIAN |
| On some machines, the order of words in a multiword object differs between |
| registers in memory. In such a situation, define this macro to describe |
| the order of words in a register. The macro @code{WORDS_BIG_ENDIAN} controls |
| the order of words in memory. |
| @end defmac |
| |
| @defmac FLOAT_WORDS_BIG_ENDIAN |
| Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or |
| @code{TFmode} floating point numbers are stored in memory with the word |
| containing the sign bit at the lowest address; otherwise define it to |
| have the value 0. This macro need not be a constant. |
| |
| You need not define this macro if the ordering is the same as for |
| multi-word integers. |
| @end defmac |
| |
| @defmac BITS_PER_WORD |
| Number of bits in a word. If you do not define this macro, the default |
| is @code{BITS_PER_UNIT * UNITS_PER_WORD}. |
| @end defmac |
| |
| @defmac MAX_BITS_PER_WORD |
| Maximum number of bits in a word. If this is undefined, the default is |
| @code{BITS_PER_WORD}. Otherwise, it is the constant value that is the |
| largest value that @code{BITS_PER_WORD} can have at run-time. |
| @end defmac |
| |
| @defmac UNITS_PER_WORD |
| Number of storage units in a word; normally the size of a general-purpose |
| register, a power of two from 1 or 8. |
| @end defmac |
| |
| @defmac MIN_UNITS_PER_WORD |
| Minimum number of units in a word. If this is undefined, the default is |
| @code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the |
| smallest value that @code{UNITS_PER_WORD} can have at run-time. |
| @end defmac |
| |
| @defmac POINTER_SIZE |
| Width of a pointer, in bits. You must specify a value no wider than the |
| width of @code{Pmode}. If it is not equal to the width of @code{Pmode}, |
| you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify |
| a value the default is @code{BITS_PER_WORD}. |
| @end defmac |
| |
| @defmac POINTERS_EXTEND_UNSIGNED |
| A C expression that determines how pointers should be extended from |
| @code{ptr_mode} to either @code{Pmode} or @code{word_mode}. It is |
| greater than zero if pointers should be zero-extended, zero if they |
| should be sign-extended, and negative if some other sort of conversion |
| is needed. In the last case, the extension is done by the target's |
| @code{ptr_extend} instruction. |
| |
| You need not define this macro if the @code{ptr_mode}, @code{Pmode} |
| and @code{word_mode} are all the same width. |
| @end defmac |
| |
| @defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) |
| A macro to update @var{m} and @var{unsignedp} when an object whose type |
| is @var{type} and which has the specified mode and signedness is to be |
| stored in a register. This macro is only called when @var{type} is a |
| scalar type. |
| |
| On most RISC machines, which only have operations that operate on a full |
| register, define this macro to set @var{m} to @code{word_mode} if |
| @var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most |
| cases, only integer modes should be widened because wider-precision |
| floating-point operations are usually more expensive than their narrower |
| counterparts. |
| |
| For most machines, the macro definition does not change @var{unsignedp}. |
| However, some machines, have instructions that preferentially handle |
| either signed or unsigned quantities of certain modes. For example, on |
| the DEC Alpha, 32-bit loads from memory and 32-bit add instructions |
| sign-extend the result to 64 bits. On such machines, set |
| @var{unsignedp} according to which kind of extension is more efficient. |
| |
| Do not define this macro if it would never modify @var{m}. |
| @end defmac |
| |
| @deftypefn {Target Hook} {enum flt_eval_method} TARGET_C_EXCESS_PRECISION (enum excess_precision_type @var{type}) |
| Return a value, with the same meaning as the C99 macro |
| @code{FLT_EVAL_METHOD} that describes which excess precision should be |
| applied. @var{type} is either @code{EXCESS_PRECISION_TYPE_IMPLICIT}, |
| @code{EXCESS_PRECISION_TYPE_FAST}, |
| @code{EXCESS_PRECISION_TYPE_STANDARD}, or |
| @code{EXCESS_PRECISION_TYPE_FLOAT16}. For |
| @code{EXCESS_PRECISION_TYPE_IMPLICIT}, the target should return which |
| precision and range operations will be implictly evaluated in regardless |
| of the excess precision explicitly added. For |
| @code{EXCESS_PRECISION_TYPE_STANDARD}, |
| @code{EXCESS_PRECISION_TYPE_FLOAT16}, and |
| @code{EXCESS_PRECISION_TYPE_FAST}, the target should return the |
| explicit excess precision that should be added depending on the |
| value set for @option{-fexcess-precision=@r{[}standard@r{|}fast@r{]}}. |
| Note that unpredictable explicit excess precision does not make sense, |
| so a target should never return @code{FLT_EVAL_METHOD_UNPREDICTABLE} |
| when @var{type} is @code{EXCESS_PRECISION_TYPE_STANDARD}, |
| @code{EXCESS_PRECISION_TYPE_FLOAT16} or |
| @code{EXCESS_PRECISION_TYPE_FAST}. |
| @end deftypefn |
| Return a value, with the same meaning as the C99 macro |
| @code{FLT_EVAL_METHOD} that describes which excess precision should be |
| applied. |
| |
| @deftypefn {Target Hook} machine_mode TARGET_PROMOTE_FUNCTION_MODE (const_tree @var{type}, machine_mode @var{mode}, int *@var{punsignedp}, const_tree @var{funtype}, int @var{for_return}) |
| Like @code{PROMOTE_MODE}, but it is applied to outgoing function arguments or |
| function return values. The target hook should return the new mode |
| and possibly change @code{*@var{punsignedp}} if the promotion should |
| change signedness. This function is called only for scalar @emph{or |
| pointer} types. |
| |
| @var{for_return} allows to distinguish the promotion of arguments and |
| return values. If it is @code{1}, a return value is being promoted and |
| @code{TARGET_FUNCTION_VALUE} must perform the same promotions done here. |
| If it is @code{2}, the returned mode should be that of the register in |
| which an incoming parameter is copied, or the outgoing result is computed; |
| then the hook should return the same mode as @code{promote_mode}, though |
| the signedness may be different. |
| |
| @var{type} can be NULL when promoting function arguments of libcalls. |
| |
| The default is to not promote arguments and return values. You can |
| also define the hook to @code{default_promote_function_mode_always_promote} |
| if you would like to apply the same rules given by @code{PROMOTE_MODE}. |
| @end deftypefn |
| |
| @defmac PARM_BOUNDARY |
| Normal alignment required for function parameters on the stack, in |
| bits. All stack parameters receive at least this much alignment |
| regardless of data type. On most machines, this is the same as the |
| size of an integer. |
| @end defmac |
| |
| @defmac STACK_BOUNDARY |
| Define this macro to the minimum alignment enforced by hardware for the |
| stack pointer on this machine. The definition is a C expression for the |
| desired alignment (measured in bits). This value is used as a default |
| if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, |
| this should be the same as @code{PARM_BOUNDARY}. |
| @end defmac |
| |
| @defmac PREFERRED_STACK_BOUNDARY |
| Define this macro if you wish to preserve a certain alignment for the |
| stack pointer, greater than what the hardware enforces. The definition |
| is a C expression for the desired alignment (measured in bits). This |
| macro must evaluate to a value equal to or larger than |
| @code{STACK_BOUNDARY}. |
| @end defmac |
| |
| @defmac INCOMING_STACK_BOUNDARY |
| Define this macro if the incoming stack boundary may be different |
| from @code{PREFERRED_STACK_BOUNDARY}. This macro must evaluate |
| to a value equal to or larger than @code{STACK_BOUNDARY}. |
| @end defmac |
| |
| @defmac FUNCTION_BOUNDARY |
| Alignment required for a function entry point, in bits. |
| @end defmac |
| |
| @defmac BIGGEST_ALIGNMENT |
| Biggest alignment that any data type can require on this machine, in |
| bits. Note that this is not the biggest alignment that is supported, |
| just the biggest alignment that, when violated, may cause a fault. |
| @end defmac |
| |
| @deftypevr {Target Hook} HOST_WIDE_INT TARGET_ABSOLUTE_BIGGEST_ALIGNMENT |
| If defined, this target hook specifies the absolute biggest alignment |
| that a type or variable can have on this machine, otherwise, |
| @code{BIGGEST_ALIGNMENT} is used. |
| @end deftypevr |
| |
| @defmac MALLOC_ABI_ALIGNMENT |
| Alignment, in bits, a C conformant malloc implementation has to |
| provide. If not defined, the default value is @code{BITS_PER_WORD}. |
| @end defmac |
| |
| @defmac ATTRIBUTE_ALIGNED_VALUE |
| Alignment used by the @code{__attribute__ ((aligned))} construct. If |
| not defined, the default value is @code{BIGGEST_ALIGNMENT}. |
| @end defmac |
| |
| @defmac MINIMUM_ATOMIC_ALIGNMENT |
| If defined, the smallest alignment, in bits, that can be given to an |
| object that can be referenced in one operation, without disturbing any |
| nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger |
| on machines that don't have byte or half-word store operations. |
| @end defmac |
| |
| @defmac BIGGEST_FIELD_ALIGNMENT |
| Biggest alignment that any structure or union field can require on this |
| machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for |
| structure and union fields only, unless the field alignment has been set |
| by the @code{__attribute__ ((aligned (@var{n})))} construct. |
| @end defmac |
| |
| @defmac ADJUST_FIELD_ALIGN (@var{field}, @var{type}, @var{computed}) |
| An expression for the alignment of a structure field @var{field} of |
| type @var{type} if the alignment computed in the usual way (including |
| applying of @code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the |
| alignment) is @var{computed}. It overrides alignment only if the |
| field alignment has not been set by the |
| @code{__attribute__ ((aligned (@var{n})))} construct. Note that @var{field} |
| may be @code{NULL_TREE} in case we just query for the minimum alignment |
| of a field of type @var{type} in structure context. |
| @end defmac |
| |
| @defmac MAX_STACK_ALIGNMENT |
| Biggest stack alignment guaranteed by the backend. Use this macro |
| to specify the maximum alignment of a variable on stack. |
| |
| If not defined, the default value is @code{STACK_BOUNDARY}. |
| |
| @c FIXME: The default should be @code{PREFERRED_STACK_BOUNDARY}. |
| @c But the fix for PR 32893 indicates that we can only guarantee |
| @c maximum stack alignment on stack up to @code{STACK_BOUNDARY}, not |
| @c @code{PREFERRED_STACK_BOUNDARY}, if stack alignment isn't supported. |
| @end defmac |
| |
| @defmac MAX_OFILE_ALIGNMENT |
| Biggest alignment supported by the object file format of this machine. |
| Use this macro to limit the alignment which can be specified using the |
| @code{__attribute__ ((aligned (@var{n})))} construct for functions and |
| objects with static storage duration. The alignment of automatic |
| objects may exceed the object file format maximum up to the maximum |
| supported by GCC. If not defined, the default value is |
| @code{BIGGEST_ALIGNMENT}. |
| |
| On systems that use ELF, the default (in @file{config/elfos.h}) is |
| the largest supported 32-bit ELF section alignment representable on |
| a 32-bit host e.g.@: @samp{(((uint64_t) 1 << 28) * 8)}. |
| On 32-bit ELF the largest supported section alignment in bits is |
| @samp{(0x80000000 * 8)}, but this is not representable on 32-bit hosts. |
| @end defmac |
| |
| @deftypefn {Target Hook} void TARGET_LOWER_LOCAL_DECL_ALIGNMENT (tree @var{decl}) |
| Define this hook to lower alignment of local, parm or result |
| decl @samp{(@var{decl})}. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} HOST_WIDE_INT TARGET_STATIC_RTX_ALIGNMENT (machine_mode @var{mode}) |
| This hook returns the preferred alignment in bits for a |
| statically-allocated rtx, such as a constant pool entry. @var{mode} |
| is the mode of the rtx. The default implementation returns |
| @samp{GET_MODE_ALIGNMENT (@var{mode})}. |
| @end deftypefn |
| |
| @defmac DATA_ALIGNMENT (@var{type}, @var{basic-align}) |
| If defined, a C expression to compute the alignment for a variable in |
| the static store. @var{type} is the data type, and @var{basic-align} is |
| the alignment that the object would ordinarily have. The value of this |
| macro is used instead of that alignment to align the object. |
| |
| If this macro is not defined, then @var{basic-align} is used. |
| |
| @findex strcpy |
| One use of this macro is to increase alignment of medium-size data to |
| make it all fit in fewer cache lines. Another is to cause character |
| arrays to be word-aligned so that @code{strcpy} calls that copy |
| constants to character arrays can be done inline. |
| @end defmac |
| |
| @defmac DATA_ABI_ALIGNMENT (@var{type}, @var{basic-align}) |
| Similar to @code{DATA_ALIGNMENT}, but for the cases where the ABI mandates |
| some alignment increase, instead of optimization only purposes. E.g.@ |
| AMD x86-64 psABI says that variables with array type larger than 15 bytes |
| must be aligned to 16 byte boundaries. |
| |
| If this macro is not defined, then @var{basic-align} is used. |
| @end defmac |
| |
| @deftypefn {Target Hook} HOST_WIDE_INT TARGET_CONSTANT_ALIGNMENT (const_tree @var{constant}, HOST_WIDE_INT @var{basic_align}) |
| This hook returns the alignment in bits of a constant that is being |
| placed in memory. @var{constant} is the constant and @var{basic_align} |
| is the alignment that the object would ordinarily have. |
| |
| The default definition just returns @var{basic_align}. |
| |
| The typical use of this hook is to increase alignment for string |
| constants to be word aligned so that @code{strcpy} calls that copy |
| constants can be done inline. The function |
| @code{constant_alignment_word_strings} provides such a definition. |
| @end deftypefn |
| |
| @defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) |
| If defined, a C expression to compute the alignment for a variable in |
| the local store. @var{type} is the data type, and @var{basic-align} is |
| the alignment that the object would ordinarily have. The value of this |
| macro is used instead of that alignment to align the object. |
| |
| If this macro is not defined, then @var{basic-align} is used. |
| |
| One use of this macro is to increase alignment of medium-size data to |
| make it all fit in fewer cache lines. |
| |
| If the value of this macro has a type, it should be an unsigned type. |
| @end defmac |
| |
| @deftypefn {Target Hook} HOST_WIDE_INT TARGET_VECTOR_ALIGNMENT (const_tree @var{type}) |
| This hook can be used to define the alignment for a vector of type |
| @var{type}, in order to comply with a platform ABI. The default is to |
| require natural alignment for vector types. The alignment returned by |
| this hook must be a power-of-two multiple of the default alignment of |
| the vector element type. |
| @end deftypefn |
| |
| @defmac STACK_SLOT_ALIGNMENT (@var{type}, @var{mode}, @var{basic-align}) |
| If defined, a C expression to compute the alignment for stack slot. |
| @var{type} is the data type, @var{mode} is the widest mode available, |
| and @var{basic-align} is the alignment that the slot would ordinarily |
| have. The value of this macro is used instead of that alignment to |
| align the slot. |
| |
| If this macro is not defined, then @var{basic-align} is used when |
| @var{type} is @code{NULL}. Otherwise, @code{LOCAL_ALIGNMENT} will |
| be used. |
| |
| This macro is to set alignment of stack slot to the maximum alignment |
| of all possible modes which the slot may have. |
| |
| If the value of this macro has a type, it should be an unsigned type. |
| @end defmac |
| |
| @defmac LOCAL_DECL_ALIGNMENT (@var{decl}) |
| If defined, a C expression to compute the alignment for a local |
| variable @var{decl}. |
| |
| If this macro is not defined, then |
| @code{LOCAL_ALIGNMENT (TREE_TYPE (@var{decl}), DECL_ALIGN (@var{decl}))} |
| is used. |
| |
| One use of this macro is to increase alignment of medium-size data to |
| make it all fit in fewer cache lines. |
| |
| If the value of this macro has a type, it should be an unsigned type. |
| @end defmac |
| |
| @defmac MINIMUM_ALIGNMENT (@var{exp}, @var{mode}, @var{align}) |
| If defined, a C expression to compute the minimum required alignment |
| for dynamic stack realignment purposes for @var{exp} (a type or decl), |
| @var{mode}, assuming normal alignment @var{align}. |
| |
| If this macro is not defined, then @var{align} will be used. |
| @end defmac |
| |
| @defmac EMPTY_FIELD_BOUNDARY |
| Alignment in bits to be given to a structure bit-field that follows an |
| empty field such as @code{int : 0;}. |
| |
| If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro. |
| @end defmac |
| |
| @defmac STRUCTURE_SIZE_BOUNDARY |
| Number of bits which any structure or union's size must be a multiple of. |
| Each structure or union's size is rounded up to a multiple of this. |
| |
| If you do not define this macro, the default is the same as |
| @code{BITS_PER_UNIT}. |
| @end defmac |
| |
| @defmac STRICT_ALIGNMENT |
| Define this macro to be the value 1 if instructions will fail to work |
| if given data not on the nominal alignment. If instructions will merely |
| go slower in that case, define this macro as 0. |
| @end defmac |
| |
| @defmac PCC_BITFIELD_TYPE_MATTERS |
| Define this if you wish to imitate the way many other C compilers handle |
| alignment of bit-fields and the structures that contain them. |
| |
| The behavior is that the type written for a named bit-field (@code{int}, |
| @code{short}, or other integer type) imposes an alignment for the entire |
| structure, as if the structure really did contain an ordinary field of |
| that type. In addition, the bit-field is placed within the structure so |
| that it would fit within such a field, not crossing a boundary for it. |
| |
| Thus, on most machines, a named bit-field whose type is written as |
| @code{int} would not cross a four-byte boundary, and would force |
| four-byte alignment for the whole structure. (The alignment used may |
| not be four bytes; it is controlled by the other alignment parameters.) |
| |
| An unnamed bit-field will not affect the alignment of the containing |
| structure. |
| |
| If the macro is defined, its definition should be a C expression; |
| a nonzero value for the expression enables this behavior. |
| |
| Note that if this macro is not defined, or its value is zero, some |
| bit-fields may cross more than one alignment boundary. The compiler can |
| support such references if there are @samp{insv}, @samp{extv}, and |
| @samp{extzv} insns that can directly reference memory. |
| |
| The other known way of making bit-fields work is to define |
| @code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. |
| Then every structure can be accessed with fullwords. |
| |
| Unless the machine has bit-field instructions or you define |
| @code{STRUCTURE_SIZE_BOUNDARY} that way, you must define |
| @code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. |
| |
| If your aim is to make GCC use the same conventions for laying out |
| bit-fields as are used by another compiler, here is how to investigate |
| what the other compiler does. Compile and run this program: |
| |
| @smallexample |
| struct foo1 |
| @{ |
| char x; |
| char :0; |
| char y; |
| @}; |
| |
| struct foo2 |
| @{ |
| char x; |
| int :0; |
| char y; |
| @}; |
| |
| main () |
| @{ |
| printf ("Size of foo1 is %d\n", |
| sizeof (struct foo1)); |
| printf ("Size of foo2 is %d\n", |
| sizeof (struct foo2)); |
| exit (0); |
| @} |
| @end smallexample |
| |
| If this prints 2 and 5, then the compiler's behavior is what you would |
| get from @code{PCC_BITFIELD_TYPE_MATTERS}. |
| @end defmac |
| |
| @defmac BITFIELD_NBYTES_LIMITED |
| Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited |
| to aligning a bit-field within the structure. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_ALIGN_ANON_BITFIELD (void) |
| When @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine |
| whether unnamed bitfields affect the alignment of the containing |
| structure. The hook should return true if the structure should inherit |
| the alignment requirements of an unnamed bitfield's type. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_NARROW_VOLATILE_BITFIELD (void) |
| This target hook should return @code{true} if accesses to volatile bitfields |
| should use the narrowest mode possible. It should return @code{false} if |
| these accesses should use the bitfield container type. |
| |
| The default is @code{false}. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_MEMBER_TYPE_FORCES_BLK (const_tree @var{field}, machine_mode @var{mode}) |
| Return true if a structure, union or array containing @var{field} should |
| be accessed using @code{BLKMODE}. |
| |
| If @var{field} is the only field in the structure, @var{mode} is its |
| mode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the |
| case where structures of one field would require the structure's mode to |
| retain the field's mode. |
| |
| Normally, this is not needed. |
| @end deftypefn |
| |
| @defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) |
| Define this macro as an expression for the alignment of a type (given |
| by @var{type} as a tree node) if the alignment computed in the usual |
| way is @var{computed} and the alignment explicitly specified was |
| @var{specified}. |
| |
| The default is to use @var{specified} if it is larger; otherwise, use |
| the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} |
| @end defmac |
| |
| @defmac MAX_FIXED_MODE_SIZE |
| An integer expression for the size in bits of the largest integer |
| machine mode that should actually be used. All integer machine modes of |
| this size or smaller can be used for structures and unions with the |
| appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE |
| (DImode)} is assumed. |
| @end defmac |
| |
| @defmac STACK_SAVEAREA_MODE (@var{save_level}) |
| If defined, an expression of type @code{machine_mode} that |
| specifies the mode of the save area operand of a |
| @code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). |
| @var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or |
| @code{SAVE_NONLOCAL} and selects which of the three named patterns is |
| having its mode specified. |
| |
| You need not define this macro if it always returns @code{Pmode}. You |
| would most commonly define this macro if the |
| @code{save_stack_@var{level}} patterns need to support both a 32- and a |
| 64-bit mode. |
| @end defmac |
| |
| @defmac STACK_SIZE_MODE |
| If defined, an expression of type @code{machine_mode} that |
| specifies the mode of the size increment operand of an |
| @code{allocate_stack} named pattern (@pxref{Standard Names}). |
| |
| You need not define this macro if it always returns @code{word_mode}. |
| You would most commonly define this macro if the @code{allocate_stack} |
| pattern needs to support both a 32- and a 64-bit mode. |
| @end defmac |
| |
| @deftypefn {Target Hook} scalar_int_mode TARGET_LIBGCC_CMP_RETURN_MODE (void) |
| This target hook should return the mode to be used for the return value |
| of compare instructions expanded to libgcc calls. If not defined |
| @code{word_mode} is returned which is the right choice for a majority of |
| targets. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} scalar_int_mode TARGET_LIBGCC_SHIFT_COUNT_MODE (void) |
| This target hook should return the mode to be used for the shift count operand |
| of shift instructions expanded to libgcc calls. If not defined |
| @code{word_mode} is returned which is the right choice for a majority of |
| targets. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} scalar_int_mode TARGET_UNWIND_WORD_MODE (void) |
| Return machine mode to be used for @code{_Unwind_Word} type. |
| The default is to use @code{word_mode}. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (const_tree @var{record_type}) |
| This target hook returns @code{true} if bit-fields in the given |
| @var{record_type} are to be laid out following the rules of Microsoft |
| Visual C/C++, namely: (i) a bit-field won't share the same storage |
| unit with the previous bit-field if their underlying types have |
| different sizes, and the bit-field will be aligned to the highest |
| alignment of the underlying types of itself and of the previous |
| bit-field; (ii) a zero-sized bit-field will affect the alignment of |
| the whole enclosing structure, even if it is unnamed; except that |
| (iii) a zero-sized bit-field will be disregarded unless it follows |
| another bit-field of nonzero size. If this hook returns @code{true}, |
| other macros that control bit-field layout are ignored. |
| |
| When a bit-field is inserted into a packed record, the whole size |
| of the underlying type is used by one or more same-size adjacent |
| bit-fields (that is, if its long:3, 32 bits is used in the record, |
| and any additional adjacent long bit-fields are packed into the same |
| chunk of 32 bits. However, if the size changes, a new field of that |
| size is allocated). In an unpacked record, this is the same as using |
| alignment, but not equivalent when packing. |
| |
| If both MS bit-fields and @samp{__attribute__((packed))} are used, |
| the latter will take precedence. If @samp{__attribute__((packed))} is |
| used on a single field when MS bit-fields are in use, it will take |
| precedence for that field, but the alignment of the rest of the structure |
| may affect its placement. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_DECIMAL_FLOAT_SUPPORTED_P (void) |
| Returns true if the target supports decimal floating point. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_FIXED_POINT_SUPPORTED_P (void) |
| Returns true if the target supports fixed-point arithmetic. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} void TARGET_EXPAND_TO_RTL_HOOK (void) |
| This hook is called just before expansion into rtl, allowing the target |
| to perform additional initializations or analysis before the expansion. |
| For example, the rs6000 port uses it to allocate a scratch stack slot |
| for use in copying SDmode values between memory and floating point |
| registers whenever the function being expanded has any SDmode |
| usage. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} void TARGET_INSTANTIATE_DECLS (void) |
| This hook allows the backend to perform additional instantiations on rtl |
| that are not actually in any insns yet, but will be later. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} {const char *} TARGET_MANGLE_TYPE (const_tree @var{type}) |
| If your target defines any fundamental types, or any types your target |
| uses should be mangled differently from the default, define this hook |
| to return the appropriate encoding for these types as part of a C++ |
| mangled name. The @var{type} argument is the tree structure representing |
| the type to be mangled. The hook may be applied to trees which are |
| not target-specific fundamental types; it should return @code{NULL} |
| for all such types, as well as arguments it does not recognize. If the |
| return value is not @code{NULL}, it must point to a statically-allocated |
| string constant. |
| |
| Target-specific fundamental types might be new fundamental types or |
| qualified versions of ordinary fundamental types. Encode new |
| fundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name} |
| is the name used for the type in source code, and @var{n} is the |
| length of @var{name} in decimal. Encode qualified versions of |
| ordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where |
| @var{name} is the name used for the type qualifier in source code, |
| @var{n} is the length of @var{name} as above, and @var{code} is the |
| code used to represent the unqualified version of this type. (See |
| @code{write_builtin_type} in @file{cp/mangle.c} for the list of |
| codes.) In both cases the spaces are for clarity; do not include any |
| spaces in your string. |
| |
| This hook is applied to types prior to typedef resolution. If the mangled |
| name for a particular type depends only on that type's main variant, you |
| can perform typedef resolution yourself using @code{TYPE_MAIN_VARIANT} |
| before mangling. |
| |
| The default version of this hook always returns @code{NULL}, which is |
| appropriate for a target that does not define any new fundamental |
| types. |
| @end deftypefn |
| |
| @node Type Layout |
| @section Layout of Source Language Data Types |
| |
| These macros define the sizes and other characteristics of the standard |
| basic data types used in programs being compiled. Unlike the macros in |
| the previous section, these apply to specific features of C and related |
| languages, rather than to fundamental aspects of storage layout. |
| |
| @defmac INT_TYPE_SIZE |
| A C expression for the size in bits of the type @code{int} on the |
| target machine. If you don't define this, the default is one word. |
| @end defmac |
| |
| @defmac SHORT_TYPE_SIZE |
| A C expression for the size in bits of the type @code{short} on the |
| target machine. If you don't define this, the default is half a word. |
| (If this would be less than one storage unit, it is rounded up to one |
| unit.) |
| @end defmac |
| |
| @defmac LONG_TYPE_SIZE |
| A C expression for the size in bits of the type @code{long} on the |
| target machine. If you don't define this, the default is one word. |
| @end defmac |
| |
| @defmac ADA_LONG_TYPE_SIZE |
| On some machines, the size used for the Ada equivalent of the type |
| @code{long} by a native Ada compiler differs from that used by C@. In |
| that situation, define this macro to be a C expression to be used for |
| the size of that type. If you don't define this, the default is the |
| value of @code{LONG_TYPE_SIZE}. |
| @end defmac |
| |
| @defmac LONG_LONG_TYPE_SIZE |
| A C expression for the size in bits of the type @code{long long} on the |
| target machine. If you don't define this, the default is two |
| words. If you want to support GNU Ada on your machine, the value of this |
| macro must be at least 64. |
| @end defmac |
| |
| @defmac CHAR_TYPE_SIZE |
| A C expression for the size in bits of the type @code{char} on the |
| target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT}. |
| @end defmac |
| |
| @defmac BOOL_TYPE_SIZE |
| A C expression for the size in bits of the C++ type @code{bool} and |
| C99 type @code{_Bool} on the target machine. If you don't define |
| this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. |
| @end defmac |
| |
| @defmac FLOAT_TYPE_SIZE |
| A C expression for the size in bits of the type @code{float} on the |
| target machine. If you don't define this, the default is one word. |
| @end defmac |
| |
| @defmac DOUBLE_TYPE_SIZE |
| A C expression for the size in bits of the type @code{double} on the |
| target machine. If you don't define this, the default is two |
| words. |
| @end defmac |
| |
| @defmac LONG_DOUBLE_TYPE_SIZE |
| A C expression for the size in bits of the type @code{long double} on |
| the target machine. If you don't define this, the default is two |
| words. |
| @end defmac |
| |
| @defmac SHORT_FRACT_TYPE_SIZE |
| A C expression for the size in bits of the type @code{short _Fract} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT}. |
| @end defmac |
| |
| @defmac FRACT_TYPE_SIZE |
| A C expression for the size in bits of the type @code{_Fract} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT * 2}. |
| @end defmac |
| |
| @defmac LONG_FRACT_TYPE_SIZE |
| A C expression for the size in bits of the type @code{long _Fract} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT * 4}. |
| @end defmac |
| |
| @defmac LONG_LONG_FRACT_TYPE_SIZE |
| A C expression for the size in bits of the type @code{long long _Fract} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT * 8}. |
| @end defmac |
| |
| @defmac SHORT_ACCUM_TYPE_SIZE |
| A C expression for the size in bits of the type @code{short _Accum} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT * 2}. |
| @end defmac |
| |
| @defmac ACCUM_TYPE_SIZE |
| A C expression for the size in bits of the type @code{_Accum} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT * 4}. |
| @end defmac |
| |
| @defmac LONG_ACCUM_TYPE_SIZE |
| A C expression for the size in bits of the type @code{long _Accum} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT * 8}. |
| @end defmac |
| |
| @defmac LONG_LONG_ACCUM_TYPE_SIZE |
| A C expression for the size in bits of the type @code{long long _Accum} on |
| the target machine. If you don't define this, the default is |
| @code{BITS_PER_UNIT * 16}. |
| @end defmac |
| |
| @defmac LIBGCC2_GNU_PREFIX |
| This macro corresponds to the @code{TARGET_LIBFUNC_GNU_PREFIX} target |
| hook and should be defined if that hook is overriden to be true. It |
| causes function names in libgcc to be changed to use a @code{__gnu_} |
| prefix for their name rather than the default @code{__}. A port which |
| uses this macro should also arrange to use @file{t-gnu-prefix} in |
| the libgcc @file{config.host}. |
| @end defmac |
| |
| @defmac WIDEST_HARDWARE_FP_SIZE |
| A C expression for the size in bits of the widest floating-point format |
| supported by the hardware. If you define this macro, you must specify a |
| value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. |
| If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} |
| is the default. |
| @end defmac |
| |
| @defmac DEFAULT_SIGNED_CHAR |
| An expression whose value is 1 or 0, according to whether the type |
| @code{char} should be signed or unsigned by default. The user can |
| always override this default with the options @option{-fsigned-char} |
| and @option{-funsigned-char}. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_DEFAULT_SHORT_ENUMS (void) |
| This target hook should return true if the compiler should give an |
| @code{enum} type only as many bytes as it takes to represent the range |
| of possible values of that type. It should return false if all |
| @code{enum} types should be allocated like @code{int}. |
| |
| The default is to return false. |
| @end deftypefn |
| |
| @defmac SIZE_TYPE |
| A C expression for a string describing the name of the data type to use |
| for size values. The typedef name @code{size_t} is defined using the |
| contents of the string. |
| |
| The string can contain more than one keyword. If so, separate them with |
| spaces, and write first any length keyword, then @code{unsigned} if |
| appropriate, and finally @code{int}. The string must exactly match one |
| of the data type names defined in the function |
| @code{c_common_nodes_and_builtins} in the file @file{c-family/c-common.c}. |
| You may not omit @code{int} or change the order---that would cause the |
| compiler to crash on startup. |
| |
| If you don't define this macro, the default is @code{"long unsigned |
| int"}. |
| @end defmac |
| |
| @defmac SIZETYPE |
| GCC defines internal types (@code{sizetype}, @code{ssizetype}, |
| @code{bitsizetype} and @code{sbitsizetype}) for expressions |
| dealing with size. This macro is a C expression for a string describing |
| the name of the data type from which the precision of @code{sizetype} |
| is extracted. |
| |
| The string has the same restrictions as @code{SIZE_TYPE} string. |
| |
| If you don't define this macro, the default is @code{SIZE_TYPE}. |
| @end defmac |
| |
| @defmac PTRDIFF_TYPE |
| A C expression for a string describing the name of the data type to use |
| for the result of subtracting two pointers. The typedef name |
| @code{ptrdiff_t} is defined using the contents of the string. See |
| @code{SIZE_TYPE} above for more information. |
| |
| If you don't define this macro, the default is @code{"long int"}. |
| @end defmac |
| |
| @defmac WCHAR_TYPE |
| A C expression for a string describing the name of the data type to use |
| for wide characters. The typedef name @code{wchar_t} is defined using |
| the contents of the string. See @code{SIZE_TYPE} above for more |
| information. |
| |
| If you don't define this macro, the default is @code{"int"}. |
| @end defmac |
| |
| @defmac WCHAR_TYPE_SIZE |
| A C expression for the size in bits of the data type for wide |
| characters. This is used in @code{cpp}, which cannot make use of |
| @code{WCHAR_TYPE}. |
| @end defmac |
| |
| @defmac WINT_TYPE |
| A C expression for a string describing the name of the data type to |
| use for wide characters passed to @code{printf} and returned from |
| @code{getwc}. The typedef name @code{wint_t} is defined using the |
| contents of the string. See @code{SIZE_TYPE} above for more |
| information. |
| |
| If you don't define this macro, the default is @code{"unsigned int"}. |
| @end defmac |
| |
| @defmac INTMAX_TYPE |
| A C expression for a string describing the name of the data type that |
| can represent any value of any standard or extended signed integer type. |
| The typedef name @code{intmax_t} is defined using the contents of the |
| string. See @code{SIZE_TYPE} above for more information. |
| |
| If you don't define this macro, the default is the first of |
| @code{"int"}, @code{"long int"}, or @code{"long long int"} that has as |
| much precision as @code{long long int}. |
| @end defmac |
| |
| @defmac UINTMAX_TYPE |
| A C expression for a string describing the name of the data type that |
| can represent any value of any standard or extended unsigned integer |
| type. The typedef name @code{uintmax_t} is defined using the contents |
| of the string. See @code{SIZE_TYPE} above for more information. |
| |
| If you don't define this macro, the default is the first of |
| @code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long |
| unsigned int"} that has as much precision as @code{long long unsigned |
| int}. |
| @end defmac |
| |
| @defmac SIG_ATOMIC_TYPE |
| @defmacx INT8_TYPE |
| @defmacx INT16_TYPE |
| @defmacx INT32_TYPE |
| @defmacx INT64_TYPE |
| @defmacx UINT8_TYPE |
| @defmacx UINT16_TYPE |
| @defmacx UINT32_TYPE |
| @defmacx UINT64_TYPE |
| @defmacx INT_LEAST8_TYPE |
| @defmacx INT_LEAST16_TYPE |
| @defmacx INT_LEAST32_TYPE |
| @defmacx INT_LEAST64_TYPE |
| @defmacx UINT_LEAST8_TYPE |
| @defmacx UINT_LEAST16_TYPE |
| @defmacx UINT_LEAST32_TYPE |
| @defmacx UINT_LEAST64_TYPE |
| @defmacx INT_FAST8_TYPE |
| @defmacx INT_FAST16_TYPE |
| @defmacx INT_FAST32_TYPE |
| @defmacx INT_FAST64_TYPE |
| @defmacx UINT_FAST8_TYPE |
| @defmacx UINT_FAST16_TYPE |
| @defmacx UINT_FAST32_TYPE |
| @defmacx UINT_FAST64_TYPE |
| @defmacx INTPTR_TYPE |
| @defmacx UINTPTR_TYPE |
| C expressions for the standard types @code{sig_atomic_t}, |
| @code{int8_t}, @code{int16_t}, @code{int32_t}, @code{int64_t}, |
| @code{uint8_t}, @code{uint16_t}, @code{uint32_t}, @code{uint64_t}, |
| @code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, |
| @code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, |
| @code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, |
| @code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, |
| @code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, |
| @code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t}. See |
| @code{SIZE_TYPE} above for more information. |
| |
| If any of these macros evaluates to a null pointer, the corresponding |
| type is not supported; if GCC is configured to provide |
| @code{<stdint.h>} in such a case, the header provided may not conform |
| to C99, depending on the type in question. The defaults for all of |
| these macros are null pointers. |
| @end defmac |
| |
| @defmac TARGET_PTRMEMFUNC_VBIT_LOCATION |
| The C++ compiler represents a pointer-to-member-function with a struct |
| that looks like: |
| |
| @smallexample |
| struct @{ |
| union @{ |
| void (*fn)(); |
| ptrdiff_t vtable_index; |
| @}; |
| ptrdiff_t delta; |
| @}; |
| @end smallexample |
| |
| @noindent |
| The C++ compiler must use one bit to indicate whether the function that |
| will be called through a pointer-to-member-function is virtual. |
| Normally, we assume that the low-order bit of a function pointer must |
| always be zero. Then, by ensuring that the vtable_index is odd, we can |
| distinguish which variant of the union is in use. But, on some |
| platforms function pointers can be odd, and so this doesn't work. In |
| that case, we use the low-order bit of the @code{delta} field, and shift |
| the remainder of the @code{delta} field to the left. |
| |
| GCC will automatically make the right selection about where to store |
| this bit using the @code{FUNCTION_BOUNDARY} setting for your platform. |
| However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} |
| set such that functions always start at even addresses, but the lowest |
| bit of pointers to functions indicate whether the function at that |
| address is in ARM or Thumb mode. If this is the case of your |
| architecture, you should define this macro to |
| @code{ptrmemfunc_vbit_in_delta}. |
| |
| In general, you should not have to define this macro. On architectures |
| in which function addresses are always even, according to |
| @code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to |
| @code{ptrmemfunc_vbit_in_pfn}. |
| @end defmac |
| |
| @defmac TARGET_VTABLE_USES_DESCRIPTORS |
| Normally, the C++ compiler uses function pointers in vtables. This |
| macro allows the target to change to use ``function descriptors'' |
| instead. Function descriptors are found on targets for whom a |
| function pointer is actually a small data structure. Normally the |
| data structure consists of the actual code address plus a data |
| pointer to which the function's data is relative. |
| |
| If vtables are used, the value of this macro should be the number |
| of words that the function descriptor occupies. |
| @end defmac |
| |
| @defmac TARGET_VTABLE_ENTRY_ALIGN |
| By default, the vtable entries are void pointers, the so the alignment |
| is the same as pointer alignment. The value of this macro specifies |
| the alignment of the vtable entry in bits. It should be defined only |
| when special alignment is necessary. */ |
| @end defmac |
| |
| @defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE |
| There are a few non-descriptor entries in the vtable at offsets below |
| zero. If these entries must be padded (say, to preserve the alignment |
| specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number |
| of words in each data entry. |
| @end defmac |
| |
| @node Registers |
| @section Register Usage |
| @cindex register usage |
| |
| This section explains how to describe what registers the target machine |
| has, and how (in general) they can be used. |
| |
| The description of which registers a specific instruction can use is |
| done with register classes; see @ref{Register Classes}. For information |
| on using registers to access a stack frame, see @ref{Frame Registers}. |
| For passing values in registers, see @ref{Register Arguments}. |
| For returning values in registers, see @ref{Scalar Return}. |
| |
| @menu |
| * Register Basics:: Number and kinds of registers. |
| * Allocation Order:: Order in which registers are allocated. |
| * Values in Registers:: What kinds of values each reg can hold. |
| * Leaf Functions:: Renumbering registers for leaf functions. |
| * Stack Registers:: Handling a register stack such as 80387. |
| @end menu |
| |
| @node Register Basics |
| @subsection Basic Characteristics of Registers |
| |
| @c prevent bad page break with this line |
| Registers have various characteristics. |
| |
| @defmac FIRST_PSEUDO_REGISTER |
| Number of hardware registers known to the compiler. They receive |
| numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first |
| pseudo register's number really is assigned the number |
| @code{FIRST_PSEUDO_REGISTER}. |
| @end defmac |
| |
| @defmac FIXED_REGISTERS |
| @cindex fixed register |
| An initializer that says which registers are used for fixed purposes |
| all throughout the compiled code and are therefore not available for |
| general allocation. These would include the stack pointer, the frame |
| pointer (except on machines where that can be used as a general |
| register when no frame pointer is needed), the program counter on |
| machines where that is considered one of the addressable registers, |
| and any other numbered register with a standard use. |
| |
| This information is expressed as a sequence of numbers, separated by |
| commas and surrounded by braces. The @var{n}th number is 1 if |
| register @var{n} is fixed, 0 otherwise. |
| |
| The table initialized from this macro, and the table initialized by |
| the following one, may be overridden at run time either automatically, |
| by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by |
| the user with the command options @option{-ffixed-@var{reg}}, |
| @option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. |
| @end defmac |
| |
| @defmac CALL_USED_REGISTERS |
| @cindex call-used register |
| @cindex call-clobbered register |
| @cindex call-saved register |
| Like @code{FIXED_REGISTERS} but has 1 for each register that is |
| clobbered (in general) by function calls as well as for fixed |
| registers. This macro therefore identifies the registers that are not |
| available for general allocation of values that must live across |
| function calls. |
| |
| If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler |
| automatically saves it on function entry and restores it on function |
| exit, if the register is used within the function. |
| |
| Exactly one of @code{CALL_USED_REGISTERS} and @code{CALL_REALLY_USED_REGISTERS} |
| must be defined. Modern ports should define @code{CALL_REALLY_USED_REGISTERS}. |
| @end defmac |
| |
| @defmac CALL_REALLY_USED_REGISTERS |
| @cindex call-used register |
| @cindex call-clobbered register |
| @cindex call-saved register |
| Like @code{CALL_USED_REGISTERS} except this macro doesn't require |
| that the entire set of @code{FIXED_REGISTERS} be included. |
| (@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). |
| |
| Exactly one of @code{CALL_USED_REGISTERS} and @code{CALL_REALLY_USED_REGISTERS} |
| must be defined. Modern ports should define @code{CALL_REALLY_USED_REGISTERS}. |
| @end defmac |
| |
| @cindex call-used register |
| @cindex call-clobbered register |
| @cindex call-saved register |
| @deftypefn {Target Hook} {const predefined_function_abi &} TARGET_FNTYPE_ABI (const_tree @var{type}) |
| Return the ABI used by a function with type @var{type}; see the |
| definition of @code{predefined_function_abi} for details of the ABI |
| descriptor. Targets only need to define this hook if they support |
| interoperability between several ABIs in the same translation unit. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} {const predefined_function_abi &} TARGET_INSN_CALLEE_ABI (const rtx_insn *@var{insn}) |
| This hook returns a description of the ABI used by the target of |
| call instruction @var{insn}; see the definition of |
| @code{predefined_function_abi} for details of the ABI descriptor. |
| Only the global function @code{insn_callee_abi} should call this hook |
| directly. |
| |
| Targets only need to define this hook if they support |
| interoperability between several ABIs in the same translation unit. |
| @end deftypefn |
| |
| @cindex call-used register |
| @cindex call-clobbered register |
| @cindex call-saved register |
| @deftypefn {Target Hook} bool TARGET_HARD_REGNO_CALL_PART_CLOBBERED (unsigned int @var{abi_id}, unsigned int @var{regno}, machine_mode @var{mode}) |
| ABIs usually specify that calls must preserve the full contents |
| of a particular register, or that calls can alter any part of a |
| particular register. This information is captured by the target macro |
| @code{CALL_REALLY_USED_REGISTERS}. However, some ABIs specify that calls |
| must preserve certain bits of a particular register but can alter others. |
| This hook should return true if this applies to at least one of the |
| registers in @samp{(reg:@var{mode} @var{regno})}, and if as a result the |
| call would alter part of the @var{mode} value. For example, if a call |
| preserves the low 32 bits of a 64-bit hard register @var{regno} but can |
| clobber the upper 32 bits, this hook should return true for a 64-bit mode |
| but false for a 32-bit mode. |
| |
| The value of @var{abi_id} comes from the @code{predefined_function_abi} |
| structure that describes the ABI of the call; see the definition of the |
| structure for more details. If (as is usual) the target uses the same ABI |
| for all functions in a translation unit, @var{abi_id} is always 0. |
| |
| The default implementation returns false, which is correct |
| for targets that don't have partly call-clobbered registers. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} {const char *} TARGET_GET_MULTILIB_ABI_NAME (void) |
| This hook returns name of multilib ABI name. |
| @end deftypefn |
| |
| @findex fixed_regs |
| @findex call_used_regs |
| @findex global_regs |
| @findex reg_names |
| @findex reg_class_contents |
| @deftypefn {Target Hook} void TARGET_CONDITIONAL_REGISTER_USAGE (void) |
| This hook may conditionally modify five variables |
| @code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, |
| @code{reg_names}, and @code{reg_class_contents}, to take into account |
| any dependence of these register sets on target flags. The first three |
| of these are of type @code{char []} (interpreted as boolean vectors). |
| @code{global_regs} is a @code{const char *[]}, and |
| @code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is |
| called, @code{fixed_regs}, @code{call_used_regs}, |
| @code{reg_class_contents}, and @code{reg_names} have been initialized |
| from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, |
| @code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. |
| @code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, |
| @option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} |
| command options have been applied. |
| |
| @cindex disabling certain registers |
| @cindex controlling register usage |
| If the usage of an entire class of registers depends on the target |
| flags, you may indicate this to GCC by using this macro to modify |
| @code{fixed_regs} and @code{call_used_regs} to 1 for each of the |
| registers in the classes which should not be used by GCC@. Also make |
| @code{define_register_constraint}s return @code{NO_REGS} for constraints |
| that shouldn't be used. |
| |
| (However, if this class is not included in @code{GENERAL_REGS} and all |
| of the insn patterns whose constraints permit this class are |
| controlled by target switches, then GCC will automatically avoid using |
| these registers when the target switches are opposed to them.) |
| @end deftypefn |
| |
| @defmac INCOMING_REGNO (@var{out}) |
| Define this macro if the target machine has register windows. This C |
| expression returns the register number as seen by the called function |
| corresponding to the register number @var{out} as seen by the calling |
| function. Return @var{out} if register number @var{out} is not an |
| outbound register. |
| @end defmac |
| |
| @defmac OUTGOING_REGNO (@var{in}) |
| Define this macro if the target machine has register windows. This C |
| expression returns the register number as seen by the calling function |
| corresponding to the register number @var{in} as seen by the called |
| function. Return @var{in} if register number @var{in} is not an inbound |
| register. |
| @end defmac |
| |
| @defmac LOCAL_REGNO (@var{regno}) |
| Define this macro if the target machine has register windows. This C |
| expression returns true if the register is call-saved but is in the |
| register window. Unlike most call-saved registers, such registers |
| need not be explicitly restored on function exit or during non-local |
| gotos. |
| @end defmac |
| |
| @defmac PC_REGNUM |
| If the program counter has a register number, define this as that |
| register number. Otherwise, do not define it. |
| @end defmac |
| |
| @node Allocation Order |
| @subsection Order of Allocation of Registers |
| @cindex order of register allocation |
| @cindex register allocation order |
| |
| @c prevent bad page break with this line |
| Registers are allocated in order. |
| |
| @defmac REG_ALLOC_ORDER |
| If defined, an initializer for a vector of integers, containing the |
| numbers of hard registers in the order in which GCC should prefer |
| to use them (from most preferred to least). |
| |
| If this macro is not defined, registers are used lowest numbered first |
| (all else being equal). |
| |
| One use of this macro is on machines where the highest numbered |
| registers must always be saved and the save-multiple-registers |
| instruction supports only sequences of consecutive registers. On such |
| machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists |
| the highest numbered allocable register first. |
| @end defmac |
| |
| @defmac ADJUST_REG_ALLOC_ORDER |
| A C statement (sans semicolon) to choose the order in which to allocate |
| hard registers for pseudo-registers local to a basic block. |
| |
| Store the desired register order in the array @code{reg_alloc_order}. |
| Element 0 should be the register to allocate first; element 1, the next |
| register; and so on. |
| |
| The macro body should not assume anything about the contents of |
| @code{reg_alloc_order} before execution of the macro. |
| |
| On most machines, it is not necessary to define this macro. |
| @end defmac |
| |
| @defmac HONOR_REG_ALLOC_ORDER |
| Normally, IRA tries to estimate the costs for saving a register in the |
| prologue and restoring it in the epilogue. This discourages it from |
| using call-saved registers. If a machine wants to ensure that IRA |
| allocates registers in the order given by REG_ALLOC_ORDER even if some |
| call-saved registers appear earlier than call-used ones, then define this |
| macro as a C expression to nonzero. Default is 0. |
| @end defmac |
| |
| @defmac IRA_HARD_REGNO_ADD_COST_MULTIPLIER (@var{regno}) |
| In some case register allocation order is not enough for the |
| Integrated Register Allocator (@acronym{IRA}) to generate a good code. |
| If this macro is defined, it should return a floating point value |
| based on @var{regno}. The cost of using @var{regno} for a pseudo will |
| be increased by approximately the pseudo's usage frequency times the |
| value returned by this macro. Not defining this macro is equivalent |
| to having it always return @code{0.0}. |
| |
| On most machines, it is not necessary to define this macro. |
| @end defmac |
| |
| @node Values in Registers |
| @subsection How Values Fit in Registers |
| |
| This section discusses the macros that describe which kinds of values |
| (specifically, which machine modes) each register can hold, and how many |
| consecutive registers are needed for a given mode. |
| |
| @deftypefn {Target Hook} {unsigned int} TARGET_HARD_REGNO_NREGS (unsigned int @var{regno}, machine_mode @var{mode}) |
| This hook returns the number of consecutive hard registers, starting |
| at register number @var{regno}, required to hold a value of mode |
| @var{mode}. This hook must never return zero, even if a register |
| cannot hold the requested mode - indicate that with |
| @code{TARGET_HARD_REGNO_MODE_OK} and/or |
| @code{TARGET_CAN_CHANGE_MODE_CLASS} instead. |
| |
| The default definition returns the number of words in @var{mode}. |
| @end deftypefn |
| |
| @defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode}) |
| A C expression that is nonzero if a value of mode @var{mode}, stored |
| in memory, ends with padding that causes it to take up more space than |
| in registers starting at register number @var{regno} (as determined by |
| multiplying GCC's notion of the size of the register when containing |
| this mode by the number of registers returned by |
| @code{TARGET_HARD_REGNO_NREGS}). By default this is zero. |
| |
| For example, if a floating-point value is stored in three 32-bit |
| registers but takes up 128 bits in memory, then this would be |
| nonzero. |
| |
| This macros only needs to be defined if there are cases where |
| @code{subreg_get_info} |
| would otherwise wrongly determine that a @code{subreg} can be |
| represented by an offset to the register number, when in fact such a |
| @code{subreg} would contain some of the padding not stored in |
| registers and so not be representable. |
| @end defmac |
| |
| @defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode}) |
| For values of @var{regno} and @var{mode} for which |
| @code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression |
| returning the greater number of registers required to hold the value |
| including any padding. In the example above, the value would be four. |
| @end defmac |
| |
| @defmac REGMODE_NATURAL_SIZE (@var{mode}) |
| Define this macro if the natural size of registers that hold values |
| of mode @var{mode} is not the word size. It is a C expression that |
| should give the natural size in bytes for the specified mode. It is |
| used by the register allocator to try to optimize its results. This |
| happens for example on SPARC 64-bit where the natural size of |
| floating-point registers is still 32-bit. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_HARD_REGNO_MODE_OK (unsigned int @var{regno}, machine_mode @var{mode}) |
| This hook returns true if it is permissible to store a value |
| of mode @var{mode} in hard register number @var{regno} (or in several |
| registers starting with that one). The default definition returns true |
| unconditionally. |
| |
| You need not include code to check for the numbers of fixed registers, |
| because the allocation mechanism considers them to be always occupied. |
| |
| @cindex register pairs |
| On some machines, double-precision values must be kept in even/odd |
| register pairs. You can implement that by defining this hook to reject |
| odd register numbers for such modes. |
| |
| The minimum requirement for a mode to be OK in a register is that the |
| @samp{mov@var{mode}} instruction pattern support moves between the |
| register and other hard register in the same class and that moving a |
| value into the register and back out not alter it. |
| |
| Since the same instruction used to move @code{word_mode} will work for |
| all narrower integer modes, it is not necessary on any machine for |
| this hook to distinguish between these modes, provided you define |
| patterns @samp{movhi}, etc., to take advantage of this. This is |
| useful because of the interaction between @code{TARGET_HARD_REGNO_MODE_OK} |
| and @code{TARGET_MODES_TIEABLE_P}; it is very desirable for all integer |
| modes to be tieable. |
| |
| Many machines have special registers for floating point arithmetic. |
| Often people assume that floating point machine modes are allowed only |
| in floating point registers. This is not true. Any registers that |
| can hold integers can safely @emph{hold} a floating point machine |
| mode, whether or not floating arithmetic can be done on it in those |
| registers. Integer move instructions can be used to move the values. |
| |
| On some machines, though, the converse is true: fixed-point machine |
| modes may not go in floating registers. This is true if the floating |
| registers normalize any value stored in them, because storing a |
| non-floating value there would garble it. In this case, |
| @code{TARGET_HARD_REGNO_MODE_OK} should reject fixed-point machine modes in |
| floating registers. But if the floating registers do not automatically |
| normalize, if you can store any bit pattern in one and retrieve it |
| unchanged without a trap, then any machine mode may go in a floating |
| register, so you can define this hook to say so. |
| |
| The primary significance of special floating registers is rather that |
| they are the registers acceptable in floating point arithmetic |
| instructions. However, this is of no concern to |
| @code{TARGET_HARD_REGNO_MODE_OK}. You handle it by writing the proper |
| constraints for those instructions. |
| |
| On some machines, the floating registers are especially slow to access, |
| so that it is better to store a value in a stack frame than in such a |
| register if floating point arithmetic is not being done. As long as the |
| floating registers are not in class @code{GENERAL_REGS}, they will not |
| be used unless some pattern's constraint asks for one. |
| @end deftypefn |
| |
| @defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to}) |
| A C expression that is nonzero if it is OK to rename a hard register |
| @var{from} to another hard register @var{to}. |
| |
| One common use of this macro is to prevent renaming of a register to |
| another register that is not saved by a prologue in an interrupt |
| handler. |
| |
| The default is always nonzero. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_MODES_TIEABLE_P (machine_mode @var{mode1}, machine_mode @var{mode2}) |
| This hook returns true if a value of mode @var{mode1} is accessible |
| in mode @var{mode2} without copying. |
| |
| If @code{TARGET_HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and |
| @code{TARGET_HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always |
| the same for any @var{r}, then |
| @code{TARGET_MODES_TIEABLE_P (@var{mode1}, @var{mode2})} |
| should be true. If they differ for any @var{r}, you should define |
| this hook to return false unless some other mechanism ensures the |
| accessibility of the value in a narrower mode. |
| |
| You should define this hook to return true in as many cases as |
| possible since doing so will allow GCC to perform better register |
| allocation. The default definition returns true unconditionally. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_HARD_REGNO_SCRATCH_OK (unsigned int @var{regno}) |
| This target hook should return @code{true} if it is OK to use a hard register |
| @var{regno} as scratch reg in peephole2. |
| |
| One common use of this macro is to prevent using of a register that |
| is not saved by a prologue in an interrupt handler. |
| |
| The default version of this hook always returns @code{true}. |
| @end deftypefn |
| |
| @defmac AVOID_CCMODE_COPIES |
| Define this macro if the compiler should avoid copies to/from @code{CCmode} |
| registers. You should only define this macro if support for copying to/from |
| @code{CCmode} is incomplete. |
| @end defmac |
| |
| @node Leaf Functions |
| @subsection Handling Leaf Functions |
| |
| @cindex leaf functions |
| @cindex functions, leaf |
| On some machines, a leaf function (i.e., one which makes no calls) can run |
| more efficiently if it does not make its own register window. Often this |
| means it is required to receive its arguments in the registers where they |
| are passed by the caller, instead of the registers where they would |
| normally arrive. |
| |
| The special treatment for leaf functions generally applies only when |
| other conditions are met; for example, often they may use only those |
| registers for its own variables and temporaries. We use the term ``leaf |
| function'' to mean a function that is suitable for this special |
| handling, so that functions with no calls are not necessarily ``leaf |
| functions''. |
| |
| GCC assigns register numbers before it knows whether the function is |
| suitable for leaf function treatment. So it needs to renumber the |
| registers in order to output a leaf function. The following macros |
| accomplish this. |
| |
| @defmac LEAF_REGISTERS |
| Name of a char vector, indexed by hard register number, which |
| contains 1 for a register that is allowable in a candidate for leaf |
| function treatment. |
| |
| If leaf function treatment involves renumbering the registers, then the |
| registers marked here should be the ones before renumbering---those that |
| GCC would ordinarily allocate. The registers which will actually be |
| used in the assembler code, after renumbering, should not be marked with 1 |
| in this vector. |
| |
| Define this macro only if the target machine offers a way to optimize |
| the treatment of leaf functions. |
| @end defmac |
| |
| @defmac LEAF_REG_REMAP (@var{regno}) |
| A C expression whose value is the register number to which @var{regno} |
| should be renumbered, when a function is treated as a leaf function. |
| |
| If @var{regno} is a register number which should not appear in a leaf |
| function before renumbering, then the expression should yield @minus{}1, which |
| will cause the compiler to abort. |
| |
| Define this macro only if the target machine offers a way to optimize the |
| treatment of leaf functions, and registers need to be renumbered to do |
| this. |
| @end defmac |
| |
| @findex current_function_is_leaf |
| @findex current_function_uses_only_leaf_regs |
| @code{TARGET_ASM_FUNCTION_PROLOGUE} and |
| @code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions |
| specially. They can test the C variable @code{current_function_is_leaf} |
| which is nonzero for leaf functions. @code{current_function_is_leaf} is |
| set prior to local register allocation and is valid for the remaining |
| compiler passes. They can also test the C variable |
| @code{current_function_uses_only_leaf_regs} which is nonzero for leaf |
| functions which only use leaf registers. |
| @code{current_function_uses_only_leaf_regs} is valid after all passes |
| that modify the instructions have been run and is only useful if |
| @code{LEAF_REGISTERS} is defined. |
| @c changed this to fix overfull. ALSO: why the "it" at the beginning |
| @c of the next paragraph?! --mew 2feb93 |
| |
| @node Stack Registers |
| @subsection Registers That Form a Stack |
| |
| There are special features to handle computers where some of the |
| ``registers'' form a stack. Stack registers are normally written by |
| pushing onto the stack, and are numbered relative to the top of the |
| stack. |
| |
| Currently, GCC can only handle one group of stack-like registers, and |
| they must be consecutively numbered. Furthermore, the existing |
| support for stack-like registers is specific to the 80387 floating |
| point coprocessor. If you have a new architecture that uses |
| stack-like registers, you will need to do substantial work on |
| @file{reg-stack.c} and write your machine description to cooperate |
| with it, as well as defining these macros. |
| |
| @defmac STACK_REGS |
| Define this if the machine has any stack-like registers. |
| @end defmac |
| |
| @defmac STACK_REG_COVER_CLASS |
| This is a cover class containing the stack registers. Define this if |
| the machine has any stack-like registers. |
| @end defmac |
| |
| @defmac FIRST_STACK_REG |
| The number of the first stack-like register. This one is the top |
| of the stack. |
| @end defmac |
| |
| @defmac LAST_STACK_REG |
| The number of the last stack-like register. This one is the bottom of |
| the stack. |
| @end defmac |
| |
| @node Register Classes |
| @section Register Classes |
| @cindex register class definitions |
| @cindex class definitions, register |
| |
| On many machines, the numbered registers are not all equivalent. |
| For example, certain registers may not be allowed for indexed addressing; |
| certain registers may not be allowed in some instructions. These machine |
| restrictions are described to the compiler using @dfn{register classes}. |
| |
| You define a number of register classes, giving each one a name and saying |
| which of the registers belong to it. Then you can specify register classes |
| that are allowed as operands to particular instruction patterns. |
| |
| @findex ALL_REGS |
| @findex NO_REGS |
| In general, each register will belong to several classes. In fact, one |
| class must be named @code{ALL_REGS} and contain all the registers. Another |
| class must be named @code{NO_REGS} and contain no registers. Often the |
| union of two classes will be another class; however, this is not required. |
| |
| @findex GENERAL_REGS |
| One of the classes must be named @code{GENERAL_REGS}. There is nothing |
| terribly special about the name, but the operand constraint letters |
| @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is |
| the same as @code{ALL_REGS}, just define it as a macro which expands |
| to @code{ALL_REGS}. |
| |
| Order the classes so that if class @var{x} is contained in class @var{y} |
| then @var{x} has a lower class number than @var{y}. |
| |
| The way classes other than @code{GENERAL_REGS} are specified in operand |
| constraints is through machine-dependent operand constraint letters. |
| You can define such letters to correspond to various classes, then use |
| them in operand constraints. |
| |
| You must define the narrowest register classes for allocatable |
| registers, so that each class either has no subclasses, or that for |
| some mode, the move cost between registers within the class is |
| cheaper than moving a register in the class to or from memory |
| (@pxref{Costs}). |
| |
| You should define a class for the union of two classes whenever some |
| instruction allows both classes. For example, if an instruction allows |
| either a floating point (coprocessor) register or a general register for a |
| certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} |
| which includes both of them. Otherwise you will get suboptimal code, |
| or even internal compiler errors when reload cannot find a register in the |
| class computed via @code{reg_class_subunion}. |
| |
| You must also specify certain redundant information about the register |
| classes: for each class, which classes contain it and which ones are |
| contained in it; for each pair of classes, the largest class contained |
| in their union. |
| |
| When a value occupying several consecutive registers is expected in a |
| certain class, all the registers used must belong to that class. |
| Therefore, register classes cannot be used to enforce a requirement for |
| a register pair to start with an even-numbered register. The way to |
| specify this requirement is with @code{TARGET_HARD_REGNO_MODE_OK}. |
| |
| Register classes used for input-operands of bitwise-and or shift |
| instructions have a special requirement: each such class must have, for |
| each fixed-point machine mode, a subclass whose registers can transfer that |
| mode to or from memory. For example, on some machines, the operations for |
| single-byte values (@code{QImode}) are limited to certain registers. When |
| this is so, each register class that is used in a bitwise-and or shift |
| instruction must have a subclass consisting of registers from which |
| single-byte values can be loaded or stored. This is so that |
| @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. |
| |
| @deftp {Data type} {enum reg_class} |
| An enumerated type that must be defined with all the register class names |
| as enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS} |
| must be the last register class, followed by one more enumerated value, |
| @code{LIM_REG_CLASSES}, which is not a register class but rather |
| tells how many classes there are. |
| |
| Each register class has a number, which is the value of casting |
| the class name to type @code{int}. The number serves as an index |
| in many of the tables described below. |
| @end deftp |
| |
| @defmac N_REG_CLASSES |
| The number of distinct register classes, defined as follows: |
| |
| @smallexample |
| #define N_REG_CLASSES (int) LIM_REG_CLASSES |
| @end smallexample |
| @end defmac |
| |
| @defmac REG_CLASS_NAMES |
| An initializer containing the names of the register classes as C string |
| constants. These names are used in writing some of the debugging dumps. |
| @end defmac |
| |
| @defmac REG_CLASS_CONTENTS |
| An initializer containing the contents of the register classes, as integers |
| which are bit masks. The @var{n}th integer specifies the contents of class |
| @var{n}. The way the integer @var{mask} is interpreted is that |
| register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. |
| |
| When the machine has more than 32 registers, an integer does not suffice. |
| Then the integers are replaced by sub-initializers, braced groupings containing |
| several integers. Each sub-initializer must be suitable as an initializer |
| for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. |
| In this situation, the first integer in each sub-initializer corresponds to |
| registers 0 through 31, the second integer to registers 32 through 63, and |
| so on. |
| @end defmac |
| |
| @defmac REGNO_REG_CLASS (@var{regno}) |
| A C expression whose value is a register class containing hard register |
| @var{regno}. In general there is more than one such class; choose a class |
| which is @dfn{minimal}, meaning that no smaller class also contains the |
| register. |
| @end defmac |
| |
| @defmac BASE_REG_CLASS |
| A macro whose definition is the name of the class to which a valid |
| base register must belong. A base register is one used in an address |
| which is the register value plus a displacement. |
| @end defmac |
| |
| @defmac MODE_BASE_REG_CLASS (@var{mode}) |
| This is a variation of the @code{BASE_REG_CLASS} macro which allows |
| the selection of a base register in a mode dependent manner. If |
| @var{mode} is VOIDmode then it should return the same value as |
| @code{BASE_REG_CLASS}. |
| @end defmac |
| |
| @defmac MODE_BASE_REG_REG_CLASS (@var{mode}) |
| A C expression whose value is the register class to which a valid |
| base register must belong in order to be used in a base plus index |
| register address. You should define this macro if base plus index |
| addresses have different requirements than other base register uses. |
| @end defmac |
| |
| @defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{address_space}, @var{outer_code}, @var{index_code}) |
| A C expression whose value is the register class to which a valid |
| base register for a memory reference in mode @var{mode} to address |
| space @var{address_space} must belong. @var{outer_code} and @var{index_code} |
| define the context in which the base register occurs. @var{outer_code} is |
| the code of the immediately enclosing expression (@code{MEM} for the top level |
| of an address, @code{ADDRESS} for something that occurs in an |
| @code{address_operand}). @var{index_code} is the code of the corresponding |
| index expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise. |
| @end defmac |
| |
| @defmac INDEX_REG_CLASS |
| A macro whose definition is the name of the class to which a valid |
| index register must belong. An index register is one used in an |
| address where its value is either multiplied by a scale factor or |
| added to another register (as well as added to a displacement). |
| @end defmac |
| |
| @defmac REGNO_OK_FOR_BASE_P (@var{num}) |
| A C expression which is nonzero if register number @var{num} is |
| suitable for use as a base register in operand addresses. |
| @end defmac |
| |
| @defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) |
| A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that |
| that expression may examine the mode of the memory reference in |
| @var{mode}. You should define this macro if the mode of the memory |
| reference affects whether a register may be used as a base register. If |
| you define this macro, the compiler will use it instead of |
| @code{REGNO_OK_FOR_BASE_P}. The mode may be @code{VOIDmode} for |
| addresses that appear outside a @code{MEM}, i.e., as an |
| @code{address_operand}. |
| @end defmac |
| |
| @defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode}) |
| A C expression which is nonzero if register number @var{num} is suitable for |
| use as a base register in base plus index operand addresses, accessing |
| memory in mode @var{mode}. It may be either a suitable hard register or a |
| pseudo register that has been allocated such a hard register. You should |
| define this macro if base plus index addresses have different requirements |
| than other base register uses. |
| |
| Use of this macro is deprecated; please use the more general |
| @code{REGNO_MODE_CODE_OK_FOR_BASE_P}. |
| @end defmac |
| |
| @defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{address_space}, @var{outer_code}, @var{index_code}) |
| A C expression which is nonzero if register number @var{num} is |
| suitable for use as a base register in operand addresses, accessing |
| memory in mode @var{mode} in address space @var{address_space}. |
| This is similar to @code{REGNO_MODE_OK_FOR_BASE_P}, except |
| that that expression may examine the context in which the register |
| appears in the memory reference. @var{outer_code} is the code of the |
| immediately enclosing expression (@code{MEM} if at the top level of the |
| address, @code{ADDRESS} for something that occurs in an |
| @code{address_operand}). @var{index_code} is the code of the |
| corresponding index expression if @var{outer_code} is @code{PLUS}; |
| @code{SCRATCH} otherwise. The mode may be @code{VOIDmode} for addresses |
| that appear outside a @code{MEM}, i.e., as an @code{address_operand}. |
| @end defmac |
| |
| @defmac REGNO_OK_FOR_INDEX_P (@var{num}) |
| A C expression which is nonzero if register number @var{num} is |
| suitable for use as an index register in operand addresses. It may be |
| either a suitable hard register or a pseudo register that has been |
| allocated such a hard register. |
| |
| The difference between an index register and a base register is that |
| the index register may be scaled. If an address involves the sum of |
| two registers, neither one of them scaled, then either one may be |
| labeled the ``base'' and the other the ``index''; but whichever |
| labeling is used must fit the machine's constraints of which registers |
| may serve in each capacity. The compiler will try both labelings, |
| looking for one that is valid, and will reload one or both registers |
| only if neither labeling works. |
| @end defmac |
| |
| @deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RENAME_CLASS (reg_class_t @var{rclass}) |
| A target hook that places additional preference on the register |
| class to use when it is necessary to rename a register in class |
| @var{rclass} to another class, or perhaps @var{NO_REGS}, if no |
| preferred register class is found or hook @code{preferred_rename_class} |
| is not implemented. |
| Sometimes returning a more restrictive class makes better code. For |
| example, on ARM, thumb-2 instructions using @code{LO_REGS} may be |
| smaller than instructions using @code{GENERIC_REGS}. By returning |
| @code{LO_REGS} from @code{preferred_rename_class}, code size can |
| be reduced. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass}) |
| A target hook that places additional restrictions on the register class |
| to use when it is necessary to copy value @var{x} into a register in class |
| @var{rclass}. The value is a register class; perhaps @var{rclass}, or perhaps |
| another, smaller class. |
| |
| The default version of this hook always returns value of @code{rclass} argument. |
| |
| Sometimes returning a more restrictive class makes better code. For |
| example, on the 68000, when @var{x} is an integer constant that is in range |
| for a @samp{moveq} instruction, the value of this macro is always |
| @code{DATA_REGS} as long as @var{rclass} includes the data registers. |
| Requiring a data register guarantees that a @samp{moveq} will be used. |
| |
| One case where @code{TARGET_PREFERRED_RELOAD_CLASS} must not return |
| @var{rclass} is if @var{x} is a legitimate constant which cannot be |
| loaded into some register class. By returning @code{NO_REGS} you can |
| force @var{x} into a memory location. For example, rs6000 can load |
| immediate values into general-purpose registers, but does not have an |
| instruction for loading an immediate value into a floating-point |
| register, so @code{TARGET_PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when |
| @var{x} is a floating-point constant. If the constant can't be loaded |
| into any kind of register, code generation will be better if |
| @code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead |
| of using @code{TARGET_PREFERRED_RELOAD_CLASS}. |
| |
| If an insn has pseudos in it after register allocation, reload will go |
| through the alternatives and call repeatedly @code{TARGET_PREFERRED_RELOAD_CLASS} |
| to find the best one. Returning @code{NO_REGS}, in this case, makes |
| reload add a @code{!} in front of the constraint: the x86 back-end uses |
| this feature to discourage usage of 387 registers when math is done in |
| the SSE registers (and vice versa). |
| @end deftypefn |
| |
| @defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) |
| A C expression that places additional restrictions on the register class |
| to use when it is necessary to copy value @var{x} into a register in class |
| @var{class}. The value is a register class; perhaps @var{class}, or perhaps |
| another, smaller class. On many machines, the following definition is |
| safe: |
| |
| @smallexample |
| #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS |
| @end smallexample |
| |
| Sometimes returning a more restrictive class makes better code. For |
| example, on the 68000, when @var{x} is an integer constant that is in range |
| for a @samp{moveq} instruction, the value of this macro is always |
| @code{DATA_REGS} as long as @var{class} includes the data registers. |
| Requiring a data register guarantees that a @samp{moveq} will be used. |
| |
| One case where @code{PREFERRED_RELOAD_CLASS} must not return |
| @var{class} is if @var{x} is a legitimate constant which cannot be |
| loaded into some register class. By returning @code{NO_REGS} you can |
| force @var{x} into a memory location. For example, rs6000 can load |
| immediate values into general-purpose registers, but does not have an |
| instruction for loading an immediate value into a floating-point |
| register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when |
| @var{x} is a floating-point constant. If the constant cannot be loaded |
| into any kind of register, code generation will be better if |
| @code{TARGET_LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead |
| of using @code{TARGET_PREFERRED_RELOAD_CLASS}. |
| |
| If an insn has pseudos in it after register allocation, reload will go |
| through the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS} |
| to find the best one. Returning @code{NO_REGS}, in this case, makes |
| reload add a @code{!} in front of the constraint: the x86 back-end uses |
| this feature to discourage usage of 387 registers when math is done in |
| the SSE registers (and vice versa). |
| @end defmac |
| |
| @deftypefn {Target Hook} reg_class_t TARGET_PREFERRED_OUTPUT_RELOAD_CLASS (rtx @var{x}, reg_class_t @var{rclass}) |
| Like @code{TARGET_PREFERRED_RELOAD_CLASS}, but for output reloads instead of |
| input reloads. |
| |
| The default version of this hook always returns value of @code{rclass} |
| argument. |
| |
| You can also use @code{TARGET_PREFERRED_OUTPUT_RELOAD_CLASS} to discourage |
| reload from using some alternatives, like @code{TARGET_PREFERRED_RELOAD_CLASS}. |
| @end deftypefn |
| |
| @defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) |
| A C expression that places additional restrictions on the register class |
| to use when it is necessary to be able to hold a value of mode |
| @var{mode} in a reload register for which class @var{class} would |
| ordinarily be used. |
| |
| Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when |
| there are certain modes that simply cannot go in certain reload classes. |
| |
| The value is a register class; perhaps @var{class}, or perhaps another, |
| smaller class. |
| |
| Don't define this macro unless the target machine has limitations which |
| require the macro to do something nontrivial. |
| @end defmac |
| |
| @deftypefn {Target Hook} reg_class_t TARGET_SECONDARY_RELOAD (bool @var{in_p}, rtx @var{x}, reg_class_t @var{reload_class}, machine_mode @var{reload_mode}, secondary_reload_info *@var{sri}) |
| Many machines have some registers that cannot be copied directly to or |
| from memory or even from other types of registers. An example is the |
| @samp{MQ} register, which on most machines, can only be copied to or |
| from general registers, but not memory. Below, we shall be using the |
| term 'intermediate register' when a move operation cannot be performed |
| directly, but has to be done by copying the source into the intermediate |
| register first, and then copying the intermediate register to the |
| destination. An intermediate register always has the same mode as |
| source and destination. Since it holds the actual value being copied, |
| reload might apply optimizations to re-use an intermediate register |
| and eliding the copy from the source when it can determine that the |
| intermediate register still holds the required value. |
| |
| Another kind of secondary reload is required on some machines which |
| allow copying all registers to and from memory, but require a scratch |
| register for stores to some memory locations (e.g., those with symbolic |
| address on the RT, and those with certain symbolic address on the SPARC |
| when compiling PIC)@. Scratch registers need not have the same mode |
| as the value being copied, and usually hold a different value than |
| that being copied. Special patterns in the md file are needed to |
| describe how the copy is performed with the help of the scratch register; |
| these patterns also describe the number, register class(es) and mode(s) |
| of the scratch register(s). |
| |
| In some cases, both an intermediate and a scratch register are required. |
| |
| For input reloads, this target hook is called with nonzero @var{in_p}, |
| and @var{x} is an rtx that needs to be copied to a register of class |
| @var{reload_class} in @var{reload_mode}. For output reloads, this target |
| hook is called with zero @var{in_p}, and a register of class @var{reload_class} |
| needs to be copied to rtx @var{x} in @var{reload_mode}. |
| |
| If copying a register of @var{reload_class} from/to @var{x} requires |
| an intermediate register, the hook @code{secondary_reload} should |
| return the register class required for this intermediate register. |
| If no intermediate register is required, it should return NO_REGS. |
| If more than one intermediate register is required, describe the one |
| that is closest in the copy chain to the reload register. |
| |
| If scratch registers are needed, you also have to describe how to |
| perform the copy from/to the reload register to/from this |
| closest intermediate register. Or if no intermediate register is |
| required, but still a scratch register is needed, describe the |
| copy from/to the reload register to/from the reload operand @var{x}. |
| |
| You do this by setting @code{sri->icode} to the instruction code of a pattern |
| in the md file which performs the move. Operands 0 and 1 are the output |
| and input of this copy, respectively. Operands from operand 2 onward are |
| for scratch operands. These scratch operands must have a mode, and a |
| single-register-class |
| @c [later: or memory] |
| output constraint. |
| |
| When an intermediate register is used, the @code{secondary_reload} |
| hook will be called again to determine how to copy the intermediate |
| register to/from the reload operand @var{x}, so your hook must also |
| have code to handle the register class of the intermediate operand. |
| |
| @c [For later: maybe we'll allow multi-alternative reload patterns - |
| @c the port maintainer could name a mov<mode> pattern that has clobbers - |
| @c and match the constraints of input and output to determine the required |
| @c alternative. A restriction would be that constraints used to match |
| @c against reloads registers would have to be written as register class |
| @c constraints, or we need a new target macro / hook that tells us if an |
| @c arbitrary constraint can match an unknown register of a given class. |
| @c Such a macro / hook would also be useful in other places.] |
| |
| |
| @var{x} might be a pseudo-register or a @code{subreg} of a |
| pseudo-register, which could either be in a hard register or in memory. |
| Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is |
| in memory and the hard register number if it is in a register. |
| |
| Scratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are |
| currently not supported. For the time being, you will have to continue |
| to use @code{TARGET_SECONDARY_MEMORY_NEEDED} for that purpose. |
| |
| @code{copy_cost} also uses this target hook to find out how values are |
| copied. If you want it to include some extra cost for the need to allocate |
| (a) scratch register(s), set @code{sri->extra_cost} to the additional cost. |
| Or if two dependent moves are supposed to have a lower cost than the sum |
| of the individual moves due to expected fortuitous scheduling and/or special |
| forwarding logic, you can set @code{sri->extra_cost} to a negative amount. |
| @end deftypefn |
| |
| @defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) |
| @defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) |
| @defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) |
| These macros are obsolete, new ports should use the target hook |
| @code{TARGET_SECONDARY_RELOAD} instead. |
| |
| These are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD} |
| target hook. Older ports still define these macros to indicate to the |
| reload phase that it may |
| need to allocate at least one register for a reload in addition to the |
| register to contain the data. Specifically, if copying @var{x} to a |
| register @var{class} in @var{mode} requires an intermediate register, |
| you were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the |
| largest register class all of whose registers can be used as |
| intermediate registers or scratch registers. |
| |
| If copying a register @var{class} in @var{mode} to @var{x} requires an |
| intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} |
| was supposed to be defined be defined to return the largest register |
| class required. If the |
| requirements for input and output reloads were the same, the macro |
| @code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both |
| macros identically. |
| |
| The values returned by these macros are often @code{GENERAL_REGS}. |
| Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x} |
| can be directly copied to or from a register of @var{class} in |
| @var{mode} without requiring a scratch register. Do not define this |
| macro if it would always return @code{NO_REGS}. |
| |
| If a scratch register is required (either with or without an |
| intermediate register), you were supposed to define patterns for |
| @samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required |
| (@pxref{Standard Names}. These patterns, which were normally |
| implemented with a @code{define_expand}, should be similar to the |
| @samp{mov@var{m}} patterns, except that operand 2 is the scratch |
| register. |
| |
| These patterns need constraints for the reload register and scratch |
| register that |
| contain a single register class. If the original reload register (whose |
| class is @var{class}) can meet the constraint given in the pattern, the |
| value returned by these macros is used for the class of the scratch |
| register. Otherwise, two additional reload registers are required. |
| Their classes are obtained from the constraints in the insn pattern. |
| |
| @var{x} might be a pseudo-register or a @code{subreg} of a |
| pseudo-register, which could either be in a hard register or in memory. |
| Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is |
| in memory and the hard register number if it is in a register. |
| |
| These macros should not be used in the case where a particular class of |
| registers can only be copied to memory and not to another class of |
| registers. In that case, secondary reload registers are not needed and |
| would not be helpful. Instead, a stack location must be used to perform |
| the copy and the @code{mov@var{m}} pattern should use memory as an |
| intermediate storage. This case often occurs between floating-point and |
| general registers. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_SECONDARY_MEMORY_NEEDED (machine_mode @var{mode}, reg_class_t @var{class1}, reg_class_t @var{class2}) |
| Certain machines have the property that some registers cannot be copied |
| to some other registers without using memory. Define this hook on |
| those machines to return true if objects of mode @var{m} in registers |
| of @var{class1} can only be copied to registers of class @var{class2} by |
| storing a register of @var{class1} into memory and loading that memory |
| location into a register of @var{class2}. The default definition returns |
| false for all inputs. |
| @end deftypefn |
| |
| @defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) |
| Normally when @code{TARGET_SECONDARY_MEMORY_NEEDED} is defined, the compiler |
| allocates a stack slot for a memory location needed for register copies. |
| If this macro is defined, the compiler instead uses the memory location |
| defined by this macro. |
| |
| Do not define this macro if you do not define |
| @code{TARGET_SECONDARY_MEMORY_NEEDED}. |
| @end defmac |
| |
| @deftypefn {Target Hook} machine_mode TARGET_SECONDARY_MEMORY_NEEDED_MODE (machine_mode @var{mode}) |
| If @code{TARGET_SECONDARY_MEMORY_NEEDED} tells the compiler to use memory |
| when moving between two particular registers of mode @var{mode}, |
| this hook specifies the mode that the memory should have. |
| |
| The default depends on @code{TARGET_LRA_P}. Without LRA, the default |
| is to use a word-sized mode for integral modes that are smaller than a |
| a word. This is right thing to do on most machines because it ensures |
| that all bits of the register are copied and prevents accesses to the |
| registers in a narrower mode, which some machines prohibit for |
| floating-point registers. |
| |
| However, this default behavior is not correct on some machines, such as |
| the DEC Alpha, that store short integers in floating-point registers |
| differently than in integer registers. On those machines, the default |
| widening will not work correctly and you must define this hook to |
| suppress that widening in some cases. See the file @file{alpha.c} for |
| details. |
| |
| With LRA, the default is to use @var{mode} unmodified. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} void TARGET_SELECT_EARLY_REMAT_MODES (sbitmap @var{modes}) |
| On some targets, certain modes cannot be held in registers around a |
| standard ABI call and are relatively expensive to spill to the stack. |
| The early rematerialization pass can help in such cases by aggressively |
| recomputing values after calls, so that they don't need to be spilled. |
| |
| This hook returns the set of such modes by setting the associated bits |
| in @var{modes}. The default implementation selects no modes, which has |
| the effect of disabling the early rematerialization pass. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_CLASS_LIKELY_SPILLED_P (reg_class_t @var{rclass}) |
| A target hook which returns @code{true} if pseudos that have been assigned |
| to registers of class @var{rclass} would likely be spilled because |
| registers of @var{rclass} are needed for spill registers. |
| |
| The default version of this target hook returns @code{true} if @var{rclass} |
| has exactly one register and @code{false} otherwise. On most machines, this |
| default should be used. For generally register-starved machines, such as |
| i386, or machines with right register constraints, such as SH, this hook |
| can be used to avoid excessive spilling. |
| |
| This hook is also used by some of the global intra-procedural code |
| transformations to throtle code motion, to avoid increasing register |
| pressure. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} {unsigned char} TARGET_CLASS_MAX_NREGS (reg_class_t @var{rclass}, machine_mode @var{mode}) |
| A target hook returns the maximum number of consecutive registers |
| of class @var{rclass} needed to hold a value of mode @var{mode}. |
| |
| This is closely related to the macro @code{TARGET_HARD_REGNO_NREGS}. |
| In fact, the value returned by @code{TARGET_CLASS_MAX_NREGS (@var{rclass}, |
| @var{mode})} target hook should be the maximum value of |
| @code{TARGET_HARD_REGNO_NREGS (@var{regno}, @var{mode})} for all @var{regno} |
| values in the class @var{rclass}. |
| |
| This target hook helps control the handling of multiple-word values |
| in the reload pass. |
| |
| The default version of this target hook returns the size of @var{mode} |
| in words. |
| @end deftypefn |
| |
| @defmac CLASS_MAX_NREGS (@var{class}, @var{mode}) |
| A C expression for the maximum number of consecutive registers |
| of class @var{class} needed to hold a value of mode @var{mode}. |
| |
| This is closely related to the macro @code{TARGET_HARD_REGNO_NREGS}. In fact, |
| the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} |
| should be the maximum value of @code{TARGET_HARD_REGNO_NREGS (@var{regno}, |
| @var{mode})} for all @var{regno} values in the class @var{class}. |
| |
| This macro helps control the handling of multiple-word values |
| in the reload pass. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_CAN_CHANGE_MODE_CLASS (machine_mode @var{from}, machine_mode @var{to}, reg_class_t @var{rclass}) |
| This hook returns true if it is possible to bitcast values held in |
| registers of class @var{rclass} from mode @var{from} to mode @var{to} |
| and if doing so preserves the low-order bits that are common to both modes. |
| The result is only meaningful if @var{rclass} has registers that can hold |
| both @code{from} and @code{to}. The default implementation returns true. |
| |
| As an example of when such bitcasting is invalid, loading 32-bit integer or |
| floating-point objects into floating-point registers on Alpha extends them |
| to 64 bits. Therefore loading a 64-bit object and then storing it as a |
| 32-bit object does not store the low-order 32 bits, as would be the case |
| for a normal register. Therefore, @file{alpha.h} defines |
| @code{TARGET_CAN_CHANGE_MODE_CLASS} to return: |
| |
| @smallexample |
| (GET_MODE_SIZE (from) == GET_MODE_SIZE (to) |
| || !reg_classes_intersect_p (FLOAT_REGS, rclass)) |
| @end smallexample |
| |
| Even if storing from a register in mode @var{to} would be valid, |
| if both @var{from} and @code{raw_reg_mode} for @var{rclass} are wider |
| than @code{word_mode}, then we must prevent @var{to} narrowing the |
| mode. This happens when the middle-end assumes that it can load |
| or store pieces of an @var{N}-word pseudo, and that the pseudo will |
| eventually be allocated to @var{N} @code{word_mode} hard registers. |
| Failure to prevent this kind of mode change will result in the |
| entire @code{raw_reg_mode} being modified instead of the partial |
| value that the middle-end intended. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} reg_class_t TARGET_IRA_CHANGE_PSEUDO_ALLOCNO_CLASS (int, @var{reg_class_t}, @var{reg_class_t}) |
| A target hook which can change allocno class for given pseudo from |
| allocno and best class calculated by IRA. |
| |
| The default version of this target hook always returns given class. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_LRA_P (void) |
| A target hook which returns true if we use LRA instead of reload pass. |
| |
| The default version of this target hook returns true. New ports |
| should use LRA, and existing ports are encouraged to convert. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} int TARGET_REGISTER_PRIORITY (int) |
| A target hook which returns the register priority number to which the |
| register @var{hard_regno} belongs to. The bigger the number, the |
| more preferable the hard register usage (when all other conditions are |
| the same). This hook can be used to prefer some hard register over |
| others in LRA. For example, some x86-64 register usage needs |
| additional prefix which makes instructions longer. The hook can |
| return lower priority number for such registers make them less favorable |
| and as result making the generated code smaller. |
| |
| The default version of this target hook returns always zero. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_REGISTER_USAGE_LEVELING_P (void) |
| A target hook which returns true if we need register usage leveling. |
| That means if a few hard registers are equally good for the |
| assignment, we choose the least used hard register. The register |
| usage leveling may be profitable for some targets. Don't use the |
| usage leveling for targets with conditional execution or targets |
| with big register files as it hurts if-conversion and cross-jumping |
| optimizations. |
| |
| The default version of this target hook returns always false. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_DIFFERENT_ADDR_DISPLACEMENT_P (void) |
| A target hook which returns true if an address with the same structure |
| can have different maximal legitimate displacement. For example, the |
| displacement can depend on memory mode or on operand combinations in |
| the insn. |
| |
| The default version of this target hook returns always false. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_CANNOT_SUBSTITUTE_MEM_EQUIV_P (rtx @var{subst}) |
| A target hook which returns @code{true} if @var{subst} can't |
| substitute safely pseudos with equivalent memory values during |
| register allocation. |
| The default version of this target hook returns @code{false}. |
| On most machines, this default should be used. For generally |
| machines with non orthogonal register usage for addressing, such |
| as SH, this hook can be used to avoid excessive spilling. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_LEGITIMIZE_ADDRESS_DISPLACEMENT (rtx *@var{offset1}, rtx *@var{offset2}, poly_int64 @var{orig_offset}, machine_mode @var{mode}) |
| This hook tries to split address offset @var{orig_offset} into |
| two parts: one that should be added to the base address to create |
| a local anchor point, and an additional offset that can be applied |
| to the anchor to address a value of mode @var{mode}. The idea is that |
| the local anchor could be shared by other accesses to nearby locations. |
| |
| The hook returns true if it succeeds, storing the offset of the |
| anchor from the base in @var{offset1} and the offset of the final address |
| from the anchor in @var{offset2}. The default implementation returns false. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} reg_class_t TARGET_SPILL_CLASS (reg_class_t, @var{machine_mode}) |
| This hook defines a class of registers which could be used for spilling |
| pseudos of the given mode and class, or @code{NO_REGS} if only memory |
| should be used. Not defining this hook is equivalent to returning |
| @code{NO_REGS} for all inputs. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_ADDITIONAL_ALLOCNO_CLASS_P (reg_class_t) |
| This hook should return @code{true} if given class of registers should |
| be an allocno class in any way. Usually RA uses only one register |
| class from all classes containing the same register set. In some |
| complicated cases, you need to have two or more such classes as |
| allocno ones for RA correct work. Not defining this hook is |
| equivalent to returning @code{false} for all inputs. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} scalar_int_mode TARGET_CSTORE_MODE (enum insn_code @var{icode}) |
| This hook defines the machine mode to use for the boolean result of |
| conditional store patterns. The ICODE argument is the instruction code |
| for the cstore being performed. Not definiting this hook is the same |
| as accepting the mode encoded into operand 0 of the cstore expander |
| patterns. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} int TARGET_COMPUTE_PRESSURE_CLASSES (enum reg_class *@var{pressure_classes}) |
| A target hook which lets a backend compute the set of pressure classes to |
| be used by those optimization passes which take register pressure into |
| account, as opposed to letting IRA compute them. It returns the number of |
| register classes stored in the array @var{pressure_classes}. |
| @end deftypefn |
| |
| @node Stack and Calling |
| @section Stack Layout and Calling Conventions |
| @cindex calling conventions |
| |
| @c prevent bad page break with this line |
| This describes the stack layout and calling conventions. |
| |
| @menu |
| * Frame Layout:: |
| * Exception Handling:: |
| * Stack Checking:: |
| * Frame Registers:: |
| * Elimination:: |
| * Stack Arguments:: |
| * Register Arguments:: |
| * Scalar Return:: |
| * Aggregate Return:: |
| * Caller Saves:: |
| * Function Entry:: |
| * Profiling:: |
| * Tail Calls:: |
| * Shrink-wrapping separate components:: |
| * Stack Smashing Protection:: |
| * Miscellaneous Register Hooks:: |
| @end menu |
| |
| @node Frame Layout |
| @subsection Basic Stack Layout |
| @cindex stack frame layout |
| @cindex frame layout |
| |
| @c prevent bad page break with this line |
| Here is the basic stack layout. |
| |
| @defmac STACK_GROWS_DOWNWARD |
| Define this macro to be true if pushing a word onto the stack moves the stack |
| pointer to a smaller address, and false otherwise. |
| @end defmac |
| |
| @defmac STACK_PUSH_CODE |
| This macro defines the operation used when something is pushed |
| on the stack. In RTL, a push operation will be |
| @code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} |
| |
| The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, |
| and @code{POST_INC}. Which of these is correct depends on |
| the stack direction and on whether the stack pointer points |
| to the last item on the stack or whether it points to the |
| space for the next item on the stack. |
| |
| The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is |
| true, which is almost always right, and @code{PRE_INC} otherwise, |
| which is often wrong. |
| @end defmac |
| |
| @defmac FRAME_GROWS_DOWNWARD |
| Define this macro to nonzero value if the addresses of local variable slots |
| are at negative offsets from the frame pointer. |
| @end defmac |
| |
| @defmac ARGS_GROW_DOWNWARD |
| Define this macro if successive arguments to a function occupy decreasing |
| addresses on the stack. |
| @end defmac |
| |
| @deftypefn {Target Hook} HOST_WIDE_INT TARGET_STARTING_FRAME_OFFSET (void) |
| This hook returns the offset from the frame pointer to the first local |
| variable slot to be allocated. If @code{FRAME_GROWS_DOWNWARD}, it is the |
| offset to @emph{end} of the first slot allocated, otherwise it is the |
| offset to @emph{beginning} of the first slot allocated. The default |
| implementation returns 0. |
| @end deftypefn |
| |
| @defmac STACK_ALIGNMENT_NEEDED |
| Define to zero to disable final alignment of the stack during reload. |
| The nonzero default for this macro is suitable for most ports. |
| |
| On ports where @code{TARGET_STARTING_FRAME_OFFSET} is nonzero or where there |
| is a register save block following the local block that doesn't require |
| alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable |
| stack alignment and do it in the backend. |
| @end defmac |
| |
| @defmac STACK_POINTER_OFFSET |
| Offset from the stack pointer register to the first location at which |
| outgoing arguments are placed. If not specified, the default value of |
| zero is used. This is the proper value for most machines. |
| |
| If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above |
| the first location at which outgoing arguments are placed. |
| @end defmac |
| |
| @defmac FIRST_PARM_OFFSET (@var{fundecl}) |
| Offset from the argument pointer register to the first argument's |
| address. On some machines it may depend on the data type of the |
| function. |
| |
| If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above |
| the first argument's address. |
| @end defmac |
| |
| @defmac STACK_DYNAMIC_OFFSET (@var{fundecl}) |
| Offset from the stack pointer register to an item dynamically allocated |
| on the stack, e.g., by @code{alloca}. |
| |
| The default value for this macro is @code{STACK_POINTER_OFFSET} plus the |
| length of the outgoing arguments. The default is correct for most |
| machines. See @file{function.c} for details. |
| @end defmac |
| |
| @defmac INITIAL_FRAME_ADDRESS_RTX |
| A C expression whose value is RTL representing the address of the initial |
| stack frame. This address is passed to @code{RETURN_ADDR_RTX} and |
| @code{DYNAMIC_CHAIN_ADDRESS}. If you don't define this macro, a reasonable |
| default value will be used. Define this macro in order to make frame pointer |
| elimination work in the presence of @code{__builtin_frame_address (count)} and |
| @code{__builtin_return_address (count)} for @code{count} not equal to zero. |
| @end defmac |
| |
| @defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) |
| A C expression whose value is RTL representing the address in a stack |
| frame where the pointer to the caller's frame is stored. Assume that |
| @var{frameaddr} is an RTL expression for the address of the stack frame |
| itself. |
| |
| If you don't define this macro, the default is to return the value |
| of @var{frameaddr}---that is, the stack frame address is also the |
| address of the stack word that points to the previous frame. |
| @end defmac |
| |
| @defmac SETUP_FRAME_ADDRESSES |
| A C expression that produces the machine-specific code to |
| setup the stack so that arbitrary frames can be accessed. For example, |
| on the SPARC, we must flush all of the register windows to the stack |
| before we can access arbitrary stack frames. You will seldom need to |
| define this macro. The default is to do nothing. |
| @end defmac |
| |
| @deftypefn {Target Hook} rtx TARGET_BUILTIN_SETJMP_FRAME_VALUE (void) |
| This target hook should return an rtx that is used to store |
| the address of the current frame into the built in @code{setjmp} buffer. |
| The default value, @code{virtual_stack_vars_rtx}, is correct for most |
| machines. One reason you may need to define this target hook is if |
| @code{hard_frame_pointer_rtx} is the appropriate value on your machine. |
| @end deftypefn |
| |
| @defmac FRAME_ADDR_RTX (@var{frameaddr}) |
| A C expression whose value is RTL representing the value of the frame |
| address for the current frame. @var{frameaddr} is the frame pointer |
| of the current frame. This is used for __builtin_frame_address. |
| You need only define this macro if the frame address is not the same |
| as the frame pointer. Most machines do not need to define it. |
| @end defmac |
| |
| @defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) |
| A C expression whose value is RTL representing the value of the return |
| address for the frame @var{count} steps up from the current frame, after |
| the prologue. @var{frameaddr} is the frame pointer of the @var{count} |
| frame, or the frame pointer of the @var{count} @minus{} 1 frame if |
| @code{RETURN_ADDR_IN_PREVIOUS_FRAME} is nonzero. |
| |
| The value of the expression must always be the correct address when |
| @var{count} is zero, but may be @code{NULL_RTX} if there is no way to |
| determine the return address of other frames. |
| @end defmac |
| |
| @defmac RETURN_ADDR_IN_PREVIOUS_FRAME |
| Define this macro to nonzero value if the return address of a particular |
| stack frame is accessed from the frame pointer of the previous stack |
| frame. The zero default for this macro is suitable for most ports. |
| @end defmac |
| |
| @defmac INCOMING_RETURN_ADDR_RTX |
| A C expression whose value is RTL representing the location of the |
| incoming return address at the beginning of any function, before the |
| prologue. This RTL is either a @code{REG}, indicating that the return |
| value is saved in @samp{REG}, or a @code{MEM} representing a location in |
| the stack. |
| |
| You only need to define this macro if you want to support call frame |
| debugging information like that provided by DWARF 2. |
| |
| If this RTL is a @code{REG}, you should also define |
| @code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. |
| @end defmac |
| |
| @defmac DWARF_ALT_FRAME_RETURN_COLUMN |
| A C expression whose value is an integer giving a DWARF 2 column |
| number that may be used as an alternative return column. The column |
| must not correspond to any gcc hard register (that is, it must not |
| be in the range of @code{DWARF_FRAME_REGNUM}). |
| |
| This macro can be useful if @code{DWARF_FRAME_RETURN_COLUMN} is set to a |
| general register, but an alternative column needs to be used for signal |
| frames. Some targets have also used different frame return columns |
| over time. |
| @end defmac |
| |
| @defmac DWARF_ZERO_REG |
| A C expression whose value is an integer giving a DWARF 2 register |
| number that is considered to always have the value zero. This should |
| only be defined if the target has an architected zero register, and |
| someone decided it was a good idea to use that register number to |
| terminate the stack backtrace. New ports should avoid this. |
| @end defmac |
| |
| @deftypefn {Target Hook} void TARGET_DWARF_HANDLE_FRAME_UNSPEC (const char *@var{label}, rtx @var{pattern}, int @var{index}) |
| This target hook allows the backend to emit frame-related insns that |
| contain UNSPECs or UNSPEC_VOLATILEs. The DWARF 2 call frame debugging |
| info engine will invoke it on insns of the form |
| @smallexample |
| (set (reg) (unspec [@dots{}] UNSPEC_INDEX)) |
| @end smallexample |
| and |
| @smallexample |
| (set (reg) (unspec_volatile [@dots{}] UNSPECV_INDEX)). |
| @end smallexample |
| to let the backend emit the call frame instructions. @var{label} is |
| the CFI label attached to the insn, @var{pattern} is the pattern of |
| the insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} {unsigned int} TARGET_DWARF_POLY_INDETERMINATE_VALUE (unsigned int @var{i}, unsigned int *@var{factor}, int *@var{offset}) |
| Express the value of @code{poly_int} indeterminate @var{i} as a DWARF |
| expression, with @var{i} counting from 1. Return the number of a DWARF |
| register @var{R} and set @samp{*@var{factor}} and @samp{*@var{offset}} such |
| that the value of the indeterminate is: |
| @smallexample |
| value_of(@var{R}) / @var{factor} - @var{offset} |
| @end smallexample |
| |
| A target only needs to define this hook if it sets |
| @samp{NUM_POLY_INT_COEFFS} to a value greater than 1. |
| @end deftypefn |
| |
| @defmac INCOMING_FRAME_SP_OFFSET |
| A C expression whose value is an integer giving the offset, in bytes, |
| from the value of the stack pointer register to the top of the stack |
| frame at the beginning of any function, before the prologue. The top of |
| the frame is defined to be the value of the stack pointer in the |
| previous frame, just before the call instruction. |
| |
| You only need to define this macro if you want to support call frame |
| debugging information like that provided by DWARF 2. |
| @end defmac |
| |
| @defmac DEFAULT_INCOMING_FRAME_SP_OFFSET |
| Like @code{INCOMING_FRAME_SP_OFFSET}, but must be the same for all |
| functions of the same ABI, and when using GAS @code{.cfi_*} directives |
| must also agree with the default CFI GAS emits. Define this macro |
| only if @code{INCOMING_FRAME_SP_OFFSET} can have different values |
| between different functions of the same ABI or when |
| @code{INCOMING_FRAME_SP_OFFSET} does not agree with GAS default CFI. |
| @end defmac |
| |
| @defmac ARG_POINTER_CFA_OFFSET (@var{fundecl}) |
| A C expression whose value is an integer giving the offset, in bytes, |
| from the argument pointer to the canonical frame address (cfa). The |
| final value should coincide with that calculated by |
| @code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable |
| during virtual register instantiation. |
| |
| The default value for this macro is |
| @code{FIRST_PARM_OFFSET (fundecl) + crtl->args.pretend_args_size}, |
| which is correct for most machines; in general, the arguments are found |
| immediately before the stack frame. Note that this is not the case on |
| some targets that save registers into the caller's frame, such as SPARC |
| and rs6000, and so such targets need to define this macro. |
| |
| You only need to define this macro if the default is incorrect, and you |
| want to support call frame debugging information like that provided by |
| DWARF 2. |
| @end defmac |
| |
| @defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl}) |
| If defined, a C expression whose value is an integer giving the offset |
| in bytes from the frame pointer to the canonical frame address (cfa). |
| The final value should coincide with that calculated by |
| @code{INCOMING_FRAME_SP_OFFSET}. |
| |
| Normally the CFA is calculated as an offset from the argument pointer, |
| via @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is |
| variable due to the ABI, this may not be possible. If this macro is |
| defined, it implies that the virtual register instantiation should be |
| based on the frame pointer instead of the argument pointer. Only one |
| of @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET} |
| should be defined. |
| @end defmac |
| |
| @defmac CFA_FRAME_BASE_OFFSET (@var{fundecl}) |
| If defined, a C expression whose value is an integer giving the offset |
| in bytes from the canonical frame address (cfa) to the frame base used |
| in DWARF 2 debug information. The default is zero. A different value |
| may reduce the size of debug information on some ports. |
| @end defmac |
| |
| @node Exception Handling |
| @subsection Exception Handling Support |
| @cindex exception handling |
| |
| @defmac EH_RETURN_DATA_REGNO (@var{N}) |
| A C expression whose value is the @var{N}th register number used for |
| data by exception handlers, or @code{INVALID_REGNUM} if fewer than |
| @var{N} registers are usable. |
| |
| The exception handling library routines communicate with the exception |
| handlers via a set of agreed upon registers. Ideally these registers |
| should be call-clobbered; it is possible to use call-saved registers, |
| but may negatively impact code size. The target must support at least |
| 2 data registers, but should define 4 if there are enough free registers. |
| |
| You must define this macro if you want to support call frame exception |
| handling like that provided by DWARF 2. |
| @end defmac |
| |
| @defmac EH_RETURN_STACKADJ_RTX |
| A C expression whose value is RTL representing a location in which |
| to store a stack adjustment to be applied before function return. |
| This is used to unwind the stack to an exception handler's call frame. |
| It will be assigned zero on code paths that return normally. |
| |
| Typically this is a call-clobbered hard register that is otherwise |
| untouched by the epilogue, but could also be a stack slot. |
| |
| Do not define this macro if the stack pointer is saved and restored |
| by the regular prolog and epilog code in the call frame itself; in |
| this case, the exception handling library routines will update the |
| stack location to be restored in place. Otherwise, you must define |
| this macro if you want to support call frame exception handling like |
| that provided by DWARF 2. |
| @end defmac |
| |
| @defmac EH_RETURN_HANDLER_RTX |
| A C expression whose value is RTL representing a location in which |
| to store the address of an exception handler to which we should |
| return. It will not be assigned on code paths that return normally. |
| |
| Typically this is the location in the call frame at which the normal |
| return address is stored. For targets that return by popping an |
| address off the stack, this might be a memory address just below |
| the @emph{target} call frame rather than inside the current call |
| frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already |
| been assigned, so it may be used to calculate the location of the |
| target call frame. |
| |
| Some targets have more complex requirements than storing to an |
| address calculable during initial code generation. In that case |
| the @code{eh_return} instruction pattern should be used instead. |
| |
| If you want to support call frame exception handling, you must |
| define either this macro or the @code{eh_return} instruction pattern. |
| @end defmac |
| |
| @defmac RETURN_ADDR_OFFSET |
| If defined, an integer-valued C expression for which rtl will be generated |
| to add it to the exception handler address before it is searched in the |
| exception handling tables, and to subtract it again from the address before |
| using it to return to the exception handler. |
| @end defmac |
| |
| @defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global}) |
| This macro chooses the encoding of pointers embedded in the exception |
| handling sections. If at all possible, this should be defined such |
| that the exception handling section will not require dynamic relocations, |
| and so may be read-only. |
| |
| @var{code} is 0 for data, 1 for code labels, 2 for function pointers. |
| @var{global} is true if the symbol may be affected by dynamic relocations. |
| The macro should return a combination of the @code{DW_EH_PE_*} defines |
| as found in @file{dwarf2.h}. |
| |
| If this macro is not defined, pointers will not be encoded but |
| represented directly. |
| @end defmac |
| |
| @defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) |
| This macro allows the target to emit whatever special magic is required |
| to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. |
| Generic code takes care of pc-relative and indirect encodings; this must |
| be defined if the target uses text-relative or data-relative encodings. |
| |
| This is a C statement that branches to @var{done} if the format was |
| handled. @var{encoding} is the format chosen, @var{size} is the number |
| of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} |
| to be emitted. |
| @end defmac |
| |
| @defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs}) |
| This macro allows the target to add CPU and operating system specific |
| code to the call-frame unwinder for use when there is no unwind data |
| available. The most common reason to implement this macro is to unwind |
| through signal frames. |
| |
| This macro is called from @code{uw_frame_state_for} in |
| @file{unwind-dw2.c}, @file{unwind-dw2-xtensa.c} and |
| @file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; |
| @var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} |
| for the address of the code being executed and @code{context->cfa} for |
| the stack pointer value. If the frame can be decoded, the register |
| save addresses should be updated in @var{fs} and the macro should |
| evaluate to @code{_URC_NO_REASON}. If the frame cannot be decoded, |
| the macro should evaluate to @code{_URC_END_OF_STACK}. |
| |
| For proper signal handling in Java this macro is accompanied by |
| @code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers. |
| @end defmac |
| |
| @defmac MD_HANDLE_UNWABI (@var{context}, @var{fs}) |
| This macro allows the target to add operating system specific code to the |
| call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive, |
| usually used for signal or interrupt frames. |
| |
| This macro is called from @code{uw_update_context} in libgcc's |
| @file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; |
| @var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi} |
| for the abi and context in the @code{.unwabi} directive. If the |
| @code{.unwabi} directive can be handled, the register save addresses should |
| be updated in @var{fs}. |
| @end defmac |
| |
| @defmac TARGET_USES_WEAK_UNWIND_INFO |
| A C expression that evaluates to true if the target requires unwind |
| info to be given comdat linkage. Define it to be @code{1} if comdat |
| linkage is necessary. The default is @code{0}. |
| @end defmac |
| |
| @node Stack Checking |
| @subsection Specifying How Stack Checking is Done |
| |
| GCC will check that stack references are within the boundaries of the |
| stack, if the option @option{-fstack-check} is specified, in one of |
| three ways: |
| |
| @enumerate |
| @item |
| If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC |
| will assume that you have arranged for full stack checking to be done |
| at appropriate places in the configuration files. GCC will not do |
| other special processing. |
| |
| @item |
| If @code{STACK_CHECK_BUILTIN} is zero and the value of the |
| @code{STACK_CHECK_STATIC_BUILTIN} macro is nonzero, GCC will assume |
| that you have arranged for static stack checking (checking of the |
| static stack frame of functions) to be done at appropriate places |
| in the configuration files. GCC will only emit code to do dynamic |
| stack checking (checking on dynamic stack allocations) using the third |
| approach below. |
| |
| @item |
| If neither of the above are true, GCC will generate code to periodically |
| ``probe'' the stack pointer using the values of the macros defined below. |
| @end enumerate |
| |
| If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined, |
| GCC will change its allocation strategy for large objects if the option |
| @option{-fstack-check} is specified: they will always be allocated |
| dynamically if their size exceeds @code{STACK_CHECK_MAX_VAR_SIZE} bytes. |
| |
| @defmac STACK_CHECK_BUILTIN |
| A nonzero value if stack checking is done by the configuration files in a |
| machine-dependent manner. You should define this macro if stack checking |
| is required by the ABI of your machine or if you would like to do stack |
| checking in some more efficient way than the generic approach. The default |
| value of this macro is zero. |
| @end defmac |
| |
| @defmac STACK_CHECK_STATIC_BUILTIN |
| A nonzero value if static stack checking is done by the configuration files |
| in a machine-dependent manner. You should define this macro if you would |
| like to do static stack checking in some more efficient way than the generic |
| approach. The default value of this macro is zero. |
| @end defmac |
| |
| @defmac STACK_CHECK_PROBE_INTERVAL_EXP |
| An integer specifying the interval at which GCC must generate stack probe |
| instructions, defined as 2 raised to this integer. You will normally |
| define this macro so that the interval be no larger than the size of |
| the ``guard pages'' at the end of a stack area. The default value |
| of 12 (4096-byte interval) is suitable for most systems. |
| @end defmac |
| |
| @defmac STACK_CHECK_MOVING_SP |
| An integer which is nonzero if GCC should move the stack pointer page by page |
| when doing probes. This can be necessary on systems where the stack pointer |
| contains the bottom address of the memory area accessible to the executing |
| thread at any point in time. In this situation an alternate signal stack |
| is required in order to be able to recover from a stack overflow. The |
| default value of this macro is zero. |
| @end defmac |
| |
| @defmac STACK_CHECK_PROTECT |
| The number of bytes of stack needed to recover from a stack overflow, for |
| languages where such a recovery is supported. The default value of 4KB/8KB |
| with the @code{setjmp}/@code{longjmp}-based exception handling mechanism and |
| 8KB/12KB with other exception handling mechanisms should be adequate for most |
| architectures and operating systems. |
| @end defmac |
| |
| The following macros are relevant only if neither STACK_CHECK_BUILTIN |
| nor STACK_CHECK_STATIC_BUILTIN is defined; you can omit them altogether |
| in the opposite case. |
| |
| @defmac STACK_CHECK_MAX_FRAME_SIZE |
| The maximum size of a stack frame, in bytes. GCC will generate probe |
| instructions in non-leaf functions to ensure at least this many bytes of |
| stack are available. If a stack frame is larger than this size, stack |
| checking will not be reliable and GCC will issue a warning. The |
| default is chosen so that GCC only generates one instruction on most |
| systems. You should normally not change the default value of this macro. |
| @end defmac |
| |
| @defmac STACK_CHECK_FIXED_FRAME_SIZE |
| GCC uses this value to generate the above warning message. It |
| represents the amount of fixed frame used by a function, not including |
| space for any callee-saved registers, temporaries and user variables. |
| You need only specify an upper bound for this amount and will normally |
| use the default of four words. |
| @end defmac |
| |
| @defmac STACK_CHECK_MAX_VAR_SIZE |
| The maximum size, in bytes, of an object that GCC will place in the |
| fixed area of the stack frame when the user specifies |
| @option{-fstack-check}. |
| GCC computed the default from the values of the above macros and you will |
| normally not need to override that default. |
| @end defmac |
| |
| @deftypefn {Target Hook} HOST_WIDE_INT TARGET_STACK_CLASH_PROTECTION_ALLOCA_PROBE_RANGE (void) |
| Some targets have an ABI defined interval for which no probing needs to be done. |
| When a probe does need to be done this same interval is used as the probe distance |
| up when doing stack clash protection for alloca. |
| On such targets this value can be set to override the default probing up interval. |
| Define this variable to return nonzero if such a probe range is required or zero otherwise. |
| Defining this hook also requires your functions which make use of alloca to have at least 8 byes |
| of outgoing arguments. If this is not the case the stack will be corrupted. |
| You need not define this macro if it would always have the value zero. |
| @end deftypefn |
| |
| @need 2000 |
| @node Frame Registers |
| @subsection Registers That Address the Stack Frame |
| |
| @c prevent bad page break with this line |
| This discusses registers that address the stack frame. |
| |
| @defmac STACK_POINTER_REGNUM |
| The register number of the stack pointer register, which must also be a |
| fixed register according to @code{FIXED_REGISTERS}. On most machines, |
| the hardware determines which register this is. |
| @end defmac |
| |
| @defmac FRAME_POINTER_REGNUM |
| The register number of the frame pointer register, which is used to |
| access automatic variables in the stack frame. On some machines, the |
| hardware determines which register this is. On other machines, you can |
| choose any register you wish for this purpose. |
| @end defmac |
| |
| @defmac HARD_FRAME_POINTER_REGNUM |
| On some machines the offset between the frame pointer and starting |
| offset of the automatic variables is not known until after register |
| allocation has been done (for example, because the saved registers are |
| between these two locations). On those machines, define |
| @code{FRAME_POINTER_REGNUM} the number of a special, fixed register to |
| be used internally until the offset is known, and define |
| @code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number |
| used for the frame pointer. |
| |
| You should define this macro only in the very rare circumstances when it |
| is not possible to calculate the offset between the frame pointer and |
| the automatic variables until after register allocation has been |
| completed. When this macro is defined, you must also indicate in your |
| definition of @code{ELIMINABLE_REGS} how to eliminate |
| @code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} |
| or @code{STACK_POINTER_REGNUM}. |
| |
| Do not define this macro if it would be the same as |
| @code{FRAME_POINTER_REGNUM}. |
| @end defmac |
| |
| @defmac ARG_POINTER_REGNUM |
| The register number of the arg pointer register, which is used to access |
| the function's argument list. On some machines, this is the same as the |
| frame pointer register. On some machines, the hardware determines which |
| register this is. On other machines, you can choose any register you |
| wish for this purpose. If this is not the same register as the frame |
| pointer register, then you must mark it as a fixed register according to |
| @code{FIXED_REGISTERS}, or arrange to be able to eliminate it |
| (@pxref{Elimination}). |
| @end defmac |
| |
| @defmac HARD_FRAME_POINTER_IS_FRAME_POINTER |
| Define this to a preprocessor constant that is nonzero if |
| @code{hard_frame_pointer_rtx} and @code{frame_pointer_rtx} should be |
| the same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM |
| == FRAME_POINTER_REGNUM)}; you only need to define this macro if that |
| definition is not suitable for use in preprocessor conditionals. |
| @end defmac |
| |
| @defmac HARD_FRAME_POINTER_IS_ARG_POINTER |
| Define this to a preprocessor constant that is nonzero if |
| @code{hard_frame_pointer_rtx} and @code{arg_pointer_rtx} should be the |
| same. The default definition is @samp{(HARD_FRAME_POINTER_REGNUM == |
| ARG_POINTER_REGNUM)}; you only need to define this macro if that |
| definition is not suitable for use in preprocessor conditionals. |
| @end defmac |
| |
| @defmac RETURN_ADDRESS_POINTER_REGNUM |
| The register number of the return address pointer register, which is used to |
| access the current function's return address from the stack. On some |
| machines, the return address is not at a fixed offset from the frame |
| pointer or stack pointer or argument pointer. This register can be defined |
| to point to the return address on the stack, and then be converted by |
| @code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. |
| |
| Do not define this macro unless there is no other way to get the return |
| address from the stack. |
| @end defmac |
| |
| @defmac STATIC_CHAIN_REGNUM |
| @defmacx STATIC_CHAIN_INCOMING_REGNUM |
| Register numbers used for passing a function's static chain pointer. If |
| register windows are used, the register number as seen by the called |
| function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register |
| number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If |
| these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need |
| not be defined. |
| |
| The static chain register need not be a fixed register. |
| |
| If the static chain is passed in memory, these macros should not be |
| defined; instead, the @code{TARGET_STATIC_CHAIN} hook should be used. |
| @end defmac |
| |
| @deftypefn {Target Hook} rtx TARGET_STATIC_CHAIN (const_tree @var{fndecl_or_type}, bool @var{incoming_p}) |
| This hook replaces the use of @code{STATIC_CHAIN_REGNUM} et al for |
| targets that may use different static chain locations for different |
| nested functions. This may be required if the target has function |
| attributes that affect the calling conventions of the function and |
| those calling conventions use different static chain locations. |
| |
| The default version of this hook uses @code{STATIC_CHAIN_REGNUM} et al. |
| |
| If the static chain is passed in memory, this hook should be used to |
| provide rtx giving @code{mem} expressions that denote where they are stored. |
| Often the @code{mem} expression as seen by the caller will be at an offset |
| from the stack pointer and the @code{mem} expression as seen by the callee |
| will be at an offset from the frame pointer. |
| @findex stack_pointer_rtx |
| @findex frame_pointer_rtx |
| @findex arg_pointer_rtx |
| The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and |
| @code{arg_pointer_rtx} will have been initialized and should be used |
| to refer to those items. |
| @end deftypefn |
| |
| @defmac DWARF_FRAME_REGISTERS |
| This macro specifies the maximum number of hard registers that can be |
| saved in a call frame. This is used to size data structures used in |
| DWARF2 exception handling. |
| |
| Prior to GCC 3.0, this macro was needed in order to establish a stable |
| exception handling ABI in the face of adding new hard registers for ISA |
| extensions. In GCC 3.0 and later, the EH ABI is insulated from changes |
| in the number of hard registers. Nevertheless, this macro can still be |
| used to reduce the runtime memory requirements of the exception handling |
| routines, which can be substantial if the ISA contains a lot of |
| registers that are not call-saved. |
| |
| If this macro is not defined, it defaults to |
| @code{FIRST_PSEUDO_REGISTER}. |
| @end defmac |
| |
| @defmac PRE_GCC3_DWARF_FRAME_REGISTERS |
| |
| This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided |
| for backward compatibility in pre GCC 3.0 compiled code. |
| |
| If this macro is not defined, it defaults to |
| @code{DWARF_FRAME_REGISTERS}. |
| @end defmac |
| |
| @defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno}) |
| |
| Define this macro if the target's representation for dwarf registers |
| is different than the internal representation for unwind column. |
| Given a dwarf register, this macro should return the internal unwind |
| column number to use instead. |
| @end defmac |
| |
| @defmac DWARF_FRAME_REGNUM (@var{regno}) |
| |
| Define this macro if the target's representation for dwarf registers |
| used in .eh_frame or .debug_frame is different from that used in other |
| debug info sections. Given a GCC hard register number, this macro |
| should return the .eh_frame register number. The default is |
| @code{DBX_REGISTER_NUMBER (@var{regno})}. |
| |
| @end defmac |
| |
| @defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh}) |
| |
| Define this macro to map register numbers held in the call frame info |
| that GCC has collected using @code{DWARF_FRAME_REGNUM} to those that |
| should be output in .debug_frame (@code{@var{for_eh}} is zero) and |
| .eh_frame (@code{@var{for_eh}} is nonzero). The default is to |
| return @code{@var{regno}}. |
| |
| @end defmac |
| |
| @defmac REG_VALUE_IN_UNWIND_CONTEXT |
| |
| Define this macro if the target stores register values as |
| @code{_Unwind_Word} type in unwind context. It should be defined if |
| target register size is larger than the size of @code{void *}. The |
| default is to store register values as @code{void *} type. |
| |
| @end defmac |
| |
| @defmac ASSUME_EXTENDED_UNWIND_CONTEXT |
| |
| Define this macro to be 1 if the target always uses extended unwind |
| context with version, args_size and by_value fields. If it is undefined, |
| it will be defined to 1 when @code{REG_VALUE_IN_UNWIND_CONTEXT} is |
| defined and 0 otherwise. |
| |
| @end defmac |
| |
| @defmac DWARF_LAZY_REGISTER_VALUE (@var{regno}, @var{value}) |
| Define this macro if the target has pseudo DWARF registers whose |
| values need to be computed lazily on demand by the unwinder (such as when |
| referenced in a CFA expression). The macro returns true if @var{regno} |
| is such a register and stores its value in @samp{*@var{value}} if so. |
| @end defmac |
| |
| @node Elimination |
| @subsection Eliminating Frame Pointer and Arg Pointer |
| |
| @c prevent bad page break with this line |
| This is about eliminating the frame pointer and arg pointer. |
| |
| @deftypefn {Target Hook} bool TARGET_FRAME_POINTER_REQUIRED (void) |
| This target hook should return @code{true} if a function must have and use |
| a frame pointer. This target hook is called in the reload pass. If its return |
| value is @code{true} the function will have a frame pointer. |
| |
| This target hook can in principle examine the current function and decide |
| according to the facts, but on most machines the constant @code{false} or the |
| constant @code{true} suffices. Use @code{false} when the machine allows code |
| to be generated with no frame pointer, and doing so saves some time or space. |
| Use @code{true} when there is no possible advantage to avoiding a frame |
| pointer. |
| |
| In certain cases, the compiler does not know how to produce valid code |
| without a frame pointer. The compiler recognizes those cases and |
| automatically gives the function a frame pointer regardless of what |
| @code{targetm.frame_pointer_required} returns. You don't need to worry about |
| them. |
| |
| In a function that does not require a frame pointer, the frame pointer |
| register can be allocated for ordinary usage, unless you mark it as a |
| fixed register. See @code{FIXED_REGISTERS} for more information. |
| |
| Default return value is @code{false}. |
| @end deftypefn |
| |
| @defmac ELIMINABLE_REGS |
| This macro specifies a table of register pairs used to eliminate |
| unneeded registers that point into the stack frame. |
| |
| The definition of this macro is a list of structure initializations, each |
| of which specifies an original and replacement register. |
| |
| On some machines, the position of the argument pointer is not known until |
| the compilation is completed. In such a case, a separate hard register |
| must be used for the argument pointer. This register can be eliminated by |
| replacing it with either the frame pointer or the argument pointer, |
| depending on whether or not the frame pointer has been eliminated. |
| |
| In this case, you might specify: |
| @smallexample |
| #define ELIMINABLE_REGS \ |
| @{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ |
| @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ |
| @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} |
| @end smallexample |
| |
| Note that the elimination of the argument pointer with the stack pointer is |
| specified first since that is the preferred elimination. |
| @end defmac |
| |
| @deftypefn {Target Hook} bool TARGET_CAN_ELIMINATE (const int @var{from_reg}, const int @var{to_reg}) |
| This target hook should return @code{true} if the compiler is allowed to |
| try to replace register number @var{from_reg} with register number |
| @var{to_reg}. This target hook will usually be @code{true}, since most of the |
| cases preventing register elimination are things that the compiler already |
| knows about. |
| |
| Default return value is @code{true}. |
| @end deftypefn |
| |
| @defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) |
| This macro returns the initial difference between the specified pair |
| of registers. The value would be computed from information |
| such as the result of @code{get_frame_size ()} and the tables of |
| registers @code{df_regs_ever_live_p} and @code{call_used_regs}. |
| @end defmac |
| |
| @deftypefn {Target Hook} void TARGET_COMPUTE_FRAME_LAYOUT (void) |
| This target hook is called once each time the frame layout needs to be |
| recalculated. The calculations can be cached by the target and can then |
| be used by @code{INITIAL_ELIMINATION_OFFSET} instead of re-computing the |
| layout on every invocation of that hook. This is particularly useful |
| for targets that have an expensive frame layout function. Implementing |
| this callback is optional. |
| @end deftypefn |
| |
| @node Stack Arguments |
| @subsection Passing Function Arguments on the Stack |
| @cindex arguments on stack |
| @cindex stack arguments |
| |
| The macros in this section control how arguments are passed |
| on the stack. See the following section for other macros that |
| control passing certain arguments in registers. |
| |
| @deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (const_tree @var{fntype}) |
| This target hook returns @code{true} if an argument declared in a |
| prototype as an integral type smaller than @code{int} should actually be |
| passed as an @code{int}. In addition to avoiding errors in certain |
| cases of mismatch, it also makes for better code on certain machines. |
| The default is to not promote prototypes. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_PUSH_ARGUMENT (unsigned int @var{npush}) |
| This target hook returns @code{true} if push instructions will be |
| used to pass outgoing arguments. When the push instruction usage is |
| optional, @var{npush} is nonzero to indicate the number of bytes to |
| push. Otherwise, @var{npush} is zero. If the target machine does not |
| have a push instruction or push instruction should be avoided, |
| @code{false} should be returned. That directs GCC to use an alternate |
| strategy: to allocate the entire argument block and then store the |
| arguments into it. If this target hook may return @code{true}, |
| @code{PUSH_ROUNDING} must be defined. |
| @end deftypefn |
| |
| @defmac PUSH_ARGS_REVERSED |
| A C expression. If nonzero, function arguments will be evaluated from |
| last to first, rather than from first to last. If this macro is not |
| defined, it defaults to @code{PUSH_ARGS} on targets where the stack |
| and args grow in opposite directions, and 0 otherwise. |
| @end defmac |
| |
| @defmac PUSH_ROUNDING (@var{npushed}) |
| A C expression that is the number of bytes actually pushed onto the |
| stack when an instruction attempts to push @var{npushed} bytes. |
| |
| On some machines, the definition |
| |
| @smallexample |
| #define PUSH_ROUNDING(BYTES) (BYTES) |
| @end smallexample |
| |
| @noindent |
| will suffice. But on other machines, instructions that appear |
| to push one byte actually push two bytes in an attempt to maintain |
| alignment. Then the definition should be |
| |
| @smallexample |
| #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) |
| @end smallexample |
| |
| If the value of this macro has a type, it should be an unsigned type. |
| @end defmac |
| |
| @findex outgoing_args_size |
| @findex crtl->outgoing_args_size |
| @defmac ACCUMULATE_OUTGOING_ARGS |
| A C expression. If nonzero, the maximum amount of space required for outgoing arguments |
| will be computed and placed into |
| @code{crtl->outgoing_args_size}. No space will be pushed |
| onto the stack for each call; instead, the function prologue should |
| increase the stack frame size by this amount. |
| |
| Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} |
| is not proper. |
| @end defmac |
| |
| @defmac REG_PARM_STACK_SPACE (@var{fndecl}) |
| Define this macro if functions should assume that stack space has been |
| allocated for arguments even when their values are passed in |
| registers. |
| |
| The value of this macro is the size, in bytes, of the area reserved for |
| arguments passed in registers for the function represented by @var{fndecl}, |
| which can be zero if GCC is calling a library function. |
| The argument @var{fndecl} can be the FUNCTION_DECL, or the type itself |
| of the function. |
| |
| This space can be allocated by the caller, or be a part of the |
| machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says |
| which. |
| @end defmac |
| @c above is overfull. not sure what to do. --mew 5feb93 did |
| @c something, not sure if it looks good. --mew 10feb93 |
| |
| @defmac INCOMING_REG_PARM_STACK_SPACE (@var{fndecl}) |
| Like @code{REG_PARM_STACK_SPACE}, but for incoming register arguments. |
| Define this macro if space guaranteed when compiling a function body |
| is different to space required when making a call, a situation that |
| can arise with K&R style function definitions. |
| @end defmac |
| |
| @defmac OUTGOING_REG_PARM_STACK_SPACE (@var{fntype}) |
| Define this to a nonzero value if it is the responsibility of the |
| caller to allocate the area reserved for arguments passed in registers |
| when calling a function of @var{fntype}. @var{fntype} may be NULL |
| if the function called is a library function. |
| |
| If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls |
| whether the space for these arguments counts in the value of |
| @code{crtl->outgoing_args_size}. |
| @end defmac |
| |
| @defmac STACK_PARMS_IN_REG_PARM_AREA |
| Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the |
| stack parameters don't skip the area specified by it. |
| @c i changed this, makes more sens and it should have taken care of the |
| @c overfull.. not as specific, tho. --mew 5feb93 |
| |
| Normally, when a parameter is not passed in registers, it is placed on the |
| stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro |
| suppresses this behavior and causes the parameter to be passed on the |
| stack in its natural location. |
| @end defmac |
| |
| @deftypefn {Target Hook} poly_int64 TARGET_RETURN_POPS_ARGS (tree @var{fundecl}, tree @var{funtype}, poly_int64 @var{size}) |
| This target hook returns the number of bytes of its own arguments that |
| a function pops on returning, or 0 if the function pops no arguments |
| and the caller must therefore pop them all after the function returns. |
| |
| @var{fundecl} is a C variable whose value is a tree node that describes |
| the function in question. Normally it is a node of type |
| @code{FUNCTION_DECL} that describes the declaration of the function. |
| From this you can obtain the @code{DECL_ATTRIBUTES} of the function. |
| |
| @var{funtype} is a C variable whose value is a tree node that |
| describes the function in question. Normally it is a node of type |
| @code{FUNCTION_TYPE} that describes the data type of the function. |
| From this it is possible to obtain the data types of the value and |
| arguments (if known). |
| |
| When a call to a library function is being considered, @var{fundecl} |
| will contain an identifier node for the library function. Thus, if |
| you need to distinguish among various library functions, you can do so |
| by their names. Note that ``library function'' in this context means |
| a function used to perform arithmetic, whose name is known specially |
| in the compiler and was not mentioned in the C code being compiled. |
| |
| @var{size} is the number of bytes of arguments passed on the |
| stack. If a variable number of bytes is passed, it is zero, and |
| argument popping will always be the responsibility of the calling function. |
| |
| On the VAX, all functions always pop their arguments, so the definition |
| of this macro is @var{size}. On the 68000, using the standard |
| calling convention, no functions pop their arguments, so the value of |
| the macro is always 0 in this case. But an alternative calling |
| convention is available in which functions that take a fixed number of |
| arguments pop them but other functions (such as @code{printf}) pop |
| nothing (the caller pops all). When this convention is in use, |
| @var{funtype} is examined to determine whether a function takes a fixed |
| number of arguments. |
| @end deftypefn |
| |
| @defmac CALL_POPS_ARGS (@var{cum}) |
| A C expression that should indicate the number of bytes a call sequence |
| pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} |
| when compiling a function call. |
| |
| @var{cum} is the variable in which all arguments to the called function |
| have been accumulated. |
| |
| On certain architectures, such as the SH5, a call trampoline is used |
| that pops certain registers off the stack, depending on the arguments |
| that have been passed to the function. Since this is a property of the |
| call site, not of the called function, @code{RETURN_POPS_ARGS} is not |
| appropriate. |
| @end defmac |
| |
| @node Register Arguments |
| @subsection Passing Arguments in Registers |
| @cindex arguments in registers |
| @cindex registers arguments |
| |
| This section describes the macros which let you control how various |
| types of arguments are passed in registers or how they are arranged in |
| the stack. |
| |
| @deftypefn {Target Hook} rtx TARGET_FUNCTION_ARG (cumulative_args_t @var{ca}, const function_arg_info @var{&arg}) |
| Return an RTX indicating whether function argument @var{arg} is passed |
| in a register and if so, which register. Argument @var{ca} summarizes all |
| the previous arguments. |
| |
| The return value is usually either a @code{reg} RTX for the hard |
| register in which to pass the argument, or zero to pass the argument |
| on the stack. |
| |
| The return value can be a @code{const_int} which means argument is |
| passed in a target specific slot with specified number. Target hooks |
| should be used to store or load argument in such case. See |
| @code{TARGET_STORE_BOUNDS_FOR_ARG} and @code{TARGET_LOAD_BOUNDS_FOR_ARG} |
| for more information. |
| |
| The value of the expression can also be a @code{parallel} RTX@. This is |
| used when an argument is passed in multiple locations. The mode of the |
| @code{parallel} should be the mode of the entire argument. The |
| @code{parallel} holds any number of @code{expr_list} pairs; each one |
| describes where part of the argument is passed. In each |
| @code{expr_list} the first operand must be a @code{reg} RTX for the hard |
| register in which to pass this part of the argument, and the mode of the |
| register RTX indicates how large this part of the argument is. The |
| second operand of the @code{expr_list} is a @code{const_int} which gives |
| the offset in bytes into the entire argument of where this part starts. |
| As a special exception the first @code{expr_list} in the @code{parallel} |
| RTX may have a first operand of zero. This indicates that the entire |
| argument is also stored on the stack. |
| |
| The last time this hook is called, it is called with @code{MODE == |
| VOIDmode}, and its result is passed to the @code{call} or @code{call_value} |
| pattern as operands 2 and 3 respectively. |
| |
| @cindex @file{stdarg.h} and register arguments |
| The usual way to make the ISO library @file{stdarg.h} work on a |
| machine where some arguments are usually passed in registers, is to |
| cause nameless arguments to be passed on the stack instead. This is |
| done by making @code{TARGET_FUNCTION_ARG} return 0 whenever |
| @var{named} is @code{false}. |
| |
| @cindex @code{TARGET_MUST_PASS_IN_STACK}, and @code{TARGET_FUNCTION_ARG} |
| @cindex @code{REG_PARM_STACK_SPACE}, and @code{TARGET_FUNCTION_ARG} |
| You may use the hook @code{targetm.calls.must_pass_in_stack} |
| in the definition of this macro to determine if this argument is of a |
| type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} |
| is not defined and @code{TARGET_FUNCTION_ARG} returns nonzero for such an |
| argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is |
| defined, the argument will be computed in the stack and then loaded into |
| a register. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} bool TARGET_MUST_PASS_IN_STACK (const function_arg_info @var{&arg}) |
| This target hook should return @code{true} if we should not pass @var{arg} |
| solely in registers. The file @file{expr.h} defines a |
| definition that is usually appropriate, refer to @file{expr.h} for additional |
| documentation. |
| @end deftypefn |
| |
| @deftypefn {Target Hook} rtx TARGET_FUNCTION_INCOMING_ARG (cumulative_args_t @var{ca}, const function_arg_info @var{&arg}) |
| Define this hook if the caller and callee on the target have different |
| views of where arguments are passed. Also define this hook if there are |
| functions that are never directly called, but are invoked by the hardware |
| and which have nonstandard calling conventions. |
| |
| |