tm.texi

GCC

Define this macro if you wish to preserve a certain alignment for
the stack pointer.  The definition is a C expression
for the desired alignment (measured in bits).  If STACK_BOUNDARY is
also defined, this macro must evaluate to a value equal to or larger
than STACK_BOUNDARY.

@cindex @code{PUSH_ROUNDING}, interaction with @code{PREFERRED_STACK_BOUNDARY}
If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned
to the specified boundary.  If @code{PUSH_ROUNDING} is defined and specifies
a less strict alignment than @code{PREFERRED_STACK_BOUNDARY}, the stack may
be momentarily unaligned while pushing arguments.

@findex FUNCTION_BOUNDARY
@item FUNCTION_BOUNDARY
Alignment required for a function entry point, in bits.

@findex BIGGEST_ALIGNMENT
@item BIGGEST_ALIGNMENT
Biggest alignment that any data type can require on this machine, in bits.

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

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

@findex ADJUST_FIELD_ALIGN
@item 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 is @var{computed}.  GCC uses
this value instead of the value in @code{BIGGEST_ALIGNMENT} or
@code{BIGGEST_FIELD_ALIGNMENT}, if defined, for structure fields only.

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

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

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

If this macro is not defined, then @var{basic-align} is used.

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.

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

@findex EMPTY_FIELD_BOUNDARY
@item EMPTY_FIELD_BOUNDARY
Alignment in bits to be given to a structure bit-field that follows an
empty field such as @code{int : 0;}.

Note that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment
that results from an empty field.

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

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

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

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:

@example
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 example

If this prints 2 and 5, then the compiler's behavior is what you would
get from @code{PCC_BITFIELD_TYPE_MATTERS}.

@findex BITFIELD_NBYTES_LIMITED
@item BITFIELD_NBYTES_LIMITED
Like PCC_BITFIELD_TYPE_MATTERS except that its effect is limited to
aligning a bit-field within the structure.

@findex STRUCT_FORCE_BLK
@item STRUCT_FORCE_BLK (@var{field})
Return 1 if a structure containing @var{field} should be accessed using
@code{BLKMODE}.

Normally, this is not needed.  See the file @file{c4x.h} for an example
of how to use this macro to prevent a structure having a floating point
field from being accessed in an integer mode.

@findex ROUND_TYPE_SIZE
@item ROUND_TYPE_SIZE (@var{type}, @var{computed}, @var{specified})
Define this macro as an expression for the overall size of a type
(given by @var{type} as a tree node) when the size computed in the
usual way is @var{computed} and the alignment is @var{specified}.

The default is to round @var{computed} up to a multiple of @var{specified}.

@findex ROUND_TYPE_SIZE_UNIT
@item ROUND_TYPE_SIZE_UNIT (@var{type}, @var{computed}, @var{specified})
Similar to @code{ROUND_TYPE_SIZE}, but sizes and alignments are
specified in units (bytes).  If you define @code{ROUND_TYPE_SIZE},
you must also define this macro and they must be defined consistently
with each other.

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

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

@findex VECTOR_MODE_SUPPORTED_P
@item VECTOR_MODE_SUPPORTED_P(@var{mode})
Define this macro to be nonzero if the port is prepared to handle insns
involving vector mode @var{mode}.  At the very least, it must have move
patterns for this mode.

@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
@code{double}) for mode @var{mode}.  This means that you check whether
@var{value} fits within the possible range of values for mode
@var{mode} on this target machine.  The mode @var{mode} is always
a mode of class @code{MODE_FLOAT}.  @var{overflow} is nonzero if
the value is already known to be out of range.

If @var{value} is not valid or if @var{overflow} is nonzero, you should
set @var{overflow} to 1 and then assign some valid value to @var{value}.
Allowing an invalid value to go through the compiler can produce
incorrect assembler code which may even cause Unix assemblers to crash.

This macro need not be defined if there is no work for it to do.

@findex TARGET_FLOAT_FORMAT
@item TARGET_FLOAT_FORMAT
A code distinguishing the floating point format of the target machine.
There are three defined values:

@table @code
@findex IEEE_FLOAT_FORMAT
@item IEEE_FLOAT_FORMAT
This code indicates IEEE floating point.  It is the default; there is no
need to define this macro when the format is IEEE.

@findex VAX_FLOAT_FORMAT
@item VAX_FLOAT_FORMAT
This code indicates the peculiar format used on the Vax.

@findex UNKNOWN_FLOAT_FORMAT
@item UNKNOWN_FLOAT_FORMAT
This code indicates any other format.
@end table

The value of this macro is compared with @code{HOST_FLOAT_FORMAT}
(@pxref{Config}) to determine whether the target machine has the same
format as the host machine.  If any other formats are actually in use on
supported machines, new codes should be defined for them.

The ordering of the component words of floating point values stored in
memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN} for the target
machine and @code{HOST_FLOAT_WORDS_BIG_ENDIAN} for the host.

@findex DEFAULT_VTABLE_THUNKS
@item DEFAULT_VTABLE_THUNKS
GCC supports two ways of implementing C++ vtables:  traditional or with
so-called ``thunks''.  The flag @option{-fvtable-thunk} chooses between them.
Define this macro to be a C expression for the default value of that flag.
If @code{DEFAULT_VTABLE_THUNKS} is 0, GCC uses the traditional
implementation by default.  The ``thunk'' implementation is more efficient
(especially if you have provided an implementation of
@code{ASM_OUTPUT_MI_THUNK}, see @ref{Function Entry}), but is not binary
compatible with code compiled using the traditional implementation.
If you are writing a new port, define @code{DEFAULT_VTABLE_THUNKS} to 1.

If you do not define this macro, the default for @option{-fvtable-thunk} is 0.
@end table

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