This is ../../gcc-3.4/gcc/doc/gccint.info, produced by makeinfo version
4.2 from ../../gcc-3.4/gcc/doc/gccint.texi.

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gccint: (gccint).            Internals of the GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the internals of the GNU compilers.

   Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

File: gccint.info,  Node: Conditional Execution,  Next: Constant Definitions,  Prev: Insn Attributes,  Up: Machine Desc

Conditional Execution
=====================

   A number of architectures provide for some form of conditional
execution, or predication.  The hallmark of this feature is the ability
to nullify most of the instructions in the instruction set.  When the
instruction set is large and not entirely symmetric, it can be quite
tedious to describe these forms directly in the `.md' file.  An
alternative is the `define_cond_exec' template.

     (define_cond_exec
       [PREDICATE-PATTERN]
       "CONDITION"
       "OUTPUT-TEMPLATE")

   PREDICATE-PATTERN is the condition that must be true for the insn to
be executed at runtime and should match a relational operator.  One can
use `match_operator' to match several relational operators at once.
Any `match_operand' operands must have no more than one alternative.

   CONDITION is a C expression that must be true for the generated
pattern to match.

   OUTPUT-TEMPLATE is a string similar to the `define_insn' output
template (*note Output Template::), except that the `*' and `@' special
cases do not apply.  This is only useful if the assembly text for the
predicate is a simple prefix to the main insn.  In order to handle the
general case, there is a global variable `current_insn_predicate' that
will contain the entire predicate if the current insn is predicated,
and will otherwise be `NULL'.

   When `define_cond_exec' is used, an implicit reference to the
`predicable' instruction attribute is made.  *Note Insn Attributes::.
This attribute must be boolean (i.e. have exactly two elements in its
LIST-OF-VALUES).  Further, it must not be used with complex
expressions.  That is, the default and all uses in the insns must be a
simple constant, not dependent on the alternative or anything else.

   For each `define_insn' for which the `predicable' attribute is true,
a new `define_insn' pattern will be generated that matches a predicated
version of the instruction.  For example,

     (define_insn "addsi"
       [(set (match_operand:SI 0 "register_operand" "r")
             (plus:SI (match_operand:SI 1 "register_operand" "r")
                      (match_operand:SI 2 "register_operand" "r")))]
       "TEST1"
       "add %2,%1,%0")
     
     (define_cond_exec
       [(ne (match_operand:CC 0 "register_operand" "c")
            (const_int 0))]
       "TEST2"
       "(%0)")

generates a new pattern

     (define_insn ""
       [(cond_exec
          (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
          (set (match_operand:SI 0 "register_operand" "r")
               (plus:SI (match_operand:SI 1 "register_operand" "r")
                        (match_operand:SI 2 "register_operand" "r"))))]
       "(TEST2) && (TEST1)"
       "(%3) add %2,%1,%0")


File: gccint.info,  Node: Constant Definitions,  Prev: Conditional Execution,  Up: Machine Desc

Constant Definitions
====================

   Using literal constants inside instruction patterns reduces
legibility and can be a maintenance problem.

   To overcome this problem, you may use the `define_constants'
expression.  It contains a vector of name-value pairs.  From that point
on, wherever any of the names appears in the MD file, it is as if the
corresponding value had been written instead.  You may use
`define_constants' multiple times; each appearance adds more constants
to the table.  It is an error to redefine a constant with a different
value.

   To come back to the a29k load multiple example, instead of

     (define_insn ""
       [(match_parallel 0 "load_multiple_operation"
          [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
                (match_operand:SI 2 "memory_operand" "m"))
           (use (reg:SI 179))
           (clobber (reg:SI 179))])]
       ""
       "loadm 0,0,%1,%2")

   You could write:

     (define_constants [
         (R_BP 177)
         (R_FC 178)
         (R_CR 179)
         (R_Q  180)
     ])
     
     (define_insn ""
       [(match_parallel 0 "load_multiple_operation"
          [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
                (match_operand:SI 2 "memory_operand" "m"))
           (use (reg:SI R_CR))
           (clobber (reg:SI R_CR))])]
       ""
       "loadm 0,0,%1,%2")

   The constants that are defined with a define_constant are also output
in the insn-codes.h header file as #defines.


File: gccint.info,  Node: Target Macros,  Next: Host Config,  Prev: Machine Desc,  Up: Top

Target Description Macros and Functions
***************************************

   In addition to the file `MACHINE.md', a machine description includes
a C header file conventionally given the name `MACHINE.h' and a C
source file named `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 `.md' file.  The file `tm.h' should be a link to
`MACHINE.h'.  The header file `config.h' includes `tm.h' and most
compiler source files include `config.h'.  The source file defines a
variable `targetm', which is a structure containing pointers to
functions and data relating to the target machine.  `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 `.h'
file.

* Menu:

* Target Structure::    The `targetm' variable.
* Driver::              Controlling how the driver runs the compilation passes.
* Run-time Target::     Defining `-m' options like `-m68000' and `-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.
* Escape Sequences::    Defining the value of target character escape sequences
* Registers::           Naming and describing the hardware registers.
* Register Classes::    Defining the classes of hardware registers.
* Stack and Calling::   Defining which way the stack grows and by how much.
* Varargs::		Defining the varargs macros.
* Trampolines::         Code set up at run time to enter a nested function.
* Library Calls::       Controlling how library routines are implicitly called.
* Addressing Modes::    Defining addressing modes valid for memory operands.
* Condition Code::      Defining how insns update the condition code.
* Costs::               Defining relative costs of different operations.
* 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 `__attribute__'.
* MIPS Coprocessors::   MIPS coprocessor support and how to customize it.
* Misc::                Everything else.


File: gccint.info,  Node: Target Structure,  Next: Driver,  Up: Target Macros

The Global `targetm' Variable
=============================

 - Variable: struct gcc_target targetm
     The target `.c' file must define the global `targetm' variable
     which contains pointers to functions and data relating to the
     target machine.  The variable is declared in `target.h';
     `target-def.h' defines the macro `TARGET_INITIALIZER' which is
     used to initialize the variable, and macros for the default
     initializers for elements of the structure.  The `.c' file should
     override those macros for which the default definition is
     inappropriate.  For example:
          #include "target.h"
          #include "target-def.h"
          
          /* Initialize the GCC target structure.  */
          
          #undef TARGET_COMP_TYPE_ATTRIBUTES
          #define TARGET_COMP_TYPE_ATTRIBUTES MACHINE_comp_type_attributes
          
          struct gcc_target targetm = TARGET_INITIALIZER;

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


File: gccint.info,  Node: Driver,  Next: Run-time Target,  Prev: Target Structure,  Up: Target Macros

Controlling the Compilation Driver, `gcc'
=========================================

   You can control the compilation driver.

 - Macro: SWITCH_TAKES_ARG (CHAR)
     A C expression which determines whether the option `-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 `DEFAULT_SWITCH_TAKES_ARG',
     which handles the standard options properly.  You need not define
     `SWITCH_TAKES_ARG' unless you wish to add additional options which
     take arguments.  Any redefinition should call
     `DEFAULT_SWITCH_TAKES_ARG' and then check for additional options.

 - Macro: WORD_SWITCH_TAKES_ARG (NAME)
     A C expression which determines whether the option `-NAME' takes
     arguments.  The value should be the number of arguments that
     option takes-zero, for many options.  This macro rather than
     `SWITCH_TAKES_ARG' is used for multi-character option names.

     By default, this macro is defined as
     `DEFAULT_WORD_SWITCH_TAKES_ARG', which handles the standard options
     properly.  You need not define `WORD_SWITCH_TAKES_ARG' unless you
     wish to add additional options which take arguments.  Any
     redefinition should call `DEFAULT_WORD_SWITCH_TAKES_ARG' and then
     check for additional options.

 - Macro: SWITCH_CURTAILS_COMPILATION (CHAR)
     A C expression which determines whether the option `-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
     `DEFAULT_SWITCH_CURTAILS_COMPILATION', which handles the standard
     options properly.  You need not define
     `SWITCH_CURTAILS_COMPILATION' unless you wish to add additional
     options which affect the generation of an executable.  Any
     redefinition should call `DEFAULT_SWITCH_CURTAILS_COMPILATION' and
     then check for additional options.

 - Macro: 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 `""'.

 - Macro: TARGET_OPTION_TRANSLATE_TABLE
     If defined, a list of pairs of strings, the first of which is a
     potential command line target to the `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
     `--opt' style, they must be the `-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 `-malt-abi', `-EB', and `-mspoo' cause different
     multilibs to be chosen:

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

 - Macro: 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 `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 `%<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.

 - Macro: OPTION_DEFAULT_SPECS
     A list of specs used to support configure-time default options
     (i.e.  `--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 `config.gcc' for the target.  The second item is
     a spec to apply if a default with this name was specified.  The
     string `%(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 `specs' files and processing `DRIVER_SELF_SPECS',
     using the same mechanism as `DRIVER_SELF_SPECS'.

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

 - Macro: 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.

 - Macro: CPLUSPLUS_CPP_SPEC
     This macro is just like `CPP_SPEC', but is used for C++, rather
     than C.  If you do not define this macro, then the value of
     `CPP_SPEC' (if any) will be used instead.

 - Macro: CC1_SPEC
     A C string constant that tells the GCC driver program options to
     pass to `cc1', `cc1plus', `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.

 - Macro: CC1PLUS_SPEC
     A C string constant that tells the GCC driver program options to
     pass to `cc1plus'.  It can also specify how to translate options
     you give to GCC into options for GCC to pass to the `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 `cc1plus'
     so there is no need to duplicate the contents of CC1_SPEC in
     CC1PLUS_SPEC.

 - Macro: 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 `sun3.h' for an example of this.

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

 - Macro: 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 `mips.h' for an example of this.

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

 - Macro: 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, `-', 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 `-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 `%{pipe:%e}'
     construct; see `mips.h' for instance.

 - Macro: 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.

 - Macro: LIB_SPEC
     Another C string constant used much like `LINK_SPEC'.  The
     difference between the two is that `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 `gcc.c'.

 - Macro: LIBGCC_SPEC
     Another C string constant that tells the GCC driver program how
     and when to place a reference to `libgcc.a' into the linker
     command line.  This constant is placed both before and after the
     value of `LIB_SPEC'.

     If this macro is not defined, the GCC driver provides a default
     that passes the string `-lgcc' to the linker.

 - Macro: STARTFILE_SPEC
     Another C string constant used much like `LINK_SPEC'.  The
     difference between the two is that `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 `gcc.c'.

 - Macro: ENDFILE_SPEC
     Another C string constant used much like `LINK_SPEC'.  The
     difference between the two is that `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.

 - Macro: THREAD_MODEL_SPEC
     GCC `-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
     `THREAD_MODEL_SPEC' such that it evaluates to a string without
     blanks that names one of the recognized thread models.  `%*', the
     default value of this macro, will expand to the value of
     `thread_file' set in `config.gcc'.

 - Macro: 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.

 - Macro: 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 CPPc,ausing it to
     search for usr/include, et al, within sysroot+headers_suffix.

 - Macro: EXTRA_SPECS
     Define this macro to provide additional specifications to put in
     the `specs' file that can be used in various specifications like
     `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.

     `EXTRA_SPECS' is useful when an architecture contains several
     related targets, which have various `..._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 `EXTRA_SPECS' to
     define either `_CALL_SYSV' when the System V calling sequence is
     used or `_CALL_AIX' when the older AIX-based calling sequence is
     used.

     The `config/rs6000/rs6000.h' target file defines:

          #define EXTRA_SPECS \
            { "cpp_sysv_default", CPP_SYSV_DEFAULT },
          
          #define CPP_SYS_DEFAULT ""

     The `config/rs6000/sysv.h' target file defines:
          #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"

     while the `config/rs6000/eabiaix.h' target file defines
     `CPP_SYSV_DEFAULT' as:

          #undef CPP_SYSV_DEFAULT
          #define CPP_SYSV_DEFAULT "-D_CALL_AIX"

 - Macro: LINK_LIBGCC_SPECIAL
     Define this macro if the driver program should find the library
     `libgcc.a' itself and should not pass `-L' options to the linker.
     If you do not define this macro, the driver program will pass the
     argument `-lgcc' to tell the linker to do the search and will pass
     `-L' options to it.

 - Macro: LINK_LIBGCC_SPECIAL_1
     Define this macro if the driver program should find the library
     `libgcc.a'.  If you do not define this macro, the driver program
     will pass the argument `-lgcc' to tell the linker to do the search.
     This macro is similar to `LINK_LIBGCC_SPECIAL', except that it does
     not affect `-L' options.

 - Macro: LINK_GCC_C_SEQUENCE_SPEC
     The sequence in which libgcc and libc are specified to the linker.
     By default this is `%G %L %G'.

 - Macro: 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 `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
     `LINK_GCC_C_SEQUENCE_SPEC' instead.

 - Macro: LINK_ELIMINATE_DUPLICATE_LDIRECTORIES
     A nonzero value causes `collect2' to remove duplicate
     `-LDIRECTORY' search directories from linking commands.  Do not
     give it a nonzero value if removing duplicate search directories
     changes the linker's semantics.

 - Macro: 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 `MULTILIB_OPTIONS'.

     Do not define this macro if `MULTILIB_OPTIONS' is not defined in
     the target makefile fragment or if none of the options listed in
     `MULTILIB_OPTIONS' are set by default.  *Note Target Fragment::.

 - Macro: RELATIVE_PREFIX_NOT_LINKDIR
     Define this macro to tell `gcc' that it should only translate a
     `-B' prefix into a `-L' linker option if the prefix indicates an
     absolute file name.

 - Macro: MD_EXEC_PREFIX
     If defined, this macro is an additional prefix to try after
     `STANDARD_EXEC_PREFIX'.  `MD_EXEC_PREFIX' is not searched when the
     `-b' option is used, or the compiler is built as a cross compiler.
     If you define `MD_EXEC_PREFIX', then be sure to add it to the
     list of directories used to find the assembler in `configure.in'.

 - Macro: STANDARD_STARTFILE_PREFIX
     Define this macro as a C string constant if you wish to override
     the standard choice of `/usr/local/lib/' as the default prefix to
     try when searching for startup files such as `crt0.o'.

 - Macro: MD_STARTFILE_PREFIX
     If defined, this macro supplies an additional prefix to try after
     the standard prefixes.  `MD_EXEC_PREFIX' is not searched when the
     `-b' option is used, or when the compiler is built as a cross
     compiler.

 - Macro: MD_STARTFILE_PREFIX_1
     If defined, this macro supplies yet another prefix to try after the
     standard prefixes.  It is not searched when the `-b' option is
     used, or when the compiler is built as a cross compiler.

 - Macro: 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 `putenv' to initialize the necessary environment
     variables.

 - Macro: LOCAL_INCLUDE_DIR
     Define this macro as a C string constant if you wish to override
     the standard choice of `/usr/local/include' as the default prefix
     to try when searching for local header files.  `LOCAL_INCLUDE_DIR'
     comes before `SYSTEM_INCLUDE_DIR' in the search order.

     Cross compilers do not search either `/usr/local/include' or its
     replacement.

 - Macro: 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 `ADD' or
     `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 `64' at the end of the
     configuration name denotes a 64-bit target and you want the `-32'
     and `-64' switches to select between 32- and 64-bit targets, you
     would code

          #define MODIFY_TARGET_NAME \
            { { "-32", DELETE, "64"}, \
               {"-64", ADD, "64"}}

 - Macro: 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.  `SYSTEM_INCLUDE_DIR' comes before
     `STANDARD_INCLUDE_DIR' in the search order.

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

 - Macro: STANDARD_INCLUDE_DIR
     Define this macro as a C string constant if you wish to override
     the standard choice of `/usr/include' as the default prefix to try
     when searching for header files.

     Cross compilers ignore this macro and do not search either
     `/usr/include' or its replacement.

 - Macro: STANDARD_INCLUDE_COMPONENT
     The "component" corresponding to `STANDARD_INCLUDE_DIR'.  See
     `INCLUDE_DEFAULTS', below, for the description of components.  If
     you do not define this macro, no component is used.

 - Macro: 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 `GCC_INCLUDE_DIR',
     `LOCAL_INCLUDE_DIR', `SYSTEM_INCLUDE_DIR',
     `GPLUSPLUS_INCLUDE_DIR', and `STANDARD_INCLUDE_DIR'.  In addition,
     `GPLUSPLUS_INCLUDE_DIR' and `GCC_INCLUDE_DIR' are defined
     automatically by `Makefile', and specify private search areas for
     GCC.  The directory `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 `extern `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 `GCC' or `BINUTILS'.  If the package is part of a
     vendor-supplied operating system, code the component name as `0'.

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

          #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}                         \
          }

   Here is the order of prefixes tried for exec files:

  1. Any prefixes specified by the user with `-B'.

  2. The environment variable `GCC_EXEC_PREFIX', if any.

  3. The directories specified by the environment variable
     `COMPILER_PATH'.

  4. The macro `STANDARD_EXEC_PREFIX'.

  5. `/usr/lib/gcc/'.

  6. The macro `MD_EXEC_PREFIX', if any.

   Here is the order of prefixes tried for startfiles:

  1. Any prefixes specified by the user with `-B'.

  2. The environment variable `GCC_EXEC_PREFIX', if any.

  3. The directories specified by the environment variable
     `LIBRARY_PATH' (or port-specific name; native only, cross
     compilers do not use this).

  4. The macro `STANDARD_EXEC_PREFIX'.

  5. `/usr/lib/gcc/'.

  6. The macro `MD_EXEC_PREFIX', if any.

  7. The macro `MD_STARTFILE_PREFIX', if any.

  8. The macro `STANDARD_STARTFILE_PREFIX'.

  9. `/lib/'.

 10. `/usr/lib/'.


File: gccint.info,  Node: Run-time Target,  Next: Per-Function Data,  Prev: Driver,  Up: Target Macros

Run-time Target Specification
=============================

   Here are run-time target specifications.

 - Macro: 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 `builtin_define', `builtin_define_std' and
     `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.

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

     `builtin_define_std' takes a string representing the name of an
     object-like macro.  If it doesn't lie in the user's namespace,
     `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 `unix' defines `__unix', `__unix__' and possibly
     `unix'; passing `_mips' defines `__mips', `__mips__' and possibly
     `_mips', and passing `_ABI64' defines only `_ABI64'.

     You can also test for the C dialect being compiled.  The variable
     `c_language' is set to one of `clk_c', `clk_cplusplus' or
     `clk_objective_c'.  Note that if we are preprocessing assembler,
     this variable will be `clk_c' but the function-like macro
     `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 `flag_iso' can be used.  The function-like macro
     `preprocessing_trad_p()' can be used to check for traditional
     preprocessing.

 - Macro: TARGET_OS_CPP_BUILTINS ()
     Similarly to `TARGET_CPU_CPP_BUILTINS' but this macro is optional
     and is used for the target operating system instead.

 - Macro: TARGET_OBJFMT_CPP_BUILTINS ()
     Similarly to `TARGET_CPU_CPP_BUILTINS' but this macro is optional
     and is used for the target object format.  `elfos.h' uses this
     macro to define `__ELF__', so you probably do not need to define
     it yourself.

 - Variable: extern int target_flags
     This declaration should be present.

 - Macro: TARGET_FEATURENAME
     This series of macros is to allow compiler command arguments to
     enable or disable the use of optional features of the target
     machine.  For example, one machine description serves both the
     68000 and the 68020; a command argument tells the compiler whether
     it should use 68020-only instructions or not.  This command
     argument works by means of a macro `TARGET_68020' that tests a bit
     in `target_flags'.

     Define a macro `TARGET_FEATURENAME' for each such option.  Its
     definition should test a bit in `target_flags'.  It is recommended
     that a helper macro `MASK_FEATURENAME' is defined for each
     bit-value to test, and used in `TARGET_FEATURENAME' and
     `TARGET_SWITCHES'.  For example:

          #define TARGET_MASK_68020 1
          #define TARGET_68020 (target_flags & MASK_68020)

     One place where these macros are used is in the
     condition-expressions of instruction patterns.  Note how
     `TARGET_68020' appears frequently in the 68000 machine description
     file, `m68k.md'.  Another place they are used is in the
     definitions of the other macros in the `MACHINE.h' file.

 - Macro: TARGET_SWITCHES
     This macro defines names of command options to set and clear bits
     in `target_flags'.  Its definition is an initializer with a
     subgrouping for each command option.

     Each subgrouping contains a string constant, that defines the
     option name, a number, which contains the bits to set in
     `target_flags', and a second string which is the description
     displayed by `--help'.  If the number is negative then the bits
     specified by the number are cleared instead of being set.  If the
     description string is present but empty, then no help information
     will be displayed for that option, but it will not count as an
     undocumented option.  The actual option name is made by appending
     `-m' to the specified name.  Non-empty description strings should
     be marked with `N_(...)' for `xgettext'.  Please do not mark empty
     strings because the empty string is reserved by GNU gettext.
     `gettext("")' returns the header entry of the message catalog with
     meta information, not the empty string.

     In addition to the description for `--help', more detailed
     documentation for each option should be added to `invoke.texi'.

     One of the subgroupings should have a null string.  The number in
     this grouping is the default value for `target_flags'.  Any target
     options act starting with that value.

     Here is an example which defines `-m68000' and `-m68020' with
     opposite meanings, and picks the latter as the default:

          #define TARGET_SWITCHES \
            { { "68020", MASK_68020, "" },     \
              { "68000", -MASK_68020,          \
                N_("Compile for the 68000") }, \
              { "", MASK_68020, "" },          \
            }

 - Macro: TARGET_OPTIONS
     This macro is similar to `TARGET_SWITCHES' but defines names of
     command options that have values.  Its definition is an
     initializer with a subgrouping for each command option.

     Each subgrouping contains a string constant, that defines the
     option name, the address of a variable, a description string, and
     a value.  Non-empty description strings should be marked with
     `N_(...)' for `xgettext'.  Please do not mark empty strings
     because the empty string is reserved by GNU gettext. `gettext("")'
     returns the header entry of the message catalog with meta
     information, not the empty string.

     If the value listed in the table is `NULL', then the variable, type
     `char *', is set to the variable part of the given option if the
     fixed part matches.  In other words, if the first part of the
     option matches what's in the table, the variable will be set to
     point to the rest of the option.  This allows the user to specify
     a value for that option.  The actual option name is made by
     appending `-m' to the specified name.  Again, each option should
     also be documented in `invoke.texi'.

     If the value listed in the table is non-`NULL', then the option
     must match the option in the table exactly (with `-m'), and the
     variable is set to point to the value listed in the table.

     Here is an example which defines `-mshort-data-NUMBER'.  If the
     given option is `-mshort-data-512', the variable `m88k_short_data'
     will be set to the string `"512"'.

          extern char *m88k_short_data;
          #define TARGET_OPTIONS \
           { { "short-data-", &m88k_short_data, \
               N_("Specify the size of the short data section"), 0 } }

     Here is a variant of the above that allows the user to also specify
     just `-mshort-data' where a default of `"64"' is used.

          extern char *m88k_short_data;
          #define TARGET_OPTIONS \
           { { "short-data-", &m88k_short_data, \
               N_("Specify the size of the short data section"), 0 } \
              { "short-data", &m88k_short_data, "", "64" },
              }

     Here is an example which defines `-mno-alu', `-malu1', and
     `-malu2' as a three-state switch, along with suitable macros for
     checking the state of the option (documentation is elided for
     brevity).

          [chip.c]
          char *chip_alu = ""; /* Specify default here.  */
          
          [chip.h]
          extern char *chip_alu;
          #define TARGET_OPTIONS \
            { { "no-alu", &chip_alu, "", "" }, \
               { "alu1", &chip_alu, "", "1" }, \
               { "alu2", &chip_alu, "", "2" }, }
          #define TARGET_ALU (chip_alu[0] != '\0')
          #define TARGET_ALU1 (chip_alu[0] == '1')
          #define TARGET_ALU2 (chip_alu[0] == '2')

 - Macro: TARGET_VERSION
     This macro is a C statement to print on `stderr' a string
     describing the particular machine description choice.  Every
     machine description should define `TARGET_VERSION'.  For example:

          #ifdef MOTOROLA
          #define TARGET_VERSION \
            fprintf (stderr, " (68k, Motorola syntax)");
          #else
          #define TARGET_VERSION \
            fprintf (stderr, " (68k, MIT syntax)");
          #endif

 - Macro: OVERRIDE_OPTIONS
     Sometimes certain combinations of command options do not make
     sense on a particular target machine.  You can define a macro
     `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
     `-O'.  That is what `OPTIMIZATION_OPTIONS' is for.

 - Macro: OPTIMIZATION_OPTIONS (LEVEL, 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.

     LEVEL is the optimization level specified; 2 if `-O2' is
     specified, 1 if `-O' is specified, and 0 if neither is specified.

     SIZE is nonzero if `-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.

     *Do not examine `write_symbols' in this macro!* The debugging
     options are not supposed to alter the generated code.

 - Macro: 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
     `-fomit-frame-pointer' option whenever `-O' is specified.


File: gccint.info,  Node: Per-Function Data,  Next: Storage Layout,  Prev: Run-time Target,  Up: Target Macros

Defining data structures for per-function information.
======================================================

   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 `struct function' which contains
all of the data specific to an individual function.  This structure
contains a field called `machine' whose type is `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 `struct machine_function' and also the macro `INIT_EXPANDERS'.
This macro should be used to initialize the function pointer
`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 `__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
`save_machine_status' and `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.

 - Macro: 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 `init_machine_status'.

 - Variable: void (*)(struct function *) init_machine_status
     If this function pointer is non-`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
     `struct function' structure.  It is intended that this would be
     used to initialize the `machine' of that structure.

     `struct machine_function' structures are expected to be freed by
     GC.  Generally, any memory that they reference must be allocated
     by using `ggc_alloc', including the structure itself.

