tm.texi

GCC

One of the subgroupings should have a null string.  The number in
this grouping is the default value for @code{target_flags}.  Any
target options act starting with that value.

Here is an example which defines @option{-m68000} and @option{-m68020}
with opposite meanings, and picks the latter as the default:

@smallexample
#define TARGET_SWITCHES \
  @{ @{ "68020", TARGET_MASK_68020, "" @},      \
    @{ "68000", -TARGET_MASK_68020, \
      N_("Compile for the 68000") @}, \
    @{ "", TARGET_MASK_68020, "" @}@}
@end smallexample

@findex TARGET_OPTIONS
@item TARGET_OPTIONS
This macro is similar to @code{TARGET_SWITCHES} but defines names of command
options that have values.  Its definition is an initializer with a
subgrouping for each command option.

Each subgrouping contains a string constant, that defines the fixed part
of the option name, the address of a variable, and a description string
(which should again be marked with @code{N_(@dots{})}).
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.  Again, each option should
also be documented in @file{invoke.texi}.

Here is an example which defines @option{-mshort-data-@var{number}}.  If the
given option is @option{-mshort-data-512}, the variable @code{m88k_short_data}
will be set to the string @code{"512"}.

@smallexample
extern char *m88k_short_data;
#define TARGET_OPTIONS \
 @{ @{ "short-data-", &m88k_short_data, \
     N_("Specify the size of the short data section") @} @}
@end smallexample

@findex TARGET_VERSION
@item TARGET_VERSION
This macro is a C statement to print on @code{stderr} a string
describing the particular machine description choice.  Every machine
description should define @code{TARGET_VERSION}.  For example:

@smallexample
#ifdef MOTOROLA
#define TARGET_VERSION \
  fprintf (stderr, " (68k, Motorola syntax)");
#else
#define TARGET_VERSION \
  fprintf (stderr, " (68k, MIT syntax)");
#endif
@end smallexample

@findex OVERRIDE_OPTIONS
@item OVERRIDE_OPTIONS
Sometimes certain combinations of command options do not make sense on
a particular target machine.  You can define a macro
@code{OVERRIDE_OPTIONS} to take account of this.  This macro, if
defined, is executed once just after all the command options have been
parsed.

Don't use this macro to turn on various extra optimizations for
@option{-O}.  That is what @code{OPTIMIZATION_OPTIONS} is for.

@findex OPTIMIZATION_OPTIONS
@item OPTIMIZATION_OPTIONS (@var{level}, @var{size})
Some machines may desire to change what optimizations are performed for
various optimization levels.   This macro, if defined, is executed once
just after the optimization level is determined and before the remainder
of the command options have been parsed.  Values set in this macro are
used as the default values for the other command line options.

@var{level} is the optimization level specified; 2 if @option{-O2} is
specified, 1 if @option{-O} is specified, and 0 if neither is specified.

@var{size} is non-zero if @option{-Os} is specified and zero otherwise.

You should not use this macro to change options that are not
machine-specific.  These should uniformly selected by the same
optimization level on all supported machines.  Use this macro to enable
machine-specific optimizations.

@strong{Do not examine @code{write_symbols} in
this macro!} The debugging options are not supposed to alter the
generated code.

@findex CAN_DEBUG_WITHOUT_FP
@item CAN_DEBUG_WITHOUT_FP
Define this macro if debugging can be performed even without a frame
pointer.  If this macro is defined, GCC will turn on the
@option{-fomit-frame-pointer} option whenever @option{-O} is specified.
@end table

@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 initialise some or
all of the function pointers @code{init_machine_status},
@code{free_machine_status} and @code{mark_machine_status}.  These
pointers are 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.

The macro and function pointers are described below.

@table @code
@findex INIT_EXPANDERS
@item   INIT_EXPANDERS
Macro called to initialise 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 initialisation of the
function pointers below.

@findex init_machine_status
@item   init_machine_status
This is a @code{void (*)(struct function *)} function pointer.  If this
pointer is non-NULL it will be called once per function, before function
compilation starts, in order to allow the target to perform any target
specific initialisation of the @code{struct function} structure.  It is
intended that this would be used to initialise the @code{machine} of
that structure.

@findex free_machine_status
@item   free_machine_status
This is a @code{void (*)(struct function *)} function pointer.  If this
pointer is non-NULL it will be called once per function, after the
function has been compiled, in order to allow any memory allocated
during the @code{init_machine_status} function call to be freed.

@findex mark_machine_status
@item   mark_machine_status
This is a @code{void (*)(struct function *)} function pointer.  If this
pointer is non-NULL it will be called once per function in order to mark
any data items in the @code{struct machine_function} structure which
need garbage collection.

@end table

@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}.

@table @code
@findex BITS_BIG_ENDIAN
@item 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}.

@findex BYTES_BIG_ENDIAN
@item 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.

@findex WORDS_BIG_ENDIAN
@item 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; GCC fundamentally assumes that the
order of words in memory is the same as the order in registers.  This
macro need not be a constant.

@findex LIBGCC2_WORDS_BIG_ENDIAN
@item LIBGCC2_WORDS_BIG_ENDIAN
Define this macro if WORDS_BIG_ENDIAN is not constant.  This must be a
constant value with the same meaning as WORDS_BIG_ENDIAN, which will be
used only when compiling libgcc2.c.  Typically the value will be set
based on preprocessor defines.

@findex FLOAT_WORDS_BIG_ENDIAN
@item 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.

@findex BITS_PER_UNIT
@item BITS_PER_UNIT
Define this macro to be the number of bits in an addressable storage
unit (byte); normally 8.

@findex BITS_PER_WORD
@item BITS_PER_WORD
Number of bits in a word; normally 32.

@findex MAX_BITS_PER_WORD
@item 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.

@findex UNITS_PER_WORD
@item UNITS_PER_WORD
Number of storage units in a word; normally 4.

@findex MIN_UNITS_PER_WORD
@item 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.

@findex POINTER_SIZE
@item 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}.

@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 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 PROMOTE_MODE
@item 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}.

@findex PROMOTE_FUNCTION_ARGS
@item PROMOTE_FUNCTION_ARGS
Define this macro if the promotion described by @code{PROMOTE_MODE}
should also be done for outgoing function arguments.

@findex PROMOTE_FUNCTION_RETURN
@item PROMOTE_FUNCTION_RETURN
Define this macro if the promotion described by @code{PROMOTE_MODE}
should also be done for the return value of functions.

If this macro is defined, @code{FUNCTION_VALUE} must perform the same
promotions done by @code{PROMOTE_MODE}.

@findex PROMOTE_FOR_CALL_ONLY
@item PROMOTE_FOR_CALL_ONLY
Define this macro if the promotion described by @code{PROMOTE_MODE}
should @emph{only} be performed for outgoing function arguments or
function return values, as specified by @code{PROMOTE_FUNCTION_ARGS}
and @code{PROMOTE_FUNCTION_RETURN}, respectively.

@findex PARM_BOUNDARY
@item 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.

@findex STACK_BOUNDARY
@item STACK_BOUNDARY
Define this macro if there is a guaranteed alignment 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 PREFERRED_STACK_BOUNDARY is not defined.

@findex PREFERRED_STACK_BOUNDARY
@item PREFERRED_STACK_BOUNDARY