tm.texi

GCC

@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001
@c 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
@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}.  This 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}.

@menu
* 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.
* Condition Code::      Defining how insns update the condition code.
* Costs::               Defining relative costs of different operations.
* 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.
* Cross-compilation::   Handling floating point for cross-compilers.
* Mode Switching::      Insertion of mode-switching instructions.
* Misc::                Everything else.
@end menu

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

@table @code
@findex SWITCH_TAKES_ARG
@item SWITCH_TAKES_ARG (@var{char})
A C expression which determines whether the option @option{-@var{char}}
takes arguments.  The value should be the number of arguments that
option takes--zero, for many options.

By default, this macro is defined as
@code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options
properly.  You need not define @code{SWITCH_TAKES_ARG} unless you
wish to add additional options which take arguments.  Any redefinition
should call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for
additional options.

@findex WORD_SWITCH_TAKES_ARG
@item WORD_SWITCH_TAKES_ARG (@var{name})
A C expression which determines whether the option @option{-@var{name}}
takes arguments.  The value should be the number of arguments that
option takes--zero, for many options.  This macro rather than
@code{SWITCH_TAKES_ARG} is used for multi-character option names.

By default, this macro is defined as
@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options
properly.  You need not define @code{WORD_SWITCH_TAKES_ARG} unless you
wish to add additional options which take arguments.  Any redefinition
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 @option{-@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
the linker needs a space between the option and its argument.

If this macro is not defined, the default value is @code{""}.

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

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

@findex NO_BUILTIN_SIZE_TYPE
@item NO_BUILTIN_SIZE_TYPE
If this macro is defined, the preprocessor will not define the built-in macro
@code{__SIZE_TYPE__}.  The macro @code{__SIZE_TYPE__} must then be defined
by @code{CPP_SPEC} instead.

This should be defined if @code{SIZE_TYPE} depends on target dependent flags
which are not accessible to the preprocessor.  Otherwise, it should not
be defined.

@findex NO_BUILTIN_PTRDIFF_TYPE
@item NO_BUILTIN_PTRDIFF_TYPE
If this macro is defined, the preprocessor will not define the built-in macro
@code{__PTRDIFF_TYPE__}.  The macro @code{__PTRDIFF_TYPE__} must then be
defined by @code{CPP_SPEC} instead.

This should be defined if @code{PTRDIFF_TYPE} depends on target dependent flags
which are not accessible to the preprocessor.  Otherwise, it should not
be defined.

@findex NO_BUILTIN_WCHAR_TYPE
@item NO_BUILTIN_WCHAR_TYPE
If this macro is defined, the preprocessor will not define the built-in macro
@code{__WCHAR_TYPE__}.  The macro @code{__WCHAR_TYPE__} must then be
defined by @code{CPP_SPEC} instead.

This should be defined if @code{WCHAR_TYPE} depends on target dependent flags
which are not accessible to the preprocessor.  Otherwise, it should not
be defined.

@findex NO_BUILTIN_WINT_TYPE
@item NO_BUILTIN_WINT_TYPE
If this macro is defined, the preprocessor will not define the built-in macro
@code{__WINT_TYPE__}.  The macro @code{__WINT_TYPE__} must then be
defined by @code{CPP_SPEC} instead.

This should be defined if @code{WINT_TYPE} depends on target dependent flags
which are not accessible to the preprocessor.  Otherwise, it should not
be defined.

@findex SIGNED_CHAR_SPEC
@item SIGNED_CHAR_SPEC
A C string constant that tells the GCC driver program options to
pass to CPP.  By default, this macro is defined to pass the option
@option{-D__CHAR_UNSIGNED__} to CPP if @code{char} will be treated as
@code{unsigned char} by @code{cc1}.

Do not define this macro unless you need to override the default
definition.

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

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

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

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

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

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

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

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

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

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

@findex EXTRA_SPECS
@item 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:

@example
#define EXTRA_SPECS \
  @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @},

#define CPP_SYS_DEFAULT ""
@end example

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-aix: -D_CALL_AIX @} \
%@{!mcall-sysv: %@{!mcall-aix: %(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

@findex LINK_LIBGCC_SPECIAL
@item LINK_LIBGCC_SPECIAL
Define this macro if the driver program should find the library
@file{libgcc.a} itself and should not pass @option{-L} options to the
linker.  If you do not define this macro, the driver program will pass
the argument @option{-lgcc} to tell the linker to do the search and will
pass @option{-L} options to it.

@findex LINK_LIBGCC_SPECIAL_1