tm.texi

理解和实践操作系统的一本好书

@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,
@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 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 and Functions
@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} and a C source file named @file{@var{machine}.c}.
The 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}.  The
source file defines a variable @code{targetm}, which is a structure
containing pointers to functions and data relating to the target
machine.  @file{@var{machine}.c} should also contain their definitions,
if they are not defined elsewhere in GCC, and other functions called
through the macros defined in the @file{.h} file.

@menu
* Target Structure::    The @code{targetm} variable.
* 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.
* Old Constraints::     The old way to define machine-specific constraints.
* 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.
* Anchored Addresses::  Defining how @option{-fsection-anchors} should work.
* Condition Code::      Defining how insns update the condition code.
* Costs::               Defining relative costs of different operations.
* Scheduling::          Adjusting the behavior of the instruction scheduler.
* 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.
* Floating Point::      Handling floating point for cross-compilers.
* Mode Switching::      Insertion of mode-switching instructions.
* Target Attributes::   Defining target-specific uses of @code{__attribute__}.
* MIPS Coprocessors::   MIPS coprocessor support and how to customize it.
* PCH Target::          Validity checking for precompiled headers.
* C++ ABI::             Controlling C++ ABI changes.
* Misc::                Everything else.
@end menu

@node Target Structure
@section The Global @code{targetm} Variable
@cindex target hooks
@cindex target functions

@deftypevar {struct gcc_target} targetm
The target @file{.c} file must define the global @code{targetm} variable
which contains pointers to functions and data relating to the target
machine.  The variable is declared in @file{target.h};
@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is
used to initialize the variable, and macros for the default initializers
for elements of the structure.  The @file{.c} file should override those
macros for which the default definition is inappropriate.  For example:
@smallexample
#include "target.h"
#include "target-def.h"

/* @r{Initialize the GCC target structure.}  */

#undef TARGET_COMP_TYPE_ATTRIBUTES
#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes

struct gcc_target targetm = TARGET_INITIALIZER;
@end smallexample
@end deftypevar

Where a macro should be defined in the @file{.c} file in this manner to
form part of the @code{targetm} structure, it is documented below as a
``Target Hook'' with a prototype.  Many macros will change in future
from being defined in the @file{.h} file to being part of the
@code{targetm} structure.

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

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

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

@defmac 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, nonzero 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.
@end defmac

@defmac 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{""}.
@end defmac

@defmac TARGET_OPTION_TRANSLATE_TABLE
If defined, a list of pairs of strings, the first of which is a
potential command line target to the @file{gcc} driver program, and the
second of which is a space-separated (tabs and other whitespace are not
supported) list of options with which to replace the first option.  The
target defining this list is responsible for assuring that the results
are valid.  Replacement options may not be the @code{--opt} style, they
must be the @code{-opt} style.  It is the intention of this macro to
provide a mechanism for substitution that affects the multilibs chosen,
such as one option that enables many options, some of which select
multilibs.  Example nonsensical definition, where @option{-malt-abi},
@option{-EB}, and @option{-mspoo} cause different multilibs to be chosen:

@smallexample
#define TARGET_OPTION_TRANSLATE_TABLE \
@{ "-fast",   "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \
@{ "-compat", "-EB -malign=4 -mspoo" @}
@end smallexample
@end defmac

@defmac DRIVER_SELF_SPECS
A list of specs for the driver itself.  It should be a suitable
initializer for an array of strings, with no surrounding braces.

The driver applies these specs to its own command line between loading
default @file{specs} files (but not command-line specified ones) and
choosing the multilib directory or running any subcommands.  It
applies them in the order given, so each spec can depend on the
options added by earlier ones.  It is also possible to remove options
using @samp{%<@var{option}} in the usual way.

This macro can be useful when a port has several interdependent target
options.  It provides a way of standardizing the command line so
that the other specs are easier to write.

Do not define this macro if it does not need to do anything.
@end defmac

@defmac OPTION_DEFAULT_SPECS
A list of specs used to support configure-time default options (i.e.@:
@option{--with} options) in the driver.  It should be a suitable initializer
for an array of structures, each containing two strings, without the
outermost pair of surrounding braces.

The first item in the pair is the name of the default.  This must match
the code in @file{config.gcc} for the target.  The second item is a spec
to apply if a default with this name was specified.  The string
@samp{%(VALUE)} in the spec will be replaced by the value of the default
everywhere it occurs.

The driver will apply these specs to its own command line between loading
default @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using
the same mechanism as @code{DRIVER_SELF_SPECS}.

Do not define this macro if it does not need to do anything.
@end defmac

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

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

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

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

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

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

@defmac AS_NEEDS_DASH_FOR_PIPED_INPUT
Define this macro, with no value, if the driver should give the assembler
an argument consisting of a single dash, @option{-}, to instruct it to
read from its standard input (which will be a pipe connected to the
output of the compiler proper).  This argument is given after any
@option{-o} option specifying the name of the output file.

If you do not define this macro, the assembler is assumed to read its
standard input if given no non-option arguments.  If your assembler
cannot read standard input at all, use a @samp{%@{pipe:%e@}} construct;
see @file{mips.h} for instance.
@end defmac

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

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

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

@defmac REAL_LIBGCC_SPEC
By default, if @code{ENABLE_SHARED_LIBGCC} is defined, the
@code{LIBGCC_SPEC} is not directly used by the driver program but is
instead modified to refer to different versions of @file{libgcc.a}
depending on the values of the command line flags @option{-static},
@option{-shared}, @option{-static-libgcc}, and @option{-shared-libgcc}.  On
targets where these modifications are inappropriate, define
@code{REAL_LIBGCC_SPEC} instead.  @code{REAL_LIBGCC_SPEC} tells the
driver how to place a reference to @file{libgcc} on the link command
line, but, unlike @code{LIBGCC_SPEC}, it is used unmodified.
@end defmac

@defmac USE_LD_AS_NEEDED
A macro that controls the modifications to @code{LIBGCC_SPEC}
mentioned in @code{REAL_LIBGCC_SPEC}.  If nonzero, a spec will be
generated that uses --as-needed and the shared libgcc in place of the
static exception handler library, when linking without any of
@code{-static}, @code{-static-libgcc}, or @code{-shared-libgcc}.
@end defmac