-@c Copyright (C) 1988-2016 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2020 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
* 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
@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
@hook TARGET_OPTION_INIT_STRUCT
-@hook TARGET_OPTION_DEFAULT_PARAMS
-
@defmac SWITCHABLE_TARGET
Some targets need to switch between substantially different subtargets
during compilation. For example, the MIPS target has one subtarget for
by the @code{__attribute__ ((aligned (@var{n})))} construct.
@end defmac
-@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed})
-An expression for the alignment of a structure field @var{field} if the
-alignment computed in the usual way (including applying of
-@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the
+@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.
+@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
@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. If not defined,
-the default value is @code{BIGGEST_ALIGNMENT}.
+@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)}.
+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
+@hook TARGET_STATIC_RTX_ALIGNMENT
+
@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
If this macro is not defined, then @var{basic-align} is used.
@end defmac
-@defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align})
-If defined, a C expression to compute the alignment given to 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 value of this macro is used instead of that alignment to
-align the object.
-
-The default definition just returns @var{basic-align}.
-
-The typical use of this macro is to increase alignment for string
-constants to be word aligned so that @code{strcpy} calls that copy
-constants can be done inline.
-@end defmac
+@hook TARGET_CONSTANT_ALIGNMENT
@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align})
If defined, a C expression to compute the alignment for a variable in
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
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}).
-This macro is optional. If not specified, it defaults to the value
-of @code{CALL_USED_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
-@defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode})
@cindex call-used register
@cindex call-clobbered register
@cindex call-saved register
-A C expression that is nonzero if it is not permissible to store a
-value of mode @var{mode} in hard register number @var{regno} across a
-call without some part of it being clobbered. For most machines this
-macro need not be defined. It is only required for machines that do not
-preserve the entire contents of a register across a call.
-@end defmac
+@hook TARGET_FNTYPE_ABI
+
+@hook TARGET_INSN_CALLEE_ABI
+
+@cindex call-used register
+@cindex call-clobbered register
+@cindex call-saved register
+@hook TARGET_HARD_REGNO_CALL_PART_CLOBBERED
+
+@hook TARGET_GET_MULTILIB_ABI_NAME
@findex fixed_regs
@findex call_used_regs
(specifically, which machine modes) each register can hold, and how many
consecutive registers are needed for a given mode.
-@defmac HARD_REGNO_NREGS (@var{regno}, @var{mode})
-A C expression for the number of consecutive hard registers, starting
-at register number @var{regno}, required to hold a value of mode
-@var{mode}. This macro must never return zero, even if a register
-cannot hold the requested mode - indicate that with HARD_REGNO_MODE_OK
-and/or CANNOT_CHANGE_MODE_CLASS instead.
-
-On a machine where all registers are exactly one word, a suitable
-definition of this macro is
-
-@smallexample
-#define HARD_REGNO_NREGS(REGNO, MODE) \
- ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \
- / UNITS_PER_WORD)
-@end smallexample
-@end defmac
+@hook TARGET_HARD_REGNO_NREGS
@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 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{HARD_REGNO_NREGS}). By default this is zero.
+@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
floating-point registers is still 32-bit.
@end defmac
-@defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
-A C expression that is nonzero 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). For a machine where all registers
-are equivalent, a suitable definition is
-
-@smallexample
-#define HARD_REGNO_MODE_OK(REGNO, MODE) 1
-@end smallexample
-
-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 macro 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
-@code{HARD_REGNO_MODE_OK} 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{HARD_REGNO_MODE_OK}
-and @code{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{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 macro 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{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 defmac
+@hook TARGET_HARD_REGNO_MODE_OK
@defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to})
A C expression that is nonzero if it is OK to rename a hard register
The default is always nonzero.
@end defmac
-@defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2})
-A C expression that is nonzero if a value of mode
-@var{mode1} is accessible in mode @var{mode2} without copying.
-
-If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
-@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for
-any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})}
-should be nonzero. If they differ for any @var{r}, you should define
-this macro to return zero unless some other mechanism ensures the
-accessibility of the value in a narrower mode.
-
-You should define this macro to return nonzero in as many cases as
-possible since doing so will allow GCC to perform better register
-allocation.
-@end defmac
+@hook TARGET_MODES_TIEABLE_P
@hook TARGET_HARD_REGNO_SCRATCH_OK
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{HARD_REGNO_MODE_OK}.
+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
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 can't be loaded
+@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}.
ordinarily be used.
Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when
-there are certain modes that simply can't go in certain reload classes.
+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.
general registers.
@end defmac
-@defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m})
-Certain machines have the property that some registers cannot be copied
-to some other registers without using memory. Define this macro on
-those machines to be a C expression that is nonzero 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}.
-
-Do not define this macro if its value would always be zero.
-@end defmac
+@hook TARGET_SECONDARY_MEMORY_NEEDED
@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode})
-Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler
+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{SECONDARY_MEMORY_NEEDED}.
+@code{TARGET_SECONDARY_MEMORY_NEEDED}.
@end defmac
-@defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode})
-When the compiler needs a secondary memory location to copy between two
-registers of mode @var{mode}, it normally allocates sufficient memory to
-hold a quantity of @code{BITS_PER_WORD} bits and performs the store and
-load operations in a mode that many bits wide and whose class is the
-same as that of @var{mode}.
+@hook TARGET_SECONDARY_MEMORY_NEEDED_MODE
-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 macro to
-suppress that widening in some cases. See the file @file{alpha.h} for
-details.
-
-Do not define this macro if you do not define
-@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that
-is @code{BITS_PER_WORD} bits wide is correct for your machine.
-@end defmac
+@hook TARGET_SELECT_EARLY_REMAT_MODES
@hook TARGET_CLASS_LIKELY_SPILLED_P
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{HARD_REGNO_NREGS}. In fact,
+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{HARD_REGNO_NREGS (@var{regno},
+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
-@defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class})
-If defined, a C expression that returns nonzero for a @var{class} for which
-a change from mode @var{from} to mode @var{to} is invalid.
-
-For example, 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{CANNOT_CHANGE_MODE_CLASS}
-as below:
-
-@smallexample
-#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \
- (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \
- ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0)
-@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{class} 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 defmac
+@hook TARGET_CAN_CHANGE_MODE_CLASS
@hook TARGET_IRA_CHANGE_PSEUDO_ALLOCNO_CLASS
addresses on the stack.
@end defmac
-@defmac STARTING_FRAME_OFFSET
-Offset from the frame pointer to the first local variable slot to be allocated.
-
-If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by
-subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}.
-Otherwise, it is found by adding the length of the first slot to the
-value @code{STARTING_FRAME_OFFSET}.
-@c i'm not sure if the above is still correct.. had to change it to get
-@c rid of an overfull. --mew 2feb93
-@end defmac
+@hook TARGET_STARTING_FRAME_OFFSET
@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{STARTING_FRAME_OFFSET} is nonzero or where there
+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.
@hook TARGET_DWARF_HANDLE_FRAME_UNSPEC
+@hook TARGET_DWARF_POLY_INDETERMINATE_VALUE
+
@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
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
normally not need to override that default.
@end defmac
+@hook TARGET_STACK_CLASH_PROTECTION_ALLOCA_PROBE_RANGE
+
@need 2000
@node Frame Registers
@subsection Registers That Address the Stack Frame
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.
-
-See the PowerPC's SPE target for an example.
@end defmac
@defmac DWARF_FRAME_REGNUM (@var{regno})
@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
registers @code{df_regs_ever_live_p} and @code{call_used_regs}.
@end defmac
+@hook TARGET_COMPUTE_FRAME_LAYOUT
+
@node Stack Arguments
@subsection Passing Function Arguments on the Stack
@cindex arguments on stack
@hook TARGET_FUNCTION_ARG_ADVANCE
-@defmac FUNCTION_ARG_OFFSET (@var{mode}, @var{type})
-If defined, a C expression that is the number of bytes to add to the
-offset of the argument passed in memory. This is needed for the SPU,
-which passes @code{char} and @code{short} arguments in the preferred
-slot that is in the middle of the quad word instead of starting at the
-top.
-@end defmac
-
-@defmac FUNCTION_ARG_PADDING (@var{mode}, @var{type})
-If defined, a C expression which determines whether, and in which direction,
-to pad out an argument with extra space. The value should be of type
-@code{enum direction}: either @code{upward} to pad above the argument,
-@code{downward} to pad below, or @code{none} to inhibit padding.
+@hook TARGET_FUNCTION_ARG_OFFSET
-The @emph{amount} of padding is not controlled by this macro, but by the
-target hook @code{TARGET_FUNCTION_ARG_ROUND_BOUNDARY}. It is
-always just enough to reach the next multiple of that boundary.
-
-This macro has a default definition which is right for most systems.
-For little-endian machines, the default is to pad upward. For
-big-endian machines, the default is to pad downward for an argument of
-constant size shorter than an @code{int}, and upward otherwise.
-@end defmac
+@hook TARGET_FUNCTION_ARG_PADDING
@defmac PAD_VARARGS_DOWN
If defined, a C expression which determines whether the default
@hook TARGET_REF_MAY_ALIAS_ERRNO
+@hook TARGET_TRANSLATE_MODE_ATTRIBUTE
+
@hook TARGET_SCALAR_MODE_SUPPORTED_P
@hook TARGET_VECTOR_MODE_SUPPORTED_P
+@hook TARGET_ARRAY_MODE
+
@hook TARGET_ARRAY_MODE_SUPPORTED_P
@hook TARGET_LIBGCC_FLOATING_MODE_SUPPORTED_P
@hook TARGET_FLOATN_MODE
+@hook TARGET_FLOATN_BUILTIN_P
+
@hook TARGET_SMALL_REGISTER_CLASSES_FOR_MODE_P
@node Scalar Return
@hook TARGET_GET_RAW_ARG_MODE
+@hook TARGET_EMPTY_RECORD_P
+
+@hook TARGET_WARN_PARAMETER_PASSING_ABI
+
@node Caller Saves
@subsection Caller-Saves Register Allocation
This section describes the macros that output function entry
(@dfn{prologue}) and exit (@dfn{epilogue}) code.
+@hook TARGET_ASM_PRINT_PATCHABLE_FUNCTION_ENTRY
+
@hook TARGET_ASM_FUNCTION_PROLOGUE
@hook TARGET_ASM_FUNCTION_END_PROLOGUE
@hook TARGET_STACK_PROTECT_FAIL
+@hook TARGET_STACK_PROTECT_RUNTIME_ENABLED_P
+
@hook TARGET_SUPPORTS_SPLIT_STACK
+@hook TARGET_GET_VALID_OPTION_VALUES
+
@node Miscellaneous Register Hooks
@subsection Miscellaneous register hooks
@cindex miscellaneous register hooks
@hook TARGET_STORE_RETURNED_BOUNDS
-@hook TARGET_CHKP_FUNCTION_VALUE_BOUNDS
-
-@hook TARGET_SETUP_INCOMING_VARARG_BOUNDS
-
@node Trampolines
-@section Trampolines for Nested Functions
+@section Support for Nested Functions
+@cindex support for nested functions
@cindex trampolines for nested functions
-@cindex nested functions, trampolines for
-
-A @dfn{trampoline} is a small piece of code that is created at run time
-when the address of a nested function is taken. It normally resides on
-the stack, in the stack frame of the containing function. These macros
-tell GCC how to generate code to allocate and initialize a
-trampoline.
-
-The instructions in the trampoline must do two things: load a constant
-address into the static chain register, and jump to the real address of
-the nested function. On CISC machines such as the m68k, this requires
-two instructions, a move immediate and a jump. Then the two addresses
-exist in the trampoline as word-long immediate operands. On RISC
-machines, it is often necessary to load each address into a register in
-two parts. Then pieces of each address form separate immediate
-operands.
+@cindex descriptors for nested functions
+@cindex nested functions, support for
+
+Taking the address of a nested function requires special compiler
+handling to ensure that the static chain register is loaded when
+the function is invoked via an indirect call.
+
+GCC has traditionally supported nested functions by creating an
+executable @dfn{trampoline} at run time when the address of a nested
+function is taken. This is a small piece of code which normally
+resides on the stack, in the stack frame of the containing function.
+The trampoline loads the static chain register and then jumps to the
+real address of the nested function.
+
+The use of trampolines requires an executable stack, which is a
+security risk. To avoid this problem, GCC also supports another
+strategy: using descriptors for nested functions. Under this model,
+taking the address of a nested function results in a pointer to a
+non-executable function descriptor object. Initializing the static chain
+from the descriptor is handled at indirect call sites.
+
+On some targets, including HPPA and IA-64, function descriptors may be
+mandated by the ABI or be otherwise handled in a target-specific way
+by the back end in its code generation strategy for indirect calls.
+GCC also provides its own generic descriptor implementation to support the
+@option{-fno-trampolines} option. In this case runtime detection of
+function descriptors at indirect call sites relies on descriptor
+pointers being tagged with a bit that is never set in bare function
+addresses. Since GCC's generic function descriptors are
+not ABI-compliant, this option is typically used only on a
+per-language basis (notably by Ada) or when it can otherwise be
+applied to the whole program.
+
+Define the following hook if your backend either implements ABI-specified
+descriptor support, or can use GCC's generic descriptor implementation
+for nested functions.
+
+@hook TARGET_CUSTOM_FUNCTION_DESCRIPTORS
+
+The following macros tell GCC how to generate code to allocate and
+initialize an executable trampoline. You can also use this interface
+if your back end needs to create ABI-specified non-executable descriptors; in
+this case the "trampoline" created is the descriptor containing data only.
+
+The instructions in an executable trampoline must do two things: load
+a constant address into the static chain register, and jump to the real
+address of the nested function. On CISC machines such as the m68k,
+this requires two instructions, a move immediate and a jump. Then the
+two addresses exist in the trampoline as word-long immediate operands.
+On RISC machines, it is often necessary to load each address into a
+register in two parts. Then pieces of each address form separate
+immediate operands.
The code generated to initialize the trampoline must store the variable
parts---the static chain value and the function address---into the
@hook TARGET_TRAMPOLINE_ADJUST_ADDRESS
-@hook TARGET_CUSTOM_FUNCTION_DESCRIPTORS
-
Implementing trampolines is difficult on many machines because they have
separate instruction and data caches. Writing into a stack location
fails to clear the memory in the instruction cache, so when the program
@hook TARGET_LIBC_HAS_FUNCTION
+@hook TARGET_LIBC_HAS_FAST_FUNCTION
+
@defmac NEXT_OBJC_RUNTIME
Set this macro to 1 to use the "NeXT" Objective-C message sending conventions
by default. This calling convention involves passing the object, the selector
scheme, by means of compiler command line switches.
@end defmac
-@hook TARGET_PRINTF_POINTER_FORMAT
-
@node Addressing Modes
@section Addressing Modes
@cindex addressing modes
@hook TARGET_VECTORIZE_BUILTIN_VECTORIZATION_COST
-@hook TARGET_VECTORIZE_VECTOR_ALIGNMENT_REACHABLE
+@hook TARGET_VECTORIZE_PREFERRED_VECTOR_ALIGNMENT
-@hook TARGET_VECTORIZE_VEC_PERM_CONST_OK
+@hook TARGET_VECTORIZE_VECTOR_ALIGNMENT_REACHABLE
-@hook TARGET_VECTORIZE_BUILTIN_CONVERSION
+@hook TARGET_VECTORIZE_VEC_PERM_CONST
@hook TARGET_VECTORIZE_BUILTIN_VECTORIZED_FUNCTION
@hook TARGET_VECTORIZE_PREFERRED_SIMD_MODE
-@hook TARGET_VECTORIZE_AUTOVECTORIZE_VECTOR_SIZES
+@hook TARGET_VECTORIZE_SPLIT_REDUCTION
+
+@hook TARGET_VECTORIZE_AUTOVECTORIZE_VECTOR_MODES
+
+@hook TARGET_VECTORIZE_RELATED_MODE
@hook TARGET_VECTORIZE_GET_MASK_MODE
+@hook TARGET_VECTORIZE_EMPTY_MASK_IS_EXPENSIVE
+
@hook TARGET_VECTORIZE_INIT_COST
@hook TARGET_VECTORIZE_ADD_STMT_COST
@hook TARGET_SIMT_VF
+@hook TARGET_OMP_DEVICE_KIND_ARCH_ISA
+
@hook TARGET_GOACC_VALIDATE_DIMS
@hook TARGET_GOACC_DIM_LIMIT
@hook TARGET_GOACC_REDUCTION
+@hook TARGET_PREFERRED_ELSE_VALUE
+
@node Anchored Addresses
@section Anchored Addresses
@cindex anchored addresses
branch instruction must be used for some conditional branches. When
this happens, use the machine mode of the condition code register to
record different formats of the condition code register. Modes can
-also be used to record which compare instruction (e.g. a signed or an
+also be used to record which compare instruction (e.g.@: a signed or an
unsigned comparison) produced the condition codes.
If other modes than @code{CCmode} are required, add them to
other fields in the same word of the structure, but to different bytes.
@end defmac
-@defmac SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment})
-Define this macro to be the value 1 if memory accesses described by the
-@var{mode} and @var{alignment} parameters have a cost many times greater
-than aligned accesses, for example if they are emulated in a trap
-handler. This macro is invoked only for unaligned accesses, i.e. when
-@code{@var{alignment} < GET_MODE_ALIGNMENT (@var{mode})}.
-
-When this macro is nonzero, the compiler will act as if
-@code{STRICT_ALIGNMENT} were nonzero when generating code for block
-moves. This can cause significantly more instructions to be produced.
-Therefore, do not set this macro nonzero if unaligned accesses only add a
-cycle or two to the time for a memory access.
-
-If the value of this macro is always zero, it need not be defined. If
-this macro is defined, it should produce a nonzero value when
-@code{STRICT_ALIGNMENT} is nonzero.
-@end defmac
+@hook TARGET_SLOW_UNALIGNED_ACCESS
@defmac MOVE_RATIO (@var{speed})
The threshold of number of scalar memory-to-memory move insns, @emph{below}
@hook TARGET_ADDRESS_COST
+@hook TARGET_INSN_COST
+
@hook TARGET_MAX_NOCE_IFCVT_SEQ_COST
+@hook TARGET_NOCE_CONVERSION_PROFITABLE_P
+
@hook TARGET_NO_SPECULATION_IN_DELAY_SLOTS_P
+@hook TARGET_ESTIMATED_POLY_VALUE
+
@node Scheduling
@section Adjusting the Instruction Scheduler
@hook TARGET_SCHED_SET_SCHED_FLAGS
+@hook TARGET_SCHED_CAN_SPECULATE_INSN
+
@hook TARGET_SCHED_SMS_RES_MII
@hook TARGET_SCHED_DISPATCH
@hook TARGET_ASM_RELOC_RW_MASK
+@hook TARGET_ASM_GENERATE_PIC_ADDR_DIFF_VEC
+
@hook TARGET_ASM_SELECT_SECTION
@defmac USE_SELECT_SECTION_FOR_FUNCTIONS
the jump-table.
@end defmac
+@hook TARGET_ASM_POST_CFI_STARTPROC
+
@hook TARGET_ASM_EMIT_UNWIND_LABEL
@hook TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL
function prologue at an offset to the stack pointer that is not aligned to
@code{UNITS_PER_WORD}. The definition should be the negative minimum
alignment if @code{STACK_GROWS_DOWNWARD} is true, and the positive
-minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if
+minimum alignment otherwise. @xref{DWARF}. Only applicable if
the target supports DWARF 2 frame unwind information.
@end defmac
selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation.
@end defmac
-@hook TARGET_ASM_JUMP_ALIGN_MAX_SKIP
-
@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label})
The alignment (log base 2) to put in front of @var{label}, which follows
a @code{BARRIER}.
define the macro.
@end defmac
-@hook TARGET_ASM_LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP
-
@defmac LOOP_ALIGN (@var{label})
The alignment (log base 2) to put in front of @var{label} that heads
a frequently executed basic block (usually the header of a loop).
selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation.
@end defmac
-@hook TARGET_ASM_LOOP_ALIGN_MAX_SKIP
-
@defmac LABEL_ALIGN (@var{label})
The alignment (log base 2) to put in front of @var{label}.
If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment,
selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation.
@end defmac
-@hook TARGET_ASM_LABEL_ALIGN_MAX_SKIP
-
@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
A C statement to output to the stdio stream @var{stream} an assembler
instruction to advance the location counter by @var{nbytes} bytes.
* DBX Options:: Macros enabling specific options in DBX format.
* DBX Hooks:: Hook macros for varying DBX format.
* File Names and DBX:: Macros controlling output of file names in DBX format.
-* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats.
+* DWARF:: Macros for DWARF format.
* VMS Debug:: Macros for VMS debug format.
@end menu
variable having address @var{x} (an RTL expression). The default
computation assumes that @var{x} is based on the frame-pointer and
gives the offset from the frame-pointer. This is required for targets
-that produce debugging output for DBX or COFF-style debugging output
-for SDB and allow the frame-pointer to be eliminated when the
-@option{-g} options is used.
+that produce debugging output for DBX and allow the frame-pointer to be
+eliminated when the @option{-g} option is used.
@end defmac
@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x})
produce when the user specifies just @option{-g}. Define
this if you have arranged for GCC to support more than one format of
debugging output. Currently, the allowable values are @code{DBX_DEBUG},
-@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG},
-@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}.
+@code{DWARF2_DEBUG}, @code{XCOFF_DEBUG}, @code{VMS_DEBUG},
+and @code{VMS_AND_DWARF2_DEBUG}.
When the user specifies @option{-ggdb}, GCC normally also uses the
value of this macro to select the debugging output format, but with two
The value of this macro only affects the default debugging output; the
user can always get a specific type of output by using @option{-gstabs},
-@option{-gcoff}, @option{-gdwarf-2}, @option{-gxcoff}, or @option{-gvms}.
+@option{-gdwarf-2}, @option{-gxcoff}, or @option{-gvms}.
@end defmac
@node DBX Options
@end defmac
@need 2000
-@node SDB and DWARF
-@subsection Macros for SDB and DWARF Output
+@node DWARF
+@subsection Macros for DWARF Output
@c prevent bad page break with this line
-Here are macros for SDB and DWARF output.
-
-@defmac SDB_DEBUGGING_INFO
-Define this macro to 1 if GCC should produce COFF-style debugging output
-for SDB in response to the @option{-g} option.
-@end defmac
+Here are macros for DWARF output.
@defmac DWARF2_DEBUGGING_INFO
Define this macro if GCC should produce dwarf version 2 format
tables, and hence is desirable if it works.
@end defmac
+@defmac DWARF2_ASM_VIEW_DEBUG_INFO
+Define this macro to be a nonzero value if the assembler supports view
+assignment and verification in @code{.loc}. If it does not, but the
+user enables location views, the compiler may have to fallback to
+internal line number tables.
+@end defmac
+
+@hook TARGET_RESET_LOCATION_VIEW
+
@hook TARGET_WANT_DEBUG_PUB_SECTIONS
@hook TARGET_DELAY_SCHED2
@defmac ASM_OUTPUT_DWARF_VMS_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2})
A C statement to issue assembly directives that create a difference
-between the two given labels in system defined units, e.g. instruction
+between the two given labels in system defined units, e.g.@: instruction
slots on IA64 VMS, using an integer of the given size.
@end defmac
@hook TARGET_ASM_OUTPUT_DWARF_DTPREL
-@defmac PUT_SDB_@dots{}
-Define these macros to override the assembler syntax for the special
-SDB assembler directives. See @file{sdbout.c} for a list of these
-macros and their arguments. If the standard syntax is used, you need
-not define them yourself.
-@end defmac
-
-@defmac SDB_DELIM
-Some assemblers do not support a semicolon as a delimiter, even between
-SDB assembler directives. In that case, define this macro to be the
-delimiter to use (usually @samp{\n}). It is not necessary to define
-a new set of @code{PUT_SDB_@var{op}} macros if this is the only change
-required.
-@end defmac
-
-@defmac SDB_ALLOW_UNKNOWN_REFERENCES
-Define this macro to allow references to unknown structure,
-union, or enumeration tags to be emitted. Standard COFF does not
-allow handling of unknown references, MIPS ECOFF has support for
-it.
-@end defmac
-
-@defmac SDB_ALLOW_FORWARD_REFERENCES
-Define this macro to allow references to structure, union, or
-enumeration tags that have not yet been seen to be handled. Some
-assemblers choke if forward tags are used, while some require it.
-@end defmac
-
-@defmac SDB_OUTPUT_SOURCE_LINE (@var{stream}, @var{line})
-A C statement to output SDB debugging information before code for line
-number @var{line} of the current source file to the stdio stream
-@var{stream}. The default is to emit an @code{.ln} directive.
-@end defmac
-
@need 2000
@node VMS Debug
@subsection Macros for VMS Debug Format
the FPSCR PR bit has to be cleared, while for a double precision
operation, this bit has to be set. Changing the PR bit requires a general
purpose register as a scratch register, hence these FPSCR sets have to
-be inserted before reload, i.e.@: you can't put this into instruction emitting
+be inserted before reload, i.e.@: you cannot put this into instruction emitting
or @code{TARGET_MACHINE_DEPENDENT_REORG}.
You can have multiple entities that are mode-switched, and select at run time
@hook TARGET_INSERT_ATTRIBUTES
+@hook TARGET_HANDLE_GENERIC_ATTRIBUTE
+
@hook TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P
@hook TARGET_OPTION_VALID_ATTRIBUTE_P
@hook TARGET_CXX_DECL_MANGLING_CONTEXT
+@node D Language and ABI
+@section D ABI parameters
+@cindex parameters, d abi
+
+@hook TARGET_D_CPU_VERSIONS
+
+@hook TARGET_D_OS_VERSIONS
+
+@hook TARGET_D_CRITSEC_SIZE
+
@node Named Address Spaces
@section Adding support for named address spaces
@cindex named address spaces
@defmac WORD_REGISTER_OPERATIONS
Define this macro to 1 if operations between registers with integral mode
-smaller than a word are always performed on the entire register.
-Most RISC machines have this property and most CISC machines do not.
+smaller than a word are always performed on the entire register. To be
+more explicit, if you start with a pair of @code{word_mode} registers with
+known values and you do a subword, for example @code{QImode}, addition on
+the low part of the registers, then the compiler may consider that the
+result has a known value in @code{word_mode} too if the macro is defined
+to 1. Most RISC machines have this property and most CISC machines do not.
@end defmac
@hook TARGET_MIN_ARITHMETIC_PRECISION
You may return a non-@code{UNKNOWN} value even if for some hard registers
the sign extension is not performed, if for the @code{REGNO_REG_CLASS}
-of these hard registers @code{CANNOT_CHANGE_MODE_CLASS} returns nonzero
+of these hard registers @code{TARGET_CAN_CHANGE_MODE_CLASS} returns false
when the @var{from} mode is @var{mem_mode} and the @var{to} mode is any
integral mode larger than this but not larger than @code{word_mode}.
You must return @code{UNKNOWN} if for some hard registers that allow this
-mode, @code{CANNOT_CHANGE_MODE_CLASS} says that they cannot change to
+mode, @code{TARGET_CAN_CHANGE_MODE_CLASS} says that they cannot change to
@code{word_mode}, but that they can change to another integral mode that
is larger then @var{mem_mode} but still smaller than @code{word_mode}.
@end defmac
@anchor{TARGET_SHIFT_TRUNCATION_MASK}
@hook TARGET_SHIFT_TRUNCATION_MASK
-@defmac TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
-A C expression which is nonzero if on this machine it is safe to
-``convert'' an integer of @var{inprec} bits to one of @var{outprec}
-bits (where @var{outprec} is smaller than @var{inprec}) by merely
-operating on it as if it had only @var{outprec} bits.
-
-On many machines, this expression can be 1.
-
-@c rearranged this, removed the phrase "it is reported that". this was
-@c to fix an overfull hbox. --mew 10feb93
-When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for
-modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result.
-If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in
-such cases may improve things.
-@end defmac
+@hook TARGET_TRULY_NOOP_TRUNCATION
@hook TARGET_MODE_REP_EXTENDED
+@hook TARGET_SETJMP_PRESERVES_NONVOLATILE_REGS_P
+
@defmac STORE_FLAG_VALUE
A C expression describing the value returned by a comparison operator
with an integral mode and stored by a store-flag instruction
@hook TARGET_CXX_IMPLICIT_EXTERN_C
-@defmac NO_IMPLICIT_EXTERN_C
-Define this macro if the system header files support C++ as well as C@.
-This macro inhibits the usual method of using system header files in
-C++, which is to pretend that the file's contents are enclosed in
-@samp{extern "C" @{@dots{}@}}.
+@defmac SYSTEM_IMPLICIT_EXTERN_C
+Define this macro if the system header files do not support C++@.
+This macro handles system header files by pretending that system
+header files are enclosed in @samp{extern "C" @{@dots{}@}}.
@end defmac
@findex #pragma
@hook TARGET_EXPAND_BUILTIN
-@hook TARGET_BUILTIN_CHKP_FUNCTION
-@hook TARGET_CHKP_BOUND_TYPE
-@hook TARGET_CHKP_BOUND_MODE
-@hook TARGET_CHKP_MAKE_BOUNDS_CONSTANT
-@hook TARGET_CHKP_INITIALIZE_BOUNDS
-
@hook TARGET_RESOLVE_OVERLOADED_BUILTIN
+@hook TARGET_CHECK_BUILTIN_CALL
+
@hook TARGET_FOLD_BUILTIN
@hook TARGET_GIMPLE_FOLD_BUILTIN
@hook TARGET_GENERATE_VERSION_DISPATCHER_BODY
+@hook TARGET_PREDICT_DOLOOP_P
+
+@hook TARGET_HAVE_COUNT_REG_DECR_P
+
+@hook TARGET_DOLOOP_COST_FOR_GENERIC
+
+@hook TARGET_DOLOOP_COST_FOR_ADDRESS
+
@hook TARGET_CAN_USE_DOLOOP_P
@hook TARGET_INVALID_WITHIN_DOLOOP
lists.
@end defmac
-@defmac MODIFY_JNI_METHOD_CALL (@var{mdecl})
-Define this macro to a C expression representing a variant of the
-method call @var{mdecl}, if Java Native Interface (JNI) methods
-must be invoked differently from other methods on your target.
-For example, on 32-bit Microsoft Windows, JNI methods must be invoked using
-the @code{stdcall} calling convention and this macro is then
-defined as this expression:
-
-@smallexample
-build_type_attribute_variant (@var{mdecl},
- build_tree_list
- (get_identifier ("stdcall"),
- NULL))
-@end smallexample
-@end defmac
-
@hook TARGET_CANNOT_MODIFY_JUMPS_P
-@hook TARGET_BRANCH_TARGET_REGISTER_CLASS
-
-@hook TARGET_BRANCH_TARGET_REGISTER_CALLEE_SAVED
-
@hook TARGET_HAVE_CONDITIONAL_EXECUTION
@hook TARGET_GEN_CCMP_FIRST
@hook TARGET_CONVERT_TO_TYPE
+@hook TARGET_VERIFY_TYPE_CONTEXT
+
@defmac OBJC_JBLEN
This macro determines the size of the objective C jump buffer for the
NeXT runtime. By default, OBJC_JBLEN is defined to an innocuous value.
@end defmac
+@hook TARGET_HAVE_SPECULATION_SAFE_VALUE
+
+@hook TARGET_SPECULATION_SAFE_VALUE
+
@hook TARGET_RUN_TARGET_SELFTESTS
projects / thirdparty / gcc.git / blobdiff