This is Info file gcc.info, produced by Makeinfo version 1.68 from the
input file
/tantor/build/intel-xscale/xscale-010413/i686-pc-linux-gnulibc2.1/src/gcc/gcc.texi.

START-INFO-DIR-ENTRY
* Gcc: (gcc).                           Using and Porting the GNU C compiler.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gcc: (gcc).                  The GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the use and the internals of the GNU compiler.

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

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

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License" and "Funding
for Free Software" are included exactly as in the original, and
provided that the entire resulting derived work is distributed under
the terms of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License" and "Funding for Free Software", and this permission notice,
may be included in translations approved by the Free Software Foundation
instead of in the original English.


File: gcc.info,  Node: Tagging Insns,  Next: Attr Example,  Prev: Expressions,  Up: Insn Attributes

Assigning Attribute Values to Insns
-----------------------------------

   The value assigned to an attribute of an insn is primarily
determined by which pattern is matched by that insn (or which
`define_peephole' generated it).  Every `define_insn' and
`define_peephole' can have an optional last argument to specify the
values of attributes for matching insns.  The value of any attribute
not specified in a particular insn is set to the default value for that
attribute, as specified in its `define_attr'.  Extensive use of default
values for attributes permits the specification of the values for only
one or two attributes in the definition of most insn patterns, as seen
in the example in the next section.

   The optional last argument of `define_insn' and `define_peephole' is
a vector of expressions, each of which defines the value for a single
attribute.  The most general way of assigning an attribute's value is
to use a `set' expression whose first operand is an `attr' expression
giving the name of the attribute being set.  The second operand of the
`set' is an attribute expression (*note Expressions::.) giving the
value of the attribute.

   When the attribute value depends on the `alternative' attribute
(i.e., which is the applicable alternative in the constraint of the
insn), the `set_attr_alternative' expression can be used.  It allows
the specification of a vector of attribute expressions, one for each
alternative.

   When the generality of arbitrary attribute expressions is not
required, the simpler `set_attr' expression can be used, which allows
specifying a string giving either a single attribute value or a list of
attribute values, one for each alternative.

   The form of each of the above specifications is shown below.  In
each case, NAME is a string specifying the attribute to be set.

`(set_attr NAME VALUE-STRING)'
     VALUE-STRING is either a string giving the desired attribute value,
     or a string containing a comma-separated list giving the values for
     succeeding alternatives.  The number of elements must match the
     number of alternatives in the constraint of the insn pattern.

     Note that it may be useful to specify `*' for some alternative, in
     which case the attribute will assume its default value for insns
     matching that alternative.

`(set_attr_alternative NAME [VALUE1 VALUE2 ...])'
     Depending on the alternative of the insn, the value will be one of
     the specified values.  This is a shorthand for using a `cond' with
     tests on the `alternative' attribute.

`(set (attr NAME) VALUE)'
     The first operand of this `set' must be the special RTL expression
     `attr', whose sole operand is a string giving the name of the
     attribute being set.  VALUE is the value of the attribute.

   The following shows three different ways of representing the same
attribute value specification:

     (set_attr "type" "load,store,arith")
     
     (set_attr_alternative "type"
                           [(const_string "load") (const_string "store")
                            (const_string "arith")])
     
     (set (attr "type")
          (cond [(eq_attr "alternative" "1") (const_string "load")
                 (eq_attr "alternative" "2") (const_string "store")]
                (const_string "arith")))

   The `define_asm_attributes' expression provides a mechanism to
specify the attributes assigned to insns produced from an `asm'
statement.  It has the form:

     (define_asm_attributes [ATTR-SETS])

where ATTR-SETS is specified the same as for both the `define_insn' and
the `define_peephole' expressions.

   These values will typically be the "worst case" attribute values.
For example, they might indicate that the condition code will be
clobbered.

   A specification for a `length' attribute is handled specially.  The
way to compute the length of an `asm' insn is to multiply the length
specified in the expression `define_asm_attributes' by the number of
machine instructions specified in the `asm' statement, determined by
counting the number of semicolons and newlines in the string.
Therefore, the value of the `length' attribute specified in a
`define_asm_attributes' should be the maximum possible length of a
single machine instruction.


File: gcc.info,  Node: Attr Example,  Next: Insn Lengths,  Prev: Tagging Insns,  Up: Insn Attributes

Example of Attribute Specifications
-----------------------------------

   The judicious use of defaulting is important in the efficient use of
insn attributes.  Typically, insns are divided into "types" and an
attribute, customarily called `type', is used to represent this value.
This attribute is normally used only to define the default value for
other attributes.  An example will clarify this usage.

   Assume we have a RISC machine with a condition code and in which only
full-word operations are performed in registers.  Let us assume that we
can divide all insns into loads, stores, (integer) arithmetic
operations, floating point operations, and branches.

   Here we will concern ourselves with determining the effect of an
insn on the condition code and will limit ourselves to the following
possible effects:  The condition code can be set unpredictably
(clobbered), not be changed, be set to agree with the results of the
operation, or only changed if the item previously set into the
condition code has been modified.

   Here is part of a sample `md' file for such a machine:

     (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
     
     (define_attr "cc" "clobber,unchanged,set,change0"
                  (cond [(eq_attr "type" "load")
                             (const_string "change0")
                         (eq_attr "type" "store,branch")
                             (const_string "unchanged")
                         (eq_attr "type" "arith")
                             (if_then_else (match_operand:SI 0 "" "")
                                           (const_string "set")
                                           (const_string "clobber"))]
                        (const_string "clobber")))
     
     (define_insn ""
       [(set (match_operand:SI 0 "general_operand" "=r,r,m")
             (match_operand:SI 1 "general_operand" "r,m,r"))]
       ""
       "@
        move %0,%1
        load %0,%1
        store %0,%1"
       [(set_attr "type" "arith,load,store")])

   Note that we assume in the above example that arithmetic operations
performed on quantities smaller than a machine word clobber the
condition code since they will set the condition code to a value
corresponding to the full-word result.


File: gcc.info,  Node: Insn Lengths,  Next: Constant Attributes,  Prev: Attr Example,  Up: Insn Attributes

Computing the Length of an Insn
-------------------------------

   For many machines, multiple types of branch instructions are
provided, each for different length branch displacements.  In most
cases, the assembler will choose the correct instruction to use.
However, when the assembler cannot do so, GCC can when a special
attribute, the `length' attribute, is defined.  This attribute must be
defined to have numeric values by specifying a null string in its
`define_attr'.

   In the case of the `length' attribute, two additional forms of
arithmetic terms are allowed in test expressions:

`(match_dup N)'
     This refers to the address of operand N of the current insn, which
     must be a `label_ref'.

`(pc)'
     This refers to the address of the *current* insn.  It might have
     been more consistent with other usage to make this the address of
     the *next* insn but this would be confusing because the length of
     the current insn is to be computed.

   For normal insns, the length will be determined by value of the
`length' attribute.  In the case of `addr_vec' and `addr_diff_vec' insn
patterns, the length is computed as the number of vectors multiplied by
the size of each vector.

   Lengths are measured in addressable storage units (bytes).

   The following macros can be used to refine the length computation:

`FIRST_INSN_ADDRESS'
     When the `length' insn attribute is used, this macro specifies the
     value to be assigned to the address of the first insn in a
     function.  If not specified, 0 is used.

`ADJUST_INSN_LENGTH (INSN, LENGTH)'
     If defined, modifies the length assigned to instruction INSN as a
     function of the context in which it is used.  LENGTH is an lvalue
     that contains the initially computed length of the insn and should
     be updated with the correct length of the insn.

     This macro will normally not be required.  A case in which it is
     required is the ROMP.  On this machine, the size of an `addr_vec'
     insn must be increased by two to compensate for the fact that
     alignment may be required.

   The routine that returns `get_attr_length' (the value of the
`length' attribute) can be used by the output routine to determine the
form of the branch instruction to be written, as the example below
illustrates.

   As an example of the specification of variable-length branches,
consider the IBM 360.  If we adopt the convention that a register will
be set to the starting address of a function, we can jump to labels
within 4k of the start using a four-byte instruction.  Otherwise, we
need a six-byte sequence to load the address from memory and then
branch to it.

   On such a machine, a pattern for a branch instruction might be
specified as follows:

     (define_insn "jump"
       [(set (pc)
             (label_ref (match_operand 0 "" "")))]
       ""
       "*
     {
        return (get_attr_length (insn) == 4
                ? \"b %l0\" : \"l r15,=a(%l0); br r15\");
     }"
       [(set (attr "length") (if_then_else (lt (match_dup 0) (const_int 4096))
                                           (const_int 4)
                                           (const_int 6)))])


File: gcc.info,  Node: Constant Attributes,  Next: Delay Slots,  Prev: Insn Lengths,  Up: Insn Attributes

Constant Attributes
-------------------

   A special form of `define_attr', where the expression for the
default value is a `const' expression, indicates an attribute that is
constant for a given run of the compiler.  Constant attributes may be
used to specify which variety of processor is used.  For example,

     (define_attr "cpu" "m88100,m88110,m88000"
      (const
       (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
              (symbol_ref "TARGET_88110") (const_string "m88110")]
             (const_string "m88000"))))
     
     (define_attr "memory" "fast,slow"
      (const
       (if_then_else (symbol_ref "TARGET_FAST_MEM")
                     (const_string "fast")
                     (const_string "slow"))))

   The routine generated for constant attributes has no parameters as it
does not depend on any particular insn.  RTL expressions used to define
the value of a constant attribute may use the `symbol_ref' form, but
may not use either the `match_operand' form or `eq_attr' forms
involving insn attributes.


File: gcc.info,  Node: Delay Slots,  Next: Function Units,  Prev: Constant Attributes,  Up: Insn Attributes

Delay Slot Scheduling
---------------------

   The insn attribute mechanism can be used to specify the requirements
for delay slots, if any, on a target machine.  An instruction is said to
require a "delay slot" if some instructions that are physically after
the instruction are executed as if they were located before it.
Classic examples are branch and call instructions, which often execute
the following instruction before the branch or call is performed.

   On some machines, conditional branch instructions can optionally
"annul" instructions in the delay slot.  This means that the
instruction will not be executed for certain branch outcomes.  Both
instructions that annul if the branch is true and instructions that
annul if the branch is false are supported.

   Delay slot scheduling differs from instruction scheduling in that
determining whether an instruction needs a delay slot is dependent only
on the type of instruction being generated, not on data flow between the
instructions.  See the next section for a discussion of data-dependent
instruction scheduling.

   The requirement of an insn needing one or more delay slots is
indicated via the `define_delay' expression.  It has the following form:

     (define_delay TEST
                   [DELAY-1 ANNUL-TRUE-1 ANNUL-FALSE-1
                    DELAY-2 ANNUL-TRUE-2 ANNUL-FALSE-2
                    ...])

   TEST is an attribute test that indicates whether this `define_delay'
applies to a particular insn.  If so, the number of required delay
slots is determined by the length of the vector specified as the second
argument.  An insn placed in delay slot N must satisfy attribute test
DELAY-N.  ANNUL-TRUE-N is an attribute test that specifies which insns
may be annulled if the branch is true.  Similarly, ANNUL-FALSE-N
specifies which insns in the delay slot may be annulled if the branch
is false.  If annulling is not supported for that delay slot, `(nil)'
should be coded.

   For example, in the common case where branch and call insns require
a single delay slot, which may contain any insn other than a branch or
call, the following would be placed in the `md' file:

     (define_delay (eq_attr "type" "branch,call")
                   [(eq_attr "type" "!branch,call") (nil) (nil)])

   Multiple `define_delay' expressions may be specified.  In this case,
each such expression specifies different delay slot requirements and
there must be no insn for which tests in two `define_delay' expressions
are both true.

   For example, if we have a machine that requires one delay slot for
branches but two for calls,  no delay slot can contain a branch or call
insn, and any valid insn in the delay slot for the branch can be
annulled if the branch is true, we might represent this as follows:

     (define_delay (eq_attr "type" "branch")
        [(eq_attr "type" "!branch,call")
         (eq_attr "type" "!branch,call")
         (nil)])
     
     (define_delay (eq_attr "type" "call")
                   [(eq_attr "type" "!branch,call") (nil) (nil)
                    (eq_attr "type" "!branch,call") (nil) (nil)])


File: gcc.info,  Node: Function Units,  Prev: Delay Slots,  Up: Insn Attributes

Specifying Function Units
-------------------------

   On most RISC machines, there are instructions whose results are not
available for a specific number of cycles.  Common cases are
instructions that load data from memory.  On many machines, a pipeline
stall will result if the data is referenced too soon after the load
instruction.

   In addition, many newer microprocessors have multiple function
units, usually one for integer and one for floating point, and often
will incur pipeline stalls when a result that is needed is not yet
ready.

   The descriptions in this section allow the specification of how much
time must elapse between the execution of an instruction and the time
when its result is used.  It also allows specification of when the
execution of an instruction will delay execution of similar instructions
due to function unit conflicts.

   For the purposes of the specifications in this section, a machine is
divided into "function units", each of which execute a specific class
of instructions in first-in-first-out order.  Function units that
accept one instruction each cycle and allow a result to be used in the
succeeding instruction (usually via forwarding) need not be specified.
Classic RISC microprocessors will normally have a single function unit,
which we can call `memory'.  The newer "superscalar" processors will
often have function units for floating point operations, usually at
least a floating point adder and multiplier.

   Each usage of a function units by a class of insns is specified with
a `define_function_unit' expression, which looks like this:

     (define_function_unit NAME MULTIPLICITY SIMULTANEITY
                           TEST READY-DELAY ISSUE-DELAY
                          [CONFLICT-LIST])

   NAME is a string giving the name of the function unit.

   MULTIPLICITY is an integer specifying the number of identical units
in the processor.  If more than one unit is specified, they will be
scheduled independently.  Only truly independent units should be
counted; a pipelined unit should be specified as a single unit.  (The
only common example of a machine that has multiple function units for a
single instruction class that are truly independent and not pipelined
are the two multiply and two increment units of the CDC 6600.)

   SIMULTANEITY specifies the maximum number of insns that can be
executing in each instance of the function unit simultaneously or zero
if the unit is pipelined and has no limit.

   All `define_function_unit' definitions referring to function unit
NAME must have the same name and values for MULTIPLICITY and
SIMULTANEITY.

   TEST is an attribute test that selects the insns we are describing
in this definition.  Note that an insn may use more than one function
unit and a function unit may be specified in more than one
`define_function_unit'.

   READY-DELAY is an integer that specifies the number of cycles after
which the result of the instruction can be used without introducing any
stalls.

   ISSUE-DELAY is an integer that specifies the number of cycles after
the instruction matching the TEST expression begins using this unit
until a subsequent instruction can begin.  A cost of N indicates an N-1
cycle delay.  A subsequent instruction may also be delayed if an
earlier instruction has a longer READY-DELAY value.  This blocking
effect is computed using the SIMULTANEITY, READY-DELAY, ISSUE-DELAY,
and CONFLICT-LIST terms.  For a normal non-pipelined function unit,
SIMULTANEITY is one, the unit is taken to block for the READY-DELAY
cycles of the executing insn, and smaller values of ISSUE-DELAY are
ignored.

   CONFLICT-LIST is an optional list giving detailed conflict costs for
this unit.  If specified, it is a list of condition test expressions to
be applied to insns chosen to execute in NAME following the particular
insn matching TEST that is already executing in NAME.  For each insn in
the list, ISSUE-DELAY specifies the conflict cost; for insns not in the
list, the cost is zero.  If not specified, CONFLICT-LIST defaults to
all instructions that use the function unit.

   Typical uses of this vector are where a floating point function unit
can pipeline either single- or double-precision operations, but not
both, or where a memory unit can pipeline loads, but not stores, etc.

   As an example, consider a classic RISC machine where the result of a
load instruction is not available for two cycles (a single "delay"
instruction is required) and where only one load instruction can be
executed simultaneously.  This would be specified as:

     (define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 0)

   For the case of a floating point function unit that can pipeline
either single or double precision, but not both, the following could be
specified:

     (define_function_unit
        "fp" 1 0 (eq_attr "type" "sp_fp") 4 4 [(eq_attr "type" "dp_fp")])
     (define_function_unit
        "fp" 1 0 (eq_attr "type" "dp_fp") 4 4 [(eq_attr "type" "sp_fp")])

   *Note:* The scheduler attempts to avoid function unit conflicts and
uses all the specifications in the `define_function_unit' expression.
It has recently come to our attention that these specifications may not
allow modeling of some of the newer "superscalar" processors that have
insns using multiple pipelined units.  These insns will cause a
potential conflict for the second unit used during their execution and
there is no way of representing that conflict.  We welcome any examples
of how function unit conflicts work in such processors and suggestions
for their representation.


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

Target Description Macros
*************************

   In addition to the file `MACHINE.md', a machine description includes
a C header file conventionally given the name `MACHINE.h'.  This 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'.

* Menu:

* Driver::              Controlling how the driver runs the compilation passes.
* Run-time Target::     Defining `-m' options like `-m68000' and `-m68020'.
* 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.
* 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.
* 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.
* Cross-compilation::   Handling floating point for cross-compilers.
* Misc::                Everything else.


File: gcc.info,  Node: Driver,  Next: Run-time Target,  Up: Target Macros

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

   You can control the compilation driver.

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

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

`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, non-zero 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.

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

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

`NO_BUILTIN_SIZE_TYPE'
     If this macro is defined, the preprocessor will not define the
     builtin macro `__SIZE_TYPE__'.  The macro `__SIZE_TYPE__' must
     then be defined by `CPP_SPEC' instead.

     This should be defined if `SIZE_TYPE' depends on target dependent
     flags which are not accessible to the preprocessor.  Otherwise, it
     should not be defined.

`NO_BUILTIN_PTRDIFF_TYPE'
     If this macro is defined, the preprocessor will not define the
     builtin macro `__PTRDIFF_TYPE__'.  The macro `__PTRDIFF_TYPE__'
     must then be defined by `CPP_SPEC' instead.

     This should be defined if `PTRDIFF_TYPE' depends on target
     dependent flags which are not accessible to the preprocessor.
     Otherwise, it should not be defined.

`NO_BUILTIN_WCHAR_TYPE'
     If this macro is defined, the preprocessor will not define the
     builtin macro `__WCHAR_TYPE__'.  The macro `__WCHAR_TYPE__' must
     then be defined by `CPP_SPEC' instead.

     This should be defined if `WCHAR_TYPE' depends on target dependent
     flags which are not accessible to the preprocessor.  Otherwise, it
     should not be defined.

`SIGNED_CHAR_SPEC'
     A C string constant that tells the GCC driver program options to
     pass to CPP.  By default, this macro is defined to pass the option
     `-D__CHAR_UNSIGNED__' to CPP if `char' will be treated as
     `unsigned char' by `cc1'.

     Do not define this macro unless you need to override the default
     definition.

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

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

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

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

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

`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'.

`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 unless the `-shared'
     option is specified.

`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'.

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

`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-aix: -D_CALL_AIX } \
          %{!mcall-sysv: %{!mcall-aix: %(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"

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

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

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

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

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

`STANDARD_EXEC_PREFIX'
     Define this macro as a C string constant if you wish to override
     the standard choice of `/usr/local/lib/gcc-lib/' as the default
     prefix to try when searching for the executable files of the
     compiler.

`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'.

`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'.

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

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

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

`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 use this macro and do not search either
     `/usr/local/include' or its replacement.

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

`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 do not use this macro and do not search either
     `/usr/include' or its replacement.

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

`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, and 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 upper-case letters.  For example, it might
     be `GCC' or `BINUTILS'.  If the package is part of the 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' (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: gcc.info,  Node: Run-time Target,  Next: Storage Layout,  Prev: Driver,  Up: Target Macros

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

   Here are run-time target specifications.

`CPP_PREDEFINES'
     Define this to be a string constant containing `-D' options to
     define the predefined macros that identify this machine and system.
     These macros will be predefined unless the `-ansi' option is
     specified.

     In addition, a parallel set of macros are predefined, whose names
     are made by appending `__' at the beginning and at the end.  These
     `__' macros are permitted by the ANSI standard, so they are
     predefined regardless of whether `-ansi' is specified.

     For example, on the Sun, one can use the following value:

          "-Dmc68000 -Dsun -Dunix"

     The result is to define the macros `__mc68000__', `__sun__' and
     `__unix__' unconditionally, and the macros `mc68000', `sun' and
     `unix' provided `-ansi' is not specified.

`extern int target_flags;'
     This declaration should be present.

`TARGET_...'
     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'; for example:

          #define TARGET_68020 (target_flags & 1)

     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.

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

     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", 1, "" },      \
              { "68000", -1, "Compile for the 68000" }, \
              { "", 1, "" }}

`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
     fixed part of the option name, the address of a variable, and a
     description string.  The variable, type `char *', is set to the
     variable part of the given option if the fixed part matches.  The
     actual option name is made by appending `-m' to the specified name.

     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, "Specify the size of the short data section" } }

`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

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

`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 non-zero 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.

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

