Subversion Repositories openrisc_2011-10-31

@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,

@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010

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

* Emulated TLS::        Emulated TLS support.

* MIPS Coprocessors::   MIPS coprocessor support and how to customize it.

* PCH Target::          Validity checking for precompiled headers.

* C++ ABI::             Controlling C++ ABI changes.

* Named Address Spaces:: Adding support for named address spaces

* 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

@defmac LINK_EH_SPEC

If defined, this C string constant is added to @code{LINK_SPEC}.

When @code{USE_LD_AS_NEEDED} is zero or undefined, it also affects

the modifications to @code{LIBGCC_SPEC} mentioned in

@code{REAL_LIBGCC_SPEC}.

@end defmac

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

@end defmac

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

@end defmac

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

@end defmac

@defmac SYSROOT_SUFFIX_SPEC

Define this macro to add a suffix to the target sysroot when GCC is

configured with a sysroot.  This will cause GCC to search for usr/lib,

et al, within sysroot+suffix.

@end defmac

@defmac SYSROOT_HEADERS_SUFFIX_SPEC

Define this macro to add a headers_suffix to the target sysroot when

GCC is configured with a sysroot.  This will cause GCC to pass the

updated sysroot+headers_suffix to CPP, causing it to search for

usr/include, et al, within sysroot+headers_suffix.

@end defmac

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

@smallexample

#define EXTRA_SPECS \

  @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @},

#define CPP_SYS_DEFAULT ""

@end smallexample

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-sysv: %(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

@end defmac

@defmac LINK_LIBGCC_SPECIAL_1

Define this macro if the driver program should find the library

@file{libgcc.a}.  If you do not define this macro, the driver program will pass

the argument @option{-lgcc} to tell the linker to do the search.

@end defmac

@defmac LINK_GCC_C_SEQUENCE_SPEC

The sequence in which libgcc and libc are specified to the linker.

By default this is @code{%G %L %G}.

@end defmac

@defmac LINK_COMMAND_SPEC

A C string constant giving the complete command line need to execute the

linker.  When you do this, you will need to update your port each time a

change is made to the link command line within @file{gcc.c}.  Therefore,

define this macro only if you need to completely redefine the command

line for invoking the linker and there is no other way to accomplish

the effect you need.  Overriding this macro may be avoidable by overriding

@code{LINK_GCC_C_SEQUENCE_SPEC} instead.

@end defmac

@defmac LINK_ELIMINATE_DUPLICATE_LDIRECTORIES

A nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search

directories from linking commands.  Do not give it a nonzero value if

removing duplicate search directories changes the linker's semantics.

@end defmac

@defmac MULTILIB_DEFAULTS

Define this macro as a C expression for the initializer of an array of

string to tell the driver program which options are defaults for this

target and thus do not need to be handled specially when using

@code{MULTILIB_OPTIONS}.

Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in

the target makefile fragment or if none of the options listed in

@code{MULTILIB_OPTIONS} are set by default.

@xref{Target Fragment}.

@end defmac

@defmac RELATIVE_PREFIX_NOT_LINKDIR

Define this macro to tell @command{gcc} that it should only translate

a @option{-B} prefix into a @option{-L} linker option if the prefix

indicates an absolute file name.

@end defmac

@defmac MD_EXEC_PREFIX

If defined, this macro is an additional prefix to try after

@code{STANDARD_EXEC_PREFIX}.  @code{MD_EXEC_PREFIX} is not searched

when the @option{-b} option is used, or the compiler is built as a cross

compiler.  If you define @code{MD_EXEC_PREFIX}, then be sure to add it

to the list of directories used to find the assembler in @file{configure.in}.

@end defmac

@defmac STANDARD_STARTFILE_PREFIX

Define this macro as a C string constant if you wish to override the

standard choice of @code{libdir} as the default prefix to

try when searching for startup files such as @file{crt0.o}.

@code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler

is built as a cross compiler.

@end defmac

@defmac STANDARD_STARTFILE_PREFIX_1

Define this macro as a C string constant if you wish to override the

standard choice of @code{/lib} as a prefix to try after the default prefix

when searching for startup files such as @file{crt0.o}.

@code{STANDARD_STARTFILE_PREFIX_1} is not searched when the compiler

is built as a cross compiler.

@end defmac

@defmac STANDARD_STARTFILE_PREFIX_2

Define this macro as a C string constant if you wish to override the

standard choice of @code{/lib} as yet another prefix to try after the

default prefix when searching for startup files such as @file{crt0.o}.

@code{STANDARD_STARTFILE_PREFIX_2} is not searched when the compiler

is built as a cross compiler.

@end defmac

@defmac MD_STARTFILE_PREFIX

If defined, this macro supplies an additional prefix to try after the

standard prefixes.  @code{MD_EXEC_PREFIX} is not searched when the

@option{-b} option is used, or when the compiler is built as a cross

compiler.

@end defmac

@defmac MD_STARTFILE_PREFIX_1

If defined, this macro supplies yet another prefix to try after the

standard prefixes.  It is not searched when the @option{-b} option is

used, or when the compiler is built as a cross compiler.

@end defmac

@defmac INIT_ENVIRONMENT

Define this macro as a C string constant if you wish to set environment

variables for programs called by the driver, such as the assembler and

loader.  The driver passes the value of this macro to @code{putenv} to

initialize the necessary environment variables.

@end defmac

@defmac LOCAL_INCLUDE_DIR

Define this macro as a C string constant if you wish to override the

standard choice of @file{/usr/local/include} as the default prefix to

try when searching for local header files.  @code{LOCAL_INCLUDE_DIR}

comes before @code{SYSTEM_INCLUDE_DIR} in the search order.

Cross compilers do not search either @file{/usr/local/include} or its

replacement.

@end defmac

@defmac MODIFY_TARGET_NAME

Define this macro if you wish to define command-line switches that

modify the default target name.

For each switch, you can include a string to be appended to the first

part of the configuration name or a string to be deleted from the

configuration name, if present.  The definition should be an initializer

for an array of structures.  Each array element should have three

elements: the switch name (a string constant, including the initial

dash), one of the enumeration codes @code{ADD} or @code{DELETE} to

indicate whether the string should be inserted or deleted, and the string

to be inserted or deleted (a string constant).

For example, on a machine where @samp{64} at the end of the

configuration name denotes a 64-bit target and you want the @option{-32}

and @option{-64} switches to select between 32- and 64-bit targets, you would

code

@smallexample

#define MODIFY_TARGET_NAME \

  @{ @{ "-32", DELETE, "64"@}, \

     @{"-64", ADD, "64"@}@}

@end smallexample

@end defmac

@defmac SYSTEM_INCLUDE_DIR

Define this macro as a C string constant if you wish to specify a

system-specific directory to search for header files before the standard

directory.  @code{SYSTEM_INCLUDE_DIR} comes before

@code{STANDARD_INCLUDE_DIR} in the search order.

Cross compilers do not use this macro and do not search the directory

specified.

@end defmac

@defmac STANDARD_INCLUDE_DIR

Define this macro as a C string constant if you wish to override the

standard choice of @file{/usr/include} as the default prefix to

try when searching for header files.

Cross compilers ignore this macro and do not search either

@file{/usr/include} or its replacement.

@end defmac

@defmac STANDARD_INCLUDE_COMPONENT

The ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}.

See @code{INCLUDE_DEFAULTS}, below, for the description of components.

If you do not define this macro, no component is used.

@end defmac

@defmac INCLUDE_DEFAULTS

Define this macro if you wish to override the entire default search path

for include files.  For a native compiler, the default search path

usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR},

@code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and

@code{STANDARD_INCLUDE_DIR}.  In addition, @code{GPLUSPLUS_INCLUDE_DIR}

and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile},

and specify private search areas for GCC@.  The directory

@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs.

The definition should be an initializer for an array of structures.

Each array element should have four elements: the directory name (a

string constant), the component name (also a string constant), a flag

for C++-only directories,

and a flag showing that the includes in the directory don't need to be

wrapped in @code{extern @samp{C}} when compiling C++.  Mark the end of

the array with a null element.

The component name denotes what GNU package the include file is part of,

if any, in all uppercase letters.  For example, it might be @samp{GCC}

or @samp{BINUTILS}.  If the package is part of a vendor-supplied

operating system, code the component name as @samp{0}.

For example, here is the definition used for VAX/VMS:

@smallexample

#define INCLUDE_DEFAULTS \

@{                                       \

  @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@},   \

  @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@},    \

  @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@},  \

  @{ ".", 0, 0, 0@},                      \

  @{ 0, 0, 0, 0@}                         \

@}

@end smallexample

@end defmac

Here is the order of prefixes tried for exec files:

@enumerate

@item

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

@item

The environment variable @code{GCC_EXEC_PREFIX} or, if @code{GCC_EXEC_PREFIX}

is not set and the compiler has not been installed in the configure-time

@var{prefix}, the location in which the compiler has actually been installed.

@item

The directories specified by the environment variable @code{COMPILER_PATH}.

@item

The macro @code{STANDARD_EXEC_PREFIX}, if the compiler has been installed

in the configured-time @var{prefix}.

@item

The location @file{/usr/libexec/gcc/}, but only if 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.

@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

@deftypevr {Target Hook} int TARGET_DEFAULT_TARGET_FLAGS

This variable specifies the initial value of @code{target_flags}.

Its default setting is 0.

@end deftypevr

@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 arguments are like for @code{TARGET_HANDLE_OPTION}.  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.

If you need to do something whenever the optimization level is

changed via the optimize attribute or pragma, see

@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}

@end defmac

@deftypefn {Target Hook} void TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE (void)

This target function is similar to the macro @code{OVERRIDE_OPTIONS}

but is called when the optimize level is changed via an attribute or

pragma or when it is reset at the end of the code affected by the

attribute or pragma.  It is not called at the beginning of compilation

when @code{OVERRIDE_OPTIONS} is called so if you want to perform these

actions then, you should have @code{OVERRIDE_OPTIONS} call

@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}.

@end deftypefn

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

This macro is run once at program startup and when the optimization

options are changed via @code{#pragma GCC optimize} or by using the

@code{optimize} attribute.

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