Subversion Repositories openrisc

@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, 2011, 2012

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

Similarly, there is a @code{targetcm} variable for hooks that are

specific to front ends for C-family languages, documented as ``C

Target Hook''.  This is declared in @file{c-family/c-target.h}, the

initializer @code{TARGETCM_INITIALIZER} in

@file{c-family/c-target-def.h}.  If targets initialize @code{targetcm}

themselves, they should set @code{target_has_targetcm=yes} in

@file{config.gcc}; otherwise a default definition is used.

Similarly, there is a @code{targetm_common} variable for hooks that

are shared between the compiler driver and the compilers proper,

documented as ``Common Target Hook''.  This is declared in

@file{common/common-target.h}, the initializer

@code{TARGETM_COMMON_INITIALIZER} in

@file{common/common-target-def.h}.  If targets initialize

@code{targetm_common} themselves, they should set

@code{target_has_targetm_common=yes} in @file{config.gcc}; otherwise a

default definition is used.

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

@deftypevr {Common Target Hook} bool TARGET_ALWAYS_STRIP_DOTDOT

True if @file{..} components should always be removed from directory names computed relative to GCC's internal directories, false (default) if such components should be preserved and directory names containing them passed to other tools such as the linker.

@end deftypevr

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

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 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{NATIVE_SYSTEM_HEADER_DIR} (set in

@file{config.gcc}, normally @file{/usr/include}) in the search order.

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

replacement.

@end defmac

@defmac NATIVE_SYSTEM_HEADER_COMPONENT

The ``component'' corresponding to @code{NATIVE_SYSTEM_HEADER_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{GPLUSPLUS_INCLUDE_DIR}, and

@code{NATIVE_SYSTEM_HEADER_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 {Common 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 {Common Target Hook} bool TARGET_HANDLE_OPTION (struct gcc_options *@var{opts}, struct gcc_options *@var{opts_set}, const struct cl_decoded_option *@var{decoded}, location_t @var{loc})

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{decoded} specifies the option and its arguments.  @var{opts} and

@var{opts_set} are the @code{gcc_options} structures to be used for

storing option state, and @var{loc} is the location at which the

option was passed (@code{UNKNOWN_LOCATION} except for options passed

via attributes).

@end deftypefn

@deftypefn {C 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

@deftypefn {C Target Hook} tree TARGET_OBJC_CONSTRUCT_STRING_OBJECT (tree @var{string})

Targets may provide a string object type that can be used within and between C, C++ and their respective Objective-C dialects. A string object might, for example, embed encoding and length information. These objects are considered opaque to the compiler and handled as references. An ideal implementation makes the composition of the string object match that of the Objective-C @code{NSString} (@code{NXString} for GNUStep), allowing efficient interworking between C-only and Objective-C code. If a target implements string objects then this hook should return a reference to such an object constructed from the normal `C' string representation provided in @var{string}. At present, the hook is used by Objective-C only, to obtain a common-format string object when the target provides one.

@end deftypefn

@deftypefn {C Target Hook} bool TARGET_STRING_OBJECT_REF_TYPE_P (const_tree @var{stringref})

If a target implements string objects then this hook should return @code{true} if @var{stringref} is a valid reference to such an object.

@end deftypefn

@deftypefn {C Target Hook} void TARGET_CHECK_STRING_OBJECT_FORMAT_ARG (tree @var{format_arg}, tree @var{args_list})

If a target implements string objects then this hook should should  provide a facility to check the function arguments in @var{args_list}  against the format specifiers in @var{format_arg} where the type of  @var{format_arg} is one recognized as a valid string reference type.

@end deftypefn

@deftypefn {Target Hook} void TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE (void)

This target function is similar to the hook @code{TARGET_OPTION_OVERRIDE}

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{TARGET_OPTION_OVERRIDE} is called so if you want to perform these

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

@code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}.

@end deftypefn

@defmac C_COMMON_OVERRIDE_OPTIONS

This is similar to the @code{TARGET_OPTION_OVERRIDE} hook

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

@deftypevr {Common Target Hook} {const struct default_options *} TARGET_OPTION_OPTIMIZATION_TABLE

Some machines may desire to change what optimizations are performed for

various optimization levels.   This variable, if defined, describes

options to enable at particular sets of optimization levels.  These

options are processed once

just after the optimization level is determined and before the remainder

of the command options have been parsed, so may be overridden by other

options passed explicitly.

This processing 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.

@end deftypevr

@deftypefn {Common Target Hook} void TARGET_OPTION_INIT_STRUCT (struct gcc_options *@var{opts})

Set target-dependent initial values of fields in @var{opts}.

@end deftypefn

@deftypefn {Common Target Hook} void TARGET_OPTION_DEFAULT_PARAMS (void)

Set target-dependent default values for @option{--param} settings, using calls to @code{set_default_param_value}.

@end deftypefn

@defmac SWITCHABLE_TARGET

Some targets need to switch between substantially different subtargets

during compilation.  For example, the MIPS target has one subtarget for

the traditional MIPS architecture and another for MIPS16.  Source code

can switch between these two subarchitectures using the @code{mips16}

and @code{nomips16} attributes.

Such subtargets can differ in things like the set of available

registers, the set of available instructions, the costs of various

operations, and so on.  GCC caches a lot of this type of information

in global variables, and recomputing them for each subtarget takes a

significant amount of time.  The compiler therefore provides a facility

for maintaining several versions of the global variables and quickly

switching between them; see @file{target-globals.h} for details.

Define this macro to 1 if your target needs this facility.  The default

is 0.

@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

GC allocation, 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; see @code{REG_WORDS_BIG_ENDIAN} if the

order of words in memory is not the same as the order in registers.  This

macro need not be a constant.

@end defmac

@defmac REG_WORDS_BIG_ENDIAN

On some machines, the order of words in a multiword object differs between

registers in memory.  In such a situation, define this macro to describe

the order of words in a register.  The macro @code{WORDS_BIG_ENDIAN} controls

the order of words in memory.

@end defmac

@defmac FLOAT_WORDS_BIG_ENDIAN

Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or

@code{TFmode} floating point numbers are stored in memory with the word

containing the sign bit at the lowest address; otherwise define it to

have the value 0.  This macro need not be a constant.

You need not define this macro if the ordering is the same as for

multi-word integers.

@end defmac

@defmac BITS_PER_UNIT

Define this macro to be the number of bits in an addressable storage

unit (byte).  If you do not define this macro the default is 8.

@end defmac

@defmac BITS_PER_WORD

Number of bits in a word.  If you do not define this macro, the default

is @code{BITS_PER_UNIT * UNITS_PER_WORD}.

@end defmac

@defmac MAX_BITS_PER_WORD

Maximum number of bits in a word.  If this is undefined, the default is

@code{BITS_PER_WORD}.  Otherwise, it is the constant value that is the

largest value that @code{BITS_PER_WORD} can have at run-time.

@end defmac

@defmac UNITS_PER_WORD

Number of storage units in a word; normally the size of a general-purpose

register, a power of two from 1 or 8.

@end defmac

@defmac MIN_UNITS_PER_WORD

Minimum number of units in a word.  If this is undefined, the default is

@code{UNITS_PER_WORD}.  Otherwise, it is the constant value that is the

smallest value that @code{UNITS_PER_WORD} can have at run-time.

@end defmac

@defmac POINTER_SIZE

Width of a pointer, in bits.  You must specify a value no wider than the

width of @code{Pmode}.  If it is not equal to the width of @code{Pmode},

you must define @code{POINTERS_EXTEND_UNSIGNED}.  If you do not specify

a value the default is @code{BITS_PER_WORD}.

@end defmac

@defmac POINTERS_EXTEND_UNSIGNED

A C expression that determines how pointers should be extended from

@code{ptr_mode} to either @code{Pmode} or @code{word_mode}.  It is

greater than zero if pointers should be zero-extended, zero if they

should be sign-extended, and negative if some other sort of conversion

is needed.  In the last case, the extension is done by the target's

@code{ptr_extend} instruction.

You need not define this macro if the @code{ptr_mode}, @code{Pmode}

and @code{word_mode} are all the same width.

@end defmac

@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type})

A macro to update @var{m} and @var{unsignedp} when an object whose type

is @var{type} and which has the specified mode and signedness is to be

stored in a register.  This macro is only called when @var{type} is a

scalar type.

On most RISC machines, which only have operations that operate on a full

register, define this macro to set @var{m} to @code{word_mode} if

@var{m} is an integer mode narrower than @code{BITS_PER_WORD}.  In most

cases, only integer modes should be widened because wider-precision

floating-point operations are usually more expensive than their narrower

counterparts.

For most machines, the macro definition does not change @var{unsignedp}.

However, some machines, have instructions that preferentially handle

either signed or unsigned quantities of certain modes.  For example, on

the DEC Alpha, 32-bit loads from memory and 32-bit add instructions

sign-extend the result to 64 bits.  On such machines, set