tm.texi

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

The location @file{/usr/lib/gcc/}, but only if this is a native compiler. 

@item
The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 
compiler.
@end enumerate

Here is the order of prefixes tried for startfiles:

@enumerate
@item
Any prefixes specified by the user with @option{-B}.

@item
The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined
value based on the installed toolchain location.

@item
The directories specified by the environment variable @code{LIBRARY_PATH}
(or port-specific name; native only, cross compilers do not use this).

@item
The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed
in the configured @var{prefix} or this is a native compiler. 

@item
The location @file{/usr/lib/gcc/}, but only if this is a native compiler.

@item
The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 
compiler.

@item
The macro @code{MD_STARTFILE_PREFIX}, if defined, but only if this is a 
native compiler, or we have a target system root.

@item
The macro @code{MD_STARTFILE_PREFIX_1}, if defined, but only if this is a 
native compiler, or we have a target system root.

@item
The macro @code{STANDARD_STARTFILE_PREFIX}, with any sysroot modifications.
If this path is relative it will be prefixed by @code{GCC_EXEC_PREFIX} and
the machine suffix or @code{STANDARD_EXEC_PREFIX} and the machine suffix.

@item
The macro @code{STANDARD_STARTFILE_PREFIX_1}, but only if this is a native
compiler, or we have a target system root. The default for this macro is
@file{/lib/}.

@item
The macro @code{STANDARD_STARTFILE_PREFIX_2}, but only if this is a native
compiler, or we have a target system root. The default for this macro is
@file{/usr/lib/}.
@end enumerate

@node Run-time Target
@section Run-time Target Specification
@cindex run-time target specification
@cindex predefined macros
@cindex target specifications

@c prevent bad page break with this line
Here are run-time target specifications.

@defmac TARGET_CPU_CPP_BUILTINS ()
This function-like macro expands to a block of code that defines
built-in preprocessor macros and assertions for the target CPU, using
the functions @code{builtin_define}, @code{builtin_define_std} and
@code{builtin_assert}.  When the front end
calls this macro it provides a trailing semicolon, and since it has
finished command line option processing your code can use those
results freely.

@code{builtin_assert} takes a string in the form you pass to the
command-line option @option{-A}, such as @code{cpu=mips}, and creates
the assertion.  @code{builtin_define} takes a string in the form
accepted by option @option{-D} and unconditionally defines the macro.

@code{builtin_define_std} takes a string representing the name of an
object-like macro.  If it doesn't lie in the user's namespace,
@code{builtin_define_std} defines it unconditionally.  Otherwise, it
defines a version with two leading underscores, and another version
with two leading and trailing underscores, and defines the original
only if an ISO standard was not requested on the command line.  For
example, passing @code{unix} defines @code{__unix}, @code{__unix__}
and possibly @code{unix}; passing @code{_mips} defines @code{__mips},
@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64}
defines only @code{_ABI64}.

You can also test for the C dialect being compiled.  The variable
@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus}
or @code{clk_objective_c}.  Note that if we are preprocessing
assembler, this variable will be @code{clk_c} but the function-like
macro @code{preprocessing_asm_p()} will return true, so you might want
to check for that first.  If you need to check for strict ANSI, the
variable @code{flag_iso} can be used.  The function-like macro
@code{preprocessing_trad_p()} can be used to check for traditional
preprocessing.
@end defmac

@defmac TARGET_OS_CPP_BUILTINS ()
Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
and is used for the target operating system instead.
@end defmac

@defmac TARGET_OBJFMT_CPP_BUILTINS ()
Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
and is used for the target object format.  @file{elfos.h} uses this
macro to define @code{__ELF__}, so you probably do not need to define
it yourself.
@end defmac

@deftypevar {extern int} target_flags
This variable is declared in @file{options.h}, which is included before
any target-specific headers.
@end deftypevar

@deftypevar {Target Hook} int TARGET_DEFAULT_TARGET_FLAGS
This variable specifies the initial value of @code{target_flags}.
Its default setting is 0.
@end deftypevar

@cindex optional hardware or system features
@cindex features, optional, in system conventions

@deftypefn {Target Hook} bool TARGET_HANDLE_OPTION (size_t @var{code}, const char *@var{arg}, int @var{value})
This hook is called whenever the user specifies one of the
target-specific options described by the @file{.opt} definition files
(@pxref{Options}).  It has the opportunity to do some option-specific
processing and should return true if the option is valid.  The default
definition does nothing but return true.

@var{code} specifies the @code{OPT_@var{name}} enumeration value
associated with the selected option; @var{name} is just a rendering of
the option name in which non-alphanumeric characters are replaced by
underscores.  @var{arg} specifies the string argument and is null if
no argument was given.  If the option is flagged as a @code{UInteger}
(@pxref{Option properties}), @var{value} is the numeric value of the
argument.  Otherwise @var{value} is 1 if the positive form of the
option was used and 0 if the ``no-'' form was.
@end deftypefn

@deftypefn {Target Hook} bool TARGET_HANDLE_C_OPTION (size_t @var{code}, const char *@var{arg}, int @var{value})
This target hook is called whenever the user specifies one of the
target-specific C language family options described by the @file{.opt}
definition files(@pxref{Options}).  It has the opportunity to do some
option-specific processing and should return true if the option is
valid.  The default definition does nothing but return false.

In general, you should use @code{TARGET_HANDLE_OPTION} to handle
options.  However, if processing an option requires routines that are
only available in the C (and related language) front ends, then you
should use @code{TARGET_HANDLE_C_OPTION} instead.
@end deftypefn

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

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

@defmac C_COMMON_OVERRIDE_OPTIONS
This is similar to @code{OVERRIDE_OPTIONS} but is only used in the C
language frontends (C, Objective-C, C++, Objective-C++) and so can be
used to alter option flag variables which only exist in those
frontends.
@end defmac

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

@deftypefn {Target Hook} bool TARGET_HELP (void)
This hook is called in response to the user invoking
@option{--target-help} on the command line.  It gives the target a
chance to display extra information on the target specific command
line options found in its @file{.opt} file.
@end deftypefn

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

@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 initialize the function pointer
@code{init_machine_status}.  This pointer is 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.

@defmac INIT_EXPANDERS
Macro called to initialize 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 initialization of the
function pointer @code{init_machine_status}.
@end defmac

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

@code{struct machine_function} structures are expected to be freed by GC@.
Generally, any memory that they reference must be allocated by using
@code{ggc_alloc}, including the structure itself.
@end deftypevar

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

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

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

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

@defmac LIBGCC2_WORDS_BIG_ENDIAN