-@c Copyright (C) 1988,89,92-97,1998 Free Software Foundation, Inc.
+@c Copyright (C) 1988,89,92,93,94,96,97,1998 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for
additional options.
+@findex SWITCH_CURTAILS_COMPILATION
+@item SWITCH_CURTAILS_COMPILATION (@var{char})
+A C expression which determines whether the option @samp{-@var{char}}
+stops compilation before the generation of an executable. The value is
+boolean, non-zero if the option does stop an executable from being
+generated, zero otherwise.
+
+By default, this macro is defined as
+@code{DEFAULT_SWITCH_CURTAILS_COMPILATION}, which handles the standard
+options properly. You need not define
+@code{SWITCH_CURTAILS_COMPILATION} unless you wish to add additional
+options which affect the generation of an executable. Any redefinition
+should call @code{DEFAULT_SWITCH_CURTAILS_COMPILATION} and then check
+for additional options.
+
@findex SWITCHES_NEED_SPACES
@item SWITCHES_NEED_SPACES
A string-valued C expression which enumerates the options for which
This macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it does
not affect @samp{-L} options.
+@findex LINK_COMMAND_SPEC
+@item 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.
+
@findex MULTILIB_DEFAULTS
@item MULTILIB_DEFAULTS
Define this macro as a C expression for the initializer of an array of
with a subgrouping for each command option.
Each subgrouping contains a string constant, that defines the option
-name, and a number, which contains the bits to set in
-@code{target_flags}. A negative number says to clear bits instead;
-the negative of the number is which bits to clear. The actual option
-name is made by appending @samp{-m} to the specified name.
+name, a number, which contains the bits to set in
+@code{target_flags}, and a second string which is the description
+displayed by --help. If the number is negative then the bits specified
+by the number are cleared instead of being set. If the description
+string is present but empty, then no help information will be displayed
+for that option, but it will not count as an undocumented option. The
+actual option name is made by appending @samp{-m} to the specified name.
One of the subgroupings should have a null string. The number in
this grouping is the default value for @code{target_flags}. Any
@smallexample
#define TARGET_SWITCHES \
- @{ @{ "68020", 1@}, \
- @{ "68000", -1@}, \
- @{ "", 1@}@}
+ @{ @{ "68020", 1, "" @}, \
+ @{ "68000", -1, "Compile for the 68000" @}, \
+ @{ "", 1, "" @}@}
@end smallexample
@findex TARGET_OPTIONS
subgrouping for each command option.
Each subgrouping contains a string constant, that defines the fixed part
-of the option name, and the address of a variable. The variable, type
-@code{char *}, is set to the variable part of the given option if the fixed
-part matches. The actual option name is made by appending @samp{-m} to the
-specified name.
+of the option name, the address of a variable, and a description string.
+The variable, type @code{char *}, is set to the variable part of the
+given option if the fixed part matches. The actual option name is made
+by appending @samp{-m} to the specified name.
Here is an example which defines @samp{-mshort-data-@var{number}}. If the
given option is @samp{-mshort-data-512}, the variable @code{m88k_short_data}
@smallexample
extern char *m88k_short_data;
#define TARGET_OPTIONS \
- @{ @{ "short-data-", &m88k_short_data @} @}
+ @{ @{ "short-data-", &m88k_short_data, "Specify the size of the short data section" @} @}
@end smallexample
@findex TARGET_VERSION
@findex POINTERS_EXTEND_UNSIGNED
@item POINTERS_EXTEND_UNSIGNED
A C expression whose value is nonzero if pointers that need to be
-extended from being @code{POINTER_SIZE} bits wide to @code{Pmode}
-are sign-extended and zero if they are zero-extended.
+extended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to
+be zero-extended and zero if they are to be sign-extended.
You need not define this macro if the @code{POINTER_SIZE} is equal
to the width of @code{Pmode}.
@findex DATA_ALIGNMENT
@item DATA_ALIGNMENT (@var{type}, @var{basic-align})
-If defined, a C expression to compute the alignment for a static
-variable. @var{type} is the data type, and @var{basic-align} is the
-alignment that the object would ordinarily have. The value of this
+If defined, a C expression to compute the alignment for a variables 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.
appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE
(DImode)} is assumed.
+@findex STACK_SAVEAREA_MODE
+@item STACK_SAVEAREA_MODE (@var{save_level})
+If defined, an expression of type @code{enum 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.
+
+@findex STACK_SIZE_MODE
+@item STACK_SIZE_MODE
+If defined, an expression of type @code{enum 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.
+
@findex CHECK_FLOAT_VALUE
@item CHECK_FLOAT_VALUE (@var{mode}, @var{value}, @var{overflow})
A C statement to validate the value @var{value} (of type
/ UNITS_PER_WORD))
@end smallexample
+@findex ALTER_HARD_SUBREG
+@item ALTER_HARD_SUBREG (@var{tgt_mode}, @var{word}, @var{src_mode}, @var{regno})
+A C expression that returns an adjusted hard register number for
+
+@smallexample
+(subreg:@var{tgt_mode} (reg:@var{src_mode} @var{regno}) @var{word})
+@end smallexample
+
+This may be needed if the target machine has mixed sized big-endian
+registers, like Sparc v9.
+
@findex HARD_REGNO_MODE_OK
@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
A C expression that is nonzero if it is permissible to store a value
You should define this macro to return nonzero in as many cases as
possible since doing so will allow GNU CC to perform better register
allocation.
+
+@findex AVOID_CCMODE_COPIES
+@item 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 fo copying to/from
+@code{CCmode} is incomplete.
@end table
@node Leaf Functions
address of the stack word that points to the previous frame.
@findex SETUP_FRAME_ADDRESSES
-@item SETUP_FRAME_ADDRESSES ()
+@item SETUP_FRAME_ADDRESSES
If defined, 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.
-This macro will seldom need to be defined.
+before we can access arbitrary stack frames. You will seldom need to
+define this macro.
+
+@findex BUILTIN_SETJMP_FRAME_VALUE
+@item BUILTIN_SETJMP_FRAME_VALUE
+If defined, a C expression that contains 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 macro is if
+@code{hard_frame_pointer_rtx} is the appropriate value on your machine.
@findex RETURN_ADDR_RTX
@item RETURN_ADDR_RTX (@var{count}, @var{frameaddr})
@findex STRICT_ARGUMENT_NAMING
@item STRICT_ARGUMENT_NAMING
-Define this macro if the location where a function argument is passed
-depends on whether or not it is a named argument.
+Define this macro to be a nonzero value if the location where a function
+argument is passed depends on whether or not it is a named argument.
This macro controls how the @var{named} argument to @code{FUNCTION_ARG}
-is set for varargs and stdarg functions. With this macro defined,
-the @var{named} argument is always true for named arguments, and false for
-unnamed arguments. If this is not defined, but @code{SETUP_INCOMING_VARARGS}
-is defined, then all arguments are treated as named. Otherwise, all named
-arguments except the last are treated as named.
+is set for varargs and stdarg functions. If this macro returns a
+nonzero value, the @var{named} argument is always true for named
+arguments, and false for unnamed arguments. If it returns a value of
+zero, but @code{SETUP_INCOMING_VARARGS} is defined, then all arguments
+are treated as named. Otherwise, all named arguments except the last
+are treated as named.
+
+You need not define this macro if it always returns zero.
@end table
@node Trampolines
fact, it is safe for this macro to do nothing. But often a
machine-dependent strategy can generate better code.
+@findex LEGITIMIZE_RELOAD_ADDRESS
+@item LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win})
+A C compound statement that attempts to replace @var{x}, which is an address
+that needs reloading, with a valid memory address for an operand of mode
+@var{mode}. @var{win} will be a C statement label elsewhere in the code.
+It is not necessary to define this macro, but it might be useful for
+performance reasons.
+
+For example, on the i386, it is sometimes possible to use a single
+reload register instead of two by reloading a sum of two pseudo
+registers into a register. On the other hand, for number of RISC
+processors offsets are limited so that often an intermediate address
+needs to be generated in order to address a stack slot. By defining
+LEGITIMIZE_RELOAD_ADDRESS appropriately, the intermediate addresses
+generated for adjacent some stack slots can be made identical, and thus
+be shared.
+
+@emph{Note}: This macro should be used with caution. It is necessary
+to know something of how reload works in order to effectively use this,
+and it is quite easy to produce macros that build in too much knowledge
+of reload internals.
+
+@emph{Note}: This macro must be able to reload an address created by a
+previous invocation of this macro. If it fails to handle such addresses
+then the compiler may generate incorrect code or abort.
+
+@findex push_reload
+The macro definition should use @code{push_reload} to indicate parts that
+need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually
+suitable to be passed unaltered to @code{push_reload}.
+
+The code generated by this macro must not alter the substructure of
+@var{x}. If it transforms @var{x} into a more legitimate form, it
+should assign @var{x} (which will always be a C variable) a new value.
+This also applies to parts that you change indirectly by calling
+@code{push_reload}.
+
+@findex strict_memory_address_p
+The macro definition may use @code{strict_memory_address_p} to test if
+the address has become legitimate.
+
+@findex copy_rtx
+If you want to change only a part of @var{x}, one standard way of doing
+this is to use @code{copy_rtx}. Note, however, that is unshares only a
+single level of rtl. Thus, if the part to be changed is not at the
+top level, you'll need to replace first the top leve
+It is not necessary for this macro to come up with a legitimate
+address; but often a machine-dependent strategy can generate better code.
+
@findex GO_IF_MODE_DEPENDENT_ADDRESS
@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
A C statement or compound statement with a conditional @code{goto
@item MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in})
A C expression for the cost of moving data of mode @var{mode} between a
register of class @var{class} and memory; @var{in} is zero if the value
-is to be written to memory, non-zero if it is to be read in. If this
-macro is not defined, the default cost is assumed to be 4, plus any costs
-that would be incurred copying via a secondary reload register, if
-needed. This cost is relative to those in @code{REGISTER_MOVE_COST}.
-
-If moving between registers and memory is more expensive than between
-two registers, you should define this macro to express the relative cost.
-
-If a secondary reload register would be required for @var{class}, but the
-reload mechanism is more complex than copying via an intermediate, this
-macro should be defined to reflect the actual cost of the move.
-
-The function @code{memory_move_secondary_cost}, which is defined if
-secondary reloads are needed, will compute the costs due to copying; you
-can use this function if you need to take other factors into account as
-well, or if the default base value of 4 is not correct for your machine.
+is to be written to memory, non-zero if it is to be read in. This cost
+is relative to those in @code{REGISTER_MOVE_COST}. If moving between
+registers and memory is more expensive than between two registers, you
+should define this macro to express the relative cost.
+
+If you do not define this macro, GNU CC uses a default cost of 4 plus
+the cost of copying via a secondary reload register, if one is
+needed. If your machine requires a secondary reload register to copy
+between memory and a register of @var{class} but the reload mechanism is
+more complex than copying via an intermediate, define this macro to
+reflect the actual cost of the move.
+
+GNU CC defines the function @code{memory_move_secondary_cost} if
+secondary reloads are needed. It computes the costs due to copying via
+a secondary register. If your machine copies from memory using a
+secondary register in the conventional way but the default base value of
+4 is not correct for your machine, define this macro to add some other
+value to the result of that function. The arguments to that function
+are the same as to this macro.
@findex BRANCH_COST
@item BRANCH_COST
@findex JUMP_TABLES_IN_TEXT_SECTION
@item JUMP_TABLES_IN_TEXT_SECTION
-Define this macro if jump tables (for @code{tablejump} insns) should be
-output in the text section, along with the assembler instructions.
-Otherwise, the readonly data section is used.
+Define this macro to be an expression with a non-zero value if jump
+tables (for @code{tablejump} insns) should be output in the text
+section, along with the assembler instructions. Otherwise, the
+readonly data section is used.
This macro is irrelevant if there is no separate readonly data section.
Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX},
@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express
-the variations in assembly language syntax with that mechanism. Define
+the variations in assembler language syntax with that mechanism. Define
@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax
if the syntax variant are larger and involve such things as different
opcodes or operand order.
@findex PREFERRED_DEBUGGING_TYPE
@item PREFERRED_DEBUGGING_TYPE
-A C expression that returns the type of debugging output GNU CC produces
-when the user specifies @samp{-g} or @samp{-ggdb}. Define this if you
-have arranged for GNU CC to support more than one format of debugging
-output. Currently, the allowable values are @code{DBX_DEBUG},
+A C expression that returns the type of debugging output GNU CC should
+produce when the user specifies just @samp{-g}. Define
+this if you have arranged for GNU CC 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}, and
@code{XCOFF_DEBUG}.
-If the user specifies @samp{-ggdb}, then there are two special cases
-where this macro's value is ignored and another value is substituted.
-If @code{DWARF2_DEBUGGING_INFO} is defined and
-@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, then
-@code{DWARF2_DEBUG} is substituted. Otherwise, if
-@code{DBX_DEBUGGING_INFO} is defined, then @code{DBX_DEBUG} is
-substituted.
+When the user specifies @samp{-ggdb}, GNU CC normally also uses the
+value of this macro to select the debugging output format, but with two
+exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined and
+@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, GNU CC uses the
+value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is
+defined, GNU CC uses @code{DBX_DEBUG}.
The value of this macro only affects the default debugging output; the
user can always get a specific type of output by using @samp{-gstabs},
prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save}
as appropriate from @code{FUNCTION_PROLOGUE} if you don't.
+@findex DWARF2_FRAME_INFO
+@item DWARF2_FRAME_INFO
+Define this macro to a nonzero value if GNU CC should always output
+Dwarf 2 frame information. If @code{DWARF2_UNWIND_INFO}
+(@pxref{Exception Region Output} is nonzero, GNU CC will output this
+information not matter how you define @code{DWARF2_FRAME_INFO}.
+
@findex LINKER_DOES_NOT_WORK_WITH_DWARF2
@item LINKER_DOES_NOT_WORK_WITH_DWARF2
-Define this macro if the linker does not work with dwarf version 2.
-Normally, if the user specifies only @samp{-ggdb}, then GNU CC will use
-dwarf version 2 if available; this macro causes GNU CC to use the format
-specified by @code{PREFERRED_DEBUGGING_TYPE} instead.
+Define this macro if the linker does not work with Dwarf version 2.
+Normally, if the user specifies only @samp{-ggdb} GNU CC will use Dwarf
+version 2 if available; this macro disables this. See the description
+of the @code{PREFERRED_DEBUGGING_TYPE} macro for more details.
@findex PUT_SDB_@dots{}
@item PUT_SDB_@dots{}
overrides another, or when an attribute is nullified by a subsequent
definition.
+@findex SET_DEFAULT_DECL_ATTRIBUTES
+@item SET_DEFAULT_DECL_ATTRIBUTES (@var{decl}, @var{attributes})
+If defined, a C statement that assigns default attributes to
+newly defined @var{decl}.
+
@findex DOLLARS_IN_IDENTIFIERS
@item DOLLARS_IN_IDENTIFIERS
Define this macro to control use of the character @samp{$} in identifier
same time if the machine is a superscalar machine. This is only used by
the @samp{Haifa} scheduler, and not the traditional scheduler.
+@findex MD_SCHED_INIT
+@item MD_SCHED_INIT (@var{file}, @var{verbose}
+A C statement which is executed by the @samp{Haifa} scheduler at the
+beginning of each block of instructions that are to be scheduled.
+@var{file} is either a null pointer, or a stdio stream to write any
+debug output to. @var{verbose} is the verbose level provided by
+@samp{-fsched-verbose-}@var{n}.
+
+@findex MD_SCHED_REORDER
+@item MD_SCHED_REORDER (@var{file}, @var{verbose}, @var{ready}, @var{n_ready})
+A C statement which is executed by the @samp{Haifa} scheduler after it
+has scheduled the ready list to allow the machine description to reorder
+it (for example to combine two small instructions together on
+@samp{VLIW} machines). @var{file} is either a null pointer, or a stdio
+stream to write any debug output to. @var{verbose} is the verbose level
+provided by @samp{-fsched-verbose-}@var{n}. @var{ready} is a pointer to
+the ready list of instructions that are ready to be scheduled.
+@var{n_ready} is the number of elements in the ready list. The
+scheduler reads the ready list in reverse order, starting with
+@var{ready}[@var{n_ready}-1] and going to @var{ready}[0].
+
+@findex MD_SCHED_VARIABLE_ISSUE
+@item MD_SCHED_VARIABLE_ISSUE (@var{file}, @var{verbose}, @var{insn}, @var{more})
+A C statement which is executed by the @samp{Haifa} scheduler after it
+has scheduled an insn from the ready list. @var{file} is either a null
+pointer, or a stdio stream to write any debug output to. @var{verbose}
+is the verbose level provided by @samp{-fsched-verbose-}@var{n}.
+@var{insn} is the instruction that was scheduled. @var{more} is the
+number of instructions that can be issued in the current cycle. The
+@samp{MD_SCHED_VARIABLE_ISSUE} macro is responsible for updating the
+value of @var{more} (typically by @var{more}--).
+
+@findex MAX_INTEGER_COMPUTATION_MODE
+@item MAX_INTEGER_COMPUTATION_MODE
+Define this to the largest integer machine mode which can be used for
+operations other than load, store and copy operations.
+
+You need only define this macro if the target holds values larger than
+@code{word_mode} in general purpose registers. Most targets should not define
+this macro.
+
+@findex NEED_MATH_LIBRARY
+@item NEED_MATH_LIBRARY
+Define this macro as a C expression that is nonzero if @code{g++} should
+automatically link in the math library or to zero if @code{g++} should not
+automatically link in the math library.
+
+You need only define this macro if the target does not always need the math
+library linked into C++ programs.
@end table