-This is doc/gccint.info, produced by makeinfo version 4.5 from
+This is doc/gccint.info, produced by makeinfo version 4.11 from
doc/gccint.texi.
INFO-DIR-SECTION Programming
funds for GNU development.
\1f
-File: gccint.info, Node: Types, Next: Scopes, Prev: Tree overview, Up: Trees
-
-Types
-=====
-
- All types have corresponding tree nodes. However, you should not
-assume that there is exactly one tree node corresponding to each type.
-There are often several nodes each of which correspond to the same type.
-
- For the most part, different kinds of types have different tree
-codes. (For example, pointer types use a `POINTER_TYPE' code while
-arrays use an `ARRAY_TYPE' code.) However, pointers to member functions
-use the `RECORD_TYPE' code. Therefore, when writing a `switch'
-statement that depends on the code associated with a particular type,
-you should take care to handle pointers to member functions under the
-`RECORD_TYPE' case label.
-
- In C++, an array type is not qualified; rather the type of the array
-elements is qualified. This situation is reflected in the intermediate
-representation. The macros described here will always examine the
-qualification of the underlying element type when applied to an array
-type. (If the element type is itself an array, then the recursion
-continues until a non-array type is found, and the qualification of this
-type is examined.) So, for example, `CP_TYPE_CONST_P' will hold of the
-type `const int ()[7]', denoting an array of seven `int's.
-
- The following functions and macros deal with cv-qualification of
-types:
-`CP_TYPE_QUALS'
- This macro returns the set of type qualifiers applied to this type.
- This value is `TYPE_UNQUALIFIED' if no qualifiers have been
- applied. The `TYPE_QUAL_CONST' bit is set if the type is
- `const'-qualified. The `TYPE_QUAL_VOLATILE' bit is set if the
- type is `volatile'-qualified. The `TYPE_QUAL_RESTRICT' bit is set
- if the type is `restrict'-qualified.
-
-`CP_TYPE_CONST_P'
- This macro holds if the type is `const'-qualified.
-
-`CP_TYPE_VOLATILE_P'
- This macro holds if the type is `volatile'-qualified.
-
-`CP_TYPE_RESTRICT_P'
- This macro holds if the type is `restrict'-qualified.
-
-`CP_TYPE_CONST_NON_VOLATILE_P'
- This predicate holds for a type that is `const'-qualified, but
- _not_ `volatile'-qualified; other cv-qualifiers are ignored as
- well: only the `const'-ness is tested.
-
-`TYPE_MAIN_VARIANT'
- This macro returns the unqualified version of a type. It may be
- applied to an unqualified type, but it is not always the identity
- function in that case.
-
- A few other macros and functions are usable with all types:
-`TYPE_SIZE'
- The number of bits required to represent the type, represented as
- an `INTEGER_CST'. For an incomplete type, `TYPE_SIZE' will be
- `NULL_TREE'.
-
-`TYPE_ALIGN'
- The alignment of the type, in bits, represented as an `int'.
-
-`TYPE_NAME'
- This macro returns a declaration (in the form of a `TYPE_DECL') for
- the type. (Note this macro does _not_ return a `IDENTIFIER_NODE',
- as you might expect, given its name!) You can look at the
- `DECL_NAME' of the `TYPE_DECL' to obtain the actual name of the
- type. The `TYPE_NAME' will be `NULL_TREE' for a type that is not
- a built-in type, the result of a typedef, or a named class type.
-
-`CP_INTEGRAL_TYPE'
- This predicate holds if the type is an integral type. Notice that
- in C++, enumerations are _not_ integral types.
-
-`ARITHMETIC_TYPE_P'
- This predicate holds if the type is an integral type (in the C++
- sense) or a floating point type.
-
-`CLASS_TYPE_P'
- This predicate holds for a class-type.
-
-`TYPE_BUILT_IN'
- This predicate holds for a built-in type.
-
-`TYPE_PTRMEM_P'
- This predicate holds if the type is a pointer to data member.
-
-`TYPE_PTR_P'
- This predicate holds if the type is a pointer type, and the
- pointee is not a data member.
-
-`TYPE_PTRFN_P'
- This predicate holds for a pointer to function type.
-
-`TYPE_PTROB_P'
- This predicate holds for a pointer to object type. Note however
- that it does not hold for the generic pointer to object type `void
- *'. You may use `TYPE_PTROBV_P' to test for a pointer to object
- type as well as `void *'.
-
-`same_type_p'
- This predicate takes two types as input, and holds if they are the
- same type. For example, if one type is a `typedef' for the other,
- or both are `typedef's for the same type. This predicate also
- holds if the two trees given as input are simply copies of one
- another; i.e., there is no difference between them at the source
- level, but, for whatever reason, a duplicate has been made in the
- representation. You should never use `==' (pointer equality) to
- compare types; always use `same_type_p' instead.
-
- Detailed below are the various kinds of types, and the macros that
-can be used to access them. Although other kinds of types are used
-elsewhere in G++, the types described here are the only ones that you
-will encounter while examining the intermediate representation.
-
-`VOID_TYPE'
- Used to represent the `void' type.
-
-`INTEGER_TYPE'
- Used to represent the various integral types, including `char',
- `short', `int', `long', and `long long'. This code is not used
- for enumeration types, nor for the `bool' type. Note that GCC's
- `CHAR_TYPE' node is _not_ used to represent `char'. The
- `TYPE_PRECISION' is the number of bits used in the representation,
- represented as an `unsigned int'. (Note that in the general case
- this is not the same value as `TYPE_SIZE'; suppose that there were
- a 24-bit integer type, but that alignment requirements for the ABI
- required 32-bit alignment. Then, `TYPE_SIZE' would be an
- `INTEGER_CST' for 32, while `TYPE_PRECISION' would be 24.) The
- integer type is unsigned if `TREE_UNSIGNED' holds; otherwise, it
- is signed.
-
- The `TYPE_MIN_VALUE' is an `INTEGER_CST' for the smallest integer
- that may be represented by this type. Similarly, the
- `TYPE_MAX_VALUE' is an `INTEGER_CST' for the largest integer that
- may be represented by this type.
-
-`REAL_TYPE'
- Used to represent the `float', `double', and `long double' types.
- The number of bits in the floating-point representation is given
- by `TYPE_PRECISION', as in the `INTEGER_TYPE' case.
-
-`COMPLEX_TYPE'
- Used to represent GCC built-in `__complex__' data types. The
- `TREE_TYPE' is the type of the real and imaginary parts.
-
-`ENUMERAL_TYPE'
- Used to represent an enumeration type. The `TYPE_PRECISION' gives
- (as an `int'), the number of bits used to represent the type. If
- there are no negative enumeration constants, `TREE_UNSIGNED' will
- hold. The minimum and maximum enumeration constants may be
- obtained with `TYPE_MIN_VALUE' and `TYPE_MAX_VALUE', respectively;
- each of these macros returns an `INTEGER_CST'.
-
- The actual enumeration constants themselves may be obtained by
- looking at the `TYPE_VALUES'. This macro will return a
- `TREE_LIST', containing the constants. The `TREE_PURPOSE' of each
- node will be an `IDENTIFIER_NODE' giving the name of the constant;
- the `TREE_VALUE' will be an `INTEGER_CST' giving the value
- assigned to that constant. These constants will appear in the
- order in which they were declared. The `TREE_TYPE' of each of
- these constants will be the type of enumeration type itself.
-
-`BOOLEAN_TYPE'
- Used to represent the `bool' type.
-
-`POINTER_TYPE'
- Used to represent pointer types, and pointer to data member types.
- The `TREE_TYPE' gives the type to which this type points. If the
- type is a pointer to data member type, then `TYPE_PTRMEM_P' will
- hold. For a pointer to data member type of the form `T X::*',
- `TYPE_PTRMEM_CLASS_TYPE' will be the type `X', while
- `TYPE_PTRMEM_POINTED_TO_TYPE' will be the type `T'.
-
-`REFERENCE_TYPE'
- Used to represent reference types. The `TREE_TYPE' gives the type
- to which this type refers.
-
-`FUNCTION_TYPE'
- Used to represent the type of non-member functions and of static
- member functions. The `TREE_TYPE' gives the return type of the
- function. The `TYPE_ARG_TYPES' are a `TREE_LIST' of the argument
- types. The `TREE_VALUE' of each node in this list is the type of
- the corresponding argument; the `TREE_PURPOSE' is an expression
- for the default argument value, if any. If the last node in the
- list is `void_list_node' (a `TREE_LIST' node whose `TREE_VALUE' is
- the `void_type_node'), then functions of this type do not take
- variable arguments. Otherwise, they do take a variable number of
- arguments.
-
- Note that in C (but not in C++) a function declared like `void f()'
- is an unprototyped function taking a variable number of arguments;
- the `TYPE_ARG_TYPES' of such a function will be `NULL'.
-
-`METHOD_TYPE'
- Used to represent the type of a non-static member function. Like a
- `FUNCTION_TYPE', the return type is given by the `TREE_TYPE'. The
- type of `*this', i.e., the class of which functions of this type
- are a member, is given by the `TYPE_METHOD_BASETYPE'. The
- `TYPE_ARG_TYPES' is the parameter list, as for a `FUNCTION_TYPE',
- and includes the `this' argument.
-
-`ARRAY_TYPE'
- Used to represent array types. The `TREE_TYPE' gives the type of
- the elements in the array. If the array-bound is present in the
- type, the `TYPE_DOMAIN' is an `INTEGER_TYPE' whose
- `TYPE_MIN_VALUE' and `TYPE_MAX_VALUE' will be the lower and upper
- bounds of the array, respectively. The `TYPE_MIN_VALUE' will
- always be an `INTEGER_CST' for zero, while the `TYPE_MAX_VALUE'
- will be one less than the number of elements in the array, i.e.,
- the highest value which may be used to index an element in the
- array.
-
-`RECORD_TYPE'
- Used to represent `struct' and `class' types, as well as pointers
- to member functions and similar constructs in other languages.
- `TYPE_FIELDS' contains the items contained in this type, each of
- which can be a `FIELD_DECL', `VAR_DECL', `CONST_DECL', or
- `TYPE_DECL'. You may not make any assumptions about the ordering
- of the fields in the type or whether one or more of them overlap.
- If `TYPE_PTRMEMFUNC_P' holds, then this type is a pointer-to-member
- type. In that case, the `TYPE_PTRMEMFUNC_FN_TYPE' is a
- `POINTER_TYPE' pointing to a `METHOD_TYPE'. The `METHOD_TYPE' is
- the type of a function pointed to by the pointer-to-member
- function. If `TYPE_PTRMEMFUNC_P' does not hold, this type is a
- class type. For more information, see *note Classes::.
-
-`UNION_TYPE'
- Used to represent `union' types. Similar to `RECORD_TYPE' except
- that all `FIELD_DECL' nodes in `TYPE_FIELD' start at bit position
+File: gccint.info, Node: Exception Handling, Next: Stack Checking, Prev: Frame Layout, Up: Stack and Calling
+
+10.10.2 Exception Handling Support
+----------------------------------
+
+`EH_RETURN_DATA_REGNO (N)'
+ A C expression whose value is the Nth register number used for
+ data by exception handlers, or `INVALID_REGNUM' if fewer than N
+ registers are usable.
+
+ The exception handling library routines communicate with the
+ exception handlers via a set of agreed upon registers. Ideally
+ these registers should be call-clobbered; it is possible to use
+ call-saved registers, but may negatively impact code size. The
+ target must support at least 2 data registers, but should define 4
+ if there are enough free registers.
+
+ You must define this macro if you want to support call frame
+ exception handling like that provided by DWARF 2.
+
+`EH_RETURN_STACKADJ_RTX'
+ A C expression whose value is RTL representing a location in which
+ to store a stack adjustment to be applied before function return.
+ This is used to unwind the stack to an exception handler's call
+ frame. It will be assigned zero on code paths that return
+ normally.
+
+ Typically this is a call-clobbered hard register that is otherwise
+ untouched by the epilogue, but could also be a stack slot.
+
+ You must define this macro if you want to support call frame
+ exception handling like that provided by DWARF 2.
+
+`EH_RETURN_HANDLER_RTX'
+ A C expression whose value is RTL representing a location in which
+ to store the address of an exception handler to which we should
+ return. It will not be assigned on code paths that return
+ normally.
+
+ Typically this is the location in the call frame at which the
+ normal return address is stored. For targets that return by
+ popping an address off the stack, this might be a memory address
+ just below the _target_ call frame rather than inside the current
+ call frame. `EH_RETURN_STACKADJ_RTX' will have already been
+ assigned, so it may be used to calculate the location of the
+ target call frame.
+
+ Some targets have more complex requirements than storing to an
+ address calculable during initial code generation. In that case
+ the `eh_return' instruction pattern should be used instead.
+
+ If you want to support call frame exception handling, you must
+ define either this macro or the `eh_return' instruction pattern.
+
+`ASM_PREFERRED_EH_DATA_FORMAT(CODE, GLOBAL)'
+ This macro chooses the encoding of pointers embedded in the
+ exception handling sections. If at all possible, this should be
+ defined such that the exception handling section will not require
+ dynamic relocations, and so may be read-only.
+
+ CODE is 0 for data, 1 for code labels, 2 for function pointers.
+ GLOBAL is true if the symbol may be affected by dynamic
+ relocations. The macro should return a combination of the
+ `DW_EH_PE_*' defines as found in `dwarf2.h'.
+
+ If this macro is not defined, pointers will not be encoded but
+ represented directly.
+
+`ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(FILE, ENCODING, SIZE, ADDR, DONE)'
+ This macro allows the target to emit whatever special magic is
+ required to represent the encoding chosen by
+ `ASM_PREFERRED_EH_DATA_FORMAT'. Generic code takes care of
+ pc-relative and indirect encodings; this must be defined if the
+ target uses text-relative or data-relative encodings.
+
+ This is a C statement that branches to DONE if the format was
+ handled. ENCODING is the format chosen, SIZE is the number of
+ bytes that the format occupies, ADDR is the `SYMBOL_REF' to be
+ emitted.
+
+`MD_FALLBACK_FRAME_STATE_FOR(CONTEXT, FS, SUCCESS)'
+ This macro allows the target to add cpu and operating system
+ specific code to the call-frame unwinder for use when there is no
+ unwind data available. The most common reason to implement this
+ macro is to unwind through signal frames.
+
+ This macro is called from `uw_frame_state_for' in `unwind-dw2.c'
+ and `unwind-ia64.c'. CONTEXT is an `_Unwind_Context'; FS is an
+ `_Unwind_FrameState'. Examine `context->ra' for the address of
+ the code being executed and `context->cfa' for the stack pointer
+ value. If the frame can be decoded, the register save addresses
+ should be updated in FS and the macro should branch to SUCCESS.
+ If the frame cannot be decoded, the macro should do nothing.
+
+\1f
+File: gccint.info, Node: Stack Checking, Next: Frame Registers, Prev: Exception Handling, Up: Stack and Calling
+
+10.10.3 Specifying How Stack Checking is Done
+---------------------------------------------
+
+GCC will check that stack references are within the boundaries of the
+stack, if the `-fstack-check' is specified, in one of three ways:
+
+ 1. If the value of the `STACK_CHECK_BUILTIN' macro is nonzero, GCC
+ will assume that you have arranged for stack checking to be done at
+ appropriate places in the configuration files, e.g., in
+ `TARGET_ASM_FUNCTION_PROLOGUE'. GCC will do not other special
+ processing.
+
+ 2. If `STACK_CHECK_BUILTIN' is zero and you defined a named pattern
+ called `check_stack' in your `md' file, GCC will call that pattern
+ with one argument which is the address to compare the stack value
+ against. You must arrange for this pattern to report an error if
+ the stack pointer is out of range.
+
+ 3. If neither of the above are true, GCC will generate code to
+ periodically "probe" the stack pointer using the values of the
+ macros defined below.
+
+ Normally, you will use the default values of these macros, so GCC
+will use the third approach.
+
+`STACK_CHECK_BUILTIN'
+ A nonzero value if stack checking is done by the configuration
+ files in a machine-dependent manner. You should define this macro
+ if stack checking is require by the ABI of your machine or if you
+ would like to have to stack checking in some more efficient way
+ than GCC's portable approach. The default value of this macro is
zero.
-`QUAL_UNION_TYPE'
- Used to represent part of a variant record in Ada. Similar to
- `UNION_TYPE' except that each `FIELD_DECL' has a `DECL_QUALIFIER'
- field, which contains a boolean expression that indicates whether
- the field is present in the object. The type will only have one
- field, so each field's `DECL_QUALIFIER' is only evaluated if none
- of the expressions in the previous fields in `TYPE_FIELDS' are
- nonzero. Normally these expressions will reference a field in the
- outer object using a `PLACEHOLDER_EXPR'.
-
-`UNKNOWN_TYPE'
- This node is used to represent a type the knowledge of which is
- insufficient for a sound processing.
-
-`OFFSET_TYPE'
- This node is used to represent a data member; for example a
- pointer-to-data-member is represented by a `POINTER_TYPE' whose
- `TREE_TYPE' is an `OFFSET_TYPE'. For a data member `X::m' the
- `TYPE_OFFSET_BASETYPE' is `X' and the `TREE_TYPE' is the type of
- `m'.
-
-`TYPENAME_TYPE'
- Used to represent a construct of the form `typename T::A'. The
- `TYPE_CONTEXT' is `T'; the `TYPE_NAME' is an `IDENTIFIER_NODE' for
- `A'. If the type is specified via a template-id, then
- `TYPENAME_TYPE_FULLNAME' yields a `TEMPLATE_ID_EXPR'. The
- `TREE_TYPE' is non-`NULL' if the node is implicitly generated in
- support for the implicit typename extension; in which case the
- `TREE_TYPE' is a type node for the base-class.
-
-`TYPEOF_TYPE'
- Used to represent the `__typeof__' extension. The `TYPE_FIELDS'
- is the expression the type of which is being represented.
-
- There are variables whose values represent some of the basic types.
-These include:
-`void_type_node'
- A node for `void'.
-
-`integer_type_node'
- A node for `int'.
-
-`unsigned_type_node.'
- A node for `unsigned int'.
-
-`char_type_node.'
- A node for `char'.
-
-It may sometimes be useful to compare one of these variables with a type
-in hand, using `same_type_p'.
-
-\1f
-File: gccint.info, Node: Scopes, Next: Functions, Prev: Types, Up: Trees
-
-Scopes
-======
-
- The root of the entire intermediate representation is the variable
-`global_namespace'. This is the namespace specified with `::' in C++
-source code. All other namespaces, types, variables, functions, and so
-forth can be found starting with this namespace.
-
- Besides namespaces, the other high-level scoping construct in C++ is
-the class. (Throughout this manual the term "class" is used to mean the
-types referred to in the ANSI/ISO C++ Standard as classes; these include
-types defined with the `class', `struct', and `union' keywords.)
+`STACK_CHECK_PROBE_INTERVAL'
+ An integer representing the interval at which GCC must generate
+ stack probe instructions. You will normally define this macro to
+ be no larger than the size of the "guard pages" at the end of a
+ stack area. The default value of 4096 is suitable for most
+ systems.
+
+`STACK_CHECK_PROBE_LOAD'
+ A integer which is nonzero if GCC should perform the stack probe
+ as a load instruction and zero if GCC should use a store
+ instruction. The default is zero, which is the most efficient
+ choice on most systems.
+
+`STACK_CHECK_PROTECT'
+ The number of bytes of stack needed to recover from a stack
+ overflow, for languages where such a recovery is supported. The
+ default value of 75 words should be adequate for most machines.
+
+`STACK_CHECK_MAX_FRAME_SIZE'
+ The maximum size of a stack frame, in bytes. GCC will generate
+ probe instructions in non-leaf functions to ensure at least this
+ many bytes of stack are available. If a stack frame is larger
+ than this size, stack checking will not be reliable and GCC will
+ issue a warning. The default is chosen so that GCC only generates
+ one instruction on most systems. You should normally not change
+ the default value of this macro.
+
+`STACK_CHECK_FIXED_FRAME_SIZE'
+ GCC uses this value to generate the above warning message. It
+ represents the amount of fixed frame used by a function, not
+ including space for any callee-saved registers, temporaries and
+ user variables. You need only specify an upper bound for this
+ amount and will normally use the default of four words.
+
+`STACK_CHECK_MAX_VAR_SIZE'
+ The maximum size, in bytes, of an object that GCC will place in the
+ fixed area of the stack frame when the user specifies
+ `-fstack-check'. GCC computed the default from the values of the
+ above macros and you will normally not need to override that
+ default.
+
+\1f
+File: gccint.info, Node: Frame Registers, Next: Elimination, Prev: Stack Checking, Up: Stack and Calling
+
+10.10.4 Registers That Address the Stack Frame
+----------------------------------------------
+
+This discusses registers that address the stack frame.
+
+`STACK_POINTER_REGNUM'
+ The register number of the stack pointer register, which must also
+ be a fixed register according to `FIXED_REGISTERS'. On most
+ machines, the hardware determines which register this is.
+
+`FRAME_POINTER_REGNUM'
+ The register number of the frame pointer register, which is used to
+ access automatic variables in the stack frame. On some machines,
+ the hardware determines which register this is. On other
+ machines, you can choose any register you wish for this purpose.
+
+`HARD_FRAME_POINTER_REGNUM'
+ On some machines the offset between the frame pointer and starting
+ offset of the automatic variables is not known until after register
+ allocation has been done (for example, because the saved registers
+ are between these two locations). On those machines, define
+ `FRAME_POINTER_REGNUM' the number of a special, fixed register to
+ be used internally until the offset is known, and define
+ `HARD_FRAME_POINTER_REGNUM' to be the actual hard register number
+ used for the frame pointer.
+
+ You should define this macro only in the very rare circumstances
+ when it is not possible to calculate the offset between the frame
+ pointer and the automatic variables until after register
+ allocation has been completed. When this macro is defined, you
+ must also indicate in your definition of `ELIMINABLE_REGS' how to
+ eliminate `FRAME_POINTER_REGNUM' into either
+ `HARD_FRAME_POINTER_REGNUM' or `STACK_POINTER_REGNUM'.
+
+ Do not define this macro if it would be the same as
+ `FRAME_POINTER_REGNUM'.
+
+`ARG_POINTER_REGNUM'
+ The register number of the arg pointer register, which is used to
+ access the function's argument list. On some machines, this is
+ the same as the frame pointer register. On some machines, the
+ hardware determines which register this is. On other machines,
+ you can choose any register you wish for this purpose. If this is
+ not the same register as the frame pointer register, then you must
+ mark it as a fixed register according to `FIXED_REGISTERS', or
+ arrange to be able to eliminate it (*note Elimination::).
+
+`RETURN_ADDRESS_POINTER_REGNUM'
+ The register number of the return address pointer register, which
+ is used to access the current function's return address from the
+ stack. On some machines, the return address is not at a fixed
+ offset from the frame pointer or stack pointer or argument
+ pointer. This register can be defined to point to the return
+ address on the stack, and then be converted by `ELIMINABLE_REGS'
+ into either the frame pointer or stack pointer.
+
+ Do not define this macro unless there is no other way to get the
+ return address from the stack.
+
+`STATIC_CHAIN_REGNUM'
+`STATIC_CHAIN_INCOMING_REGNUM'
+ Register numbers used for passing a function's static chain
+ pointer. If register windows are used, the register number as
+ seen by the called function is `STATIC_CHAIN_INCOMING_REGNUM',
+ while the register number as seen by the calling function is
+ `STATIC_CHAIN_REGNUM'. If these registers are the same,
+ `STATIC_CHAIN_INCOMING_REGNUM' need not be defined.
+
+ The static chain register need not be a fixed register.
+
+ If the static chain is passed in memory, these macros should not be
+ defined; instead, the next two macros should be defined.
+
+`STATIC_CHAIN'
+`STATIC_CHAIN_INCOMING'
+ If the static chain is passed in memory, these macros provide rtx
+ giving `mem' expressions that denote where they are stored.
+ `STATIC_CHAIN' and `STATIC_CHAIN_INCOMING' give the locations as
+ seen by the calling and called functions, respectively. Often the
+ former will be at an offset from the stack pointer and the latter
+ at an offset from the frame pointer.
+
+ The variables `stack_pointer_rtx', `frame_pointer_rtx', and
+ `arg_pointer_rtx' will have been initialized prior to the use of
+ these macros and should be used to refer to those items.
+
+ If the static chain is passed in a register, the two previous
+ macros should be defined instead.
+
+`DWARF_FRAME_REGISTERS'
+ This macro specifies the maximum number of hard registers that can
+ be saved in a call frame. This is used to size data structures
+ used in DWARF2 exception handling.
+
+ Prior to GCC 3.0, this macro was needed in order to establish a
+ stable exception handling ABI in the face of adding new hard
+ registers for ISA extensions. In GCC 3.0 and later, the EH ABI is
+ insulated from changes in the number of hard registers.
+ Nevertheless, this macro can still be used to reduce the runtime
+ memory requirements of the exception handling routines, which can
+ be substantial if the ISA contains a lot of registers that are not
+ call-saved.
+
+ If this macro is not defined, it defaults to
+ `FIRST_PSEUDO_REGISTER'.
+
+`PRE_GCC3_DWARF_FRAME_REGISTERS'
+ This macro is similar to `DWARF_FRAME_REGISTERS', but is provided
+ for backward compatibility in pre GCC 3.0 compiled code.
+
+ If this macro is not defined, it defaults to
+ `DWARF_FRAME_REGISTERS'.
+
+
+\1f
+File: gccint.info, Node: Elimination, Next: Stack Arguments, Prev: Frame Registers, Up: Stack and Calling
+
+10.10.5 Eliminating Frame Pointer and Arg Pointer
+-------------------------------------------------
+
+This is about eliminating the frame pointer and arg pointer.
+
+`FRAME_POINTER_REQUIRED'
+ A C expression which is nonzero if a function must have and use a
+ frame pointer. This expression is evaluated in the reload pass.
+ If its value is nonzero the function will have a frame pointer.
+
+ The expression can in principle examine the current function and
+ decide according to the facts, but on most machines the constant 0
+ or the constant 1 suffices. Use 0 when the machine allows code to
+ be generated with no frame pointer, and doing so saves some time
+ or space. Use 1 when there is no possible advantage to avoiding a
+ frame pointer.
+
+ In certain cases, the compiler does not know how to produce valid
+ code without a frame pointer. The compiler recognizes those cases
+ and automatically gives the function a frame pointer regardless of
+ what `FRAME_POINTER_REQUIRED' says. You don't need to worry about
+ them.
+
+ In a function that does not require a frame pointer, the frame
+ pointer register can be allocated for ordinary usage, unless you
+ mark it as a fixed register. See `FIXED_REGISTERS' for more
+ information.
+
+`INITIAL_FRAME_POINTER_OFFSET (DEPTH-VAR)'
+ A C statement to store in the variable DEPTH-VAR the difference
+ between the frame pointer and the stack pointer values immediately
+ after the function prologue. The value would be computed from
+ information such as the result of `get_frame_size ()' and the
+ tables of registers `regs_ever_live' and `call_used_regs'.
+
+ If `ELIMINABLE_REGS' is defined, this macro will be not be used and
+ need not be defined. Otherwise, it must be defined even if
+ `FRAME_POINTER_REQUIRED' is defined to always be true; in that
+ case, you may set DEPTH-VAR to anything.
+
+`ELIMINABLE_REGS'
+ If defined, this macro specifies a table of register pairs used to
+ eliminate unneeded registers that point into the stack frame. If
+ it is not defined, the only elimination attempted by the compiler
+ is to replace references to the frame pointer with references to
+ the stack pointer.
+
+ The definition of this macro is a list of structure
+ initializations, each of which specifies an original and
+ replacement register.
+
+ On some machines, the position of the argument pointer is not
+ known until the compilation is completed. In such a case, a
+ separate hard register must be used for the argument pointer.
+ This register can be eliminated by replacing it with either the
+ frame pointer or the argument pointer, depending on whether or not
+ the frame pointer has been eliminated.
+
+ In this case, you might specify:
+ #define ELIMINABLE_REGS \
+ {{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM}, \
+ {ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM}, \
+ {FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM}}
+
+ Note that the elimination of the argument pointer with the stack
+ pointer is specified first since that is the preferred elimination.
+
+`CAN_ELIMINATE (FROM-REG, TO-REG)'
+ A C expression that returns nonzero if the compiler is allowed to
+ try to replace register number FROM-REG with register number
+ TO-REG. This macro need only be defined if `ELIMINABLE_REGS' is
+ defined, and will usually be the constant 1, since most of the
+ cases preventing register elimination are things that the compiler
+ already knows about.
+
+`INITIAL_ELIMINATION_OFFSET (FROM-REG, TO-REG, OFFSET-VAR)'
+ This macro is similar to `INITIAL_FRAME_POINTER_OFFSET'. It
+ specifies the initial difference between the specified pair of
+ registers. This macro must be defined if `ELIMINABLE_REGS' is
+ defined.
+
+\1f
+File: gccint.info, Node: Stack Arguments, Next: Register Arguments, Prev: Elimination, Up: Stack and Calling
+
+10.10.6 Passing Function Arguments on the Stack
+-----------------------------------------------
+
+The macros in this section control how arguments are passed on the
+stack. See the following section for other macros that control passing
+certain arguments in registers.
+
+`PROMOTE_PROTOTYPES'
+ A C expression whose value is nonzero if an argument declared in a
+ prototype as an integral type smaller than `int' should actually
+ be passed as an `int'. In addition to avoiding errors in certain
+ cases of mismatch, it also makes for better code on certain
+ machines. If the macro is not defined in target header files, it
+ defaults to 0.
+
+`PUSH_ARGS'
+ A C expression. If nonzero, push insns will be used to pass
+ outgoing arguments. If the target machine does not have a push
+ instruction, set it to zero. That directs GCC to use an alternate
+ strategy: to allocate the entire argument block and then store the
+ arguments into it. When `PUSH_ARGS' is nonzero, `PUSH_ROUNDING'
+ must be defined too.
+
+`PUSH_ROUNDING (NPUSHED)'
+ A C expression that is the number of bytes actually pushed onto the
+ stack when an instruction attempts to push NPUSHED bytes.
+
+ On some machines, the definition
+
+ #define PUSH_ROUNDING(BYTES) (BYTES)
+
+ will suffice. But on other machines, instructions that appear to
+ push one byte actually push two bytes in an attempt to maintain
+ alignment. Then the definition should be
+
+ #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
+
+`ACCUMULATE_OUTGOING_ARGS'
+ A C expression. If nonzero, the maximum amount of space required
+ for outgoing arguments will be computed and placed into the
+ variable `current_function_outgoing_args_size'. No space will be
+ pushed onto the stack for each call; instead, the function
+ prologue should increase the stack frame size by this amount.
+
+ Setting both `PUSH_ARGS' and `ACCUMULATE_OUTGOING_ARGS' is not
+ proper.
+
+`REG_PARM_STACK_SPACE (FNDECL)'
+ Define this macro if functions should assume that stack space has
+ been allocated for arguments even when their values are passed in
+ registers.
+
+ The value of this macro is the size, in bytes, of the area
+ reserved for arguments passed in registers for the function
+ represented by FNDECL, which can be zero if GCC is calling a
+ library function.
+
+ This space can be allocated by the caller, or be a part of the
+ machine-dependent stack frame: `OUTGOING_REG_PARM_STACK_SPACE' says
+ which.
+
+`MAYBE_REG_PARM_STACK_SPACE'
+`FINAL_REG_PARM_STACK_SPACE (CONST_SIZE, VAR_SIZE)'
+ Define these macros in addition to the one above if functions might
+ allocate stack space for arguments even when their values are
+ passed in registers. These should be used when the stack space
+ allocated for arguments in registers is not a simple constant
+ independent of the function declaration.
+
+ The value of the first macro is the size, in bytes, of the area
+ that we should initially assume would be reserved for arguments
+ passed in registers.
+
+ The value of the second macro is the actual size, in bytes, of the
+ area that will be reserved for arguments passed in registers.
+ This takes two arguments: an integer representing the number of
+ bytes of fixed sized arguments on the stack, and a tree
+ representing the number of bytes of variable sized arguments on
+ the stack.
+
+ When these macros are defined, `REG_PARM_STACK_SPACE' will only be
+ called for libcall functions, the current function, or for a
+ function being called when it is known that such stack space must
+ be allocated. In each case this value can be easily computed.
+
+ When deciding whether a called function needs such stack space,
+ and how much space to reserve, GCC uses these two macros instead of
+ `REG_PARM_STACK_SPACE'.
+
+`OUTGOING_REG_PARM_STACK_SPACE'
+ Define this if it is the responsibility of the caller to allocate
+ the area reserved for arguments passed in registers.
+
+ If `ACCUMULATE_OUTGOING_ARGS' is defined, this macro controls
+ whether the space for these arguments counts in the value of
+ `current_function_outgoing_args_size'.
+
+`STACK_PARMS_IN_REG_PARM_AREA'
+ Define this macro if `REG_PARM_STACK_SPACE' is defined, but the
+ stack parameters don't skip the area specified by it.
+
+ Normally, when a parameter is not passed in registers, it is
+ placed on the stack beyond the `REG_PARM_STACK_SPACE' area.
+ Defining this macro suppresses this behavior and causes the
+ parameter to be passed on the stack in its natural location.
+
+`RETURN_POPS_ARGS (FUNDECL, FUNTYPE, STACK-SIZE)'
+ A C expression that should indicate the number of bytes of its own
+ arguments that a function pops on returning, or 0 if the function
+ pops no arguments and the caller must therefore pop them all after
+ the function returns.
+
+ FUNDECL is a C variable whose value is a tree node that describes
+ the function in question. Normally it is a node of type
+ `FUNCTION_DECL' that describes the declaration of the function.
+ From this you can obtain the `DECL_ATTRIBUTES' of the function.
+
+ FUNTYPE is a C variable whose value is a tree node that describes
+ the function in question. Normally it is a node of type
+ `FUNCTION_TYPE' that describes the data type of the function.
+ From this it is possible to obtain the data types of the value and
+ arguments (if known).
+
+ When a call to a library function is being considered, FUNDECL
+ will contain an identifier node for the library function. Thus, if
+ you need to distinguish among various library functions, you can
+ do so by their names. Note that "library function" in this
+ context means a function used to perform arithmetic, whose name is
+ known specially in the compiler and was not mentioned in the C
+ code being compiled.
+
+ STACK-SIZE is the number of bytes of arguments passed on the
+ stack. If a variable number of bytes is passed, it is zero, and
+ argument popping will always be the responsibility of the calling
+ function.
+
+ On the VAX, all functions always pop their arguments, so the
+ definition of this macro is STACK-SIZE. On the 68000, using the
+ standard calling convention, no functions pop their arguments, so
+ the value of the macro is always 0 in this case. But an
+ alternative calling convention is available in which functions
+ that take a fixed number of arguments pop them but other functions
+ (such as `printf') pop nothing (the caller pops all). When this
+ convention is in use, FUNTYPE is examined to determine whether a
+ function takes a fixed number of arguments.
+
+`CALL_POPS_ARGS (CUM)'
+ A C expression that should indicate the number of bytes a call
+ sequence pops off the stack. It is added to the value of
+ `RETURN_POPS_ARGS' when compiling a function call.
+
+ CUM is the variable in which all arguments to the called function
+ have been accumulated.
+
+ On certain architectures, such as the SH5, a call trampoline is
+ used that pops certain registers off the stack, depending on the
+ arguments that have been passed to the function. Since this is a
+ property of the call site, not of the called function,
+ `RETURN_POPS_ARGS' is not appropriate.
+
+
+\1f
+File: gccint.info, Node: Register Arguments, Next: Scalar Return, Prev: Stack Arguments, Up: Stack and Calling
+
+10.10.7 Passing Arguments in Registers
+--------------------------------------
+
+This section describes the macros which let you control how various
+types of arguments are passed in registers or how they are arranged in
+the stack.
+
+`FUNCTION_ARG (CUM, MODE, TYPE, NAMED)'
+ A C expression that controls whether a function argument is passed
+ in a register, and which register.
+
+ The arguments are CUM, which summarizes all the previous
+ arguments; MODE, the machine mode of the argument; TYPE, the data
+ type of the argument as a tree node or 0 if that is not known
+ (which happens for C support library functions); and NAMED, which
+ is 1 for an ordinary argument and 0 for nameless arguments that
+ correspond to `...' in the called function's prototype. TYPE can
+ be an incomplete type if a syntax error has previously occurred.
+
+ The value of the expression is usually either a `reg' RTX for the
+ hard register in which to pass the argument, or zero to pass the
+ argument on the stack.
+
+ For machines like the VAX and 68000, where normally all arguments
+ are pushed, zero suffices as a definition.
+
+ The value of the expression can also be a `parallel' RTX. This is
+ used when an argument is passed in multiple locations. The mode
+ of the of the `parallel' should be the mode of the entire
+ argument. The `parallel' holds any number of `expr_list' pairs;
+ each one describes where part of the argument is passed. In each
+ `expr_list' the first operand must be a `reg' RTX for the hard
+ register in which to pass this part of the argument, and the mode
+ of the register RTX indicates how large this part of the argument
+ is. The second operand of the `expr_list' is a `const_int' which
+ gives the offset in bytes into the entire argument of where this
+ part starts. As a special exception the first `expr_list' in the
+ `parallel' RTX may have a first operand of zero. This indicates
+ that the entire argument is also stored on the stack.
+
+ The last time this macro is called, it is called with `MODE ==
+ VOIDmode', and its result is passed to the `call' or `call_value'
+ pattern as operands 2 and 3 respectively.
+
+ The usual way to make the ISO library `stdarg.h' work on a machine
+ where some arguments are usually passed in registers, is to cause
+ nameless arguments to be passed on the stack instead. This is done
+ by making `FUNCTION_ARG' return 0 whenever NAMED is 0.
+
+ You may use the macro `MUST_PASS_IN_STACK (MODE, TYPE)' in the
+ definition of this macro to determine if this argument is of a
+ type that must be passed in the stack. If `REG_PARM_STACK_SPACE'
+ is not defined and `FUNCTION_ARG' returns nonzero for such an
+ argument, the compiler will abort. If `REG_PARM_STACK_SPACE' is
+ defined, the argument will be computed in the stack and then
+ loaded into a register.
+
+`MUST_PASS_IN_STACK (MODE, TYPE)'
+ Define as a C expression that evaluates to nonzero if we do not
+ know how to pass TYPE solely in registers. The file `expr.h'
+ defines a definition that is usually appropriate, refer to
+ `expr.h' for additional documentation.
+
+`FUNCTION_INCOMING_ARG (CUM, MODE, TYPE, NAMED)'
+ Define this macro if the target machine has "register windows", so
+ that the register in which a function sees an arguments is not
+ necessarily the same as the one in which the caller passed the
+ argument.
+
+ For such machines, `FUNCTION_ARG' computes the register in which
+ the caller passes the value, and `FUNCTION_INCOMING_ARG' should be
+ defined in a similar fashion to tell the function being called
+ where the arguments will arrive.
+
+ If `FUNCTION_INCOMING_ARG' is not defined, `FUNCTION_ARG' serves
+ both purposes.
+
+`FUNCTION_ARG_PARTIAL_NREGS (CUM, MODE, TYPE, NAMED)'
+ A C expression for the number of words, at the beginning of an
+ argument, that must be put in registers. The value must be zero
+ for arguments that are passed entirely in registers or that are
+ entirely pushed on the stack.
+
+ On some machines, certain arguments must be passed partially in
+ registers and partially in memory. On these machines, typically
+ the first N words of arguments are passed in registers, and the
+ rest on the stack. If a multi-word argument (a `double' or a
+ structure) crosses that boundary, its first few words must be
+ passed in registers and the rest must be pushed. This macro tells
+ the compiler when this occurs, and how many of the words should go
+ in registers.
+
+ `FUNCTION_ARG' for these arguments should return the first
+ register to be used by the caller for this argument; likewise
+ `FUNCTION_INCOMING_ARG', for the called function.
+
+`FUNCTION_ARG_PASS_BY_REFERENCE (CUM, MODE, TYPE, NAMED)'
+ A C expression that indicates when an argument must be passed by
+ reference. If nonzero for an argument, a copy of that argument is
+ made in memory and a pointer to the argument is passed instead of
+ the argument itself. The pointer is passed in whatever way is
+ appropriate for passing a pointer to that type.
+
+ On machines where `REG_PARM_STACK_SPACE' is not defined, a suitable
+ definition of this macro might be
+ #define FUNCTION_ARG_PASS_BY_REFERENCE\
+ (CUM, MODE, TYPE, NAMED) \
+ MUST_PASS_IN_STACK (MODE, TYPE)
+
+`FUNCTION_ARG_CALLEE_COPIES (CUM, MODE, TYPE, NAMED)'
+ If defined, a C expression that indicates when it is the called
+ function's responsibility to make a copy of arguments passed by
+ invisible reference. Normally, the caller makes a copy and passes
+ the address of the copy to the routine being called. When
+ `FUNCTION_ARG_CALLEE_COPIES' is defined and is nonzero, the caller
+ does not make a copy. Instead, it passes a pointer to the "live"
+ value. The called function must not modify this value. If it can
+ be determined that the value won't be modified, it need not make a
+ copy; otherwise a copy must be made.
+
+`FUNCTION_ARG_REG_LITTLE_ENDIAN'
+ If defined TRUE on a big-endian system then structure arguments
+ passed (and returned) in registers are passed in a little-endian
+ manner instead of the big-endian manner. On the HP-UX IA64 and
+ PA64 platforms structures are aligned differently then integral
+ values and setting this value to true will allow for the special
+ handling of structure arguments and return values.
+
+`CUMULATIVE_ARGS'
+ A C type for declaring a variable that is used as the first
+ argument of `FUNCTION_ARG' and other related values. For some
+ target machines, the type `int' suffices and can hold the number
+ of bytes of argument so far.
+
+ There is no need to record in `CUMULATIVE_ARGS' anything about the
+ arguments that have been passed on the stack. The compiler has
+ other variables to keep track of that. For target machines on
+ which all arguments are passed on the stack, there is no need to
+ store anything in `CUMULATIVE_ARGS'; however, the data structure
+ must exist and should not be empty, so use `int'.
+
+`INIT_CUMULATIVE_ARGS (CUM, FNTYPE, LIBNAME, INDIRECT)'
+ A C statement (sans semicolon) for initializing the variable CUM
+ for the state at the beginning of the argument list. The variable
+ has type `CUMULATIVE_ARGS'. The value of FNTYPE is the tree node
+ for the data type of the function which will receive the args, or 0
+ if the args are to a compiler support library function. The value
+ of INDIRECT is nonzero when processing an indirect call, for
+ example a call through a function pointer. The value of INDIRECT
+ is zero for a call to an explicitly named function, a library
+ function call, or when `INIT_CUMULATIVE_ARGS' is used to find
+ arguments for the function being compiled.
+
+ When processing a call to a compiler support library function,
+ LIBNAME identifies which one. It is a `symbol_ref' rtx which
+ contains the name of the function, as a string. LIBNAME is 0 when
+ an ordinary C function call is being processed. Thus, each time
+ this macro is called, either LIBNAME or FNTYPE is nonzero, but
+ never both of them at once.
+
+`INIT_CUMULATIVE_LIBCALL_ARGS (CUM, MODE, LIBNAME)'
+ Like `INIT_CUMULATIVE_ARGS' but only used for outgoing libcalls,
+ it gets a `MODE' argument instead of FNTYPE, that would be `NULL'.
+ INDIRECT would always be zero, too. If this macro is not defined,
+ `INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 0)' is used instead.
+
+`INIT_CUMULATIVE_INCOMING_ARGS (CUM, FNTYPE, LIBNAME)'
+ Like `INIT_CUMULATIVE_ARGS' but overrides it for the purposes of
+ finding the arguments for the function being compiled. If this
+ macro is undefined, `INIT_CUMULATIVE_ARGS' is used instead.
+
+ The value passed for LIBNAME is always 0, since library routines
+ with special calling conventions are never compiled with GCC. The
+ argument LIBNAME exists for symmetry with `INIT_CUMULATIVE_ARGS'.
+
+`FUNCTION_ARG_ADVANCE (CUM, MODE, TYPE, NAMED)'
+ A C statement (sans semicolon) to update the summarizer variable
+ CUM to advance past an argument in the argument list. The values
+ MODE, TYPE and NAMED describe that argument. Once this is done,
+ the variable CUM is suitable for analyzing the _following_
+ argument with `FUNCTION_ARG', etc.
+
+ This macro need not do anything if the argument in question was
+ passed on the stack. The compiler knows how to track the amount
+ of stack space used for arguments without any special help.
+
+`FUNCTION_ARG_PADDING (MODE, TYPE)'
+ If defined, a C expression which determines whether, and in which
+ direction, to pad out an argument with extra space. The value
+ should be of type `enum direction': either `upward' to pad above
+ the argument, `downward' to pad below, or `none' to inhibit
+ padding.
+
+ The _amount_ of padding is always just enough to reach the next
+ multiple of `FUNCTION_ARG_BOUNDARY'; this macro does not control
+ it.
+
+ This macro has a default definition which is right for most
+ systems. For little-endian machines, the default is to pad
+ upward. For big-endian machines, the default is to pad downward
+ for an argument of constant size shorter than an `int', and upward
+ otherwise.
+
+`PAD_VARARGS_DOWN'
+ If defined, a C expression which determines whether the default
+ implementation of va_arg will attempt to pad down before reading
+ the next argument, if that argument is smaller than its aligned
+ space as controlled by `PARM_BOUNDARY'. If this macro is not
+ defined, all such arguments are padded down if `BYTES_BIG_ENDIAN'
+ is true.
+
+`FUNCTION_ARG_BOUNDARY (MODE, TYPE)'
+ If defined, a C expression that gives the alignment boundary, in
+ bits, of an argument with the specified mode and type. If it is
+ not defined, `PARM_BOUNDARY' is used for all arguments.
+
+`FUNCTION_ARG_REGNO_P (REGNO)'
+ A C expression that is nonzero if REGNO is the number of a hard
+ register in which function arguments are sometimes passed. This
+ does _not_ include implicit arguments such as the static chain and
+ the structure-value address. On many machines, no registers can be
+ used for this purpose since all function arguments are pushed on
+ the stack.
+
+`LOAD_ARGS_REVERSED'
+ If defined, the order in which arguments are loaded into their
+ respective argument registers is reversed so that the last
+ argument is loaded first. This macro only affects arguments
+ passed in registers.
+
+
+\1f
+File: gccint.info, Node: Scalar Return, Next: Aggregate Return, Prev: Register Arguments, Up: Stack and Calling
+
+10.10.8 How Scalar Function Values Are Returned
+-----------------------------------------------
+
+This section discusses the macros that control returning scalars as
+values--values that can fit in registers.
+
+`TRADITIONAL_RETURN_FLOAT'
+ Define this macro if `-traditional' should not cause functions
+ declared to return `float' to convert the value to `double'.
+
+`FUNCTION_VALUE (VALTYPE, FUNC)'
+ A C expression to create an RTX representing the place where a
+ function returns a value of data type VALTYPE. VALTYPE is a tree
+ node representing a data type. Write `TYPE_MODE (VALTYPE)' to get
+ the machine mode used to represent that type. On many machines,
+ only the mode is relevant. (Actually, on most machines, scalar
+ values are returned in the same place regardless of mode).
+
+ The value of the expression is usually a `reg' RTX for the hard
+ register where the return value is stored. The value can also be a
+ `parallel' RTX, if the return value is in multiple places. See
+ `FUNCTION_ARG' for an explanation of the `parallel' form.
+
+ If `PROMOTE_FUNCTION_RETURN' is defined, you must apply the same
+ promotion rules specified in `PROMOTE_MODE' if VALTYPE is a scalar
+ type.
+
+ If the precise function being called is known, FUNC is a tree node
+ (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. This
+ makes it possible to use a different value-returning convention
+ for specific functions when all their calls are known.
+
+ `FUNCTION_VALUE' is not used for return vales with aggregate data
+ types, because these are returned in another way. See
+ `STRUCT_VALUE_REGNUM' and related macros, below.
+
+`FUNCTION_OUTGOING_VALUE (VALTYPE, FUNC)'
+ Define this macro if the target machine has "register windows" so
+ that the register in which a function returns its value is not the
+ same as the one in which the caller sees the value.
+
+ For such machines, `FUNCTION_VALUE' computes the register in which
+ the caller will see the value. `FUNCTION_OUTGOING_VALUE' should be
+ defined in a similar fashion to tell the function where to put the
+ value.
+
+ If `FUNCTION_OUTGOING_VALUE' is not defined, `FUNCTION_VALUE'
+ serves both purposes.
+
+ `FUNCTION_OUTGOING_VALUE' is not used for return vales with
+ aggregate data types, because these are returned in another way.
+ See `STRUCT_VALUE_REGNUM' and related macros, below.
+
+`LIBCALL_VALUE (MODE)'
+ A C expression to create an RTX representing the place where a
+ library function returns a value of mode MODE. If the precise
+ function being called is known, FUNC is a tree node
+ (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. This
+ makes it possible to use a different value-returning convention
+ for specific functions when all their calls are known.
+
+ Note that "library function" in this context means a compiler
+ support routine, used to perform arithmetic, whose name is known
+ specially by the compiler and was not mentioned in the C code being
+ compiled.
+
+ The definition of `LIBRARY_VALUE' need not be concerned aggregate
+ data types, because none of the library functions returns such
+ types.
+
+`FUNCTION_VALUE_REGNO_P (REGNO)'
+ A C expression that is nonzero if REGNO is the number of a hard
+ register in which the values of called function may come back.
+
+ A register whose use for returning values is limited to serving as
+ the second of a pair (for a value of type `double', say) need not
+ be recognized by this macro. So for most machines, this definition
+ suffices:
+
+ #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
+
+ If the machine has register windows, so that the caller and the
+ called function use different registers for the return value, this
+ macro should recognize only the caller's register numbers.
+
+`APPLY_RESULT_SIZE'
+ Define this macro if `untyped_call' and `untyped_return' need more
+ space than is implied by `FUNCTION_VALUE_REGNO_P' for saving and
+ restoring an arbitrary return value.
+
+\1f
+File: gccint.info, Node: Aggregate Return, Next: Caller Saves, Prev: Scalar Return, Up: Stack and Calling
+
+10.10.9 How Large Values Are Returned
+-------------------------------------
+
+When a function value's mode is `BLKmode' (and in some other cases),
+the value is not returned according to `FUNCTION_VALUE' (*note Scalar
+Return::). Instead, the caller passes the address of a block of memory
+in which the value should be stored. This address is called the
+"structure value address".
+
+ This section describes how to control returning structure values in
+memory.
+
+`RETURN_IN_MEMORY (TYPE)'
+ A C expression which can inhibit the returning of certain function
+ values in registers, based on the type of value. A nonzero value
+ says to return the function value in memory, just as large
+ structures are always returned. Here TYPE will be a C expression
+ of type `tree', representing the data type of the value.
+
+ Note that values of mode `BLKmode' must be explicitly handled by
+ this macro. Also, the option `-fpcc-struct-return' takes effect
+ regardless of this macro. On most systems, it is possible to
+ leave the macro undefined; this causes a default definition to be
+ used, whose value is the constant 1 for `BLKmode' values, and 0
+ otherwise.
+
+ Do not use this macro to indicate that structures and unions
+ should always be returned in memory. You should instead use
+ `DEFAULT_PCC_STRUCT_RETURN' to indicate this.
+
+`DEFAULT_PCC_STRUCT_RETURN'
+ Define this macro to be 1 if all structure and union return values
+ must be in memory. Since this results in slower code, this should
+ be defined only if needed for compatibility with other compilers
+ or with an ABI. If you define this macro to be 0, then the
+ conventions used for structure and union return values are decided
+ by the `RETURN_IN_MEMORY' macro.
+
+ If not defined, this defaults to the value 1.
+
+`STRUCT_VALUE_REGNUM'
+ If the structure value address is passed in a register, then
+ `STRUCT_VALUE_REGNUM' should be the number of that register.
+
+`STRUCT_VALUE'
+ If the structure value address is not passed in a register, define
+ `STRUCT_VALUE' as an expression returning an RTX for the place
+ where the address is passed. If it returns 0, the address is
+ passed as an "invisible" first argument.
+
+`STRUCT_VALUE_INCOMING_REGNUM'
+ On some architectures the place where the structure value address
+ is found by the called function is not the same place that the
+ caller put it. This can be due to register windows, or it could
+ be because the function prologue moves it to a different place.
+
+ If the incoming location of the structure value address is in a
+ register, define this macro as the register number.
+
+`STRUCT_VALUE_INCOMING'
+ If the incoming location is not a register, then you should define
+ `STRUCT_VALUE_INCOMING' as an expression for an RTX for where the
+ called function should find the value. If it should find the
+ value on the stack, define this to create a `mem' which refers to
+ the frame pointer. A definition of 0 means that the address is
+ passed as an "invisible" first argument.
+
+`PCC_STATIC_STRUCT_RETURN'
+ Define this macro if the usual system convention on the target
+ machine for returning structures and unions is for the called
+ function to return the address of a static variable containing the
+ value.
+
+ Do not define this if the usual system convention is for the
+ caller to pass an address to the subroutine.
+
+ This macro has effect in `-fpcc-struct-return' mode, but it does
+ nothing when you use `-freg-struct-return' mode.
+
+\1f
+File: gccint.info, Node: Caller Saves, Next: Function Entry, Prev: Aggregate Return, Up: Stack and Calling
+
+10.10.10 Caller-Saves Register Allocation
+-----------------------------------------
+
+If you enable it, GCC can save registers around function calls. This
+makes it possible to use call-clobbered registers to hold variables that
+must live across calls.
+
+`DEFAULT_CALLER_SAVES'
+ Define this macro if function calls on the target machine do not
+ preserve any registers; in other words, if `CALL_USED_REGISTERS'
+ has 1 for all registers. When defined, this macro enables
+ `-fcaller-saves' by default for all optimization levels. It has
+ no effect for optimization levels 2 and higher, where
+ `-fcaller-saves' is the default.
+
+`CALLER_SAVE_PROFITABLE (REFS, CALLS)'
+ A C expression to determine whether it is worthwhile to consider
+ placing a pseudo-register in a call-clobbered hard register and
+ saving and restoring it around each function call. The expression
+ should be 1 when this is worth doing, and 0 otherwise.
+
+ If you don't define this macro, a default is used which is good on
+ most machines: `4 * CALLS < REFS'.
+
+`HARD_REGNO_CALLER_SAVE_MODE (REGNO, NREGS)'
+ A C expression specifying which mode is required for saving NREGS
+ of a pseudo-register in call-clobbered hard register REGNO. If
+ REGNO is unsuitable for caller save, `VOIDmode' should be
+ returned. For most machines this macro need not be defined since
+ GCC will select the smallest suitable mode.
+
+\1f
+File: gccint.info, Node: Function Entry, Next: Profiling, Prev: Caller Saves, Up: Stack and Calling
+
+10.10.11 Function Entry and Exit
+--------------------------------
+
+This section describes the macros that output function entry
+("prologue") and exit ("epilogue") code.
+
+ -- Target Hook: void TARGET_ASM_FUNCTION_PROLOGUE (FILE *FILE,
+ HOST_WIDE_INT SIZE)
+ If defined, a function that outputs the assembler code for entry
+ to a function. The prologue is responsible for setting up the
+ stack frame, initializing the frame pointer register, saving
+ registers that must be saved, and allocating SIZE additional bytes
+ of storage for the local variables. SIZE is an integer. FILE is
+ a stdio stream to which the assembler code should be output.
+
+ The label for the beginning of the function need not be output by
+ this macro. That has already been done when the macro is run.
+
+ To determine which registers to save, the macro can refer to the
+ array `regs_ever_live': element R is nonzero if hard register R is
+ used anywhere within the function. This implies the function
+ prologue should save register R, provided it is not one of the
+ call-used registers. (`TARGET_ASM_FUNCTION_EPILOGUE' must
+ likewise use `regs_ever_live'.)
+
+ On machines that have "register windows", the function entry code
+ does not save on the stack the registers that are in the windows,
+ even if they are supposed to be preserved by function calls;
+ instead it takes appropriate steps to "push" the register stack,
+ if any non-call-used registers are used in the function.
+
+ On machines where functions may or may not have frame-pointers, the
+ function entry code must vary accordingly; it must set up the frame
+ pointer if one is wanted, and not otherwise. To determine whether
+ a frame pointer is in wanted, the macro can refer to the variable
+ `frame_pointer_needed'. The variable's value will be 1 at run
+ time in a function that needs a frame pointer. *Note
+ Elimination::.
+
+ The function entry code is responsible for allocating any stack
+ space required for the function. This stack space consists of the
+ regions listed below. In most cases, these regions are allocated
+ in the order listed, with the last listed region closest to the
+ top of the stack (the lowest address if `STACK_GROWS_DOWNWARD' is
+ defined, and the highest address if it is not defined). You can
+ use a different order for a machine if doing so is more convenient
+ or required for compatibility reasons. Except in cases where
+ required by standard or by a debugger, there is no reason why the
+ stack layout used by GCC need agree with that used by other
+ compilers for a machine.
+
+ -- Target Hook: void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *FILE)
+ If defined, a function that outputs assembler code at the end of a
+ prologue. This should be used when the function prologue is being
+ emitted as RTL, and you have some extra assembler that needs to be
+ emitted. *Note prologue instruction pattern::.
+
+ -- Target Hook: void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *FILE)
+ If defined, a function that outputs assembler code at the start of
+ an epilogue. This should be used when the function epilogue is
+ being emitted as RTL, and you have some extra assembler that needs
+ to be emitted. *Note epilogue instruction pattern::.
+
+ -- Target Hook: void TARGET_ASM_FUNCTION_EPILOGUE (FILE *FILE,
+ HOST_WIDE_INT SIZE)
+ If defined, a function that outputs the assembler code for exit
+ from a function. The epilogue is responsible for restoring the
+ saved registers and stack pointer to their values when the
+ function was called, and returning control to the caller. This
+ macro takes the same arguments as the macro
+ `TARGET_ASM_FUNCTION_PROLOGUE', and the registers to restore are
+ determined from `regs_ever_live' and `CALL_USED_REGISTERS' in the
+ same way.
+
+ On some machines, there is a single instruction that does all the
+ work of returning from the function. On these machines, give that
+ instruction the name `return' and do not define the macro
+ `TARGET_ASM_FUNCTION_EPILOGUE' at all.
+
+ Do not define a pattern named `return' if you want the
+ `TARGET_ASM_FUNCTION_EPILOGUE' to be used. If you want the target
+ switches to control whether return instructions or epilogues are
+ used, define a `return' pattern with a validity condition that
+ tests the target switches appropriately. If the `return'
+ pattern's validity condition is false, epilogues will be used.
+
+ On machines where functions may or may not have frame-pointers, the
+ function exit code must vary accordingly. Sometimes the code for
+ these two cases is completely different. To determine whether a
+ frame pointer is wanted, the macro can refer to the variable
+ `frame_pointer_needed'. The variable's value will be 1 when
+ compiling a function that needs a frame pointer.
+
+ Normally, `TARGET_ASM_FUNCTION_PROLOGUE' and
+ `TARGET_ASM_FUNCTION_EPILOGUE' must treat leaf functions specially.
+ The C variable `current_function_is_leaf' is nonzero for such a
+ function. *Note Leaf Functions::.
+
+ On some machines, some functions pop their arguments on exit while
+ others leave that for the caller to do. For example, the 68020
+ when given `-mrtd' pops arguments in functions that take a fixed
+ number of arguments.
+
+ Your definition of the macro `RETURN_POPS_ARGS' decides which
+ functions pop their own arguments. `TARGET_ASM_FUNCTION_EPILOGUE'
+ needs to know what was decided. The variable that is called
+ `current_function_pops_args' is the number of bytes of its
+ arguments that a function should pop. *Note Scalar Return::.
+
+ * A region of `current_function_pretend_args_size' bytes of
+ uninitialized space just underneath the first argument
+ arriving on the stack. (This may not be at the very start of
+ the allocated stack region if the calling sequence has pushed
+ anything else since pushing the stack arguments. But
+ usually, on such machines, nothing else has been pushed yet,
+ because the function prologue itself does all the pushing.)
+ This region is used on machines where an argument may be
+ passed partly in registers and partly in memory, and, in some
+ cases to support the features in `<varargs.h>' and
+ `<stdarg.h>'.
+
+ * An area of memory used to save certain registers used by the
+ function. The size of this area, which may also include
+ space for such things as the return address and pointers to
+ previous stack frames, is machine-specific and usually
+ depends on which registers have been used in the function.
+ Machines with register windows often do not require a save
+ area.
+
+ * A region of at least SIZE bytes, possibly rounded up to an
+ allocation boundary, to contain the local variables of the
+ function. On some machines, this region and the save area
+ may occur in the opposite order, with the save area closer to
+ the top of the stack.
+
+ * Optionally, when `ACCUMULATE_OUTGOING_ARGS' is defined, a
+ region of `current_function_outgoing_args_size' bytes to be
+ used for outgoing argument lists of the function. *Note
+ Stack Arguments::.
+
+ Normally, it is necessary for the macros
+ `TARGET_ASM_FUNCTION_PROLOGUE' and `TARGET_ASM_FUNCTION_EPILOGUE'
+ to treat leaf functions specially. The C variable
+ `current_function_is_leaf' is nonzero for such a function.
+
+`EXIT_IGNORE_STACK'
+ Define this macro as a C expression that is nonzero if the return
+ instruction or the function epilogue ignores the value of the stack
+ pointer; in other words, if it is safe to delete an instruction to
+ adjust the stack pointer before a return from the function.
+
+ Note that this macro's value is relevant only for functions for
+ which frame pointers are maintained. It is never safe to delete a
+ final stack adjustment in a function that has no frame pointer,
+ and the compiler knows this regardless of `EXIT_IGNORE_STACK'.
+
+`EPILOGUE_USES (REGNO)'
+ Define this macro as a C expression that is nonzero for registers
+ that are used by the epilogue or the `return' pattern. The stack
+ and frame pointer registers are already be assumed to be used as
+ needed.
+
+`EH_USES (REGNO)'
+ Define this macro as a C expression that is nonzero for registers
+ that are used by the exception handling mechanism, and so should
+ be considered live on entry to an exception edge.
+
+`DELAY_SLOTS_FOR_EPILOGUE'
+ Define this macro if the function epilogue contains delay slots to
+ which instructions from the rest of the function can be "moved".
+ The definition should be a C expression whose value is an integer
+ representing the number of delay slots there.
+
+`ELIGIBLE_FOR_EPILOGUE_DELAY (INSN, N)'
+ A C expression that returns 1 if INSN can be placed in delay slot
+ number N of the epilogue.
+
+ The argument N is an integer which identifies the delay slot now
+ being considered (since different slots may have different rules of
+ eligibility). It is never negative and is always less than the
+ number of epilogue delay slots (what `DELAY_SLOTS_FOR_EPILOGUE'
+ returns). If you reject a particular insn for a given delay slot,
+ in principle, it may be reconsidered for a subsequent delay slot.
+ Also, other insns may (at least in principle) be considered for
+ the so far unfilled delay slot.
+
+ The insns accepted to fill the epilogue delay slots are put in an
+ RTL list made with `insn_list' objects, stored in the variable
+ `current_function_epilogue_delay_list'. The insn for the first
+ delay slot comes first in the list. Your definition of the macro
+ `TARGET_ASM_FUNCTION_EPILOGUE' should fill the delay slots by
+ outputting the insns in this list, usually by calling
+ `final_scan_insn'.
+
+ You need not define this macro if you did not define
+ `DELAY_SLOTS_FOR_EPILOGUE'.
+
+`ASM_OUTPUT_MI_THUNK (FILE, THUNK_FNDECL, DELTA, FUNCTION)'
+ A C compound statement that outputs the assembler code for a thunk
+ function, used to implement C++ virtual function calls with
+ multiple inheritance. The thunk acts as a wrapper around a
+ virtual function, adjusting the implicit object parameter before
+ handing control off to the real function.
+
+ First, emit code to add the integer DELTA to the location that
+ contains the incoming first argument. Assume that this argument
+ contains a pointer, and is the one used to pass the `this' pointer
+ in C++. This is the incoming argument _before_ the function
+ prologue, e.g. `%o0' on a sparc. The addition must preserve the
+ values of all other incoming arguments.
+
+ After the addition, emit code to jump to FUNCTION, which is a
+ `FUNCTION_DECL'. This is a direct pure jump, not a call, and does
+ not touch the return address. Hence returning from FUNCTION will
+ return to whoever called the current `thunk'.
+
+ The effect must be as if FUNCTION had been called directly with
+ the adjusted first argument. This macro is responsible for
+ emitting all of the code for a thunk function;
+ `TARGET_ASM_FUNCTION_PROLOGUE' and `TARGET_ASM_FUNCTION_EPILOGUE'
+ are not invoked.
+
+ The THUNK_FNDECL is redundant. (DELTA and FUNCTION have already
+ been extracted from it.) It might possibly be useful on some
+ targets, but probably not.
+
+ If you do not define this macro, the target-independent code in
+ the C++ front end will generate a less efficient heavyweight thunk
+ that calls FUNCTION instead of jumping to it. The generic
+ approach does not support varargs.
+
+\1f
+File: gccint.info, Node: Profiling, Next: Tail Calls, Prev: Function Entry, Up: Stack and Calling
+
+10.10.12 Generating Code for Profiling
+--------------------------------------
+
+These macros will help you generate code for profiling.
+
+`FUNCTION_PROFILER (FILE, LABELNO)'
+ A C statement or compound statement to output to FILE some
+ assembler code to call the profiling subroutine `mcount'.
+
+ The details of how `mcount' expects to be called are determined by
+ your operating system environment, not by GCC. To figure them out,
+ compile a small program for profiling using the system's installed
+ C compiler and look at the assembler code that results.
+
+ Older implementations of `mcount' expect the address of a counter
+ variable to be loaded into some register. The name of this
+ variable is `LP' followed by the number LABELNO, so you would
+ generate the name using `LP%d' in a `fprintf'.
+
+`PROFILE_HOOK'
+ A C statement or compound statement to output to FILE some assembly
+ code to call the profiling subroutine `mcount' even the target does
+ not support profiling.
+
+`NO_PROFILE_COUNTERS'
+ Define this macro if the `mcount' subroutine on your system does
+ not need a counter variable allocated for each function. This is
+ true for almost all modern implementations. If you define this
+ macro, you must not use the LABELNO argument to
+ `FUNCTION_PROFILER'.
+
+`PROFILE_BEFORE_PROLOGUE'
+ Define this macro if the code for function profiling should come
+ before the function prologue. Normally, the profiling code comes
+ after.
+
+`TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER'
+ On some targets, it is impossible to use profiling when the frame
+ pointer has been omitted. For example, on x86 GNU/Linux systems,
+ the `mcount' routine provided by the GNU C Library finds the
+ address of the routine that called the routine that called `mcount'
+ by looking in the immediate caller's stack frame. If the immediate
+ caller has no frame pointer, this lookup will fail.
+
+ By default, GCC assumes that the target does allow profiling when
+ the frame pointer is omitted. This macro should be defined to a C
+ expression that evaluates to `false' if the target does not allow
+ profiling when the frame pointer is omitted.
+
+
+\1f
+File: gccint.info, Node: Tail Calls, Prev: Profiling, Up: Stack and Calling
+
+10.10.13 Permitting tail calls
+------------------------------
+
+`FUNCTION_OK_FOR_SIBCALL (DECL)'
+ A C expression that evaluates to true if it is ok to perform a
+ sibling call to DECL from the current function.
+
+ It is not uncommon for limitations of calling conventions to
+ prevent tail calls to functions outside the current unit of
+ translation, or during PIC compilation. Use this macro to enforce
+ these restrictions, as the `sibcall' md pattern can not fail, or
+ fall over to a "normal" call.
+
+\1f
+File: gccint.info, Node: Varargs, Next: Trampolines, Prev: Stack and Calling, Up: Target Macros
+
+10.11 Implementing the Varargs Macros
+=====================================
+
+GCC comes with an implementation of `<varargs.h>' and `<stdarg.h>' that
+work without change on machines that pass arguments on the stack.
+Other machines require their own implementations of varargs, and the
+two machine independent header files must have conditionals to include
+it.
+
+ ISO `<stdarg.h>' differs from traditional `<varargs.h>' mainly in
+the calling convention for `va_start'. The traditional implementation
+takes just one argument, which is the variable in which to store the
+argument pointer. The ISO implementation of `va_start' takes an
+additional second argument. The user is supposed to write the last
+named argument of the function here.
+
+ However, `va_start' should not use this argument. The way to find
+the end of the named arguments is with the built-in functions described
+below.
+
+`__builtin_saveregs ()'
+ Use this built-in function to save the argument registers in
+ memory so that the varargs mechanism can access them. Both ISO
+ and traditional versions of `va_start' must use
+ `__builtin_saveregs', unless you use `SETUP_INCOMING_VARARGS' (see
+ below) instead.
+
+ On some machines, `__builtin_saveregs' is open-coded under the
+ control of the macro `EXPAND_BUILTIN_SAVEREGS'. On other machines,
+ it calls a routine written in assembler language, found in
+ `libgcc2.c'.
+
+ Code generated for the call to `__builtin_saveregs' appears at the
+ beginning of the function, as opposed to where the call to
+ `__builtin_saveregs' is written, regardless of what the code is.
+ This is because the registers must be saved before the function
+ starts to use them for its own purposes.
+
+`__builtin_args_info (CATEGORY)'
+ Use this built-in function to find the first anonymous arguments in
+ registers.
+
+ In general, a machine may have several categories of registers
+ used for arguments, each for a particular category of data types.
+ (For example, on some machines, floating-point registers are used
+ for floating-point arguments while other arguments are passed in
+ the general registers.) To make non-varargs functions use the
+ proper calling convention, you have defined the `CUMULATIVE_ARGS'
+ data type to record how many registers in each category have been
+ used so far
+
+ `__builtin_args_info' accesses the same data structure of type
+ `CUMULATIVE_ARGS' after the ordinary argument layout is finished
+ with it, with CATEGORY specifying which word to access. Thus, the
+ value indicates the first unused register in a given category.
+
+ Normally, you would use `__builtin_args_info' in the implementation
+ of `va_start', accessing each category just once and storing the
+ value in the `va_list' object. This is because `va_list' will
+ have to update the values, and there is no way to alter the values
+ accessed by `__builtin_args_info'.
+
+`__builtin_next_arg (LASTARG)'
+ This is the equivalent of `__builtin_args_info', for stack
+ arguments. It returns the address of the first anonymous stack
+ argument, as type `void *'. If `ARGS_GROW_DOWNWARD', it returns
+ the address of the location above the first anonymous stack
+ argument. Use it in `va_start' to initialize the pointer for
+ fetching arguments from the stack. Also use it in `va_start' to
+ verify that the second parameter LASTARG is the last named argument
+ of the current function.
+
+`__builtin_classify_type (OBJECT)'
+ Since each machine has its own conventions for which data types are
+ passed in which kind of register, your implementation of `va_arg'
+ has to embody these conventions. The easiest way to categorize the
+ specified data type is to use `__builtin_classify_type' together
+ with `sizeof' and `__alignof__'.
+
+ `__builtin_classify_type' ignores the value of OBJECT, considering
+ only its data type. It returns an integer describing what kind of
+ type that is--integer, floating, pointer, structure, and so on.
+
+ The file `typeclass.h' defines an enumeration that you can use to
+ interpret the values of `__builtin_classify_type'.
+
+ These machine description macros help implement varargs:
+
+`EXPAND_BUILTIN_SAVEREGS ()'
+ If defined, is a C expression that produces the machine-specific
+ code for a call to `__builtin_saveregs'. This code will be moved
+ to the very beginning of the function, before any parameter access
+ are made. The return value of this function should be an RTX that
+ contains the value to use as the return of `__builtin_saveregs'.
+
+`SETUP_INCOMING_VARARGS (ARGS_SO_FAR, MODE, TYPE, PRETEND_ARGS_SIZE, SECOND_TIME)'
+ This macro offers an alternative to using `__builtin_saveregs' and
+ defining the macro `EXPAND_BUILTIN_SAVEREGS'. Use it to store the
+ anonymous register arguments into the stack so that all the
+ arguments appear to have been passed consecutively on the stack.
+ Once this is done, you can use the standard implementation of
+ varargs that works for machines that pass all their arguments on
+ the stack.
+
+ The argument ARGS_SO_FAR is the `CUMULATIVE_ARGS' data structure,
+ containing the values that are obtained after processing the named
+ arguments. The arguments MODE and TYPE describe the last named
+ argument--its machine mode and its data type as a tree node.
+
+ The macro implementation should do two things: first, push onto the
+ stack all the argument registers _not_ used for the named
+ arguments, and second, store the size of the data thus pushed into
+ the `int'-valued variable whose name is supplied as the argument
+ PRETEND_ARGS_SIZE. The value that you store here will serve as
+ additional offset for setting up the stack frame.
+
+ Because you must generate code to push the anonymous arguments at
+ compile time without knowing their data types,
+ `SETUP_INCOMING_VARARGS' is only useful on machines that have just
+ a single category of argument register and use it uniformly for
+ all data types.
+
+ If the argument SECOND_TIME is nonzero, it means that the
+ arguments of the function are being analyzed for the second time.
+ This happens for an inline function, which is not actually
+ compiled until the end of the source file. The macro
+ `SETUP_INCOMING_VARARGS' should not generate any instructions in
+ this case.
+
+`STRICT_ARGUMENT_NAMING'
+ Define this macro to be a nonzero value if the location where a
+ function argument is passed depends on whether or not it is a
+ named argument.
+
+ This macro controls how the NAMED argument to `FUNCTION_ARG' is
+ set for varargs and stdarg functions. If this macro returns a
+ nonzero value, the NAMED argument is always true for named
+ arguments, and false for unnamed arguments. If it returns a value
+ of zero, but `SETUP_INCOMING_VARARGS' is defined, then all
+ arguments are treated as named. Otherwise, all named arguments
+ except the last are treated as named.
+
+ You need not define this macro if it always returns zero.
+
+`PRETEND_OUTGOING_VARARGS_NAMED'
+ If you need to conditionally change ABIs so that one works with
+ `SETUP_INCOMING_VARARGS', but the other works like neither
+ `SETUP_INCOMING_VARARGS' nor `STRICT_ARGUMENT_NAMING' was defined,
+ then define this macro to return nonzero if
+ `SETUP_INCOMING_VARARGS' is used, zero otherwise. Otherwise, you
+ should not define this macro.
+
+\1f
+File: gccint.info, Node: Trampolines, Next: Library Calls, Prev: Varargs, Up: Target Macros
+
+10.12 Trampolines for Nested Functions
+======================================
+
+A "trampoline" is a small piece of code that is created at run time
+when the address of a nested function is taken. It normally resides on
+the stack, in the stack frame of the containing function. These macros
+tell GCC how to generate code to allocate and initialize a trampoline.
+
+ The instructions in the trampoline must do two things: load a
+constant address into the static chain register, and jump to the real
+address of the nested function. On CISC machines such as the m68k,
+this requires two instructions, a move immediate and a jump. Then the
+two addresses exist in the trampoline as word-long immediate operands.
+On RISC machines, it is often necessary to load each address into a
+register in two parts. Then pieces of each address form separate
+immediate operands.
+
+ The code generated to initialize the trampoline must store the
+variable parts--the static chain value and the function address--into
+the immediate operands of the instructions. On a CISC machine, this is
+simply a matter of copying each address to a memory reference at the
+proper offset from the start of the trampoline. On a RISC machine, it
+may be necessary to take out pieces of the address and store them
+separately.
+
+`TRAMPOLINE_TEMPLATE (FILE)'
+ A C statement to output, on the stream FILE, assembler code for a
+ block of data that contains the constant parts of a trampoline.
+ This code should not include a label--the label is taken care of
+ automatically.
+
+ If you do not define this macro, it means no template is needed
+ for the target. Do not define this macro on systems where the
+ block move code to copy the trampoline into place would be larger
+ than the code to generate it on the spot.
+
+`TRAMPOLINE_SECTION'
+ The name of a subroutine to switch to the section in which the
+ trampoline template is to be placed (*note Sections::). The
+ default is a value of `readonly_data_section', which places the
+ trampoline in the section containing read-only data.
+
+`TRAMPOLINE_SIZE'
+ A C expression for the size in bytes of the trampoline, as an
+ integer.
+
+`TRAMPOLINE_ALIGNMENT'
+ Alignment required for trampolines, in bits.
+
+ If you don't define this macro, the value of `BIGGEST_ALIGNMENT'
+ is used for aligning trampolines.
+
+`INITIALIZE_TRAMPOLINE (ADDR, FNADDR, STATIC_CHAIN)'
+ A C statement to initialize the variable parts of a trampoline.
+ ADDR is an RTX for the address of the trampoline; FNADDR is an RTX
+ for the address of the nested function; STATIC_CHAIN is an RTX for
+ the static chain value that should be passed to the function when
+ it is called.
+
+`TRAMPOLINE_ADJUST_ADDRESS (ADDR)'
+ A C statement that should perform any machine-specific adjustment
+ in the address of the trampoline. Its argument contains the
+ address that was passed to `INITIALIZE_TRAMPOLINE'. In case the
+ address to be used for a function call should be different from
+ the address in which the template was stored, the different
+ address should be assigned to ADDR. If this macro is not defined,
+ ADDR will be used for function calls.
+
+`ALLOCATE_TRAMPOLINE (FP)'
+ A C expression to allocate run-time space for a trampoline. The
+ expression value should be an RTX representing a memory reference
+ to the space for the trampoline.
+
+ If this macro is not defined, by default the trampoline is
+ allocated as a stack slot. This default is right for most
+ machines. The exceptions are machines where it is impossible to
+ execute instructions in the stack area. On such machines, you may
+ have to implement a separate stack, using this macro in
+ conjunction with `TARGET_ASM_FUNCTION_PROLOGUE' and
+ `TARGET_ASM_FUNCTION_EPILOGUE'.
+
+ FP points to a data structure, a `struct function', which
+ describes the compilation status of the immediate containing
+ function of the function which the trampoline is for. Normally
+ (when `ALLOCATE_TRAMPOLINE' is not defined), the stack slot for the
+ trampoline is in the stack frame of this containing function.
+ Other allocation strategies probably must do something analogous
+ with this information.
+
+ Implementing trampolines is difficult on many machines because they
+have separate instruction and data caches. Writing into a stack
+location fails to clear the memory in the instruction cache, so when
+the program jumps to that location, it executes the old contents.
+
+ Here are two possible solutions. One is to clear the relevant parts
+of the instruction cache whenever a trampoline is set up. The other is
+to make all trampolines identical, by having them jump to a standard
+subroutine. The former technique makes trampoline execution faster; the
+latter makes initialization faster.
+
+ To clear the instruction cache when a trampoline is initialized,
+define the following macros which describe the shape of the cache.
+
+`INSN_CACHE_SIZE'
+ The total size in bytes of the cache.
+
+`INSN_CACHE_LINE_WIDTH'
+ The length in bytes of each cache line. The cache is divided into
+ cache lines which are disjoint slots, each holding a contiguous
+ chunk of data fetched from memory. Each time data is brought into
+ the cache, an entire line is read at once. The data loaded into a
+ cache line is always aligned on a boundary equal to the line size.
+
+`INSN_CACHE_DEPTH'
+ The number of alternative cache lines that can hold any particular
+ memory location.
+
+ Alternatively, if the machine has system calls or instructions to
+clear the instruction cache directly, you can define the following
+macro.
+
+`CLEAR_INSN_CACHE (BEG, END)'
+ If defined, expands to a C expression clearing the _instruction
+ cache_ in the specified interval. If it is not defined, and the
+ macro `INSN_CACHE_SIZE' is defined, some generic code is generated
+ to clear the cache. The definition of this macro would typically
+ be a series of `asm' statements. Both BEG and END are both pointer
+ expressions.
+
+ To use a standard subroutine, define the following macro. In
+addition, you must make sure that the instructions in a trampoline fill
+an entire cache line with identical instructions, or else ensure that
+the beginning of the trampoline code is always aligned at the same
+point in its cache line. Look in `m68k.h' as a guide.
+
+`TRANSFER_FROM_TRAMPOLINE'
+ Define this macro if trampolines need a special subroutine to do
+ their work. The macro should expand to a series of `asm'
+ statements which will be compiled with GCC. They go in a library
+ function named `__transfer_from_trampoline'.
+
+ If you need to avoid executing the ordinary prologue code of a
+ compiled C function when you jump to the subroutine, you can do so
+ by placing a special label of your own in the assembler code. Use
+ one `asm' statement to generate an assembler label, and another to
+ make the label global. Then trampolines can use that label to
+ jump directly to your special assembler code.
+
+\1f
+File: gccint.info, Node: Library Calls, Next: Addressing Modes, Prev: Trampolines, Up: Target Macros
+
+10.13 Implicit Calls to Library Routines
+========================================
+
+Here is an explanation of implicit calls to library routines.
+
+`MULSI3_LIBCALL'
+ A C string constant giving the name of the function to call for
+ multiplication of one signed full-word by another. If you do not
+ define this macro, the default name is used, which is `__mulsi3',
+ a function defined in `libgcc.a'.
+
+`DIVSI3_LIBCALL'
+ A C string constant giving the name of the function to call for
+ division of one signed full-word by another. If you do not define
+ this macro, the default name is used, which is `__divsi3', a
+ function defined in `libgcc.a'.
+
+`UDIVSI3_LIBCALL'
+ A C string constant giving the name of the function to call for
+ division of one unsigned full-word by another. If you do not
+ define this macro, the default name is used, which is `__udivsi3',
+ a function defined in `libgcc.a'.
+
+`MODSI3_LIBCALL'
+ A C string constant giving the name of the function to call for the
+ remainder in division of one signed full-word by another. If you
+ do not define this macro, the default name is used, which is
+ `__modsi3', a function defined in `libgcc.a'.
+
+`UMODSI3_LIBCALL'
+ A C string constant giving the name of the function to call for the
+ remainder in division of one unsigned full-word by another. If
+ you do not define this macro, the default name is used, which is
+ `__umodsi3', a function defined in `libgcc.a'.
+
+`MULDI3_LIBCALL'
+ A C string constant giving the name of the function to call for
+ multiplication of one signed double-word by another. If you do not
+ define this macro, the default name is used, which is `__muldi3',
+ a function defined in `libgcc.a'.
+
+`DIVDI3_LIBCALL'
+ A C string constant giving the name of the function to call for
+ division of one signed double-word by another. If you do not
+ define this macro, the default name is used, which is `__divdi3', a
+ function defined in `libgcc.a'.
+
+`UDIVDI3_LIBCALL'
+ A C string constant giving the name of the function to call for
+ division of one unsigned full-word by another. If you do not
+ define this macro, the default name is used, which is `__udivdi3',
+ a function defined in `libgcc.a'.
+
+`MODDI3_LIBCALL'
+ A C string constant giving the name of the function to call for the
+ remainder in division of one signed double-word by another. If
+ you do not define this macro, the default name is used, which is
+ `__moddi3', a function defined in `libgcc.a'.
+
+`UMODDI3_LIBCALL'
+ A C string constant giving the name of the function to call for the
+ remainder in division of one unsigned full-word by another. If
+ you do not define this macro, the default name is used, which is
+ `__umoddi3', a function defined in `libgcc.a'.
+
+`INIT_TARGET_OPTABS'
+ Define this macro as a C statement that declares additional library
+ routines renames existing ones. `init_optabs' calls this macro
+ after initializing all the normal library routines.
+
+`FLOAT_LIB_COMPARE_RETURNS_BOOL'
+ Define this macro as a C statement that returns nonzero if a call
+ to the floating point comparison library function will return a
+ boolean value that indicates the result of the comparison. It
+ should return zero if one of gcc's own libgcc functions is called.
+
+ Most ports don't need to define this macro.
+
+`TARGET_EDOM'
+ The value of `EDOM' on the target machine, as a C integer constant
+ expression. If you don't define this macro, GCC does not attempt
+ to deposit the value of `EDOM' into `errno' directly. Look in
+ `/usr/include/errno.h' to find the value of `EDOM' on your system.
+
+ If you do not define `TARGET_EDOM', then compiled code reports
+ domain errors by calling the library function and letting it
+ report the error. If mathematical functions on your system use
+ `matherr' when there is an error, then you should leave
+ `TARGET_EDOM' undefined so that `matherr' is used normally.
+
+`GEN_ERRNO_RTX'
+ Define this macro as a C expression to create an rtl expression
+ that refers to the global "variable" `errno'. (On certain systems,
+ `errno' may not actually be a variable.) If you don't define this
+ macro, a reasonable default is used.
+
+`TARGET_MEM_FUNCTIONS'
+ Define this macro if GCC should generate calls to the ISO C (and
+ System V) library functions `memcpy', `memmove' and `memset'
+ rather than the BSD functions `bcopy' and `bzero'.
+
+`LIBGCC_NEEDS_DOUBLE'
+ Define this macro if `float' arguments cannot be passed to library
+ routines (so they must be converted to `double'). This macro
+ affects both how library calls are generated and how the library
+ routines in `libgcc.a' accept their arguments. It is useful on
+ machines where floating and fixed point arguments are passed
+ differently, such as the i860.
+
+`NEXT_OBJC_RUNTIME'
+ Define this macro to generate code for Objective-C message sending
+ using the calling convention of the NeXT system. This calling
+ convention involves passing the object, the selector and the
+ method arguments all at once to the method-lookup library function.
+
+ The default calling convention passes just the object and the
+ selector to the lookup function, which returns a pointer to the
+ method.
+
+\1f
+File: gccint.info, Node: Addressing Modes, Next: Condition Code, Prev: Library Calls, Up: Target Macros
+
+10.14 Addressing Modes
+======================
+
+This is about addressing modes.
+
+`HAVE_PRE_INCREMENT'
+`HAVE_PRE_DECREMENT'
+`HAVE_POST_INCREMENT'
+`HAVE_POST_DECREMENT'
+ A C expression that is nonzero if the machine supports
+ pre-increment, pre-decrement, post-increment, or post-decrement
+ addressing respectively.
+
+`HAVE_PRE_MODIFY_DISP'
+`HAVE_POST_MODIFY_DISP'
+ A C expression that is nonzero if the machine supports pre- or
+ post-address side-effect generation involving constants other than
+ the size of the memory operand.
+
+`HAVE_PRE_MODIFY_REG'
+`HAVE_POST_MODIFY_REG'
+ A C expression that is nonzero if the machine supports pre- or
+ post-address side-effect generation involving a register
+ displacement.
+
+`CONSTANT_ADDRESS_P (X)'
+ A C expression that is 1 if the RTX X is a constant which is a
+ valid address. On most machines, this can be defined as
+ `CONSTANT_P (X)', but a few machines are more restrictive in which
+ constant addresses are supported.
+
+ `CONSTANT_P' accepts integer-values expressions whose values are
+ not explicitly known, such as `symbol_ref', `label_ref', and
+ `high' expressions and `const' arithmetic expressions, in addition
+ to `const_int' and `const_double' expressions.
+
+`MAX_REGS_PER_ADDRESS'
+ A number, the maximum number of registers that can appear in a
+ valid memory address. Note that it is up to you to specify a
+ value equal to the maximum number that `GO_IF_LEGITIMATE_ADDRESS'
+ would ever accept.
+
+`GO_IF_LEGITIMATE_ADDRESS (MODE, X, LABEL)'
+ A C compound statement with a conditional `goto LABEL;' executed
+ if X (an RTX) is a legitimate memory address on the target machine
+ for a memory operand of mode MODE.
+
+ It usually pays to define several simpler macros to serve as
+ subroutines for this one. Otherwise it may be too complicated to
+ understand.
+
+ This macro must exist in two variants: a strict variant and a
+ non-strict one. The strict variant is used in the reload pass. It
+ must be defined so that any pseudo-register that has not been
+ allocated a hard register is considered a memory reference. In
+ contexts where some kind of register is required, a pseudo-register
+ with no hard register must be rejected.
+
+ The non-strict variant is used in other passes. It must be
+ defined to accept all pseudo-registers in every context where some
+ kind of register is required.
+
+ Compiler source files that want to use the strict variant of this
+ macro define the macro `REG_OK_STRICT'. You should use an `#ifdef
+ REG_OK_STRICT' conditional to define the strict variant in that
+ case and the non-strict variant otherwise.
+
+ Subroutines to check for acceptable registers for various purposes
+ (one for base registers, one for index registers, and so on) are
+ typically among the subroutines used to define
+ `GO_IF_LEGITIMATE_ADDRESS'. Then only these subroutine macros
+ need have two variants; the higher levels of macros may be the
+ same whether strict or not.
+
+ Normally, constant addresses which are the sum of a `symbol_ref'
+ and an integer are stored inside a `const' RTX to mark them as
+ constant. Therefore, there is no need to recognize such sums
+ specifically as legitimate addresses. Normally you would simply
+ recognize any `const' as legitimate.
+
+ Usually `PRINT_OPERAND_ADDRESS' is not prepared to handle constant
+ sums that are not marked with `const'. It assumes that a naked
+ `plus' indicates indexing. If so, then you _must_ reject such
+ naked constant sums as illegitimate addresses, so that none of
+ them will be given to `PRINT_OPERAND_ADDRESS'.
+
+ On some machines, whether a symbolic address is legitimate depends
+ on the section that the address refers to. On these machines,
+ define the macro `ENCODE_SECTION_INFO' to store the information
+ into the `symbol_ref', and then check for it here. When you see a
+ `const', you will have to look inside it to find the `symbol_ref'
+ in order to determine the section. *Note Assembler Format::.
+
+ The best way to modify the name string is by adding text to the
+ beginning, with suitable punctuation to prevent any ambiguity.
+ Allocate the new name in `saveable_obstack'. You will have to
+ modify `ASM_OUTPUT_LABELREF' to remove and decode the added text
+ and output the name accordingly, and define `STRIP_NAME_ENCODING'
+ to access the original name string.
+
+ You can check the information stored here into the `symbol_ref' in
+ the definitions of the macros `GO_IF_LEGITIMATE_ADDRESS' and
+ `PRINT_OPERAND_ADDRESS'.
+
+`REG_OK_FOR_BASE_P (X)'
+ A C expression that is nonzero if X (assumed to be a `reg' RTX) is
+ valid for use as a base register. For hard registers, it should
+ always accept those which the hardware permits and reject the
+ others. Whether the macro accepts or rejects pseudo registers
+ must be controlled by `REG_OK_STRICT' as described above. This
+ usually requires two variant definitions, of which `REG_OK_STRICT'
+ controls the one actually used.
+
+`REG_MODE_OK_FOR_BASE_P (X, MODE)'
+ A C expression that is just like `REG_OK_FOR_BASE_P', except that
+ that expression may examine the mode of the memory reference in
+ MODE. You should define this macro if the mode of the memory
+ reference affects whether a register may be used as a base
+ register. If you define this macro, the compiler will use it
+ instead of `REG_OK_FOR_BASE_P'.
+
+`REG_OK_FOR_INDEX_P (X)'
+ A C expression that is nonzero if X (assumed to be a `reg' RTX) is
+ valid for use as an index register.
+
+ The difference between an index register and a base register is
+ that the index register may be scaled. If an address involves the
+ sum of two registers, neither one of them scaled, then either one
+ may be labeled the "base" and the other the "index"; but whichever
+ labeling is used must fit the machine's constraints of which
+ registers may serve in each capacity. The compiler will try both
+ labelings, looking for one that is valid, and will reload one or
+ both registers only if neither labeling works.
+
+`FIND_BASE_TERM (X)'
+ A C expression to determine the base term of address X. This
+ macro is used in only one place: `find_base_term' in alias.c.
+
+ It is always safe for this macro to not be defined. It exists so
+ that alias analysis can understand machine-dependent addresses.
+
+ The typical use of this macro is to handle addresses containing a
+ label_ref or symbol_ref within an UNSPEC.
+
+`LEGITIMIZE_ADDRESS (X, OLDX, MODE, WIN)'
+ A C compound statement that attempts to replace X with a valid
+ memory address for an operand of mode MODE. WIN will be a C
+ statement label elsewhere in the code; the macro definition may use
+
+ GO_IF_LEGITIMATE_ADDRESS (MODE, X, WIN);
+
+ to avoid further processing if the address has become legitimate.
+
+ X will always be the result of a call to `break_out_memory_refs',
+ and OLDX will be the operand that was given to that function to
+ produce X.
+
+ The code generated by this macro should not alter the substructure
+ of X. If it transforms X into a more legitimate form, it should
+ assign X (which will always be a C variable) a new value.
+
+ It is not necessary for this macro to come up with a legitimate
+ address. The compiler has standard ways of doing so in all cases.
+ In fact, it is safe for this macro to do nothing. But often a
+ machine-dependent strategy can generate better code.
+
+`LEGITIMIZE_RELOAD_ADDRESS (X, MODE, OPNUM, TYPE, IND_LEVELS, WIN)'
+ A C compound statement that attempts to replace X, which is an
+ address that needs reloading, with a valid memory address for an
+ operand of mode MODE. WIN will be a C statement label elsewhere
+ in the code. It is not necessary to define this macro, but it
+ might be useful for performance reasons.
+
+ For example, on the i386, it is sometimes possible to use a single
+ reload register instead of two by reloading a sum of two pseudo
+ registers into a register. On the other hand, for number of RISC
+ processors offsets are limited so that often an intermediate
+ address needs to be generated in order to address a stack slot.
+ By defining `LEGITIMIZE_RELOAD_ADDRESS' appropriately, the
+ intermediate addresses generated for adjacent some stack slots can
+ be made identical, and thus be shared.
+
+ _Note_: This macro should be used with caution. It is necessary
+ to know something of how reload works in order to effectively use
+ this, and it is quite easy to produce macros that build in too
+ much knowledge of reload internals.
+
+ _Note_: This macro must be able to reload an address created by a
+ previous invocation of this macro. If it fails to handle such
+ addresses then the compiler may generate incorrect code or abort.
+
+ The macro definition should use `push_reload' to indicate parts
+ that need reloading; OPNUM, TYPE and IND_LEVELS are usually
+ suitable to be passed unaltered to `push_reload'.
+
+ The code generated by this macro must not alter the substructure of
+ X. If it transforms X into a more legitimate form, it should
+ assign X (which will always be a C variable) a new value. This
+ also applies to parts that you change indirectly by calling
+ `push_reload'.
+
+ The macro definition may use `strict_memory_address_p' to test if
+ the address has become legitimate.
+
+ If you want to change only a part of X, one standard way of doing
+ this is to use `copy_rtx'. Note, however, that is unshares only a
+ single level of rtl. Thus, if the part to be changed is not at the
+ top level, you'll need to replace first the top level. It is not
+ necessary for this macro to come up with a legitimate address;
+ but often a machine-dependent strategy can generate better code.
+
+`GO_IF_MODE_DEPENDENT_ADDRESS (ADDR, LABEL)'
+ A C statement or compound statement with a conditional `goto
+ LABEL;' executed if memory address X (an RTX) can have different
+ meanings depending on the machine mode of the memory reference it
+ is used for or if the address is valid for some modes but not
+ others.
+
+ Autoincrement and autodecrement addresses typically have
+ mode-dependent effects because the amount of the increment or
+ decrement is the size of the operand being addressed. Some
+ machines have other mode-dependent addresses. Many RISC machines
+ have no mode-dependent addresses.
+
+ You may assume that ADDR is a valid address for the machine.
+
+`LEGITIMATE_CONSTANT_P (X)'
+ A C expression that is nonzero if X is a legitimate constant for
+ an immediate operand on the target machine. You can assume that X
+ satisfies `CONSTANT_P', so you need not check this. In fact, `1'
+ is a suitable definition for this macro on machines where anything
+ `CONSTANT_P' is valid.
+
+\1f
+File: gccint.info, Node: Condition Code, Next: Costs, Prev: Addressing Modes, Up: Target Macros
+
+10.15 Condition Code Status
+===========================
+
+This describes the condition code status.
+
+ The file `conditions.h' defines a variable `cc_status' to describe
+how the condition code was computed (in case the interpretation of the
+condition code depends on the instruction that it was set by). This
+variable contains the RTL expressions on which the condition code is
+currently based, and several standard flags.
+
+ Sometimes additional machine-specific flags must be defined in the
+machine description header file. It can also add additional
+machine-specific information by defining `CC_STATUS_MDEP'.
+
+`CC_STATUS_MDEP'
+ C code for a data type which is used for declaring the `mdep'
+ component of `cc_status'. It defaults to `int'.
+
+ This macro is not used on machines that do not use `cc0'.
+
+`CC_STATUS_MDEP_INIT'
+ A C expression to initialize the `mdep' field to "empty". The
+ default definition does nothing, since most machines don't use the
+ field anyway. If you want to use the field, you should probably
+ define this macro to initialize it.
+
+ This macro is not used on machines that do not use `cc0'.
+
+`NOTICE_UPDATE_CC (EXP, INSN)'
+ A C compound statement to set the components of `cc_status'
+ appropriately for an insn INSN whose body is EXP. It is this
+ macro's responsibility to recognize insns that set the condition
+ code as a byproduct of other activity as well as those that
+ explicitly set `(cc0)'.
+
+ This macro is not used on machines that do not use `cc0'.
+
+ If there are insns that do not set the condition code but do alter
+ other machine registers, this macro must check to see whether they
+ invalidate the expressions that the condition code is recorded as
+ reflecting. For example, on the 68000, insns that store in address
+ registers do not set the condition code, which means that usually
+ `NOTICE_UPDATE_CC' can leave `cc_status' unaltered for such insns.
+ But suppose that the previous insn set the condition code based on
+ location `a4@(102)' and the current insn stores a new value in
+ `a4'. Although the condition code is not changed by this, it will
+ no longer be true that it reflects the contents of `a4@(102)'.
+ Therefore, `NOTICE_UPDATE_CC' must alter `cc_status' in this case
+ to say that nothing is known about the condition code value.
+
+ The definition of `NOTICE_UPDATE_CC' must be prepared to deal with
+ the results of peephole optimization: insns whose patterns are
+ `parallel' RTXs containing various `reg', `mem' or constants which
+ are just the operands. The RTL structure of these insns is not
+ sufficient to indicate what the insns actually do. What
+ `NOTICE_UPDATE_CC' should do when it sees one is just to run
+ `CC_STATUS_INIT'.
+
+ A possible definition of `NOTICE_UPDATE_CC' is to call a function
+ that looks at an attribute (*note Insn Attributes::) named, for
+ example, `cc'. This avoids having detailed information about
+ patterns in two places, the `md' file and in `NOTICE_UPDATE_CC'.
+
+`EXTRA_CC_MODES'
+ A list of additional modes for condition code values in registers
+ (*note Jump Patterns::). This macro should expand to a sequence of
+ calls of the macro `CC' separated by white space. `CC' takes two
+ arguments. The first is the enumeration name of the mode, which
+ should begin with `CC' and end with `mode'. The second is a C
+ string giving the printable name of the mode; it should be the
+ same as the first argument, but with the trailing `mode' removed.
+
+ You should only define this macro if additional modes are required.
+
+ A sample definition of `EXTRA_CC_MODES' is:
+ #define EXTRA_CC_MODES \
+ CC(CC_NOOVmode, "CC_NOOV") \
+ CC(CCFPmode, "CCFP") \
+ CC(CCFPEmode, "CCFPE")
+
+`SELECT_CC_MODE (OP, X, Y)'
+ Returns a mode from class `MODE_CC' to be used when comparison
+ operation code OP is applied to rtx X and Y. For example, on the
+ Sparc, `SELECT_CC_MODE' is defined as (see *note Jump Patterns::
+ for a description of the reason for this definition)
+
+ #define SELECT_CC_MODE(OP,X,Y) \
+ (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \
+ ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \
+ : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \
+ || GET_CODE (X) == NEG) \
+ ? CC_NOOVmode : CCmode))
+
+ You need not define this macro if `EXTRA_CC_MODES' is not defined.
+
+`CANONICALIZE_COMPARISON (CODE, OP0, OP1)'
+ On some machines not all possible comparisons are defined, but you
+ can convert an invalid comparison into a valid one. For example,
+ the Alpha does not have a `GT' comparison, but you can use an `LT'
+ comparison instead and swap the order of the operands.
+
+ On such machines, define this macro to be a C statement to do any
+ required conversions. CODE is the initial comparison code and OP0
+ and OP1 are the left and right operands of the comparison,
+ respectively. You should modify CODE, OP0, and OP1 as required.
+
+ GCC will not assume that the comparison resulting from this macro
+ is valid but will see if the resulting insn matches a pattern in
+ the `md' file.
+
+ You need not define this macro if it would never change the
+ comparison code or operands.
+
+`REVERSIBLE_CC_MODE (MODE)'
+ A C expression whose value is one if it is always safe to reverse a
+ comparison whose mode is MODE. If `SELECT_CC_MODE' can ever
+ return MODE for a floating-point inequality comparison, then
+ `REVERSIBLE_CC_MODE (MODE)' must be zero.
+
+ You need not define this macro if it would always returns zero or
+ if the floating-point format is anything other than
+ `IEEE_FLOAT_FORMAT'. For example, here is the definition used on
+ the Sparc, where floating-point inequality comparisons are always
+ given `CCFPEmode':
+
+ #define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode)
+
+ A C expression whose value is reversed condition code of the CODE
+ for comparison done in CC_MODE MODE. The macro is used only in
+ case `REVERSIBLE_CC_MODE (MODE)' is nonzero. Define this macro in
+ case machine has some non-standard way how to reverse certain
+ conditionals. For instance in case all floating point conditions
+ are non-trapping, compiler may freely convert unordered compares
+ to ordered one. Then definition may look like:
+
+ #define REVERSE_CONDITION(CODE, MODE) \
+ ((MODE) != CCFPmode ? reverse_condition (CODE) \
+ : reverse_condition_maybe_unordered (CODE))
+
+`REVERSE_CONDEXEC_PREDICATES_P (CODE1, CODE2)'
+ A C expression that returns true if the conditional execution
+ predicate CODE1 is the inverse of CODE2 and vice versa. Define
+ this to return 0 if the target has conditional execution
+ predicates that cannot be reversed safely. If no expansion is
+ specified, this macro is defined as follows:
+
+ #define REVERSE_CONDEXEC_PREDICATES_P (x, y) \
+ ((x) == reverse_condition (y))
+
+
+\1f
+File: gccint.info, Node: Costs, Next: Scheduling, Prev: Condition Code, Up: Target Macros
+
+10.16 Describing Relative Costs of Operations
+=============================================
+
+These macros let you describe the relative speed of various operations
+on the target machine.
+
+`CONST_COSTS (X, CODE, OUTER_CODE)'
+ A part of a C `switch' statement that describes the relative costs
+ of constant RTL expressions. It must contain `case' labels for
+ expression codes `const_int', `const', `symbol_ref', `label_ref'
+ and `const_double'. Each case must ultimately reach a `return'
+ statement to return the relative cost of the use of that kind of
+ constant value in an expression. The cost may depend on the
+ precise value of the constant, which is available for examination
+ in X, and the rtx code of the expression in which it is contained,
+ found in OUTER_CODE.
+
+ CODE is the expression code--redundant, since it can be obtained
+ with `GET_CODE (X)'.
+
+`RTX_COSTS (X, CODE, OUTER_CODE)'
+ Like `CONST_COSTS' but applies to nonconstant RTL expressions.
+ This can be used, for example, to indicate how costly a multiply
+ instruction is. In writing this macro, you can use the construct
+ `COSTS_N_INSNS (N)' to specify a cost equal to N fast
+ instructions. OUTER_CODE is the code of the expression in which X
+ is contained.
+
+ This macro is optional; do not define it if the default cost
+ assumptions are adequate for the target machine.
+
+`DEFAULT_RTX_COSTS (X, CODE, OUTER_CODE)'
+ This macro, if defined, is called for any case not handled by the
+ `RTX_COSTS' or `CONST_COSTS' macros. This eliminates the need to
+ put case labels into the macro, but the code, or any functions it
+ calls, must assume that the RTL in X could be of any type that has
+ not already been handled. The arguments are the same as for
+ `RTX_COSTS', and the macro should execute a return statement giving
+ the cost of any RTL expressions that it can handle. The default
+ cost calculation is used for any RTL for which this macro does not
+ return a value.
+
+ This macro is optional; do not define it if the default cost
+ assumptions are adequate for the target machine.
+
+`ADDRESS_COST (ADDRESS)'
+ An expression giving the cost of an addressing mode that contains
+ ADDRESS. If not defined, the cost is computed from the ADDRESS
+ expression and the `CONST_COSTS' values.
+
+ For most CISC machines, the default cost is a good approximation
+ of the true cost of the addressing mode. However, on RISC
+ machines, all instructions normally have the same length and
+ execution time. Hence all addresses will have equal costs.
+
+ In cases where more than one form of an address is known, the form
+ with the lowest cost will be used. If multiple forms have the
+ same, lowest, cost, the one that is the most complex will be used.
+
+ For example, suppose an address that is equal to the sum of a
+ register and a constant is used twice in the same basic block.
+ When this macro is not defined, the address will be computed in a
+ register and memory references will be indirect through that
+ register. On machines where the cost of the addressing mode
+ containing the sum is no higher than that of a simple indirect
+ reference, this will produce an additional instruction and
+ possibly require an additional register. Proper specification of
+ this macro eliminates this overhead for such machines.
+
+ Similar use of this macro is made in strength reduction of loops.
+
+ ADDRESS need not be valid as an address. In such a case, the cost
+ is not relevant and can be any value; invalid addresses need not be
+ assigned a different cost.
+
+ On machines where an address involving more than one register is as
+ cheap as an address computation involving only one register,
+ defining `ADDRESS_COST' to reflect this can cause two registers to
+ be live over a region of code where only one would have been if
+ `ADDRESS_COST' were not defined in that manner. This effect should
+ be considered in the definition of this macro. Equivalent costs
+ should probably only be given to addresses with different numbers
+ of registers on machines with lots of registers.
+
+ This macro will normally either not be defined or be defined as a
+ constant.
+
+`REGISTER_MOVE_COST (MODE, FROM, TO)'
+ A C expression for the cost of moving data of mode MODE from a
+ register in class FROM to one in class TO. The classes are
+ expressed using the enumeration values such as `GENERAL_REGS'. A
+ value of 2 is the default; other values are interpreted relative to
+ that.
+
+ It is not required that the cost always equal 2 when FROM is the
+ same as TO; on some machines it is expensive to move between
+ registers if they are not general registers.
+
+ If reload sees an insn consisting of a single `set' between two
+ hard registers, and if `REGISTER_MOVE_COST' applied to their
+ classes returns a value of 2, reload does not check to ensure that
+ the constraints of the insn are met. Setting a cost of other than
+ 2 will allow reload to verify that the constraints are met. You
+ should do this if the `movM' pattern's constraints do not allow
+ such copying.
+
+`MEMORY_MOVE_COST (MODE, CLASS, IN)'
+ A C expression for the cost of moving data of mode MODE between a
+ register of class CLASS and memory; IN is zero if the value is to
+ be written to memory, nonzero if it is to be read in. This cost
+ is relative to those in `REGISTER_MOVE_COST'. If moving between
+ registers and memory is more expensive than between two registers,
+ you should define this macro to express the relative cost.
+
+ If you do not define this macro, GCC uses a default cost of 4 plus
+ the cost of copying via a secondary reload register, if one is
+ needed. If your machine requires a secondary reload register to
+ copy between memory and a register of CLASS but the reload
+ mechanism is more complex than copying via an intermediate, define
+ this macro to reflect the actual cost of the move.
+
+ GCC defines the function `memory_move_secondary_cost' if secondary
+ reloads are needed. It computes the costs due to copying via a
+ secondary register. If your machine copies from memory using a
+ secondary register in the conventional way but the default base
+ value of 4 is not correct for your machine, define this macro to
+ add some other value to the result of that function. The
+ arguments to that function are the same as to this macro.
+
+`BRANCH_COST'
+ A C expression for the cost of a branch instruction. A value of 1
+ is the default; other values are interpreted relative to that.
+
+ Here are additional macros which do not specify precise relative
+costs, but only that certain actions are more expensive than GCC would
+ordinarily expect.
+
+`SLOW_BYTE_ACCESS'
+ Define this macro as a C expression which is nonzero if accessing
+ less than a word of memory (i.e. a `char' or a `short') is no
+ faster than accessing a word of memory, i.e., if such access
+ require more than one instruction or if there is no difference in
+ cost between byte and (aligned) word loads.
+
+ When this macro is not defined, the compiler will access a field by
+ finding the smallest containing object; when it is defined, a
+ fullword load will be used if alignment permits. Unless bytes
+ accesses are faster than word accesses, using word accesses is
+ preferable since it may eliminate subsequent memory access if
+ subsequent accesses occur to other fields in the same word of the
+ structure, but to different bytes.
+
+`SLOW_UNALIGNED_ACCESS (MODE, ALIGNMENT)'
+ Define this macro to be the value 1 if memory accesses described
+ by the MODE and ALIGNMENT parameters have a cost many times greater
+ than aligned accesses, for example if they are emulated in a trap
+ handler.
+
+ When this macro is nonzero, the compiler will act as if
+ `STRICT_ALIGNMENT' were nonzero when generating code for block
+ moves. This can cause significantly more instructions to be
+ produced. Therefore, do not set this macro nonzero if unaligned
+ accesses only add a cycle or two to the time for a memory access.
+
+ If the value of this macro is always zero, it need not be defined.
+ If this macro is defined, it should produce a nonzero value when
+ `STRICT_ALIGNMENT' is nonzero.
+
+`DONT_REDUCE_ADDR'
+ Define this macro to inhibit strength reduction of memory
+ addresses. (On some machines, such strength reduction seems to do
+ harm rather than good.)
+
+`MOVE_RATIO'
+ The threshold of number of scalar memory-to-memory move insns,
+ _below_ which a sequence of insns should be generated instead of a
+ string move insn or a library call. Increasing the value will
+ always make code faster, but eventually incurs high cost in
+ increased code size.
+
+ Note that on machines where the corresponding move insn is a
+ `define_expand' that emits a sequence of insns, this macro counts
+ the number of such sequences.
+
+ If you don't define this, a reasonable default is used.
+
+`MOVE_BY_PIECES_P (SIZE, ALIGNMENT)'
+ A C expression used to determine whether `move_by_pieces' will be
+ used to copy a chunk of memory, or whether some other block move
+ mechanism will be used. Defaults to 1 if `move_by_pieces_ninsns'
+ returns less than `MOVE_RATIO'.
+
+`MOVE_MAX_PIECES'
+ A C expression used by `move_by_pieces' to determine the largest
+ unit a load or store used to copy memory is. Defaults to
+ `MOVE_MAX'.
+
+`USE_LOAD_POST_INCREMENT (MODE)'
+ A C expression used to determine whether a load postincrement is a
+ good thing to use for a given mode. Defaults to the value of
+ `HAVE_POST_INCREMENT'.
+
+`USE_LOAD_POST_DECREMENT (MODE)'
+ A C expression used to determine whether a load postdecrement is a
+ good thing to use for a given mode. Defaults to the value of
+ `HAVE_POST_DECREMENT'.
+
+`USE_LOAD_PRE_INCREMENT (MODE)'
+ A C expression used to determine whether a load preincrement is a
+ good thing to use for a given mode. Defaults to the value of
+ `HAVE_PRE_INCREMENT'.
+
+`USE_LOAD_PRE_DECREMENT (MODE)'
+ A C expression used to determine whether a load predecrement is a
+ good thing to use for a given mode. Defaults to the value of
+ `HAVE_PRE_DECREMENT'.
+
+`USE_STORE_POST_INCREMENT (MODE)'
+ A C expression used to determine whether a store postincrement is
+ a good thing to use for a given mode. Defaults to the value of
+ `HAVE_POST_INCREMENT'.
+
+`USE_STORE_POST_DECREMENT (MODE)'
+ A C expression used to determine whether a store postdecrement is
+ a good thing to use for a given mode. Defaults to the value of
+ `HAVE_POST_DECREMENT'.
+
+`USE_STORE_PRE_INCREMENT (MODE)'
+ This macro is used to determine whether a store preincrement is a
+ good thing to use for a given mode. Defaults to the value of
+ `HAVE_PRE_INCREMENT'.
+
+`USE_STORE_PRE_DECREMENT (MODE)'
+ This macro is used to determine whether a store predecrement is a
+ good thing to use for a given mode. Defaults to the value of
+ `HAVE_PRE_DECREMENT'.
+
+`NO_FUNCTION_CSE'
+ Define this macro if it is as good or better to call a constant
+ function address than to call an address kept in a register.
+
+`NO_RECURSIVE_FUNCTION_CSE'
+ Define this macro if it is as good or better for a function to call
+ itself with an explicit address than to call an address kept in a
+ register.
+
+\1f
+File: gccint.info, Node: Scheduling, Next: Sections, Prev: Costs, Up: Target Macros
+
+10.17 Adjusting the Instruction Scheduler
+=========================================
+
+The instruction scheduler may need a fair amount of machine-specific
+adjustment in order to produce good code. GCC provides several target
+hooks for this purpose. It is usually enough to define just a few of
+them: try the first ones in this list first.
+
+ -- Target Hook: int TARGET_SCHED_ISSUE_RATE (void)
+ This hook returns the maximum number of instructions that can ever
+ issue at the same time on the target machine. The default is one.
+ This value must be constant over the entire compilation. If you
+ need it to vary depending on what the instructions are, you must
+ use `TARGET_SCHED_VARIABLE_ISSUE'.
+
+ -- Target Hook: int TARGET_SCHED_VARIABLE_ISSUE (FILE *FILE, int
+ VERBOSE, rtx INSN, int MORE)
+ This hook is executed by the scheduler after it has scheduled an
+ insn from the ready list. It should return the number of insns
+ which can still be issued in the current cycle. Normally this is
+ `MORE - 1'. You should define this hook if some insns take more
+ machine resources than others, so that fewer insns can follow them
+ in the same cycle. FILE is either a null pointer, or a stdio
+ stream to write any debug output to. VERBOSE is the verbose level
+ provided by `-fsched-verbose-N'. INSN is the instruction that was
+ scheduled.
+
+ -- Target Hook: int TARGET_SCHED_ADJUST_COST (rtx INSN, rtx LINK, rtx
+ DEP_INSN, int COST)
+ This function corrects the value of COST based on the relationship
+ between INSN and DEP_INSN through the dependence LINK. It should
+ return the new value. The default is to make no adjustment to
+ COST. This can be used for example to specify to the scheduler
+ that an output- or anti-dependence does not incur the same cost as
+ a data-dependence.
+
+ -- Target Hook: int TARGET_SCHED_ADJUST_PRIORITY (rtx INSN, int
+ PRIORITY)
+ This hook adjusts the integer scheduling priority PRIORITY of
+ INSN. It should return the new priority. Reduce the priority to
+ execute INSN earlier, increase the priority to execute INSN later.
+ Do not define this hook if you do not need to adjust the
+ scheduling priorities of insns.
+
+ -- Target Hook: int TARGET_SCHED_REORDER (FILE *FILE, int VERBOSE, rtx
+ *READY, int *N_READYP, int CLOCK)
+ This hook is executed by the scheduler after it has scheduled the
+ ready list, to allow the machine description to reorder it (for
+ example to combine two small instructions together on `VLIW'
+ machines). FILE is either a null pointer, or a stdio stream to
+ write any debug output to. VERBOSE is the verbose level provided
+ by `-fsched-verbose-N'. READY is a pointer to the ready list of
+ instructions that are ready to be scheduled. N_READYP is a
+ pointer to the number of elements in the ready list. The scheduler
+ reads the ready list in reverse order, starting with
+ READY[*N_READYP-1] and going to READY[0]. CLOCK is the timer tick
+ of the scheduler. You may modify the ready list and the number of
+ ready insns. The return value is the number of insns that can
+ issue this cycle; normally this is just `issue_rate'. See also
+ `TARGET_SCHED_REORDER2'.
+
+ -- Target Hook: int TARGET_SCHED_REORDER2 (FILE *FILE, int VERBOSE,
+ rtx *READY, int *N_READY, CLOCK)
+ Like `TARGET_SCHED_REORDER', but called at a different time. That
+ function is called whenever the scheduler starts a new cycle.
+ This one is called once per iteration over a cycle, immediately
+ after `TARGET_SCHED_VARIABLE_ISSUE'; it can reorder the ready list
+ and return the number of insns to be scheduled in the same cycle.
+ Defining this hook can be useful if there are frequent situations
+ where scheduling one insn causes other insns to become ready in
+ the same cycle. These other insns can then be taken into account
+ properly.
+
+ -- Target Hook: void TARGET_SCHED_INIT (FILE *FILE, int VERBOSE, int
+ MAX_READY)
+ This hook is executed by the scheduler at the beginning of each
+ block of instructions that are to be scheduled. FILE is either a
+ null pointer, or a stdio stream to write any debug output to.
+ VERBOSE is the verbose level provided by `-fsched-verbose-N'.
+ MAX_READY is the maximum number of insns in the current scheduling
+ region that can be live at the same time. This can be used to
+ allocate scratch space if it is needed, e.g. by
+ `TARGET_SCHED_REORDER'.
+
+ -- Target Hook: void TARGET_SCHED_FINISH (FILE *FILE, int VERBOSE)
+ This hook is executed by the scheduler at the end of each block of
+ instructions that are to be scheduled. It can be used to perform
+ cleanup of any actions done by the other scheduling hooks. FILE
+ is either a null pointer, or a stdio stream to write any debug
+ output to. VERBOSE is the verbose level provided by
+ `-fsched-verbose-N'.
+
+ -- Target Hook: rtx TARGET_SCHED_CYCLE_DISPLAY (int CLOCK, rtx LAST)
+ This hook is called in verbose mode only, at the beginning of each
+ pass over a basic block. It should insert an insn into the chain
+ after LAST, which has no effect, but records the value CLOCK in
+ RTL dumps and assembly output. Define this hook only if you need
+ this level of detail about what the scheduler is doing.
+
+\1f
+File: gccint.info, Node: Sections, Next: PIC, Prev: Scheduling, Up: Target Macros
+
+10.18 Dividing the Output into Sections (Texts, Data, ...)
+==========================================================
+
+An object file is divided into sections containing different types of
+data. In the most common case, there are three sections: the "text
+section", which holds instructions and read-only data; the "data
+section", which holds initialized writable data; and the "bss section",
+which holds uninitialized data. Some systems have other kinds of
+sections.
+
+ The compiler must tell the assembler when to switch sections. These
+macros control what commands to output to tell the assembler this. You
+can also define additional sections.
+
+`TEXT_SECTION_ASM_OP'
+ A C expression whose value is a string, including spacing,
+ containing the assembler operation that should precede
+ instructions and read-only data. Normally `"\t.text"' is right.
+
+`TEXT_SECTION'
+ A C statement that switches to the default section containing
+ instructions. Normally this is not needed, as simply defining
+ `TEXT_SECTION_ASM_OP' is enough. The MIPS port uses this to sort
+ all functions after all data declarations.
+
+`DATA_SECTION_ASM_OP'
+ A C expression whose value is a string, including spacing,
+ containing the assembler operation to identify the following data
+ as writable initialized data. Normally `"\t.data"' is right.
+
+`SHARED_SECTION_ASM_OP'
+ If defined, a C expression whose value is a string, including
+ spacing, containing the assembler operation to identify the
+ following data as shared data. If not defined,
+ `DATA_SECTION_ASM_OP' will be used.
+
+`BSS_SECTION_ASM_OP'
+ If defined, a C expression whose value is a string, including
+ spacing, containing the assembler operation to identify the
+ following data as uninitialized global data. If not defined, and
+ neither `ASM_OUTPUT_BSS' nor `ASM_OUTPUT_ALIGNED_BSS' are defined,
+ uninitialized global data will be output in the data section if
+ `-fno-common' is passed, otherwise `ASM_OUTPUT_COMMON' will be
+ used.
+
+`SHARED_BSS_SECTION_ASM_OP'
+ If defined, a C expression whose value is a string, including
+ spacing, containing the assembler operation to identify the
+ following data as uninitialized global shared data. If not
+ defined, and `BSS_SECTION_ASM_OP' is, the latter will be used.
+
+`INIT_SECTION_ASM_OP'
+ If defined, a C expression whose value is a string, including
+ spacing, containing the assembler operation to identify the
+ following data as initialization code. If not defined, GCC will
+ assume such a section does not exist.
+
+`FINI_SECTION_ASM_OP'
+ If defined, a C expression whose value is a string, including
+ spacing, containing the assembler operation to identify the
+ following data as finalization code. If not defined, GCC will
+ assume such a section does not exist.
+
+`CRT_CALL_STATIC_FUNCTION (SECTION_OP, FUNCTION)'
+ If defined, an ASM statement that switches to a different section
+ via SECTION_OP, calls FUNCTION, and switches back to the text
+ section. This is used in `crtstuff.c' if `INIT_SECTION_ASM_OP' or
+ `FINI_SECTION_ASM_OP' to calls to initialization and finalization
+ functions from the init and fini sections. By default, this macro
+ uses a simple function call. Some ports need hand-crafted
+ assembly code to avoid dependencies on registers initialized in
+ the function prologue or to ensure that constant pools don't end
+ up too far way in the text section.
+
+`FORCE_CODE_SECTION_ALIGN'
+ If defined, an ASM statement that aligns a code section to some
+ arbitrary boundary. This is used to force all fragments of the
+ `.init' and `.fini' sections to have to same alignment and thus
+ prevent the linker from having to add any padding.
+
+`EXTRA_SECTIONS'
+ A list of names for sections other than the standard two, which are
+ `in_text' and `in_data'. You need not define this macro on a
+ system with no other sections (that GCC needs to use).
+
+`EXTRA_SECTION_FUNCTIONS'
+ One or more functions to be defined in `varasm.c'. These
+ functions should do jobs analogous to those of `text_section' and
+ `data_section', for your additional sections. Do not define this
+ macro if you do not define `EXTRA_SECTIONS'.
+
+`READONLY_DATA_SECTION'
+ On most machines, read-only variables, constants, and jump tables
+ are placed in the text section. If this is not the case on your
+ machine, this macro should be defined to be the name of a function
+ (either `data_section' or a function defined in `EXTRA_SECTIONS')
+ that switches to the section to be used for read-only items.
+
+ If these items should be placed in the text section, this macro
+ should not be defined.
+
+`SELECT_SECTION (EXP, RELOC, ALIGN)'
+ A C statement or statements to switch to the appropriate section
+ for output of EXP. You can assume that EXP is either a `VAR_DECL'
+ node or a constant of some sort. RELOC indicates whether the
+ initial value of EXP requires link-time relocations. Bit 1 is set
+ when variable contains local relocations only, while bit 2 is set
+ for global relocations. Select the section by calling
+ `text_section' or one of the alternatives for other sections.
+ ALIGN is the constant alignment in bits.
+
+ Do not define this macro if you put all read-only variables and
+ constants in the read-only data section (usually the text section).
+
+`SELECT_RTX_SECTION (MODE, RTX, ALIGN)'
+ A C statement or statements to switch to the appropriate section
+ for output of RTX in mode MODE. You can assume that RTX is some
+ kind of constant in RTL. The argument MODE is redundant except in
+ the case of a `const_int' rtx. Select the section by calling
+ `text_section' or one of the alternatives for other sections.
+ ALIGN is the constant alignment in bits.
+
+ Do not define this macro if you put all constants in the read-only
+ data section.
+
+`JUMP_TABLES_IN_TEXT_SECTION'
+ Define this macro to be an expression with a nonzero value if jump
+ tables (for `tablejump' insns) should be output in the text
+ section, along with the assembler instructions. Otherwise, the
+ readonly data section is used.
+
+ This macro is irrelevant if there is no separate readonly data
+ section.
+
+`ENCODE_SECTION_INFO (DECL)'
+ Define this macro if references to a symbol or a constant must be
+ treated differently depending on something about the variable or
+ function named by the symbol (such as what section it is in).
+
+ The macro definition, if any, is executed under two circumstances.
+ One is immediately after the rtl for DECL that represents a
+ variable or a function has been created and stored in `DECL_RTL
+ (DECL)'. The value of the rtl will be a `mem' whose address is a
+ `symbol_ref'. The other is immediately after the rtl for DECL
+ that represents a constant has been created and stored in
+ `TREE_CST_RTL (DECL)'. The macro is called once for each distinct
+ constant in a source file.
+
+ The usual thing for this macro to do is to record a flag in the
+ `symbol_ref' (such as `SYMBOL_REF_FLAG') or to store a modified
+ name string in the `symbol_ref' (if one bit is not enough
+ information).
+
+`STRIP_NAME_ENCODING (VAR, SYM_NAME)'
+ Decode SYM_NAME and store the real name part in VAR, sans the
+ characters that encode section info. Define this macro if
+ `ENCODE_SECTION_INFO' alters the symbol's name string.
+
+`UNIQUE_SECTION (DECL, RELOC)'
+ A C statement to build up a unique section name, expressed as a
+ `STRING_CST' node, and assign it to `DECL_SECTION_NAME (DECL)'.
+ RELOC indicates whether the initial value of EXP requires
+ link-time relocations. If you do not define this macro, GCC will
+ use the symbol name prefixed by `.' as the section name. Note -
+ this macro can now be called for uninitialized data items as well
+ as initialized data and functions.
+
+\1f
+File: gccint.info, Node: PIC, Next: Assembler Format, Prev: Sections, Up: Target Macros
+
+10.19 Position Independent Code
+===============================
+
+This section describes macros that help implement generation of position
+independent code. Simply defining these macros is not enough to
+generate valid PIC; you must also add support to the macros
+`GO_IF_LEGITIMATE_ADDRESS' and `PRINT_OPERAND_ADDRESS', as well as
+`LEGITIMIZE_ADDRESS'. You must modify the definition of `movsi' to do
+something appropriate when the source operand contains a symbolic
+address. You may also need to alter the handling of switch statements
+so that they use relative addresses.
+
+`PIC_OFFSET_TABLE_REGNUM'
+ The register number of the register used to address a table of
+ static data addresses in memory. In some cases this register is
+ defined by a processor's "application binary interface" (ABI).
+ When this macro is defined, RTL is generated for this register
+ once, as with the stack pointer and frame pointer registers. If
+ this macro is not defined, it is up to the machine-dependent files
+ to allocate such a register (if necessary). Note that this
+ register must be fixed when in use (e.g. when `flag_pic' is true).
+
+`PIC_OFFSET_TABLE_REG_CALL_CLOBBERED'
+ Define this macro if the register defined by
+ `PIC_OFFSET_TABLE_REGNUM' is clobbered by calls. Do not define
+ this macro if `PIC_OFFSET_TABLE_REGNUM' is not defined.
+
+`FINALIZE_PIC'
+ By generating position-independent code, when two different
+ programs (A and B) share a common library (libC.a), the text of
+ the library can be shared whether or not the library is linked at
+ the same address for both programs. In some of these
+ environments, position-independent code requires not only the use
+ of different addressing modes, but also special code to enable the
+ use of these addressing modes.
+
+ The `FINALIZE_PIC' macro serves as a hook to emit these special
+ codes once the function is being compiled into assembly code, but
+ not before. (It is not done before, because in the case of
+ compiling an inline function, it would lead to multiple PIC
+ prologues being included in functions which used inline functions
+ and were compiled to assembly language.)
+
+`LEGITIMATE_PIC_OPERAND_P (X)'
+ A C expression that is nonzero if X is a legitimate immediate
+ operand on the target machine when generating position independent
+ code. You can assume that X satisfies `CONSTANT_P', so you need
+ not check this. You can also assume FLAG_PIC is true, so you need
+ not check it either. You need not define this macro if all
+ constants (including `SYMBOL_REF') can be immediate operands when
+ generating position independent code.
+
+\1f
+File: gccint.info, Node: Assembler Format, Next: Debugging Info, Prev: PIC, Up: Target Macros
+
+10.20 Defining the Output Assembler Language
+============================================
+
+This section describes macros whose principal purpose is to describe how
+to write instructions in assembler language--rather than what the
+instructions do.
* Menu:
-* Namespaces:: Member functions, types, etc.
-* Classes:: Members, bases, friends, etc.
-
-\1f
-File: gccint.info, Node: Namespaces, Next: Classes, Up: Scopes
-
-Namespaces
-----------
-
- A namespace is represented by a `NAMESPACE_DECL' node.
-
- However, except for the fact that it is distinguished as the root of
-the representation, the global namespace is no different from any other
-namespace. Thus, in what follows, we describe namespaces generally,
-rather than the global namespace in particular.
-
- The following macros and functions can be used on a `NAMESPACE_DECL':
-
-`DECL_NAME'
- This macro is used to obtain the `IDENTIFIER_NODE' corresponding to
- the unqualified name of the name of the namespace (*note
- Identifiers::). The name of the global namespace is `::', even
- though in C++ the global namespace is unnamed. However, you
- should use comparison with `global_namespace', rather than
- `DECL_NAME' to determine whether or not a namespaces is the global
- one. An unnamed namespace will have a `DECL_NAME' equal to
- `anonymous_namespace_name'. Within a single translation unit, all
- unnamed namespaces will have the same name.
-
-`DECL_CONTEXT'
- This macro returns the enclosing namespace. The `DECL_CONTEXT' for
- the `global_namespace' is `NULL_TREE'.
-
-`DECL_NAMESPACE_ALIAS'
- If this declaration is for a namespace alias, then
- `DECL_NAMESPACE_ALIAS' is the namespace for which this one is an
- alias.
-
- Do not attempt to use `cp_namespace_decls' for a namespace which is
- an alias. Instead, follow `DECL_NAMESPACE_ALIAS' links until you
- reach an ordinary, non-alias, namespace, and call
- `cp_namespace_decls' there.
-
-`DECL_NAMESPACE_STD_P'
- This predicate holds if the namespace is the special `::std'
- namespace.
-
-`cp_namespace_decls'
- This function will return the declarations contained in the
- namespace, including types, overloaded functions, other
- namespaces, and so forth. If there are no declarations, this
- function will return `NULL_TREE'. The declarations are connected
- through their `TREE_CHAIN' fields.
-
- Although most entries on this list will be declarations,
- `TREE_LIST' nodes may also appear. In this case, the `TREE_VALUE'
- will be an `OVERLOAD'. The value of the `TREE_PURPOSE' is
- unspecified; back ends should ignore this value. As with the
- other kinds of declarations returned by `cp_namespace_decls', the
- `TREE_CHAIN' will point to the next declaration in this list.
-
- For more information on the kinds of declarations that can occur
- on this list, *Note Declarations::. Some declarations will not
- appear on this list. In particular, no `FIELD_DECL',
- `LABEL_DECL', or `PARM_DECL' nodes will appear here.
-
- This function cannot be used with namespaces that have
- `DECL_NAMESPACE_ALIAS' set.
-
-
-\1f
-File: gccint.info, Node: Classes, Prev: Namespaces, Up: Scopes
-
-Classes
--------
-
- A class type is represented by either a `RECORD_TYPE' or a
-`UNION_TYPE'. A class declared with the `union' tag is represented by
-a `UNION_TYPE', while classes declared with either the `struct' or the
-`class' tag are represented by `RECORD_TYPE's. You can use the
-`CLASSTYPE_DECLARED_CLASS' macro to discern whether or not a particular
-type is a `class' as opposed to a `struct'. This macro will be true
-only for classes declared with the `class' tag.
-
- Almost all non-function members are available on the `TYPE_FIELDS'
-list. Given one member, the next can be found by following the
-`TREE_CHAIN'. You should not depend in any way on the order in which
-fields appear on this list. All nodes on this list will be `DECL'
-nodes. A `FIELD_DECL' is used to represent a non-static data member, a
-`VAR_DECL' is used to represent a static data member, and a `TYPE_DECL'
-is used to represent a type. Note that the `CONST_DECL' for an
-enumeration constant will appear on this list, if the enumeration type
-was declared in the class. (Of course, the `TYPE_DECL' for the
-enumeration type will appear here as well.) There are no entries for
-base classes on this list. In particular, there is no `FIELD_DECL' for
-the "base-class portion" of an object.
-
- The `TYPE_VFIELD' is a compiler-generated field used to point to
-virtual function tables. It may or may not appear on the `TYPE_FIELDS'
-list. However, back ends should handle the `TYPE_VFIELD' just like all
-the entries on the `TYPE_FIELDS' list.
-
- The function members are available on the `TYPE_METHODS' list.
-Again, subsequent members are found by following the `TREE_CHAIN'
-field. If a function is overloaded, each of the overloaded functions
-appears; no `OVERLOAD' nodes appear on the `TYPE_METHODS' list.
-Implicitly declared functions (including default constructors, copy
-constructors, assignment operators, and destructors) will appear on
-this list as well.
-
- Every class has an associated "binfo", which can be obtained with
-`TYPE_BINFO'. Binfos are used to represent base-classes. The binfo
-given by `TYPE_BINFO' is the degenerate case, whereby every class is
-considered to be its own base-class. The base classes for a particular
-binfo can be obtained with `BINFO_BASETYPES'. These base-classes are
-themselves binfos. The class type associated with a binfo is given by
-`BINFO_TYPE'. It is always the case that `BINFO_TYPE (TYPE_BINFO (x))'
-is the same type as `x', up to qualifiers. However, it is not always
-the case that `TYPE_BINFO (BINFO_TYPE (y))' is always the same binfo as
-`y'. The reason is that if `y' is a binfo representing a base-class
-`B' of a derived class `D', then `BINFO_TYPE (y)' will be `B', and
-`TYPE_BINFO (BINFO_TYPE (y))' will be `B' as its own base-class, rather
-than as a base-class of `D'.
-
- The `BINFO_BASETYPES' is a `TREE_VEC' (*note Containers::). Base
-types appear in left-to-right order in this vector. You can tell
-whether or `public', `protected', or `private' inheritance was used by
-using the `TREE_VIA_PUBLIC', `TREE_VIA_PROTECTED', and
-`TREE_VIA_PRIVATE' macros. Each of these macros takes a `BINFO' and is
-true if and only if the indicated kind of inheritance was used. If
-`TREE_VIA_VIRTUAL' holds of a binfo, then its `BINFO_TYPE' was
-inherited from virtually.
-
- The following macros can be used on a tree node representing a
-class-type.
-
-`LOCAL_CLASS_P'
- This predicate holds if the class is local class _i.e._ declared
- inside a function body.
-
-`TYPE_POLYMORPHIC_P'
- This predicate holds if the class has at least one virtual function
- (declared or inherited).
-
-`TYPE_HAS_DEFAULT_CONSTRUCTOR'
- This predicate holds whenever its argument represents a class-type
- with default constructor.
-
-`CLASSTYPE_HAS_MUTABLE'
-
-`TYPE_HAS_MUTABLE_P'
- These predicates hold for a class-type having a mutable data
- member.
-
-`CLASSTYPE_NON_POD_P'
- This predicate holds only for class-types that are not PODs.
-
-`TYPE_HAS_NEW_OPERATOR'
- This predicate holds for a class-type that defines `operator new'.
-
-`TYPE_HAS_ARRAY_NEW_OPERATOR'
- This predicate holds for a class-type for which `operator new[]'
- is defined.
-
-`TYPE_OVERLOADS_CALL_EXPR'
- This predicate holds for class-type for which the function call
- `operator()' is overloaded.
-
-`TYPE_OVERLOADS_ARRAY_REF'
- This predicate holds for a class-type that overloads `operator[]'
-
-`TYPE_OVERLOADS_ARROW'
- This predicate holds for a class-type for which `operator->' is
- overloaded.
-
-
-\1f
-File: gccint.info, Node: Declarations, Next: Attributes, Prev: Functions, Up: Trees
-
-Declarations
-============
-
- This section covers the various kinds of declarations that appear in
-the internal representation, except for declarations of functions
-(represented by `FUNCTION_DECL' nodes), which are described in *Note
-Functions::.
-
- Some macros can be used with any kind of declaration. These include:
-`DECL_NAME'
- This macro returns an `IDENTIFIER_NODE' giving the name of the
- entity.
-
-`TREE_TYPE'
- This macro returns the type of the entity declared.
-
-`DECL_SOURCE_FILE'
- This macro returns the name of the file in which the entity was
- declared, as a `char*'. For an entity declared implicitly by the
- compiler (like `__builtin_memcpy'), this will be the string
- `"<internal>"'.
-
-`DECL_SOURCE_LINE'
- This macro returns the line number at which the entity was
- declared, as an `int'.
-
-`DECL_ARTIFICIAL'
- This predicate holds if the declaration was implicitly generated
- by the compiler. For example, this predicate will hold of an
- implicitly declared member function, or of the `TYPE_DECL'
- implicitly generated for a class type. Recall that in C++ code
- like:
- struct S {};
-
- is roughly equivalent to C code like:
- struct S {};
- typedef struct S S;
- The implicitly generated `typedef' declaration is represented by a
- `TYPE_DECL' for which `DECL_ARTIFICIAL' holds.
-
-`DECL_NAMESPACE_SCOPE_P'
- This predicate holds if the entity was declared at a namespace
- scope.
-
-`DECL_CLASS_SCOPE_P'
- This predicate holds if the entity was declared at a class scope.
-
-`DECL_FUNCTION_SCOPE_P'
- This predicate holds if the entity was declared inside a function
- body.
-
-
- The various kinds of declarations include:
-`LABEL_DECL'
- These nodes are used to represent labels in function bodies. For
- more information, see *Note Functions::. These nodes only appear
- in block scopes.
-
-`CONST_DECL'
- These nodes are used to represent enumeration constants. The
- value of the constant is given by `DECL_INITIAL' which will be an
- `INTEGER_CST' with the same type as the `TREE_TYPE' of the
- `CONST_DECL', i.e., an `ENUMERAL_TYPE'.
-
-`RESULT_DECL'
- These nodes represent the value returned by a function. When a
- value is assigned to a `RESULT_DECL', that indicates that the
- value should be returned, via bitwise copy, by the function. You
- can use `DECL_SIZE' and `DECL_ALIGN' on a `RESULT_DECL', just as
- with a `VAR_DECL'.
-
-`TYPE_DECL'
- These nodes represent `typedef' declarations. The `TREE_TYPE' is
- the type declared to have the name given by `DECL_NAME'. In some
- cases, there is no associated name.
-
-`VAR_DECL'
- These nodes represent variables with namespace or block scope, as
- well as static data members. The `DECL_SIZE' and `DECL_ALIGN' are
- analogous to `TYPE_SIZE' and `TYPE_ALIGN'. For a declaration, you
- should always use the `DECL_SIZE' and `DECL_ALIGN' rather than the
- `TYPE_SIZE' and `TYPE_ALIGN' given by the `TREE_TYPE', since
- special attributes may have been applied to the variable to give
- it a particular size and alignment. You may use the predicates
- `DECL_THIS_STATIC' or `DECL_THIS_EXTERN' to test whether the
- storage class specifiers `static' or `extern' were used to declare
- a variable.
-
- If this variable is initialized (but does not require a
- constructor), the `DECL_INITIAL' will be an expression for the
- initializer. The initializer should be evaluated, and a bitwise
- copy into the variable performed. If the `DECL_INITIAL' is the
- `error_mark_node', there is an initializer, but it is given by an
- explicit statement later in the code; no bitwise copy is required.
-
- GCC provides an extension that allows either automatic variables,
- or global variables, to be placed in particular registers. This
- extension is being used for a particular `VAR_DECL' if
- `DECL_REGISTER' holds for the `VAR_DECL', and if
- `DECL_ASSEMBLER_NAME' is not equal to `DECL_NAME'. In that case,
- `DECL_ASSEMBLER_NAME' is the name of the register into which the
- variable will be placed.
-
-`PARM_DECL'
- Used to represent a parameter to a function. Treat these nodes
- similarly to `VAR_DECL' nodes. These nodes only appear in the
- `DECL_ARGUMENTS' for a `FUNCTION_DECL'.
-
- The `DECL_ARG_TYPE' for a `PARM_DECL' is the type that will
- actually be used when a value is passed to this function. It may
- be a wider type than the `TREE_TYPE' of the parameter; for
- example, the ordinary type might be `short' while the
- `DECL_ARG_TYPE' is `int'.
-
-`FIELD_DECL'
- These nodes represent non-static data members. The `DECL_SIZE' and
- `DECL_ALIGN' behave as for `VAR_DECL' nodes. The
- `DECL_FIELD_BITPOS' gives the first bit used for this field, as an
- `INTEGER_CST'. These values are indexed from zero, where zero
- indicates the first bit in the object.
-
- If `DECL_C_BIT_FIELD' holds, this field is a bit-field.
-
-`NAMESPACE_DECL'
- *Note Namespaces::.
-
-`TEMPLATE_DECL'
- These nodes are used to represent class, function, and variable
- (static data member) templates. The
- `DECL_TEMPLATE_SPECIALIZATIONS' are a `TREE_LIST'. The
- `TREE_VALUE' of each node in the list is a `TEMPLATE_DECL's or
- `FUNCTION_DECL's representing specializations (including
- instantiations) of this template. Back ends can safely ignore
- `TEMPLATE_DECL's, but should examine `FUNCTION_DECL' nodes on the
- specializations list just as they would ordinary `FUNCTION_DECL'
- nodes.
-
- For a class template, the `DECL_TEMPLATE_INSTANTIATIONS' list
- contains the instantiations. The `TREE_VALUE' of each node is an
- instantiation of the class. The `DECL_TEMPLATE_SPECIALIZATIONS'
- contains partial specializations of the class.
-
-`USING_DECL'
- Back ends can safely ignore these nodes.
-
-
-\1f
-File: gccint.info, Node: Functions, Next: Declarations, Prev: Scopes, Up: Trees
-
-Functions
-=========
-
- A function is represented by a `FUNCTION_DECL' node. A set of
-overloaded functions is sometimes represented by a `OVERLOAD' node.
-
- An `OVERLOAD' node is not a declaration, so none of the `DECL_'
-macros should be used on an `OVERLOAD'. An `OVERLOAD' node is similar
-to a `TREE_LIST'. Use `OVL_CURRENT' to get the function associated
-with an `OVERLOAD' node; use `OVL_NEXT' to get the next `OVERLOAD' node
-in the list of overloaded functions. The macros `OVL_CURRENT' and
-`OVL_NEXT' are actually polymorphic; you can use them to work with
-`FUNCTION_DECL' nodes as well as with overloads. In the case of a
-`FUNCTION_DECL', `OVL_CURRENT' will always return the function itself,
-and `OVL_NEXT' will always be `NULL_TREE'.
-
- To determine the scope of a function, you can use the
-`DECL_REAL_CONTEXT' macro. This macro will return the class (either a
-`RECORD_TYPE' or a `UNION_TYPE') or namespace (a `NAMESPACE_DECL') of
-which the function is a member. For a virtual function, this macro
-returns the class in which the function was actually defined, not the
-base class in which the virtual declaration occurred. If a friend
-function is defined in a class scope, the `DECL_CLASS_CONTEXT' macro
-can be used to determine the class in which it was defined. For
-example, in
- class C { friend void f() {} };
- the `DECL_REAL_CONTEXT' for `f' will be the `global_namespace', but
-the `DECL_CLASS_CONTEXT' will be the `RECORD_TYPE' for `C'.
-
- The `DECL_REAL_CONTEXT' and `DECL_CLASS_CONTEXT' are not available
-in C; instead you should simply use `DECL_CONTEXT'. In C, the
-`DECL_CONTEXT' for a function maybe another function. This
-representation indicates that the GNU nested function extension is in
-use. For details on the semantics of nested functions, see the GCC
-Manual. The nested function can refer to local variables in its
-containing function. Such references are not explicitly marked in the
-tree structure; back ends must look at the `DECL_CONTEXT' for the
-referenced `VAR_DECL'. If the `DECL_CONTEXT' for the referenced
-`VAR_DECL' is not the same as the function currently being processed,
-and neither `DECL_EXTERNAL' nor `DECL_STATIC' hold, then the reference
-is to a local variable in a containing function, and the back end must
-take appropriate action.
+* File Framework:: Structural information for the assembler file.
+* Data Output:: Output of constants (numbers, strings, addresses).
+* Uninitialized Data:: Output of uninitialized variables.
+* Label Output:: Output and generation of labels.
+* Initialization:: General principles of initialization
+ and termination routines.
+* Macros for Initialization::
+ Specific macros that control the handling of
+ initialization and termination routines.
+* Instruction Output:: Output of actual instructions.
+* Dispatch Tables:: Output of jump tables.
+* Exception Region Output:: Output of exception region code.
+* Alignment Output:: Pseudo ops for alignment and skipping data.
+
+\1f
+File: gccint.info, Node: File Framework, Next: Data Output, Up: Assembler Format
+
+10.20.1 The Overall Framework of an Assembler File
+--------------------------------------------------
+
+This describes the overall framework of an assembler file.
+
+`ASM_FILE_START (STREAM)'
+ A C expression which outputs to the stdio stream STREAM some
+ appropriate text to go at the start of an assembler file.
+
+ Normally this macro is defined to output a line containing
+ `#NO_APP', which is a comment that has no effect on most
+ assemblers but tells the GNU assembler that it can save time by not
+ checking for certain assembler constructs.
+
+ On systems that use SDB, it is necessary to output certain
+ commands; see `attasm.h'.
+
+`ASM_FILE_END (STREAM)'
+ A C expression which outputs to the stdio stream STREAM some
+ appropriate text to go at the end of an assembler file.
+
+ If this macro is not defined, the default is to output nothing
+ special at the end of the file. Most systems don't require any
+ definition.
+
+ On systems that use SDB, it is necessary to output certain
+ commands; see `attasm.h'.
+
+`ASM_COMMENT_START'
+ A C string constant describing how to begin a comment in the target
+ assembler language. The compiler assumes that the comment will
+ end at the end of the line.
+
+`ASM_APP_ON'
+ A C string constant for text to be output before each `asm'
+ statement or group of consecutive ones. Normally this is
+ `"#APP"', which is a comment that has no effect on most assemblers
+ but tells the GNU assembler that it must check the lines that
+ follow for all valid assembler constructs.
+
+`ASM_APP_OFF'
+ A C string constant for text to be output after each `asm'
+ statement or group of consecutive ones. Normally this is
+ `"#NO_APP"', which tells the GNU assembler to resume making the
+ time-saving assumptions that are valid for ordinary compiler
+ output.
+
+`ASM_OUTPUT_SOURCE_FILENAME (STREAM, NAME)'
+ A C statement to output COFF information or DWARF debugging
+ information which indicates that filename NAME is the current
+ source file to the stdio stream STREAM.
+
+ This macro need not be defined if the standard form of output for
+ the file format in use is appropriate.
+
+`OUTPUT_QUOTED_STRING (STREAM, STRING)'
+ A C statement to output the string STRING to the stdio stream
+ STREAM. If you do not call the function `output_quoted_string' in
+ your config files, GCC will only call it to output filenames to
+ the assembler source. So you can use it to canonicalize the format
+ of the filename using this macro.
+
+`ASM_OUTPUT_SOURCE_LINE (STREAM, LINE)'
+ A C statement to output DBX or SDB debugging information before
+ code for line number LINE of the current source file to the stdio
+ stream STREAM.
+
+ This macro need not be defined if the standard form of debugging
+ information for the debugger in use is appropriate.
+
+`ASM_OUTPUT_IDENT (STREAM, STRING)'
+ A C statement to output something to the assembler file to handle a
+ `#ident' directive containing the text STRING. If this macro is
+ not defined, nothing is output for a `#ident' directive.
+
+`OBJC_PROLOGUE'
+ A C statement to output any assembler statements which are
+ required to precede any Objective-C object definitions or message
+ sending. The statement is executed only when compiling an
+ Objective-C program.
+
+ -- Target Hook: void TARGET_ASM_NAMED_SECTION (const char *NAME,
+ unsigned int FLAGS, unsigned int ALIGN)
+ Output assembly directives to switch to section NAME. The section
+ should have attributes as specified by FLAGS, which is a bit mask
+ of the `SECTION_*' flags defined in `output.h'. If ALIGN is
+ nonzero, it contains an alignment in bytes to be used for the
+ section, otherwise some target default should be used. Only
+ targets that must specify an alignment within the section
+ directive need pay attention to ALIGN - we will still use
+ `ASM_OUTPUT_ALIGN'.
+
+ -- Target Hook: bool TARGET_HAVE_NAMED_SECTIONS
+ This flag is true if the target supports
+ `TARGET_ASM_NAMED_SECTION'.
+
+ -- Target Hook: unsigned int TARGET_SECTION_TYPE_FLAGS (tree DECL,
+ const char *NAME, int RELOC)
+ Choose a set of section attributes for use by
+ `TARGET_ASM_NAMED_SECTION' based on a variable or function decl, a
+ section name, and whether or not the declaration's initializer may
+ contain runtime relocations. DECL may be null, in which case
+ read-write data should be assumed.
+
+ The default version if this function handles choosing code vs data,
+ read-only vs read-write data, and `flag_pic'. You should only
+ need to override this if your target has special flags that might
+ be set via `__attribute__'.
+
+\1f
+File: gccint.info, Node: Data Output, Next: Uninitialized Data, Prev: File Framework, Up: Assembler Format
+
+10.20.2 Output of Data
+----------------------
+
+ -- Target Hook: const char * TARGET_ASM_BYTE_OP
+ -- Target Hook: const char * TARGET_ASM_ALIGNED_HI_OP
+ -- Target Hook: const char * TARGET_ASM_ALIGNED_SI_OP
+ -- Target Hook: const char * TARGET_ASM_ALIGNED_DI_OP
+ -- Target Hook: const char * TARGET_ASM_ALIGNED_TI_OP
+ -- Target Hook: const char * TARGET_ASM_UNALIGNED_HI_OP
+ -- Target Hook: const char * TARGET_ASM_UNALIGNED_SI_OP
+ -- Target Hook: const char * TARGET_ASM_UNALIGNED_DI_OP
+ -- Target Hook: const char * TARGET_ASM_UNALIGNED_TI_OP
+ These hooks specify assembly directives for creating certain kinds
+ of integer object. The `TARGET_ASM_BYTE_OP' directive creates a
+ byte-sized object, the `TARGET_ASM_ALIGNED_HI_OP' one creates an
+ aligned two-byte object, and so on. Any of the hooks may be
+ `NULL', indicating that no suitable directive is available.
+
+ The compiler will print these strings at the start of a new line,
+ followed immediately by the object's initial value. In most cases,
+ the string should contain a tab, a pseudo-op, and then another tab.
+
+ -- Target Hook: bool TARGET_ASM_INTEGER (rtx X, unsigned int SIZE, int
+ ALIGNED_P)
+ The `assemble_integer' function uses this hook to output an
+ integer object. X is the object's value, SIZE is its size in
+ bytes and ALIGNED_P indicates whether it is aligned. The function
+ should return `true' if it was able to output the object. If it
+ returns false, `assemble_integer' will try to split the object
+ into smaller parts.
+
+ The default implementation of this hook will use the
+ `TARGET_ASM_BYTE_OP' family of strings, returning `false' when the
+ relevant string is `NULL'.
+
+`OUTPUT_ADDR_CONST_EXTRA (STREAM, X, FAIL)'
+ A C statement to recognize RTX patterns that `output_addr_const'
+ can't deal with, and output assembly code to STREAM corresponding
+ to the pattern X. This may be used to allow machine-dependent
+ `UNSPEC's to appear within constants.
+
+ If `OUTPUT_ADDR_CONST_EXTRA' fails to recognize a pattern, it must
+ `goto fail', so that a standard error message is printed. If it
+ prints an error message itself, by calling, for example,
+ `output_operand_lossage', it may just complete normally.
+
+`ASM_OUTPUT_ASCII (STREAM, PTR, LEN)'
+ A C statement to output to the stdio stream STREAM an assembler
+ instruction to assemble a string constant containing the LEN bytes
+ at PTR. PTR will be a C expression of type `char *' and LEN a C
+ expression of type `int'.
+
+ If the assembler has a `.ascii' pseudo-op as found in the Berkeley
+ Unix assembler, do not define the macro `ASM_OUTPUT_ASCII'.
+
+`ASM_OUTPUT_FDESC (STREAM, DECL, N)'
+ A C statement to output word N of a function descriptor for DECL.
+ This must be defined if `TARGET_VTABLE_USES_DESCRIPTORS' is
+ defined, and is otherwise unused.
+
+`CONSTANT_POOL_BEFORE_FUNCTION'
+ You may define this macro as a C expression. You should define the
+ expression to have a nonzero value if GCC should output the
+ constant pool for a function before the code for the function, or
+ a zero value if GCC should output the constant pool after the
+ function. If you do not define this macro, the usual case, GCC
+ will output the constant pool before the function.
+
+`ASM_OUTPUT_POOL_PROLOGUE (FILE, FUNNAME, FUNDECL, SIZE)'
+ A C statement to output assembler commands to define the start of
+ the constant pool for a function. FUNNAME is a string giving the
+ name of the function. Should the return type of the function be
+ required, it can be obtained via FUNDECL. SIZE is the size, in
+ bytes, of the constant pool that will be written immediately after
+ this call.
+
+ If no constant-pool prefix is required, the usual case, this macro
+ need not be defined.
+
+`ASM_OUTPUT_SPECIAL_POOL_ENTRY (FILE, X, MODE, ALIGN, LABELNO, JUMPTO)'
+ A C statement (with or without semicolon) to output a constant in
+ the constant pool, if it needs special treatment. (This macro
+ need not do anything for RTL expressions that can be output
+ normally.)
+
+ The argument FILE is the standard I/O stream to output the
+ assembler code on. X is the RTL expression for the constant to
+ output, and MODE is the machine mode (in case X is a `const_int').
+ ALIGN is the required alignment for the value X; you should output
+ an assembler directive to force this much alignment.
+
+ The argument LABELNO is a number to use in an internal label for
+ the address of this pool entry. The definition of this macro is
+ responsible for outputting the label definition at the proper
+ place. Here is how to do this:
+
+ ASM_OUTPUT_INTERNAL_LABEL (FILE, "LC", LABELNO);
+
+ When you output a pool entry specially, you should end with a
+ `goto' to the label JUMPTO. This will prevent the same pool entry
+ from being output a second time in the usual manner.
+
+ You need not define this macro if it would do nothing.
+
+`CONSTANT_AFTER_FUNCTION_P (EXP)'
+ Define this macro as a C expression which is nonzero if the
+ constant EXP, of type `tree', should be output after the code for a
+ function. The compiler will normally output all constants before
+ the function; you need not define this macro if this is OK.
+
+`ASM_OUTPUT_POOL_EPILOGUE (FILE FUNNAME FUNDECL SIZE)'
+ A C statement to output assembler commands to at the end of the
+ constant pool for a function. FUNNAME is a string giving the name
+ of the function. Should the return type of the function be
+ required, you can obtain it via FUNDECL. SIZE is the size, in
+ bytes, of the constant pool that GCC wrote immediately before this
+ call.
+
+ If no constant-pool epilogue is required, the usual case, you need
+ not define this macro.
+
+`IS_ASM_LOGICAL_LINE_SEPARATOR (C)'
+ Define this macro as a C expression which is nonzero if C is used
+ as a logical line separator by the assembler.
+
+ If you do not define this macro, the default is that only the
+ character `;' is treated as a logical line separator.
+
+ -- Target Hook: const char * TARGET_ASM_OPEN_PAREN
+ -- Target Hook: const char * TARGET_ASM_CLOSE_PAREN
+ These target hooks are C string constants, describing the syntax
+ in the assembler for grouping arithmetic expressions. If not
+ overridden, they default to normal parentheses, which is correct
+ for most assemblers.
+
+ These macros are provided by `real.h' for writing the definitions of
+`ASM_OUTPUT_DOUBLE' and the like:
+
+`REAL_VALUE_TO_TARGET_SINGLE (X, L)'
+`REAL_VALUE_TO_TARGET_DOUBLE (X, L)'
+`REAL_VALUE_TO_TARGET_LONG_DOUBLE (X, L)'
+ These translate X, of type `REAL_VALUE_TYPE', to the target's
+ floating point representation, and store its bit pattern in the
+ array of `long int' whose address is L. The number of elements in
+ the output array is determined by the size of the desired target
+ floating point data type: 32 bits of it go in each `long int' array
+ element. Each array element holds 32 bits of the result, even if
+ `long int' is wider than 32 bits on the host machine.
+
+ The array element values are designed so that you can print them
+ out using `fprintf' in the order they should appear in the target
+ machine's memory.
+
+`REAL_VALUE_TO_DECIMAL (X, FORMAT, STRING)'
+ This macro converts X, of type `REAL_VALUE_TYPE', to a decimal
+ number and stores it as a string into STRING. You must pass, as
+ STRING, the address of a long enough block of space to hold the
+ result.
+
+ The argument FORMAT is a `printf'-specification that serves as a
+ suggestion for how to format the output string.
+
+\1f
+File: gccint.info, Node: Uninitialized Data, Next: Label Output, Prev: Data Output, Up: Assembler Format
+
+10.20.3 Output of Uninitialized Variables
+-----------------------------------------
+
+Each of the macros in this section is used to do the whole job of
+outputting a single uninitialized variable.
+
+`ASM_OUTPUT_COMMON (STREAM, NAME, SIZE, ROUNDED)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM the assembler definition of a common-label named NAME whose
+ size is SIZE bytes. The variable ROUNDED is the size rounded up
+ to whatever alignment the caller wants.
+
+ Use the expression `assemble_name (STREAM, NAME)' to output the
+ name itself; before and after that, output the additional
+ assembler syntax for defining the name, and a newline.
+
+ This macro controls how the assembler definitions of uninitialized
+ common global variables are output.
+
+`ASM_OUTPUT_ALIGNED_COMMON (STREAM, NAME, SIZE, ALIGNMENT)'
+ Like `ASM_OUTPUT_COMMON' except takes the required alignment as a
+ separate, explicit argument. If you define this macro, it is used
+ in place of `ASM_OUTPUT_COMMON', and gives you more flexibility in
+ handling the required alignment of the variable. The alignment is
+ specified as the number of bits.
+
+`ASM_OUTPUT_ALIGNED_DECL_COMMON (STREAM, DECL, NAME, SIZE, ALIGNMENT)'
+ Like `ASM_OUTPUT_ALIGNED_COMMON' except that DECL of the variable
+ to be output, if there is one, or `NULL_TREE' if there is no
+ corresponding variable. If you define this macro, GCC will use it
+ in place of both `ASM_OUTPUT_COMMON' and
+ `ASM_OUTPUT_ALIGNED_COMMON'. Define this macro when you need to
+ see the variable's decl in order to chose what to output.
+
+`ASM_OUTPUT_SHARED_COMMON (STREAM, NAME, SIZE, ROUNDED)'
+ If defined, it is similar to `ASM_OUTPUT_COMMON', except that it
+ is used when NAME is shared. If not defined, `ASM_OUTPUT_COMMON'
+ will be used.
+
+`ASM_OUTPUT_BSS (STREAM, DECL, NAME, SIZE, ROUNDED)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM the assembler definition of uninitialized global DECL named
+ NAME whose size is SIZE bytes. The variable ROUNDED is the size
+ rounded up to whatever alignment the caller wants.
+
+ Try to use function `asm_output_bss' defined in `varasm.c' when
+ defining this macro. If unable, use the expression `assemble_name
+ (STREAM, NAME)' to output the name itself; before and after that,
+ output the additional assembler syntax for defining the name, and
+ a newline.
+
+ This macro controls how the assembler definitions of uninitialized
+ global variables are output. This macro exists to properly
+ support languages like C++ which do not have `common' data.
+ However, this macro currently is not defined for all targets. If
+ this macro and `ASM_OUTPUT_ALIGNED_BSS' are not defined then
+ `ASM_OUTPUT_COMMON' or `ASM_OUTPUT_ALIGNED_COMMON' or
+ `ASM_OUTPUT_ALIGNED_DECL_COMMON' is used.
+
+`ASM_OUTPUT_ALIGNED_BSS (STREAM, DECL, NAME, SIZE, ALIGNMENT)'
+ Like `ASM_OUTPUT_BSS' except takes the required alignment as a
+ separate, explicit argument. If you define this macro, it is used
+ in place of `ASM_OUTPUT_BSS', and gives you more flexibility in
+ handling the required alignment of the variable. The alignment is
+ specified as the number of bits.
+
+ Try to use function `asm_output_aligned_bss' defined in file
+ `varasm.c' when defining this macro.
+
+`ASM_OUTPUT_SHARED_BSS (STREAM, DECL, NAME, SIZE, ROUNDED)'
+ If defined, it is similar to `ASM_OUTPUT_BSS', except that it is
+ used when NAME is shared. If not defined, `ASM_OUTPUT_BSS' will
+ be used.
+
+`ASM_OUTPUT_LOCAL (STREAM, NAME, SIZE, ROUNDED)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM the assembler definition of a local-common-label named NAME
+ whose size is SIZE bytes. The variable ROUNDED is the size
+ rounded up to whatever alignment the caller wants.
+
+ Use the expression `assemble_name (STREAM, NAME)' to output the
+ name itself; before and after that, output the additional
+ assembler syntax for defining the name, and a newline.
+
+ This macro controls how the assembler definitions of uninitialized
+ static variables are output.
+
+`ASM_OUTPUT_ALIGNED_LOCAL (STREAM, NAME, SIZE, ALIGNMENT)'
+ Like `ASM_OUTPUT_LOCAL' except takes the required alignment as a
+ separate, explicit argument. If you define this macro, it is used
+ in place of `ASM_OUTPUT_LOCAL', and gives you more flexibility in
+ handling the required alignment of the variable. The alignment is
+ specified as the number of bits.
+
+`ASM_OUTPUT_ALIGNED_DECL_LOCAL (STREAM, DECL, NAME, SIZE, ALIGNMENT)'
+ Like `ASM_OUTPUT_ALIGNED_DECL' except that DECL of the variable to
+ be output, if there is one, or `NULL_TREE' if there is no
+ corresponding variable. If you define this macro, GCC will use it
+ in place of both `ASM_OUTPUT_DECL' and `ASM_OUTPUT_ALIGNED_DECL'.
+ Define this macro when you need to see the variable's decl in
+ order to chose what to output.
+
+`ASM_OUTPUT_SHARED_LOCAL (STREAM, NAME, SIZE, ROUNDED)'
+ If defined, it is similar to `ASM_OUTPUT_LOCAL', except that it is
+ used when NAME is shared. If not defined, `ASM_OUTPUT_LOCAL' will
+ be used.
+
+\1f
+File: gccint.info, Node: Label Output, Next: Initialization, Prev: Uninitialized Data, Up: Assembler Format
+
+10.20.4 Output and Generation of Labels
+---------------------------------------
+
+This is about outputting labels.
+
+`ASM_OUTPUT_LABEL (STREAM, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM the assembler definition of a label named NAME. Use the
+ expression `assemble_name (STREAM, NAME)' to output the name
+ itself; before and after that, output the additional assembler
+ syntax for defining the name, and a newline.
+
+`ASM_DECLARE_FUNCTION_NAME (STREAM, NAME, DECL)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM any text necessary for declaring the name NAME of a
+ function which is being defined. This macro is responsible for
+ outputting the label definition (perhaps using
+ `ASM_OUTPUT_LABEL'). The argument DECL is the `FUNCTION_DECL'
+ tree node representing the function.
+
+ If this macro is not defined, then the function name is defined in
+ the usual manner as a label (by means of `ASM_OUTPUT_LABEL').
+
+`ASM_DECLARE_FUNCTION_SIZE (STREAM, NAME, DECL)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM any text necessary for declaring the size of a function
+ which is being defined. The argument NAME is the name of the
+ function. The argument DECL is the `FUNCTION_DECL' tree node
+ representing the function.
+
+ If this macro is not defined, then the function size is not
+ defined.
+
+`ASM_DECLARE_OBJECT_NAME (STREAM, NAME, DECL)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM any text necessary for declaring the name NAME of an
+ initialized variable which is being defined. This macro must
+ output the label definition (perhaps using `ASM_OUTPUT_LABEL').
+ The argument DECL is the `VAR_DECL' tree node representing the
+ variable.
+
+ If this macro is not defined, then the variable name is defined in
+ the usual manner as a label (by means of `ASM_OUTPUT_LABEL').
+
+`ASM_DECLARE_REGISTER_GLOBAL (STREAM, DECL, REGNO, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM any text necessary for claiming a register REGNO for a
+ global variable DECL with name NAME.
+
+ If you don't define this macro, that is equivalent to defining it
+ to do nothing.
+
+`ASM_FINISH_DECLARE_OBJECT (STREAM, DECL, TOPLEVEL, ATEND)'
+ A C statement (sans semicolon) to finish up declaring a variable
+ name once the compiler has processed its initializer fully and
+ thus has had a chance to determine the size of an array when
+ controlled by an initializer. This is used on systems where it's
+ necessary to declare something about the size of the object.
+
+ If you don't define this macro, that is equivalent to defining it
+ to do nothing.
+
+`ASM_GLOBALIZE_LABEL (STREAM, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM some commands that will make the label NAME global; that
+ is, available for reference from other files. Use the expression
+ `assemble_name (STREAM, NAME)' to output the name itself; before
+ and after that, output the additional assembler syntax for making
+ that name global, and a newline.
+
+`ASM_WEAKEN_LABEL (STREAM, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM some commands that will make the label NAME weak; that is,
+ available for reference from other files but only used if no other
+ definition is available. Use the expression `assemble_name
+ (STREAM, NAME)' to output the name itself; before and after that,
+ output the additional assembler syntax for making that name weak,
+ and a newline.
+
+ If you don't define this macro or `ASM_WEAKEN_DECL', GCC will not
+ support weak symbols and you should not define the `SUPPORTS_WEAK'
+ macro.
+
+`ASM_WEAKEN_DECL (STREAM, DECL, NAME, VALUE)'
+ Combines (and replaces) the function of `ASM_WEAKEN_LABEL' and
+ `ASM_OUTPUT_WEAK_ALIAS', allowing access to the associated function
+ or variable decl. If VALUE is not `NULL', this C statement should
+ output to the stdio stream STREAM assembler code which defines
+ (equates) the weak symbol NAME to have the value VALUE. If VALUE
+ is `NULL', it should output commands to make NAME weak.
+
+`SUPPORTS_WEAK'
+ A C expression which evaluates to true if the target supports weak
+ symbols.
+
+ If you don't define this macro, `defaults.h' provides a default
+ definition. If either `ASM_WEAKEN_LABEL' or `ASM_WEAKEN_DECL' is
+ defined, the default definition is `1'; otherwise, it is `0'.
+ Define this macro if you want to control weak symbol support with
+ a compiler flag such as `-melf'.
+
+`MAKE_DECL_ONE_ONLY'
+ A C statement (sans semicolon) to mark DECL to be emitted as a
+ public symbol such that extra copies in multiple translation units
+ will be discarded by the linker. Define this macro if your object
+ file format provides support for this concept, such as the `COMDAT'
+ section flags in the Microsoft Windows PE/COFF format, and this
+ support requires changes to DECL, such as putting it in a separate
+ section.
+
+`SUPPORTS_ONE_ONLY'
+ A C expression which evaluates to true if the target supports
+ one-only semantics.
+
+ If you don't define this macro, `varasm.c' provides a default
+ definition. If `MAKE_DECL_ONE_ONLY' is defined, the default
+ definition is `1'; otherwise, it is `0'. Define this macro if you
+ want to control one-only symbol support with a compiler flag, or if
+ setting the `DECL_ONE_ONLY' flag is enough to mark a declaration to
+ be emitted as one-only.
+
+`ASM_OUTPUT_EXTERNAL (STREAM, DECL, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM any text necessary for declaring the name of an external
+ symbol named NAME which is referenced in this compilation but not
+ defined. The value of DECL is the tree node for the declaration.
+
+ This macro need not be defined if it does not need to output
+ anything. The GNU assembler and most Unix assemblers don't
+ require anything.
+
+`ASM_OUTPUT_EXTERNAL_LIBCALL (STREAM, SYMREF)'
+ A C statement (sans semicolon) to output on STREAM an assembler
+ pseudo-op to declare a library function name external. The name
+ of the library function is given by SYMREF, which has type `rtx'
+ and is a `symbol_ref'.
+
+ This macro need not be defined if it does not need to output
+ anything. The GNU assembler and most Unix assemblers don't
+ require anything.
+
+`ASM_OUTPUT_LABELREF (STREAM, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM a reference in assembler syntax to a label named NAME.
+ This should add `_' to the front of the name, if that is customary
+ on your operating system, as it is in most Berkeley Unix systems.
+ This macro is used in `assemble_name'.
+
+`ASM_OUTPUT_SYMBOL_REF (STREAM, SYM)'
+ A C statement (sans semicolon) to output a reference to
+ `SYMBOL_REF' SYM. If not defined, `assemble_name' will be used to
+ output the name of the symbol. This macro may be used to modify
+ the way a symbol is referenced depending on information encoded by
+ `ENCODE_SECTION_INFO'.
+
+`ASM_OUTPUT_LABEL_REF (STREAM, BUF)'
+ A C statement (sans semicolon) to output a reference to BUF, the
+ result of ASM_GENERATE_INTERNAL_LABEL. If not defined,
+ `assemble_name' will be used to output the name of the symbol.
+ This macro is not used by `output_asm_label', or the `%l'
+ specifier that calls it; the intention is that this macro should
+ be set when it is necessary to output a label differently when its
+ address is being taken.
+
+`ASM_OUTPUT_INTERNAL_LABEL (STREAM, PREFIX, NUM)'
+ A C statement to output to the stdio stream STREAM a label whose
+ name is made from the string PREFIX and the number NUM.
+
+ It is absolutely essential that these labels be distinct from the
+ labels used for user-level functions and variables. Otherwise,
+ certain programs will have name conflicts with internal labels.
+
+ It is desirable to exclude internal labels from the symbol table
+ of the object file. Most assemblers have a naming convention for
+ labels that should be excluded; on many systems, the letter `L' at
+ the beginning of a label has this effect. You should find out what
+ convention your system uses, and follow it.
+
+ The usual definition of this macro is as follows:
+
+ fprintf (STREAM, "L%s%d:\n", PREFIX, NUM)
+
+`ASM_OUTPUT_DEBUG_LABEL (STREAM, PREFIX, NUM)'
+ A C statement to output to the stdio stream STREAM a debug info
+ label whose name is made from the string PREFIX and the number
+ NUM. This is useful for VLIW targets, where debug info labels may
+ need to be treated differently than branch target labels. On some
+ systems, branch target labels must be at the beginning of
+ instruction bundles, but debug info labels can occur in the middle
+ of instruction bundles.
+
+ If this macro is not defined, then `ASM_OUTPUT_INTERNAL_LABEL'
+ will be used.
+
+`ASM_OUTPUT_ALTERNATE_LABEL_NAME (STREAM, STRING)'
+ A C statement to output to the stdio stream STREAM the string
+ STRING.
+
+ The default definition of this macro is as follows:
+
+ fprintf (STREAM, "%s:\n", LABEL_ALTERNATE_NAME (INSN))
+
+`ASM_GENERATE_INTERNAL_LABEL (STRING, PREFIX, NUM)'
+ A C statement to store into the string STRING a label whose name
+ is made from the string PREFIX and the number NUM.
+
+ This string, when output subsequently by `assemble_name', should
+ produce the output that `ASM_OUTPUT_INTERNAL_LABEL' would produce
+ with the same PREFIX and NUM.
+
+ If the string begins with `*', then `assemble_name' will output
+ the rest of the string unchanged. It is often convenient for
+ `ASM_GENERATE_INTERNAL_LABEL' to use `*' in this way. If the
+ string doesn't start with `*', then `ASM_OUTPUT_LABELREF' gets to
+ output the string, and may change it. (Of course,
+ `ASM_OUTPUT_LABELREF' is also part of your machine description, so
+ you should know what it does on your machine.)
+
+`ASM_FORMAT_PRIVATE_NAME (OUTVAR, NAME, NUMBER)'
+ A C expression to assign to OUTVAR (which is a variable of type
+ `char *') a newly allocated string made from the string NAME and
+ the number NUMBER, with some suitable punctuation added. Use
+ `alloca' to get space for the string.
+
+ The string will be used as an argument to `ASM_OUTPUT_LABELREF' to
+ produce an assembler label for an internal static variable whose
+ name is NAME. Therefore, the string must be such as to result in
+ valid assembler code. The argument NUMBER is different each time
+ this macro is executed; it prevents conflicts between
+ similarly-named internal static variables in different scopes.
+
+ Ideally this string should not be a valid C identifier, to prevent
+ any conflict with the user's own symbols. Most assemblers allow
+ periods or percent signs in assembler symbols; putting at least
+ one of these between the name and the number will suffice.
+
+`ASM_OUTPUT_DEF (STREAM, NAME, VALUE)'
+ A C statement to output to the stdio stream STREAM assembler code
+ which defines (equates) the symbol NAME to have the value VALUE.
+
+ If `SET_ASM_OP' is defined, a default definition is provided which
+ is correct for most systems.
+
+`ASM_OUTPUT_DEF_FROM_DECLS (STREAM, DECL_OF_NAME, DECL_OF_VALUE)'
+ A C statement to output to the stdio stream STREAM assembler code
+ which defines (equates) the symbol whose tree node is DECL_OF_NAME
+ to have the value of the tree node DECL_OF_VALUE. This macro will
+ be used in preference to `ASM_OUTPUT_DEF' if it is defined and if
+ the tree nodes are available.
+
+`ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL (STREAM, SYMBOL, HIGH, LOW)'
+ A C statement to output to the stdio stream STREAM assembler code
+ which defines (equates) the symbol SYMBOL to have a value equal to
+ the difference of the two symbols HIGH and LOW, i.e. HIGH minus
+ LOW. GCC guarantees that the symbols HIGH and LOW are already
+ known by the assembler so that the difference resolves into a
+ constant.
+
+ If `SET_ASM_OP' is defined, a default definition is provided which
+ is correct for most systems.
+
+`ASM_OUTPUT_WEAK_ALIAS (STREAM, NAME, VALUE)'
+ A C statement to output to the stdio stream STREAM assembler code
+ which defines (equates) the weak symbol NAME to have the value
+ VALUE. If VALUE is `NULL', it defines NAME as an undefined weak
+ symbol.
+
+ Define this macro if the target only supports weak aliases; define
+ `ASM_OUTPUT_DEF' instead if possible.
+
+`OBJC_GEN_METHOD_LABEL (BUF, IS_INST, CLASS_NAME, CAT_NAME, SEL_NAME)'
+ Define this macro to override the default assembler names used for
+ Objective-C methods.
+
+ The default name is a unique method number followed by the name of
+ the class (e.g. `_1_Foo'). For methods in categories, the name of
+ the category is also included in the assembler name (e.g.
+ `_1_Foo_Bar').
+
+ These names are safe on most systems, but make debugging difficult
+ since the method's selector is not present in the name.
+ Therefore, particular systems define other ways of computing names.
+
+ BUF is an expression of type `char *' which gives you a buffer in
+ which to store the name; its length is as long as CLASS_NAME,
+ CAT_NAME and SEL_NAME put together, plus 50 characters extra.
+
+ The argument IS_INST specifies whether the method is an instance
+ method or a class method; CLASS_NAME is the name of the class;
+ CAT_NAME is the name of the category (or `NULL' if the method is
+ not in a category); and SEL_NAME is the name of the selector.
+
+ On systems where the assembler can handle quoted names, you can
+ use this macro to provide more human-readable names.
+
+`ASM_DECLARE_CLASS_REFERENCE (STREAM, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM commands to declare that the label NAME is an Objective-C
+ class reference. This is only needed for targets whose linkers
+ have special support for NeXT-style runtimes.
+
+`ASM_DECLARE_UNRESOLVED_REFERENCE (STREAM, NAME)'
+ A C statement (sans semicolon) to output to the stdio stream
+ STREAM commands to declare that the label NAME is an unresolved
+ Objective-C class reference. This is only needed for targets
+ whose linkers have special support for NeXT-style runtimes.
+
+\1f
+File: gccint.info, Node: Initialization, Next: Macros for Initialization, Prev: Label Output, Up: Assembler Format
+
+10.20.5 How Initialization Functions Are Handled
+------------------------------------------------
+
+The compiled code for certain languages includes "constructors" (also
+called "initialization routines")--functions to initialize data in the
+program when the program is started. These functions need to be called
+before the program is "started"--that is to say, before `main' is
+called.
+
+ Compiling some languages generates "destructors" (also called
+"termination routines") that should be called when the program
+terminates.
+
+ To make the initialization and termination functions work, the
+compiler must output something in the assembler code to cause those
+functions to be called at the appropriate time. When you port the
+compiler to a new system, you need to specify how to do this.
+
+ There are two major ways that GCC currently supports the execution of
+initialization and termination functions. Each way has two variants.
+Much of the structure is common to all four variations.
+
+ The linker must build two lists of these functions--a list of
+initialization functions, called `__CTOR_LIST__', and a list of
+termination functions, called `__DTOR_LIST__'.
+
+ Each list always begins with an ignored function pointer (which may
+hold 0, -1, or a count of the function pointers after it, depending on
+the environment). This is followed by a series of zero or more function
+pointers to constructors (or destructors), followed by a function
+pointer containing zero.
+
+ Depending on the operating system and its executable file format,
+either `crtstuff.c' or `libgcc2.c' traverses these lists at startup
+time and exit time. Constructors are called in reverse order of the
+list; destructors in forward order.
+
+ The best way to handle static constructors works only for object file
+formats which provide arbitrarily-named sections. A section is set
+aside for a list of constructors, and another for a list of destructors.
+Traditionally these are called `.ctors' and `.dtors'. Each object file
+that defines an initialization function also puts a word in the
+constructor section to point to that function. The linker accumulates
+all these words into one contiguous `.ctors' section. Termination
+functions are handled similarly.
+
+ This method will be chosen as the default by `target-def.h' if
+`TARGET_ASM_NAMED_SECTION' is defined. A target that does not support
+arbitrary sections, but does support special designated constructor and
+destructor sections may define `CTORS_SECTION_ASM_OP' and
+`DTORS_SECTION_ASM_OP' to achieve the same effect.
+
+ When arbitrary sections are available, there are two variants,
+depending upon how the code in `crtstuff.c' is called. On systems that
+support a ".init" section which is executed at program startup, parts
+of `crtstuff.c' are compiled into that section. The program is linked
+by the `gcc' driver like this:
+
+ ld -o OUTPUT_FILE crti.o crtbegin.o ... -lgcc crtend.o crtn.o
+
+ The prologue of a function (`__init') appears in the `.init' section
+of `crti.o'; the epilogue appears in `crtn.o'. Likewise for the
+function `__fini' in the ".fini" section. Normally these files are
+provided by the operating system or by the GNU C library, but are
+provided by GCC for a few targets.
+
+ The objects `crtbegin.o' and `crtend.o' are (for most targets)
+compiled from `crtstuff.c'. They contain, among other things, code
+fragments within the `.init' and `.fini' sections that branch to
+routines in the `.text' section. The linker will pull all parts of a
+section together, which results in a complete `__init' function that
+invokes the routines we need at startup.
+
+ To use this variant, you must define the `INIT_SECTION_ASM_OP' macro
+properly.
+
+ If no init section is available, when GCC compiles any function
+called `main' (or more accurately, any function designated as a program
+entry point by the language front end calling `expand_main_function'),
+it inserts a procedure call to `__main' as the first executable code
+after the function prologue. The `__main' function is defined in
+`libgcc2.c' and runs the global constructors.
+
+ In file formats that don't support arbitrary sections, there are
+again two variants. In the simplest variant, the GNU linker (GNU `ld')
+and an `a.out' format must be used. In this case,
+`TARGET_ASM_CONSTRUCTOR' is defined to produce a `.stabs' entry of type
+`N_SETT', referencing the name `__CTOR_LIST__', and with the address of
+the void function containing the initialization code as its value. The
+GNU linker recognizes this as a request to add the value to a "set";
+the values are accumulated, and are eventually placed in the executable
+as a vector in the format described above, with a leading (ignored)
+count and a trailing zero element. `TARGET_ASM_DESTRUCTOR' is handled
+similarly. Since no init section is available, the absence of
+`INIT_SECTION_ASM_OP' causes the compilation of `main' to call `__main'
+as above, starting the initialization process.
+
+ The last variant uses neither arbitrary sections nor the GNU linker.
+This is preferable when you want to do dynamic linking and when using
+file formats which the GNU linker does not support, such as `ECOFF'. In
+this case, `TARGET_HAVE_CTORS_DTORS' is false, initialization and
+termination functions are recognized simply by their names. This
+requires an extra program in the linkage step, called `collect2'. This
+program pretends to be the linker, for use with GCC; it does its job by
+running the ordinary linker, but also arranges to include the vectors of
+initialization and termination functions. These functions are called
+via `__main' as described above. In order to use this method,
+`use_collect2' must be defined in the target in `config.gcc'.
+
+ The following section describes the specific macros that control and
+customize the handling of initialization and termination functions.
+
+\1f
+File: gccint.info, Node: Macros for Initialization, Next: Instruction Output, Prev: Initialization, Up: Assembler Format
+
+10.20.6 Macros Controlling Initialization Routines
+--------------------------------------------------
+
+Here are the macros that control how the compiler handles initialization
+and termination functions:
+
+`INIT_SECTION_ASM_OP'
+ If defined, a C string constant, including spacing, for the
+ assembler operation to identify the following data as
+ initialization code. If not defined, GCC will assume such a
+ section does not exist. When you are using special sections for
+ initialization and termination functions, this macro also controls
+ how `crtstuff.c' and `libgcc2.c' arrange to run the initialization
+ functions.
+
+`HAS_INIT_SECTION'
+ If defined, `main' will not call `__main' as described above.
+ This macro should be defined for systems that control start-up code
+ on a symbol-by-symbol basis, such as OSF/1, and should not be
+ defined explicitly for systems that support `INIT_SECTION_ASM_OP'.
+
+`LD_INIT_SWITCH'
+ If defined, a C string constant for a switch that tells the linker
+ that the following symbol is an initialization routine.
+
+`LD_FINI_SWITCH'
+ If defined, a C string constant for a switch that tells the linker
+ that the following symbol is a finalization routine.
+
+`COLLECT_SHARED_INIT_FUNC (STREAM, FUNC)'
+ If defined, a C statement that will write a function that can be
+ automatically called when a shared library is loaded. The function
+ should call FUNC, which takes no arguments. If not defined, and
+ the object format requires an explicit initialization function,
+ then a function called `_GLOBAL__DI' will be generated.
+
+ This function and the following one are used by collect2 when
+ linking a shared library that needs constructors or destructors,
+ or has DWARF2 exception tables embedded in the code.
+
+`COLLECT_SHARED_FINI_FUNC (STREAM, FUNC)'
+ If defined, a C statement that will write a function that can be
+ automatically called when a shared library is unloaded. The
+ function should call FUNC, which takes no arguments. If not
+ defined, and the object format requires an explicit finalization
+ function, then a function called `_GLOBAL__DD' will be generated.
+
+`INVOKE__main'
+ If defined, `main' will call `__main' despite the presence of
+ `INIT_SECTION_ASM_OP'. This macro should be defined for systems
+ where the init section is not actually run automatically, but is
+ still useful for collecting the lists of constructors and
+ destructors.
+
+`SUPPORTS_INIT_PRIORITY'
+ If nonzero, the C++ `init_priority' attribute is supported and the
+ compiler should emit instructions to control the order of
+ initialization of objects. If zero, the compiler will issue an
+ error message upon encountering an `init_priority' attribute.
+
+ -- Target Hook: bool TARGET_HAVE_CTORS_DTORS
+ This value is true if the target supports some "native" method of
+ collecting constructors and destructors to be run at startup and
+ exit. It is false if we must use `collect2'.
+
+ -- Target Hook: void TARGET_ASM_CONSTRUCTOR (rtx SYMBOL, int PRIORITY)
+ If defined, a function that outputs assembler code to arrange to
+ call the function referenced by SYMBOL at initialization time.
+
+ Assume that SYMBOL is a `SYMBOL_REF' for a function taking no
+ arguments and with no return value. If the target supports
+ initialization priorities, PRIORITY is a value between 0 and
+ `MAX_INIT_PRIORITY'; otherwise it must be `DEFAULT_INIT_PRIORITY'.
+
+ If this macro is not defined by the target, a suitable default will
+ be chosen if (1) the target supports arbitrary section names, (2)
+ the target defines `CTORS_SECTION_ASM_OP', or (3) `USE_COLLECT2'
+ is not defined.
+
+ -- Target Hook: void TARGET_ASM_DESTRUCTOR (rtx SYMBOL, int PRIORITY)
+ This is like `TARGET_ASM_CONSTRUCTOR' but used for termination
+ functions rather than initialization functions.
+
+ If `TARGET_HAVE_CTORS_DTORS' is true, the initialization routine
+generated for the generated object file will have static linkage.
+
+ If your system uses `collect2' as the means of processing
+constructors, then that program normally uses `nm' to scan an object
+file for constructor functions to be called.
+
+ On certain kinds of systems, you can define these macros to make
+`collect2' work faster (and, in some cases, make it work at all):
+
+`OBJECT_FORMAT_COFF'
+ Define this macro if the system uses COFF (Common Object File
+ Format) object files, so that `collect2' can assume this format
+ and scan object files directly for dynamic constructor/destructor
+ functions.
+
+`OBJECT_FORMAT_ROSE'
+ Define this macro if the system uses ROSE format object files, so
+ that `collect2' can assume this format and scan object files
+ directly for dynamic constructor/destructor functions.
+
+ These macros are effective only in a native compiler; `collect2' as
+ part of a cross compiler always uses `nm' for the target machine.
+
+`REAL_NM_FILE_NAME'
+ Define this macro as a C string constant containing the file name
+ to use to execute `nm'. The default is to search the path
+ normally for `nm'.
+
+ If your system supports shared libraries and has a program to list
+ the dynamic dependencies of a given library or executable, you can
+ define these macros to enable support for running initialization
+ and termination functions in shared libraries:
+
+`LDD_SUFFIX'
+ Define this macro to a C string constant containing the name of
+ the program which lists dynamic dependencies, like `"ldd"' under
+ SunOS 4.
+
+`PARSE_LDD_OUTPUT (PTR)'
+ Define this macro to be C code that extracts filenames from the
+ output of the program denoted by `LDD_SUFFIX'. PTR is a variable
+ of type `char *' that points to the beginning of a line of output
+ from `LDD_SUFFIX'. If the line lists a dynamic dependency, the
+ code must advance PTR to the beginning of the filename on that
+ line. Otherwise, it must set PTR to `NULL'.
+
+\1f
+File: gccint.info, Node: Instruction Output, Next: Dispatch Tables, Prev: Macros for Initialization, Up: Assembler Format
+
+10.20.7 Output of Assembler Instructions
+----------------------------------------
+
+This describes assembler instruction output.
+
+`REGISTER_NAMES'
+ A C initializer containing the assembler's names for the machine
+ registers, each one as a C string constant. This is what
+ translates register numbers in the compiler into assembler
+ language.
+
+`ADDITIONAL_REGISTER_NAMES'
+ If defined, a C initializer for an array of structures containing
+ a name and a register number. This macro defines additional names
+ for hard registers, thus allowing the `asm' option in declarations
+ to refer to registers using alternate names.
+
+`ASM_OUTPUT_OPCODE (STREAM, PTR)'
+ Define this macro if you are using an unusual assembler that
+ requires different names for the machine instructions.
+
+ The definition is a C statement or statements which output an
+ assembler instruction opcode to the stdio stream STREAM. The
+ macro-operand PTR is a variable of type `char *' which points to
+ the opcode name in its "internal" form--the form that is written
+ in the machine description. The definition should output the
+ opcode name to STREAM, performing any translation you desire, and
+ increment the variable PTR to point at the end of the opcode so
+ that it will not be output twice.
+
+ In fact, your macro definition may process less than the entire
+ opcode name, or more than the opcode name; but if you want to
+ process text that includes `%'-sequences to substitute operands,
+ you must take care of the substitution yourself. Just be sure to
+ increment PTR over whatever text should not be output normally.
+
+ If you need to look at the operand values, they can be found as the
+ elements of `recog_data.operand'.
+
+ If the macro definition does nothing, the instruction is output in
+ the usual way.
+
+`FINAL_PRESCAN_INSN (INSN, OPVEC, NOPERANDS)'
+ If defined, a C statement to be executed just prior to the output
+ of assembler code for INSN, to modify the extracted operands so
+ they will be output differently.
+
+ Here the argument OPVEC is the vector containing the operands
+ extracted from INSN, and NOPERANDS is the number of elements of
+ the vector which contain meaningful data for this insn. The
+ contents of this vector are what will be used to convert the insn
+ template into assembler code, so you can change the assembler
+ output by changing the contents of the vector.
+
+ This macro is useful when various assembler syntaxes share a single
+ file of instruction patterns; by defining this macro differently,
+ you can cause a large class of instructions to be output
+ differently (such as with rearranged operands). Naturally,
+ variations in assembler syntax affecting individual insn patterns
+ ought to be handled by writing conditional output routines in
+ those patterns.
+
+ If this macro is not defined, it is equivalent to a null statement.
+
+`FINAL_PRESCAN_LABEL'
+ If defined, `FINAL_PRESCAN_INSN' will be called on each
+ `CODE_LABEL'. In that case, OPVEC will be a null pointer and
+ NOPERANDS will be zero.
+
+`PRINT_OPERAND (STREAM, X, CODE)'
+ A C compound statement to output to stdio stream STREAM the
+ assembler syntax for an instruction operand X. X is an RTL
+ expression.
+
+ CODE is a value that can be used to specify one of several ways of
+ printing the operand. It is used when identical operands must be
+ printed differently depending on the context. CODE comes from the
+ `%' specification that was used to request printing of the
+ operand. If the specification was just `%DIGIT' then CODE is 0;
+ if the specification was `%LTR DIGIT' then CODE is the ASCII code
+ for LTR.
+
+ If X is a register, this macro should print the register's name.
+ The names can be found in an array `reg_names' whose type is `char
+ *[]'. `reg_names' is initialized from `REGISTER_NAMES'.
+
+ When the machine description has a specification `%PUNCT' (a `%'
+ followed by a punctuation character), this macro is called with a
+ null pointer for X and the punctuation character for CODE.
+
+`PRINT_OPERAND_PUNCT_VALID_P (CODE)'
+ A C expression which evaluates to true if CODE is a valid
+ punctuation character for use in the `PRINT_OPERAND' macro. If
+ `PRINT_OPERAND_PUNCT_VALID_P' is not defined, it means that no
+ punctuation characters (except for the standard one, `%') are used
+ in this way.
+
+`PRINT_OPERAND_ADDRESS (STREAM, X)'
+ A C compound statement to output to stdio stream STREAM the
+ assembler syntax for an instruction operand that is a memory
+ reference whose address is X. X is an RTL expression.
+
+ On some machines, the syntax for a symbolic address depends on the
+ section that the address refers to. On these machines, define the
+ macro `ENCODE_SECTION_INFO' to store the information into the
+ `symbol_ref', and then check for it here. *Note Assembler
+ Format::.
+
+`DBR_OUTPUT_SEQEND(FILE)'
+ A C statement, to be executed after all slot-filler instructions
+ have been output. If necessary, call `dbr_sequence_length' to
+ determine the number of slots filled in a sequence (zero if not
+ currently outputting a sequence), to decide how many no-ops to
+ output, or whatever.
+
+ Don't define this macro if it has nothing to do, but it is helpful
+ in reading assembly output if the extent of the delay sequence is
+ made explicit (e.g. with white space).
+
+ Note that output routines for instructions with delay slots must be
+ prepared to deal with not being output as part of a sequence (i.e.
+ when the scheduling pass is not run, or when no slot fillers could
+ be found.) The variable `final_sequence' is null when not
+ processing a sequence, otherwise it contains the `sequence' rtx
+ being output.
+
+`REGISTER_PREFIX'
+`LOCAL_LABEL_PREFIX'
+`USER_LABEL_PREFIX'
+`IMMEDIATE_PREFIX'
+ If defined, C string expressions to be used for the `%R', `%L',
+ `%U', and `%I' options of `asm_fprintf' (see `final.c'). These
+ are useful when a single `md' file must support multiple assembler
+ formats. In that case, the various `tm.h' files can define these
+ macros differently.
+
+`ASM_FPRINTF_EXTENSIONS(FILE, ARGPTR, FORMAT)'
+ If defined this macro should expand to a series of `case'
+ statements which will be parsed inside the `switch' statement of
+ the `asm_fprintf' function. This allows targets to define extra
+ printf formats which may useful when generating their assembler
+ statements. Note that upper case letters are reserved for future
+ generic extensions to asm_fprintf, and so are not available to
+ target specific code. The output file is given by the parameter
+ FILE. The varargs input pointer is ARGPTR and the rest of the
+ format string, starting the character after the one that is being
+ switched upon, is pointed to by FORMAT.
+
+`ASSEMBLER_DIALECT'
+ If your target supports multiple dialects of assembler language
+ (such as different opcodes), define this macro as a C expression
+ that gives the numeric index of the assembler language dialect to
+ use, with zero as the first variant.
+
+ If this macro is defined, you may use constructs of the form
+ `{option0|option1|option2...}'
+ in the output templates of patterns (*note Output Template::) or
+ in the first argument of `asm_fprintf'. This construct outputs
+ `option0', `option1', `option2', etc., if the value of
+ `ASSEMBLER_DIALECT' is zero, one, two, etc. Any special characters
+ within these strings retain their usual meaning. If there are
+ fewer alternatives within the braces than the value of
+ `ASSEMBLER_DIALECT', the construct outputs nothing.
+
+ If you do not define this macro, the characters `{', `|' and `}'
+ do not have any special meaning when used in templates or operands
+ to `asm_fprintf'.
+
+ Define the macros `REGISTER_PREFIX', `LOCAL_LABEL_PREFIX',
+ `USER_LABEL_PREFIX' and `IMMEDIATE_PREFIX' if you can express the
+ variations in assembler language syntax with that mechanism.
+ Define `ASSEMBLER_DIALECT' and use the `{option0|option1}' syntax
+ if the syntax variant are larger and involve such things as
+ different opcodes or operand order.
+
+`ASM_OUTPUT_REG_PUSH (STREAM, REGNO)'
+ A C expression to output to STREAM some assembler code which will
+ push hard register number REGNO onto the stack. The code need not
+ be optimal, since this macro is used only when profiling.
+
+`ASM_OUTPUT_REG_POP (STREAM, REGNO)'
+ A C expression to output to STREAM some assembler code which will
+ pop hard register number REGNO off of the stack. The code need
+ not be optimal, since this macro is used only when profiling.
+
+\1f
+File: gccint.info, Node: Dispatch Tables, Next: Exception Region Output, Prev: Instruction Output, Up: Assembler Format
+
+10.20.8 Output of Dispatch Tables
+---------------------------------
+
+This concerns dispatch tables.
+
+`ASM_OUTPUT_ADDR_DIFF_ELT (STREAM, BODY, VALUE, REL)'
+ A C statement to output to the stdio stream STREAM an assembler
+ pseudo-instruction to generate a difference between two labels.
+ VALUE and REL are the numbers of two internal labels. The
+ definitions of these labels are output using
+ `ASM_OUTPUT_INTERNAL_LABEL', and they must be printed in the same
+ way here. For example,
+
+ fprintf (STREAM, "\t.word L%d-L%d\n",
+ VALUE, REL)
+
+ You must provide this macro on machines where the addresses in a
+ dispatch table are relative to the table's own address. If
+ defined, GCC will also use this macro on all machines when
+ producing PIC. BODY is the body of the `ADDR_DIFF_VEC'; it is
+ provided so that the mode and flags can be read.
+
+`ASM_OUTPUT_ADDR_VEC_ELT (STREAM, VALUE)'
+ This macro should be provided on machines where the addresses in a
+ dispatch table are absolute.
+
+ The definition should be a C statement to output to the stdio
+ stream STREAM an assembler pseudo-instruction to generate a
+ reference to a label. VALUE is the number of an internal label
+ whose definition is output using `ASM_OUTPUT_INTERNAL_LABEL'. For
+ example,
+
+ fprintf (STREAM, "\t.word L%d\n", VALUE)
+
+`ASM_OUTPUT_CASE_LABEL (STREAM, PREFIX, NUM, TABLE)'
+ Define this if the label before a jump-table needs to be output
+ specially. The first three arguments are the same as for
+ `ASM_OUTPUT_INTERNAL_LABEL'; the fourth argument is the jump-table
+ which follows (a `jump_insn' containing an `addr_vec' or
+ `addr_diff_vec').
+
+ This feature is used on system V to output a `swbeg' statement for
+ the table.
+
+ If this macro is not defined, these labels are output with
+ `ASM_OUTPUT_INTERNAL_LABEL'.
+
+`ASM_OUTPUT_CASE_END (STREAM, NUM, TABLE)'
+ Define this if something special must be output at the end of a
+ jump-table. The definition should be a C statement to be executed
+ after the assembler code for the table is written. It should write
+ the appropriate code to stdio stream STREAM. The argument TABLE
+ is the jump-table insn, and NUM is the label-number of the
+ preceding label.
+
+ If this macro is not defined, nothing special is output at the end
+ of the jump-table.
+
+\1f
+File: gccint.info, Node: Exception Region Output, Next: Alignment Output, Prev: Dispatch Tables, Up: Assembler Format
+
+10.20.9 Assembler Commands for Exception Regions
+------------------------------------------------
+
+This describes commands marking the start and the end of an exception
+region.
+
+`EH_FRAME_SECTION_NAME'
+ If defined, a C string constant for the name of the section
+ containing exception handling frame unwind information. If not
+ defined, GCC will provide a default definition if the target
+ supports named sections. `crtstuff.c' uses this macro to switch
+ to the appropriate section.
+
+ You should define this symbol if your target supports DWARF 2 frame
+ unwind information and the default definition does not work.
+
+`EH_FRAME_IN_DATA_SECTION'
+ If defined, DWARF 2 frame unwind information will be placed in the
+ data section even though the target supports named sections. This
+ might be necessary, for instance, if the system linker does garbage
+ collection and sections cannot be marked as not to be collected.
+
+ Do not define this macro unless `TARGET_ASM_NAMED_SECTION' is also
+ defined.
+
+`MASK_RETURN_ADDR'
+ An rtx used to mask the return address found via
+ `RETURN_ADDR_RTX', so that it does not contain any extraneous set
+ bits in it.
+
+`DWARF2_UNWIND_INFO'
+ Define this macro to 0 if your target supports DWARF 2 frame unwind
+ information, but it does not yet work with exception handling.
+ Otherwise, if your target supports this information (if it defines
+ `INCOMING_RETURN_ADDR_RTX' and either `UNALIGNED_INT_ASM_OP' or
+ `OBJECT_FORMAT_ELF'), GCC will provide a default definition of 1.
+
+ If this macro is defined to 1, the DWARF 2 unwinder will be the
+ default exception handling mechanism; otherwise,
+ `setjmp'/`longjmp' will be used by default.
+
+ If this macro is defined to anything, the DWARF 2 unwinder will be
+ used instead of inline unwinders and `__unwind_function' in the
+ non-`setjmp' case.
+
+`DWARF_CIE_DATA_ALIGNMENT'
+ This macro need only be defined if the target might save registers
+ in the function prologue at an offset to the stack pointer that is
+ not aligned to `UNITS_PER_WORD'. The definition should be the
+ negative minimum alignment if `STACK_GROWS_DOWNWARD' is defined,
+ and the positive minimum alignment otherwise. *Note SDB and
+ DWARF::. Only applicable if the target supports DWARF 2 frame
+ unwind information.
+
+
+ -- Target Hook: void TARGET_ASM_EXCEPTION_SECTION ()
+ If defined, a function that switches to the section in which the
+ main exception table is to be placed (*note Sections::). The
+ default is a function that switches to a section named
+ `.gcc_except_table' on machines that support named sections via
+ `TARGET_ASM_NAMED_SECTION', otherwise if `-fpic' or `-fPIC' is in
+ effect, the `data_section', otherwise the `readonly_data_section'.
+
+ -- Target Hook: void TARGET_ASM_EH_FRAME_SECTION ()
+ If defined, a function that switches to the section in which the
+ DWARF 2 frame unwind information to be placed (*note Sections::).
+ The default is a function that outputs a standard GAS section
+ directive, if `EH_FRAME_SECTION_NAME' is defined, or else a data
+ section directive followed by a synthetic label.
+
+\1f
+File: gccint.info, Node: Alignment Output, Prev: Exception Region Output, Up: Assembler Format
+
+10.20.10 Assembler Commands for Alignment
+-----------------------------------------
+
+This describes commands for alignment.
+
+`JUMP_ALIGN (LABEL)'
+ The alignment (log base 2) to put in front of LABEL, which is a
+ common destination of jumps and has no fallthru incoming edge.
+
+ This macro need not be defined if you don't want any special
+ alignment to be done at such a time. Most machine descriptions do
+ not currently define the macro.
+
+ Unless it's necessary to inspect the LABEL parameter, it is better
+ to set the variable ALIGN_JUMPS in the target's
+ `OVERRIDE_OPTIONS'. Otherwise, you should try to honor the user's
+ selection in ALIGN_JUMPS in a `JUMP_ALIGN' implementation.
+
+`LABEL_ALIGN_AFTER_BARRIER (LABEL)'
+ The alignment (log base 2) to put in front of LABEL, which follows
+ a `BARRIER'.
+
+ This macro need not be defined if you don't want any special
+ alignment to be done at such a time. Most machine descriptions do
+ not currently define the macro.
+
+`LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP'
+ The maximum number of bytes to skip when applying
+ `LABEL_ALIGN_AFTER_BARRIER'. This works only if
+ `ASM_OUTPUT_MAX_SKIP_ALIGN' is defined.
+
+`LOOP_ALIGN (LABEL)'
+ The alignment (log base 2) to put in front of LABEL, which follows
+ a `NOTE_INSN_LOOP_BEG' note.
+
+ This macro need not be defined if you don't want any special
+ alignment to be done at such a time. Most machine descriptions do
+ not currently define the macro.
+
+ Unless it's necessary to inspect the LABEL parameter, it is better
+ to set the variable `align_loops' in the target's
+ `OVERRIDE_OPTIONS'. Otherwise, you should try to honor the user's
+ selection in `align_loops' in a `LOOP_ALIGN' implementation.
+
+`LOOP_ALIGN_MAX_SKIP'
+ The maximum number of bytes to skip when applying `LOOP_ALIGN'.
+ This works only if `ASM_OUTPUT_MAX_SKIP_ALIGN' is defined.
+
+`LABEL_ALIGN (LABEL)'
+ The alignment (log base 2) to put in front of LABEL. If
+ `LABEL_ALIGN_AFTER_BARRIER' / `LOOP_ALIGN' specify a different
+ alignment, the maximum of the specified values is used.
+
+ Unless it's necessary to inspect the LABEL parameter, it is better
+ to set the variable `align_labels' in the target's
+ `OVERRIDE_OPTIONS'. Otherwise, you should try to honor the user's
+ selection in `align_labels' in a `LABEL_ALIGN' implementation.
+
+`LABEL_ALIGN_MAX_SKIP'
+ The maximum number of bytes to skip when applying `LABEL_ALIGN'.
+ This works only if `ASM_OUTPUT_MAX_SKIP_ALIGN' is defined.
+
+`ASM_OUTPUT_SKIP (STREAM, NBYTES)'
+ A C statement to output to the stdio stream STREAM an assembler
+ instruction to advance the location counter by NBYTES bytes.
+ Those bytes should be zero when loaded. NBYTES will be a C
+ expression of type `int'.
+
+`ASM_NO_SKIP_IN_TEXT'
+ Define this macro if `ASM_OUTPUT_SKIP' should not be used in the
+ text section because it fails to put zeros in the bytes that are
+ skipped. This is true on many Unix systems, where the pseudo-op
+ to skip bytes produces no-op instructions rather than zeros when
+ used in the text section.
+
+`ASM_OUTPUT_ALIGN (STREAM, POWER)'
+ A C statement to output to the stdio stream STREAM an assembler
+ command to advance the location counter to a multiple of 2 to the
+ POWER bytes. POWER will be a C expression of type `int'.
+
+`ASM_OUTPUT_MAX_SKIP_ALIGN (STREAM, POWER, MAX_SKIP)'
+ A C statement to output to the stdio stream STREAM an assembler
+ command to advance the location counter to a multiple of 2 to the
+ POWER bytes, but only if MAX_SKIP or fewer bytes are needed to
+ satisfy the alignment request. POWER and MAX_SKIP will be a C
+ expression of type `int'.
+
+\1f
+File: gccint.info, Node: Debugging Info, Next: Cross-compilation, Prev: Assembler Format, Up: Target Macros
+
+10.21 Controlling Debugging Information Format
+==============================================
+
+This describes how to specify debugging information.
* Menu:
-* Function Basics:: Function names, linkage, and so forth.
-* Function Bodies:: The statements that make up a function body.
+* All Debuggers:: Macros that affect all debugging formats uniformly.
+* DBX Options:: Macros enabling specific options in DBX format.
+* DBX Hooks:: Hook macros for varying DBX format.
+* File Names and DBX:: Macros controlling output of file names in DBX format.
+* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats.
+* VMS Debug:: Macros for VMS debug format.
\1f
-File: gccint.info, Node: Function Basics, Next: Function Bodies, Up: Functions
+File: gccint.info, Node: All Debuggers, Next: DBX Options, Up: Debugging Info
+
+10.21.1 Macros Affecting All Debugging Formats
+----------------------------------------------
+
+These macros affect all debugging formats.
+
+`DBX_REGISTER_NUMBER (REGNO)'
+ A C expression that returns the DBX register number for the
+ compiler register number REGNO. In the default macro provided,
+ the value of this expression will be REGNO itself. But sometimes
+ there are some registers that the compiler knows about and DBX
+ does not, or vice versa. In such cases, some register may need to
+ have one number in the compiler and another for DBX.
+
+ If two registers have consecutive numbers inside GCC, and they can
+ be used as a pair to hold a multiword value, then they _must_ have
+ consecutive numbers after renumbering with `DBX_REGISTER_NUMBER'.
+ Otherwise, debuggers will be unable to access such a pair, because
+ they expect register pairs to be consecutive in their own
+ numbering scheme.
+
+ If you find yourself defining `DBX_REGISTER_NUMBER' in way that
+ does not preserve register pairs, then what you must do instead is
+ redefine the actual register numbering scheme.
+
+`DEBUGGER_AUTO_OFFSET (X)'
+ A C expression that returns the integer offset value for an
+ automatic variable having address X (an RTL expression). The
+ default computation assumes that X is based on the frame-pointer
+ and gives the offset from the frame-pointer. This is required for
+ targets that produce debugging output for DBX or COFF-style
+ debugging output for SDB and allow the frame-pointer to be
+ eliminated when the `-g' options is used.
+
+`DEBUGGER_ARG_OFFSET (OFFSET, X)'
+ A C expression that returns the integer offset value for an
+ argument having address X (an RTL expression). The nominal offset
+ is OFFSET.
+
+`PREFERRED_DEBUGGING_TYPE'
+ A C expression that returns the type of debugging output GCC should
+ produce when the user specifies just `-g'. Define this if you
+ have arranged for GCC to support more than one format of debugging
+ output. Currently, the allowable values are `DBX_DEBUG',
+ `SDB_DEBUG', `DWARF_DEBUG', `DWARF2_DEBUG', `XCOFF_DEBUG',
+ `VMS_DEBUG', and `VMS_AND_DWARF2_DEBUG'.
+
+ When the user specifies `-ggdb', GCC normally also uses the value
+ of this macro to select the debugging output format, but with two
+ exceptions. If `DWARF2_DEBUGGING_INFO' is defined and
+ `LINKER_DOES_NOT_WORK_WITH_DWARF2' is not defined, GCC uses the
+ value `DWARF2_DEBUG'. Otherwise, if `DBX_DEBUGGING_INFO' is
+ defined, GCC uses `DBX_DEBUG'.
+
+ The value of this macro only affects the default debugging output;
+ the user can always get a specific type of output by using
+ `-gstabs', `-gcoff', `-gdwarf-1', `-gdwarf-2', `-gxcoff', or
+ `-gvms'.
-Function Basics
----------------
+\1f
+File: gccint.info, Node: DBX Options, Next: DBX Hooks, Prev: All Debuggers, Up: Debugging Info
+
+10.21.2 Specific Options for DBX Output
+---------------------------------------
+
+These are specific options for DBX output.
+
+`DBX_DEBUGGING_INFO'
+ Define this macro if GCC should produce debugging output for DBX
+ in response to the `-g' option.
+
+`XCOFF_DEBUGGING_INFO'
+ Define this macro if GCC should produce XCOFF format debugging
+ output in response to the `-g' option. This is a variant of DBX
+ format.
+
+`DEFAULT_GDB_EXTENSIONS'
+ Define this macro to control whether GCC should by default generate
+ GDB's extended version of DBX debugging information (assuming
+ DBX-format debugging information is enabled at all). If you don't
+ define the macro, the default is 1: always generate the extended
+ information if there is any occasion to.
+
+`DEBUG_SYMS_TEXT'
+ Define this macro if all `.stabs' commands should be output while
+ in the text section.
+
+`ASM_STABS_OP'
+ A C string constant, including spacing, naming the assembler
+ pseudo op to use instead of `"\t.stabs\t"' to define an ordinary
+ debugging symbol. If you don't define this macro, `"\t.stabs\t"'
+ is used. This macro applies only to DBX debugging information
+ format.
+
+`ASM_STABD_OP'
+ A C string constant, including spacing, naming the assembler
+ pseudo op to use instead of `"\t.stabd\t"' to define a debugging
+ symbol whose value is the current location. If you don't define
+ this macro, `"\t.stabd\t"' is used. This macro applies only to
+ DBX debugging information format.
+
+`ASM_STABN_OP'
+ A C string constant, including spacing, naming the assembler
+ pseudo op to use instead of `"\t.stabn\t"' to define a debugging
+ symbol with no name. If you don't define this macro,
+ `"\t.stabn\t"' is used. This macro applies only to DBX debugging
+ information format.
+
+`DBX_NO_XREFS'
+ Define this macro if DBX on your system does not support the
+ construct `xsTAGNAME'. On some systems, this construct is used to
+ describe a forward reference to a structure named TAGNAME. On
+ other systems, this construct is not supported at all.
+
+`DBX_CONTIN_LENGTH'
+ A symbol name in DBX-format debugging information is normally
+ continued (split into two separate `.stabs' directives) when it
+ exceeds a certain length (by default, 80 characters). On some
+ operating systems, DBX requires this splitting; on others,
+ splitting must not be done. You can inhibit splitting by defining
+ this macro with the value zero. You can override the default
+ splitting-length by defining this macro as an expression for the
+ length you desire.
+
+`DBX_CONTIN_CHAR'
+ Normally continuation is indicated by adding a `\' character to
+ the end of a `.stabs' string when a continuation follows. To use
+ a different character instead, define this macro as a character
+ constant for the character you want to use. Do not define this
+ macro if backslash is correct for your system.
+
+`DBX_STATIC_STAB_DATA_SECTION'
+ Define this macro if it is necessary to go to the data section
+ before outputting the `.stabs' pseudo-op for a non-global static
+ variable.
+
+`DBX_TYPE_DECL_STABS_CODE'
+ The value to use in the "code" field of the `.stabs' directive for
+ a typedef. The default is `N_LSYM'.
+
+`DBX_STATIC_CONST_VAR_CODE'
+ The value to use in the "code" field of the `.stabs' directive for
+ a static variable located in the text section. DBX format does not
+ provide any "right" way to do this. The default is `N_FUN'.
+
+`DBX_REGPARM_STABS_CODE'
+ The value to use in the "code" field of the `.stabs' directive for
+ a parameter passed in registers. DBX format does not provide any
+ "right" way to do this. The default is `N_RSYM'.
+
+`DBX_REGPARM_STABS_LETTER'
+ The letter to use in DBX symbol data to identify a symbol as a
+ parameter passed in registers. DBX format does not customarily
+ provide any way to do this. The default is `'P''.
+
+`DBX_MEMPARM_STABS_LETTER'
+ The letter to use in DBX symbol data to identify a symbol as a
+ stack parameter. The default is `'p''.
+
+`DBX_FUNCTION_FIRST'
+ Define this macro if the DBX information for a function and its
+ arguments should precede the assembler code for the function.
+ Normally, in DBX format, the debugging information entirely
+ follows the assembler code.
+
+`DBX_LBRAC_FIRST'
+ Define this macro if the `N_LBRAC' symbol for a block should
+ precede the debugging information for variables and functions
+ defined in that block. Normally, in DBX format, the `N_LBRAC'
+ symbol comes first.
+
+`DBX_BLOCKS_FUNCTION_RELATIVE'
+ Define this macro if the value of a symbol describing the scope of
+ a block (`N_LBRAC' or `N_RBRAC') should be relative to the start
+ of the enclosing function. Normally, GCC uses an absolute address.
+
+`DBX_USE_BINCL'
+ Define this macro if GCC should generate `N_BINCL' and `N_EINCL'
+ stabs for included header files, as on Sun systems. This macro
+ also directs GCC to output a type number as a pair of a file
+ number and a type number within the file. Normally, GCC does not
+ generate `N_BINCL' or `N_EINCL' stabs, and it outputs a single
+ number for a type number.
- The following macros and functions can be used on a `FUNCTION_DECL':
-`DECL_MAIN_P'
- This predicate holds for a function that is the program entry point
- `::code'.
+\1f
+File: gccint.info, Node: DBX Hooks, Next: File Names and DBX, Prev: DBX Options, Up: Debugging Info
+
+10.21.3 Open-Ended Hooks for DBX Format
+---------------------------------------
+
+These are hooks for DBX format.
+
+`DBX_OUTPUT_LBRAC (STREAM, NAME)'
+ Define this macro to say how to output to STREAM the debugging
+ information for the start of a scope level for variable names. The
+ argument NAME is the name of an assembler symbol (for use with
+ `assemble_name') whose value is the address where the scope begins.
+
+`DBX_OUTPUT_RBRAC (STREAM, NAME)'
+ Like `DBX_OUTPUT_LBRAC', but for the end of a scope level.
+
+`DBX_OUTPUT_NFUN (STREAM, LSCOPE_LABEL, DECL)'
+ Define this macro if the target machine requires special handling
+ to output an `N_FUN' entry for the function DECL.
+
+`DBX_OUTPUT_ENUM (STREAM, TYPE)'
+ Define this macro if the target machine requires special handling
+ to output an enumeration type. The definition should be a C
+ statement (sans semicolon) to output the appropriate information
+ to STREAM for the type TYPE.
+
+`DBX_OUTPUT_FUNCTION_END (STREAM, FUNCTION)'
+ Define this macro if the target machine requires special output at
+ the end of the debugging information for a function. The
+ definition should be a C statement (sans semicolon) to output the
+ appropriate information to STREAM. FUNCTION is the
+ `FUNCTION_DECL' node for the function.
+
+`DBX_OUTPUT_STANDARD_TYPES (SYMS)'
+ Define this macro if you need to control the order of output of the
+ standard data types at the beginning of compilation. The argument
+ SYMS is a `tree' which is a chain of all the predefined global
+ symbols, including names of data types.
+
+ Normally, DBX output starts with definitions of the types for
+ integers and characters, followed by all the other predefined
+ types of the particular language in no particular order.
+
+ On some machines, it is necessary to output different particular
+ types first. To do this, define `DBX_OUTPUT_STANDARD_TYPES' to
+ output those symbols in the necessary order. Any predefined types
+ that you don't explicitly output will be output afterward in no
+ particular order.
+
+ Be careful not to define this macro so that it works only for C.
+ There are no global variables to access most of the built-in
+ types, because another language may have another set of types.
+ The way to output a particular type is to look through SYMS to see
+ if you can find it. Here is an example:
+
+ {
+ tree decl;
+ for (decl = syms; decl; decl = TREE_CHAIN (decl))
+ if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)),
+ "long int"))
+ dbxout_symbol (decl);
+ ...
+ }
+
+ This does nothing if the expected type does not exist.
+
+ See the function `init_decl_processing' in `c-decl.c' to find the
+ names to use for all the built-in C types.
+
+ Here is another way of finding a particular type:
+
+ {
+ tree decl;
+ for (decl = syms; decl; decl = TREE_CHAIN (decl))
+ if (TREE_CODE (decl) == TYPE_DECL
+ && (TREE_CODE (TREE_TYPE (decl))
+ == INTEGER_CST)
+ && TYPE_PRECISION (TREE_TYPE (decl)) == 16
+ && TYPE_UNSIGNED (TREE_TYPE (decl)))
+ /* This must be `unsigned short'. */
+ dbxout_symbol (decl);
+ ...
+ }
+
+`NO_DBX_FUNCTION_END'
+ Some stabs encapsulation formats (in particular ECOFF), cannot
+ handle the `.stabs "",N_FUN,,0,0,Lscope-function-1' gdb dbx
+ extension construct. On those machines, define this macro to turn
+ this feature off without disturbing the rest of the gdb extensions.
-`DECL_NAME'
- This macro returns the unqualified name of the function, as an
- `IDENTIFIER_NODE'. For an instantiation of a function template,
- the `DECL_NAME' is the unqualified name of the template, not
- something like `f<int>'. The value of `DECL_NAME' is undefined
- when used on a constructor, destructor, overloaded operator, or
- type-conversion operator, or any function that is implicitly
- generated by the compiler. See below for macros that can be used
- to distinguish these cases.
-`DECL_ASSEMBLER_NAME'
- This macro returns the mangled name of the function, also an
- `IDENTIFIER_NODE'. This name does not contain leading underscores
- on systems that prefix all identifiers with underscores. The
- mangled name is computed in the same way on all platforms; if
- special processing is required to deal with the object file format
- used on a particular platform, it is the responsibility of the
- back end to perform those modifications. (Of course, the back end
- should not modify `DECL_ASSEMBLER_NAME' itself.)
+\1f
+File: gccint.info, Node: File Names and DBX, Next: SDB and DWARF, Prev: DBX Hooks, Up: Debugging Info
-`DECL_EXTERNAL'
- This predicate holds if the function is undefined.
+10.21.4 File Names in DBX Format
+--------------------------------
-`TREE_PUBLIC'
- This predicate holds if the function has external linkage.
+This describes file names in DBX format.
-`DECL_LOCAL_FUNCTION_P'
- This predicate holds if the function was declared at block scope,
- even though it has a global scope.
+`DBX_WORKING_DIRECTORY'
+ Define this if DBX wants to have the current directory recorded in
+ each object file.
-`DECL_ANTICIPATED'
- This predicate holds if the function is a built-in function but its
- prototype is not yet explicitly declared.
+ Note that the working directory is always recorded if GDB
+ extensions are enabled.
-`DECL_EXTERN_C_FUNCTION_P'
- This predicate holds if the function is declared as an ``extern
- "C"'' function.
+`DBX_OUTPUT_MAIN_SOURCE_FILENAME (STREAM, NAME)'
+ A C statement to output DBX debugging information to the stdio
+ stream STREAM which indicates that file NAME is the main source
+ file--the file specified as the input file for compilation. This
+ macro is called only once, at the beginning of compilation.
-`DECL_LINKONCE_P'
- This macro holds if multiple copies of this function may be
- emitted in various translation units. It is the responsibility of
- the linker to merge the various copies. Template instantiations
- are the most common example of functions for which
- `DECL_LINKONCE_P' holds; G++ instantiates needed templates in all
- translation units which require them, and then relies on the
- linker to remove duplicate instantiations.
+ This macro need not be defined if the standard form of output for
+ DBX debugging information is appropriate.
- FIXME: This macro is not yet implemented.
+`DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (STREAM, NAME)'
+ A C statement to output DBX debugging information to the stdio
+ stream STREAM which indicates that the current directory during
+ compilation is named NAME.
-`DECL_FUNCTION_MEMBER_P'
- This macro holds if the function is a member of a class, rather
- than a member of a namespace.
+ This macro need not be defined if the standard form of output for
+ DBX debugging information is appropriate.
-`DECL_STATIC_FUNCTION_P'
- This predicate holds if the function a static member function.
+`DBX_OUTPUT_MAIN_SOURCE_FILE_END (STREAM, NAME)'
+ A C statement to output DBX debugging information at the end of
+ compilation of the main source file NAME.
-`DECL_NONSTATIC_MEMBER_FUNCTION_P'
- This macro holds for a non-static member function.
+ If you don't define this macro, nothing special is output at the
+ end of compilation, which is correct for most machines.
-`DECL_CONST_MEMFUNC_P'
- This predicate holds for a `const'-member function.
+`DBX_OUTPUT_SOURCE_FILENAME (STREAM, NAME)'
+ A C statement to output DBX debugging information to the stdio
+ stream STREAM which indicates that file NAME is the current source
+ file. This output is generated each time input shifts to a
+ different source file as a result of `#include', the end of an
+ included file, or a `#line' command.
-`DECL_VOLATILE_MEMFUNC_P'
- This predicate holds for a `volatile'-member function.
+ This macro need not be defined if the standard form of output for
+ DBX debugging information is appropriate.
-`DECL_CONSTRUCTOR_P'
- This macro holds if the function is a constructor.
+\1f
+File: gccint.info, Node: SDB and DWARF, Next: VMS Debug, Prev: File Names and DBX, Up: Debugging Info
+
+10.21.5 Macros for SDB and DWARF Output
+---------------------------------------
+
+Here are macros for SDB and DWARF output.
+
+`SDB_DEBUGGING_INFO'
+ Define this macro if GCC should produce COFF-style debugging output
+ for SDB in response to the `-g' option.
+
+`DWARF_DEBUGGING_INFO'
+ Define this macro if GCC should produce dwarf format debugging
+ output in response to the `-g' option.
+
+`DWARF2_DEBUGGING_INFO'
+ Define this macro if GCC should produce dwarf version 2 format
+ debugging output in response to the `-g' option.
+
+ To support optional call frame debugging information, you must also
+ define `INCOMING_RETURN_ADDR_RTX' and either set
+ `RTX_FRAME_RELATED_P' on the prologue insns if you use RTL for the
+ prologue, or call `dwarf2out_def_cfa' and `dwarf2out_reg_save' as
+ appropriate from `TARGET_ASM_FUNCTION_PROLOGUE' if you don't.
+
+`DWARF2_FRAME_INFO'
+ Define this macro to a nonzero value if GCC should always output
+ Dwarf 2 frame information. If `DWARF2_UNWIND_INFO' (*note
+ Exception Region Output:: is nonzero, GCC will output this
+ information not matter how you define `DWARF2_FRAME_INFO'.
+
+`LINKER_DOES_NOT_WORK_WITH_DWARF2'
+ Define this macro if the linker does not work with Dwarf version 2.
+ Normally, if the user specifies only `-ggdb' GCC will use Dwarf
+ version 2 if available; this macro disables this. See the
+ description of the `PREFERRED_DEBUGGING_TYPE' macro for more
+ details.
+
+`DWARF2_GENERATE_TEXT_SECTION_LABEL'
+ By default, the Dwarf 2 debugging information generator will
+ generate a label to mark the beginning of the text section. If it
+ is better simply to use the name of the text section itself,
+ rather than an explicit label, to indicate the beginning of the
+ text section, define this macro to zero.
+
+`DWARF2_ASM_LINE_DEBUG_INFO'
+ Define this macro to be a nonzero value if the assembler can
+ generate Dwarf 2 line debug info sections. This will result in
+ much more compact line number tables, and hence is desirable if it
+ works.
+
+`PUT_SDB_...'
+ Define these macros to override the assembler syntax for the
+ special SDB assembler directives. See `sdbout.c' for a list of
+ these macros and their arguments. If the standard syntax is used,
+ you need not define them yourself.
+
+`SDB_DELIM'
+ Some assemblers do not support a semicolon as a delimiter, even
+ between SDB assembler directives. In that case, define this macro
+ to be the delimiter to use (usually `\n'). It is not necessary to
+ define a new set of `PUT_SDB_OP' macros if this is the only change
+ required.
+
+`SDB_GENERATE_FAKE'
+ Define this macro to override the usual method of constructing a
+ dummy name for anonymous structure and union types. See
+ `sdbout.c' for more information.
+
+`SDB_ALLOW_UNKNOWN_REFERENCES'
+ Define this macro to allow references to unknown structure, union,
+ or enumeration tags to be emitted. Standard COFF does not allow
+ handling of unknown references, MIPS ECOFF has support for it.
+
+`SDB_ALLOW_FORWARD_REFERENCES'
+ Define this macro to allow references to structure, union, or
+ enumeration tags that have not yet been seen to be handled. Some
+ assemblers choke if forward tags are used, while some require it.
-`DECL_NONCONVERTING_P'
- This predicate holds if the constructor is a non-converting
- constructor.
+\1f
+File: gccint.info, Node: VMS Debug, Prev: SDB and DWARF, Up: Debugging Info
-`DECL_COMPLETE_CONSTRUCTOR_P'
- This predicate holds for a function which is a constructor for an
- object of a complete type.
+10.21.6 Macros for VMS Debug Format
+-----------------------------------
-`DECL_BASE_CONSTRUCTOR_P'
- This predicate holds for a function which is a constructor for a
- base class sub-object.
+Here are macros for VMS debug format.
-`DECL_COPY_CONSTRUCTOR_P'
- This predicate holds for a function which is a copy-constructor.
+`VMS_DEBUGGING_INFO'
+ Define this macro if GCC should produce debugging output for VMS
+ in response to the `-g' option. The default behavior for VMS is
+ to generate minimal debug info for a traceback in the absence of
+ `-g' unless explicitly overridden with `-g0'. This behavior is
+ controlled by `OPTIMIZATION_OPTIONS' and `OVERRIDE_OPTIONS'.
-`DECL_DESTRUCTOR_P'
- This macro holds if the function is a destructor.
+\1f
+File: gccint.info, Node: Cross-compilation, Next: Mode Switching, Prev: Debugging Info, Up: Target Macros
+
+10.22 Cross Compilation and Floating Point
+==========================================
+
+While all modern machines use 2's complement representation for
+integers, there are a variety of representations for floating point
+numbers. This means that in a cross-compiler the representation of
+floating point numbers in the compiled program may be different from
+that used in the machine doing the compilation.
+
+ Because different representation systems may offer different amounts
+of range and precision, the cross compiler cannot safely use the host
+machine's floating point arithmetic. Therefore, floating point
+constants must be represented in the target machine's format. This
+means that the cross compiler cannot use `atof' to parse a floating
+point constant; it must have its own special routine to use instead.
+Also, constant folding must emulate the target machine's arithmetic (or
+must not be done at all).
+
+ The macros in the following table should be defined only if you are
+cross compiling between different floating point formats.
+
+ Otherwise, don't define them. Then default definitions will be set
+up which use `double' as the data type, `==' to test for equality, etc.
+
+ You don't need to worry about how many times you use an operand of
+any of these macros. The compiler never uses operands which have side
+effects.
+
+`REAL_VALUE_TYPE'
+ A macro for the C data type to be used to hold a floating point
+ value in the target machine's format. Typically this would be a
+ `struct' containing an array of `int'.
+
+`REAL_VALUES_EQUAL (X, Y)'
+ A macro for a C expression which compares for equality the two
+ values, X and Y, both of type `REAL_VALUE_TYPE'.
+
+`REAL_VALUES_LESS (X, Y)'
+ A macro for a C expression which tests whether X is less than Y,
+ both values being of type `REAL_VALUE_TYPE' and interpreted as
+ floating point numbers in the target machine's representation.
+
+`REAL_VALUE_LDEXP (X, SCALE)'
+ A macro for a C expression which performs the standard library
+ function `ldexp', but using the target machine's floating point
+ representation. Both X and the value of the expression have type
+ `REAL_VALUE_TYPE'. The second argument, SCALE, is an integer.
+
+`REAL_VALUE_FIX (X)'
+ A macro whose definition is a C expression to convert the
+ target-machine floating point value X to a signed integer. X has
+ type `REAL_VALUE_TYPE'.
+
+`REAL_VALUE_UNSIGNED_FIX (X)'
+ A macro whose definition is a C expression to convert the
+ target-machine floating point value X to an unsigned integer. X
+ has type `REAL_VALUE_TYPE'.
+
+`REAL_VALUE_RNDZINT (X)'
+ A macro whose definition is a C expression to round the
+ target-machine floating point value X towards zero to an integer
+ value (but still as a floating point number). X has type
+ `REAL_VALUE_TYPE', and so does the value.
+
+`REAL_VALUE_UNSIGNED_RNDZINT (X)'
+ A macro whose definition is a C expression to round the
+ target-machine floating point value X towards zero to an unsigned
+ integer value (but still represented as a floating point number).
+ X has type `REAL_VALUE_TYPE', and so does the value.
+
+`REAL_VALUE_ATOF (STRING, MODE)'
+ A macro for a C expression which converts STRING, an expression of
+ type `char *', into a floating point number in the target machine's
+ representation for mode MODE. The value has type
+ `REAL_VALUE_TYPE'.
+
+`REAL_INFINITY'
+ Define this macro if infinity is a possible floating point value,
+ and therefore division by 0 is legitimate.
+
+`REAL_VALUE_ISINF (X)'
+ A macro for a C expression which determines whether X, a floating
+ point value, is infinity. The value has type `int'. By default,
+ this is defined to call `isinf'.
+
+`REAL_VALUE_ISNAN (X)'
+ A macro for a C expression which determines whether X, a floating
+ point value, is a "nan" (not-a-number). The value has type `int'.
+ By default, this is defined to call `isnan'.
+
+ Define the following additional macros if you want to make floating
+point constant folding work while cross compiling. If you don't define
+them, cross compilation is still possible, but constant folding will
+not happen for floating point values.
+
+`REAL_ARITHMETIC (OUTPUT, CODE, X, Y)'
+ A macro for a C statement which calculates an arithmetic operation
+ of the two floating point values X and Y, both of type
+ `REAL_VALUE_TYPE' in the target machine's representation, to
+ produce a result of the same type and representation which is
+ stored in OUTPUT (which will be a variable).
+
+ The operation to be performed is specified by CODE, a tree code
+ which will always be one of the following: `PLUS_EXPR',
+ `MINUS_EXPR', `MULT_EXPR', `RDIV_EXPR', `MAX_EXPR', `MIN_EXPR'.
+
+ The expansion of this macro is responsible for checking for
+ overflow. If overflow happens, the macro expansion should execute
+ the statement `return 0;', which indicates the inability to
+ perform the arithmetic operation requested.
+
+`REAL_VALUE_NEGATE (X)'
+ A macro for a C expression which returns the negative of the
+ floating point value X. Both X and the value of the expression
+ have type `REAL_VALUE_TYPE' and are in the target machine's
+ floating point representation.
+
+ There is no way for this macro to report overflow, since overflow
+ can't happen in the negation operation.
+
+`REAL_VALUE_TRUNCATE (MODE, X)'
+ A macro for a C expression which converts the floating point value
+ X to mode MODE.
+
+ Both X and the value of the expression are in the target machine's
+ floating point representation and have type `REAL_VALUE_TYPE'.
+ However, the value should have an appropriate bit pattern to be
+ output properly as a floating constant whose precision accords
+ with mode MODE.
+
+ There is no way for this macro to report overflow.
+
+`REAL_VALUE_TO_INT (LOW, HIGH, X)'
+ A macro for a C expression which converts a floating point value X
+ into a double-precision integer which is then stored into LOW and
+ HIGH, two variables of type INT.
+
+`REAL_VALUE_FROM_INT (X, LOW, HIGH, MODE)'
+ A macro for a C expression which converts a double-precision
+ integer found in LOW and HIGH, two variables of type INT, into a
+ floating point value which is then stored into X. The value is in
+ the target machine's representation for mode MODE and has the type
+ `REAL_VALUE_TYPE'.
-`DECL_COMPLETE_DESTRUCTOR_P'
- This predicate holds if the function is the destructor for an
- object a complete type.
+\1f
+File: gccint.info, Node: Mode Switching, Next: Target Attributes, Prev: Cross-compilation, Up: Target Macros
+
+10.23 Mode Switching Instructions
+=================================
+
+The following macros control mode switching optimizations:
+
+`OPTIMIZE_MODE_SWITCHING (ENTITY)'
+ Define this macro if the port needs extra instructions inserted
+ for mode switching in an optimizing compilation.
+
+ For an example, the SH4 can perform both single and double
+ precision floating point operations, but to perform a single
+ precision operation, the FPSCR PR bit has to be cleared, while for
+ a double precision operation, this bit has to be set. Changing
+ the PR bit requires a general purpose register as a scratch
+ register, hence these FPSCR sets have to be inserted before
+ reload, i.e. you can't put this into instruction emitting or
+ `MACHINE_DEPENDENT_REORG'.
+
+ You can have multiple entities that are mode-switched, and select
+ at run time which entities actually need it.
+ `OPTIMIZE_MODE_SWITCHING' should return nonzero for any ENTITY
+ that needs mode-switching. If you define this macro, you also
+ have to define `NUM_MODES_FOR_MODE_SWITCHING', `MODE_NEEDED',
+ `MODE_PRIORITY_TO_MODE' and `EMIT_MODE_SET'. `NORMAL_MODE' is
+ optional.
+
+`NUM_MODES_FOR_MODE_SWITCHING'
+ If you define `OPTIMIZE_MODE_SWITCHING', you have to define this as
+ initializer for an array of integers. Each initializer element N
+ refers to an entity that needs mode switching, and specifies the
+ number of different modes that might need to be set for this
+ entity. The position of the initializer in the initializer -
+ starting counting at zero - determines the integer that is used to
+ refer to the mode-switched entity in question. In macros that
+ take mode arguments / yield a mode result, modes are represented
+ as numbers 0 ... N - 1. N is used to specify that no mode switch
+ is needed / supplied.
+
+`MODE_NEEDED (ENTITY, INSN)'
+ ENTITY is an integer specifying a mode-switched entity. If
+ `OPTIMIZE_MODE_SWITCHING' is defined, you must define this macro to
+ return an integer value not larger than the corresponding element
+ in `NUM_MODES_FOR_MODE_SWITCHING', to denote the mode that ENTITY
+ must be switched into prior to the execution of INSN.
+
+`NORMAL_MODE (ENTITY)'
+ If this macro is defined, it is evaluated for every ENTITY that
+ needs mode switching. It should evaluate to an integer, which is
+ a mode that ENTITY is assumed to be switched to at function entry
+ and exit.
+
+`MODE_PRIORITY_TO_MODE (ENTITY, N)'
+ This macro specifies the order in which modes for ENTITY are
+ processed. 0 is the highest priority,
+ `NUM_MODES_FOR_MODE_SWITCHING[ENTITY] - 1' the lowest. The value
+ of the macro should be an integer designating a mode for ENTITY.
+ For any fixed ENTITY, `mode_priority_to_mode' (ENTITY, N) shall be
+ a bijection in 0 ... `num_modes_for_mode_switching[ENTITY] - 1'.
+
+`EMIT_MODE_SET (ENTITY, MODE, HARD_REGS_LIVE)'
+ Generate one or more insns to set ENTITY to MODE. HARD_REG_LIVE
+ is the set of hard registers live at the point where the insn(s)
+ are to be inserted.
-`DECL_OVERLOADED_OPERATOR_P'
- This macro holds if the function is an overloaded operator.
-
-`DECL_CONV_FN_P'
- This macro holds if the function is a type-conversion operator.
-
-`DECL_GLOBAL_CTOR_P'
- This predicate holds if the function is a file-scope initialization
- function.
+\1f
+File: gccint.info, Node: Target Attributes, Next: Misc, Prev: Mode Switching, Up: Target Macros
+
+10.24 Defining target-specific uses of `__attribute__'
+======================================================
+
+Target-specific attributes may be defined for functions, data and types.
+These are described using the following target hooks; they also need to
+be documented in `extend.texi'.
+
+ -- Target Hook: const struct attribute_spec * TARGET_ATTRIBUTE_TABLE
+ If defined, this target hook points to an array of `struct
+ attribute_spec' (defined in `tree.h') specifying the machine
+ specific attributes for this target and some of the restrictions
+ on the entities to which these attributes are applied and the
+ arguments they take.
+
+ -- Target Hook: int TARGET_COMP_TYPE_ATTRIBUTES (tree TYPE1, tree
+ TYPE2)
+ If defined, this target hook is a function which returns zero if
+ the attributes on TYPE1 and TYPE2 are incompatible, one if they
+ are compatible, and two if they are nearly compatible (which
+ causes a warning to be generated). If this is not defined,
+ machine-specific attributes are supposed always to be compatible.
+
+ -- Target Hook: void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree TYPE)
+ If defined, this target hook is a function which assigns default
+ attributes to newly defined TYPE.
+
+ -- Target Hook: tree TARGET_MERGE_TYPE_ATTRIBUTES (tree TYPE1, tree
+ TYPE2)
+ Define this target hook if the merging of type attributes needs
+ special handling. If defined, the result is a list of the combined
+ `TYPE_ATTRIBUTES' of TYPE1 and TYPE2. It is assumed that
+ `comptypes' has already been called and returned 1. This function
+ may call `merge_attributes' to handle machine-independent merging.
+
+ -- Target Hook: tree TARGET_MERGE_DECL_ATTRIBUTES (tree OLDDECL, tree
+ NEWDECL)
+ Define this target hook if the merging of decl attributes needs
+ special handling. If defined, the result is a list of the combined
+ `DECL_ATTRIBUTES' of OLDDECL and NEWDECL. NEWDECL is a duplicate
+ declaration of OLDDECL. Examples of when this is needed are when
+ one attribute overrides another, or when an attribute is nullified
+ by a subsequent definition. This function may call
+ `merge_attributes' to handle machine-independent merging.
+
+ If the only target-specific handling you require is `dllimport' for
+ Windows targets, you should define the macro
+ `TARGET_DLLIMPORT_DECL_ATTRIBUTES'. This links in a function
+ called `merge_dllimport_decl_attributes' which can then be defined
+ as the expansion of `TARGET_MERGE_DECL_ATTRIBUTES'. This is done
+ in `i386/cygwin.h' and `i386/i386.c', for example.
+
+ -- Target Hook: void TARGET_INSERT_ATTRIBUTES (tree NODE, tree
+ *ATTR_PTR)
+ Define this target hook if you want to be able to add attributes
+ to a decl when it is being created. This is normally useful for
+ back ends which wish to implement a pragma by using the attributes
+ which correspond to the pragma's effect. The NODE argument is the
+ decl which is being created. The ATTR_PTR argument is a pointer
+ to the attribute list for this decl. The list itself should not
+ be modified, since it may be shared with other decls, but
+ attributes may be chained on the head of the list and `*ATTR_PTR'
+ modified to point to the new attributes, or a copy of the list may
+ be made if further changes are needed.
+
+ -- Target Hook: bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree
+ FNDECL)
+ This target hook returns `true' if it is ok to inline FNDECL into
+ the current function, despite its having target-specific
+ attributes, `false' otherwise. By default, if a function has a
+ target specific attribute attached to it, it will not be inlined.
-`DECL_GLOBAL_DTOR_P'
- This predicate holds if the function is a file-scope finalization
- function.
+\1f
+File: gccint.info, Node: Misc, Prev: Target Attributes, Up: Target Macros
+
+10.25 Miscellaneous Parameters
+==============================
+
+Here are several miscellaneous parameters.
+
+`PREDICATE_CODES'
+ Define this if you have defined special-purpose predicates in the
+ file `MACHINE.c'. This macro is called within an initializer of an
+ array of structures. The first field in the structure is the name
+ of a predicate and the second field is an array of rtl codes. For
+ each predicate, list all rtl codes that can be in expressions
+ matched by the predicate. The list should have a trailing comma.
+ Here is an example of two entries in the list for a typical RISC
+ machine:
+
+ #define PREDICATE_CODES \
+ {"gen_reg_rtx_operand", {SUBREG, REG}}, \
+ {"reg_or_short_cint_operand", {SUBREG, REG, CONST_INT}},
+
+ Defining this macro does not affect the generated code (however,
+ incorrect definitions that omit an rtl code that may be matched by
+ the predicate can cause the compiler to malfunction). Instead, it
+ allows the table built by `genrecog' to be more compact and
+ efficient, thus speeding up the compiler. The most important
+ predicates to include in the list specified by this macro are
+ those used in the most insn patterns.
+
+ For each predicate function named in `PREDICATE_CODES', a
+ declaration will be generated in `insn-codes.h'.
+
+`SPECIAL_MODE_PREDICATES'
+ Define this if you have special predicates that know special things
+ about modes. Genrecog will warn about certain forms of
+ `match_operand' without a mode; if the operand predicate is listed
+ in `SPECIAL_MODE_PREDICATES', the warning will be suppressed.
+
+ Here is an example from the IA-32 port (`ext_register_operand'
+ specially checks for `HImode' or `SImode' in preparation for a
+ byte extraction from `%ah' etc.).
+
+ #define SPECIAL_MODE_PREDICATES \
+ "ext_register_operand",
+
+`CASE_VECTOR_MODE'
+ An alias for a machine mode name. This is the machine mode that
+ elements of a jump-table should have.
+
+`CASE_VECTOR_SHORTEN_MODE (MIN_OFFSET, MAX_OFFSET, BODY)'
+ Optional: return the preferred mode for an `addr_diff_vec' when
+ the minimum and maximum offset are known. If you define this, it
+ enables extra code in branch shortening to deal with
+ `addr_diff_vec'. To make this work, you also have to define
+ INSN_ALIGN and make the alignment for `addr_diff_vec' explicit.
+ The BODY argument is provided so that the offset_unsigned and scale
+ flags can be updated.
+
+`CASE_VECTOR_PC_RELATIVE'
+ Define this macro to be a C expression to indicate when jump-tables
+ should contain relative addresses. If jump-tables never contain
+ relative addresses, then you need not define this macro.
+
+`CASE_DROPS_THROUGH'
+ Define this if control falls through a `case' insn when the index
+ value is out of range. This means the specified default-label is
+ actually ignored by the `case' insn proper.
+
+`CASE_VALUES_THRESHOLD'
+ Define this to be the smallest number of different values for
+ which it is best to use a jump-table instead of a tree of
+ conditional branches. The default is four for machines with a
+ `casesi' instruction and five otherwise. This is best for most
+ machines.
+
+`WORD_REGISTER_OPERATIONS'
+ Define this macro if operations between registers with integral
+ mode smaller than a word are always performed on the entire
+ register. Most RISC machines have this property and most CISC
+ machines do not.
+
+`LOAD_EXTEND_OP (MODE)'
+ Define this macro to be a C expression indicating when insns that
+ read memory in MODE, an integral mode narrower than a word, set the
+ bits outside of MODE to be either the sign-extension or the
+ zero-extension of the data read. Return `SIGN_EXTEND' for values
+ of MODE for which the insn sign-extends, `ZERO_EXTEND' for which
+ it zero-extends, and `NIL' for other modes.
+
+ This macro is not called with MODE non-integral or with a width
+ greater than or equal to `BITS_PER_WORD', so you may return any
+ value in this case. Do not define this macro if it would always
+ return `NIL'. On machines where this macro is defined, you will
+ normally define it as the constant `SIGN_EXTEND' or `ZERO_EXTEND'.
+
+`SHORT_IMMEDIATES_SIGN_EXTEND'
+ Define this macro if loading short immediate values into registers
+ sign extends.
+
+`FIXUNS_TRUNC_LIKE_FIX_TRUNC'
+ Define this macro if the same instructions that convert a floating
+ point number to a signed fixed point number also convert validly
+ to an unsigned one.
+
+`MOVE_MAX'
+ The maximum number of bytes that a single instruction can move
+ quickly between memory and registers or between two memory
+ locations.
+
+`MAX_MOVE_MAX'
+ The maximum number of bytes that a single instruction can move
+ quickly between memory and registers or between two memory
+ locations. If this is undefined, the default is `MOVE_MAX'.
+ Otherwise, it is the constant value that is the largest value that
+ `MOVE_MAX' can have at run-time.
+
+`SHIFT_COUNT_TRUNCATED'
+ A C expression that is nonzero if on this machine the number of
+ bits actually used for the count of a shift operation is equal to
+ the number of bits needed to represent the size of the object
+ being shifted. When this macro is nonzero, the compiler will
+ assume that it is safe to omit a sign-extend, zero-extend, and
+ certain bitwise `and' instructions that truncates the count of a
+ shift operation. On machines that have instructions that act on
+ bit-fields at variable positions, which may include `bit test'
+ instructions, a nonzero `SHIFT_COUNT_TRUNCATED' also enables
+ deletion of truncations of the values that serve as arguments to
+ bit-field instructions.
+
+ If both types of instructions truncate the count (for shifts) and
+ position (for bit-field operations), or if no variable-position
+ bit-field instructions exist, you should define this macro.
+
+ However, on some machines, such as the 80386 and the 680x0,
+ truncation only applies to shift operations and not the (real or
+ pretended) bit-field operations. Define `SHIFT_COUNT_TRUNCATED'
+ to be zero on such machines. Instead, add patterns to the `md'
+ file that include the implied truncation of the shift instructions.
+
+ You need not define this macro if it would always have the value
+ of zero.
+
+`TRULY_NOOP_TRUNCATION (OUTPREC, INPREC)'
+ A C expression which is nonzero if on this machine it is safe to
+ "convert" an integer of INPREC bits to one of OUTPREC bits (where
+ OUTPREC is smaller than INPREC) by merely operating on it as if it
+ had only OUTPREC bits.
+
+ On many machines, this expression can be 1.
+
+ When `TRULY_NOOP_TRUNCATION' returns 1 for a pair of sizes for
+ modes for which `MODES_TIEABLE_P' is 0, suboptimal code can result.
+ If this is the case, making `TRULY_NOOP_TRUNCATION' return 0 in
+ such cases may improve things.
+
+`STORE_FLAG_VALUE'
+ A C expression describing the value returned by a comparison
+ operator with an integral mode and stored by a store-flag
+ instruction (`sCOND') when the condition is true. This
+ description must apply to _all_ the `sCOND' patterns and all the
+ comparison operators whose results have a `MODE_INT' mode.
+
+ A value of 1 or -1 means that the instruction implementing the
+ comparison operator returns exactly 1 or -1 when the comparison is
+ true and 0 when the comparison is false. Otherwise, the value
+ indicates which bits of the result are guaranteed to be 1 when the
+ comparison is true. This value is interpreted in the mode of the
+ comparison operation, which is given by the mode of the first
+ operand in the `sCOND' pattern. Either the low bit or the sign
+ bit of `STORE_FLAG_VALUE' be on. Presently, only those bits are
+ used by the compiler.
+
+ If `STORE_FLAG_VALUE' is neither 1 or -1, the compiler will
+ generate code that depends only on the specified bits. It can also
+ replace comparison operators with equivalent operations if they
+ cause the required bits to be set, even if the remaining bits are
+ undefined. For example, on a machine whose comparison operators
+ return an `SImode' value and where `STORE_FLAG_VALUE' is defined as
+ `0x80000000', saying that just the sign bit is relevant, the
+ expression
+
+ (ne:SI (and:SI X (const_int POWER-OF-2)) (const_int 0))
+
+ can be converted to
+
+ (ashift:SI X (const_int N))
+
+ where N is the appropriate shift count to move the bit being
+ tested into the sign bit.
+
+ There is no way to describe a machine that always sets the
+ low-order bit for a true value, but does not guarantee the value
+ of any other bits, but we do not know of any machine that has such
+ an instruction. If you are trying to port GCC to such a machine,
+ include an instruction to perform a logical-and of the result with
+ 1 in the pattern for the comparison operators and let us know at
+ <gcc@gcc.gnu.org>.
+
+ Often, a machine will have multiple instructions that obtain a
+ value from a comparison (or the condition codes). Here are rules
+ to guide the choice of value for `STORE_FLAG_VALUE', and hence the
+ instructions to be used:
+
+ * Use the shortest sequence that yields a valid definition for
+ `STORE_FLAG_VALUE'. It is more efficient for the compiler to
+ "normalize" the value (convert it to, e.g., 1 or 0) than for
+ the comparison operators to do so because there may be
+ opportunities to combine the normalization with other
+ operations.
+
+ * For equal-length sequences, use a value of 1 or -1, with -1
+ being slightly preferred on machines with expensive jumps and
+ 1 preferred on other machines.
+
+ * As a second choice, choose a value of `0x80000001' if
+ instructions exist that set both the sign and low-order bits
+ but do not define the others.
+
+ * Otherwise, use a value of `0x80000000'.
+
+ Many machines can produce both the value chosen for
+ `STORE_FLAG_VALUE' and its negation in the same number of
+ instructions. On those machines, you should also define a pattern
+ for those cases, e.g., one matching
+
+ (set A (neg:M (ne:M B C)))
+
+ Some machines can also perform `and' or `plus' operations on
+ condition code values with less instructions than the corresponding
+ `sCOND' insn followed by `and' or `plus'. On those machines,
+ define the appropriate patterns. Use the names `incscc' and
+ `decscc', respectively, for the patterns which perform `plus' or
+ `minus' operations on condition code values. See `rs6000.md' for
+ some examples. The GNU Superoptizer can be used to find such
+ instruction sequences on other machines.
+
+ You need not define `STORE_FLAG_VALUE' if the machine has no
+ store-flag instructions.
+
+`FLOAT_STORE_FLAG_VALUE (MODE)'
+ A C expression that gives a nonzero `REAL_VALUE_TYPE' value that is
+ returned when comparison operators with floating-point results are
+ true. Define this macro on machine that have comparison
+ operations that return floating-point values. If there are no
+ such operations, do not define this macro.
+
+`Pmode'
+ An alias for the machine mode for pointers. On most machines,
+ define this to be the integer mode corresponding to the width of a
+ hardware pointer; `SImode' on 32-bit machine or `DImode' on 64-bit
+ machines. On some machines you must define this to be one of the
+ partial integer modes, such as `PSImode'.
+
+ The width of `Pmode' must be at least as large as the value of
+ `POINTER_SIZE'. If it is not equal, you must define the macro
+ `POINTERS_EXTEND_UNSIGNED' to specify how pointers are extended to
+ `Pmode'.
+
+`FUNCTION_MODE'
+ An alias for the machine mode used for memory references to
+ functions being called, in `call' RTL expressions. On most
+ machines this should be `QImode'.
+
+`INTEGRATE_THRESHOLD (DECL)'
+ A C expression for the maximum number of instructions above which
+ the function DECL should not be inlined. DECL is a
+ `FUNCTION_DECL' node.
+
+ The default definition of this macro is 64 plus 8 times the number
+ of arguments that the function accepts. Some people think a larger
+ threshold should be used on RISC machines.
+
+`STDC_0_IN_SYSTEM_HEADERS'
+ In normal operation, the preprocessor expands `__STDC__' to the
+ constant 1, to signify that GCC conforms to ISO Standard C. On
+ some hosts, like Solaris, the system compiler uses a different
+ convention, where `__STDC__' is normally 0, but is 1 if the user
+ specifies strict conformance to the C Standard.
+
+ Defining `STDC_0_IN_SYSTEM_HEADERS' makes GNU CPP follows the host
+ convention when processing system header files, but when
+ processing user files `__STDC__' will always expand to 1.
+
+`SCCS_DIRECTIVE'
+ Define this if the preprocessor should ignore `#sccs' directives
+ and print no error message.
+
+`NO_IMPLICIT_EXTERN_C'
+ Define this macro if the system header files support C++ as well
+ as C. This macro inhibits the usual method of using system header
+ files in C++, which is to pretend that the file's contents are
+ enclosed in `extern "C" {...}'.
+
+`HANDLE_PRAGMA (GETC, UNGETC, NAME)'
+ This macro is no longer supported. You must use
+ `REGISTER_TARGET_PRAGMAS' instead.
+
+`REGISTER_TARGET_PRAGMAS (PFILE)'
+ Define this macro if you want to implement any target-specific
+ pragmas. If defined, it is a C expression which makes a series of
+ calls to `cpp_register_pragma' for each pragma, with PFILE passed
+ as the first argument to to these functions. The macro may also
+ do any setup required for the pragmas.
+
+ The primary reason to define this macro is to provide
+ compatibility with other compilers for the same target. In
+ general, we discourage definition of target-specific pragmas for
+ GCC.
+
+ If the pragma can be implemented by attributes then you should
+ consider defining the target hook `TARGET_INSERT_ATTRIBUTES' as
+ well.
+
+ Preprocessor macros that appear on pragma lines are not expanded.
+ All `#pragma' directives that do not match any registered pragma
+ are silently ignored, unless the user specifies
+ `-Wunknown-pragmas'.
+
+ -- Function: void cpp_register_pragma (cpp_reader *PFILE, const
+ char *SPACE, const char *NAME, void (*CALLBACK)
+ (cpp_reader *))
+ Each call to `cpp_register_pragma' establishes one pragma.
+ The CALLBACK routine will be called when the preprocessor
+ encounters a pragma of the form
+
+ #pragma [SPACE] NAME ...
+
+ SPACE is the case-sensitive namespace of the pragma, or
+ `NULL' to put the pragma in the global namespace. The
+ callback routine receives PFILE as its first argument, which
+ can be passed on to cpplib's functions if necessary. You can
+ lex tokens after the NAME by calling `c_lex'. Tokens that
+ are not read by the callback will be silently ignored. The
+ end of the line is indicated by a token of type `CPP_EOF'.
+
+ For an example use of this routine, see `c4x.h' and the
+ callback routines defined in `c4x-c.c'.
+
+ Note that the use of `c_lex' is specific to the C and C++
+ compilers. It will not work in the Java or Fortran
+ compilers, or any other language compilers for that matter.
+ Thus if `c_lex' is going to be called from target-specific
+ code, it must only be done so when building the C and C++
+ compilers. This can be done by defining the variables
+ `c_target_objs' and `cxx_target_objs' in the target entry in
+ the `config.gcc' file. These variables should name the
+ target-specific, language-specific object file which contains
+ the code that uses `c_lex'. Note it will also be necessary
+ to add a rule to the makefile fragment pointed to by
+ `tmake_file' that shows how to build this object file.
+
+`HANDLE_SYSV_PRAGMA'
+ Define this macro (to a value of 1) if you want the System V style
+ pragmas `#pragma pack(<n>)' and `#pragma weak <name> [=<value>]'
+ to be supported by gcc.
+
+ The pack pragma specifies the maximum alignment (in bytes) of
+ fields within a structure, in much the same way as the
+ `__aligned__' and `__packed__' `__attribute__'s do. A pack value
+ of zero resets the behavior to the default.
+
+ The weak pragma only works if `SUPPORTS_WEAK' and
+ `ASM_WEAKEN_LABEL' are defined. If enabled it allows the creation
+ of specifically named weak labels, optionally with a value.
+
+`HANDLE_PRAGMA_PACK_PUSH_POP'
+ Define this macro (to a value of 1) if you want to support the
+ Win32 style pragmas `#pragma pack(push,N)' and `#pragma
+ pack(pop)'. The `pack(push,N)' pragma specifies the maximum
+ alignment (in bytes) of fields within a structure, in much the
+ same way as the `__aligned__' and `__packed__' `__attribute__'s
+ do. A pack value of zero resets the behavior to the default.
+ Successive invocations of this pragma cause the previous values to
+ be stacked, so that invocations of `#pragma pack(pop)' will return
+ to the previous value.
+
+`DOLLARS_IN_IDENTIFIERS'
+ Define this macro to control use of the character `$' in identifier
+ names. 0 means `$' is not allowed by default; 1 means it is
+ allowed. 1 is the default; there is no need to define this macro
+ in that case. This macro controls the compiler proper; it does
+ not affect the preprocessor.
+
+`NO_DOLLAR_IN_LABEL'
+ Define this macro if the assembler does not accept the character
+ `$' in label names. By default constructors and destructors in
+ G++ have `$' in the identifiers. If this macro is defined, `.' is
+ used instead.
+
+`NO_DOT_IN_LABEL'
+ Define this macro if the assembler does not accept the character
+ `.' in label names. By default constructors and destructors in G++
+ have names that use `.'. If this macro is defined, these names
+ are rewritten to avoid `.'.
+
+`DEFAULT_MAIN_RETURN'
+ Define this macro if the target system expects every program's
+ `main' function to return a standard "success" value by default
+ (if no other value is explicitly returned).
+
+ The definition should be a C statement (sans semicolon) to
+ generate the appropriate rtl instructions. It is used only when
+ compiling the end of `main'.
+
+`NEED_ATEXIT'
+ Define this if the target system lacks the function `atexit' from
+ the ISO C standard. If this macro is defined, a default definition
+ will be provided to support C++. If `ON_EXIT' is not defined, a
+ default `exit' function will also be provided.
+
+`ON_EXIT'
+ Define this macro if the target has another way to implement atexit
+ functionality without replacing `exit'. For instance, SunOS 4 has
+ a similar `on_exit' library function.
+
+ The definition should be a functional macro which can be used just
+ like the `atexit' function.
+
+`EXIT_BODY'
+ Define this if your `exit' function needs to do something besides
+ calling an external function `_cleanup' before terminating with
+ `_exit'. The `EXIT_BODY' macro is only needed if `NEED_ATEXIT' is
+ defined and `ON_EXIT' is not defined.
+
+`INSN_SETS_ARE_DELAYED (INSN)'
+ Define this macro as a C expression that is nonzero if it is safe
+ for the delay slot scheduler to place instructions in the delay
+ slot of INSN, even if they appear to use a resource set or
+ clobbered in INSN. INSN is always a `jump_insn' or an `insn'; GCC
+ knows that every `call_insn' has this behavior. On machines where
+ some `insn' or `jump_insn' is really a function call and hence has
+ this behavior, you should define this macro.
+
+ You need not define this macro if it would always return zero.
+
+`INSN_REFERENCES_ARE_DELAYED (INSN)'
+ Define this macro as a C expression that is nonzero if it is safe
+ for the delay slot scheduler to place instructions in the delay
+ slot of INSN, even if they appear to set or clobber a resource
+ referenced in INSN. INSN is always a `jump_insn' or an `insn'.
+ On machines where some `insn' or `jump_insn' is really a function
+ call and its operands are registers whose use is actually in the
+ subroutine it calls, you should define this macro. Doing so
+ allows the delay slot scheduler to move instructions which copy
+ arguments into the argument registers into the delay slot of INSN.
+
+ You need not define this macro if it would always return zero.
+
+`MACHINE_DEPENDENT_REORG (INSN)'
+ In rare cases, correct code generation requires extra machine
+ dependent processing between the second jump optimization pass and
+ delayed branch scheduling. On those machines, define this macro
+ as a C statement to act on the code starting at INSN.
+
+`MULTIPLE_SYMBOL_SPACES'
+ Define this macro if in some cases global symbols from one
+ translation unit may not be bound to undefined symbols in another
+ translation unit without user intervention. For instance, under
+ Microsoft Windows symbols must be explicitly imported from shared
+ libraries (DLLs).
+
+`MD_ASM_CLOBBERS (CLOBBERS)'
+ A C statement that adds to CLOBBERS `STRING_CST' trees for any
+ hard regs the port wishes to automatically clobber for all asms.
+
+`MAX_INTEGER_COMPUTATION_MODE'
+ Define this to the largest integer machine mode which can be used
+ for operations other than load, store and copy operations.
+
+ You need only define this macro if the target holds values larger
+ than `word_mode' in general purpose registers. Most targets
+ should not define this macro.
+
+`MATH_LIBRARY'
+ Define this macro as a C string constant for the linker argument
+ to link in the system math library, or `""' if the target does not
+ have a separate math library.
+
+ You need only define this macro if the default of `"-lm"' is wrong.
+
+`LIBRARY_PATH_ENV'
+ Define this macro as a C string constant for the environment
+ variable that specifies where the linker should look for libraries.
+
+ You need only define this macro if the default of `"LIBRARY_PATH"'
+ is wrong.
+
+`TARGET_HAS_F_SETLKW'
+ Define this macro if the target supports file locking with fcntl /
+ F_SETLKW. Note that this functionality is part of POSIX.
+ Defining `TARGET_HAS_F_SETLKW' will enable the test coverage code
+ to use file locking when exiting a program, which avoids race
+ conditions if the program has forked.
+
+`MAX_CONDITIONAL_EXECUTE'
+ A C expression for the maximum number of instructions to execute
+ via conditional execution instructions instead of a branch. A
+ value of `BRANCH_COST'+1 is the default if the machine does not
+ use cc0, and 1 if it does use cc0.
+
+`IFCVT_MODIFY_TESTS'
+ A C expression to modify the tests in `TRUE_EXPR', and
+ `FALSE_EXPR' for use in converting insns in `TEST_BB', `THEN_BB',
+ `ELSE_BB', and `JOIN_BB' basic blocks to conditional execution.
+ Set either `TRUE_EXPR' or `FALSE_EXPR' to a null pointer if the
+ tests cannot be converted.
+
+`IFCVT_MODIFY_INSN'
+ A C expression to modify the `PATTERN' of an `INSN' that is to be
+ converted to conditional execution format.
+
+`IFCVT_MODIFY_FINAL'
+ A C expression to perform any final machine dependent
+ modifications in converting code to conditional execution in the
+ basic blocks `TEST_BB', `THEN_BB', `ELSE_BB', and `JOIN_BB'.
+
+`IFCVT_MODIFY_CANCEL'
+ A C expression to cancel any machine dependent modifications in
+ converting code to conditional execution in the basic blocks
+ `TEST_BB', `THEN_BB', `ELSE_BB', and `JOIN_BB'.
+
+ -- Target Hook: void TARGET_INIT_BUILTINS ()
+ Define this hook if you have any machine-specific built-in
+ functions that need to be defined. It should be a function that
+ performs the necessary setup.
+
+ Machine specific built-in functions can be useful to expand
+ special machine instructions that would otherwise not normally be
+ generated because they have no equivalent in the source language
+ (for example, SIMD vector instructions or prefetch instructions).
+
+ To create a built-in function, call the function `builtin_function'
+ which is defined by the language front end. You can use any type
+ nodes set up by `build_common_tree_nodes' and
+ `build_common_tree_nodes_2'; only language front ends that use
+ those two functions will call `TARGET_INIT_BUILTINS'.
+
+ -- Target Hook: rtx TARGET_EXPAND_BUILTIN (tree EXP, rtx TARGET, rtx
+ SUBTARGET, enum machine_mode MODE, int IGNORE)
+ Expand a call to a machine specific built-in function that was set
+ up by `TARGET_INIT_BUILTINS'. EXP is the expression for the
+ function call; the result should go to TARGET if that is
+ convenient, and have mode MODE if that is convenient. SUBTARGET
+ may be used as the target for computing one of EXP's operands.
+ IGNORE is nonzero if the value is to be ignored. This function
+ should return the result of the call to the built-in function.
+
+`MD_CAN_REDIRECT_BRANCH(BRANCH1, BRANCH2)'
+ Take a branch insn in BRANCH1 and another in BRANCH2. Return true
+ if redirecting BRANCH1 to the destination of BRANCH2 is possible.
+
+ On some targets, branches may have a limited range. Optimizing the
+ filling of delay slots can result in branches being redirected,
+ and this may in turn cause a branch offset to overflow.
+
+`ALLOCATE_INITIAL_VALUE(HARD_REG)'
+ When the initial value of a hard register has been copied in a
+ pseudo register, it is often not necessary to actually allocate
+ another register to this pseudo register, because the original
+ hard register or a stack slot it has been saved into can be used.
+ `ALLOCATE_INITIAL_VALUE', if defined, is called at the start of
+ register allocation once for each hard register that had its
+ initial value copied by using `get_func_hard_reg_initial_val' or
+ `get_hard_reg_initial_val'. Possible values are `NULL_RTX', if
+ you don't want to do any special allocation, a `REG' rtx--that
+ would typically be the hard register itself, if it is known not to
+ be clobbered--or a `MEM'. If you are returning a `MEM', this is
+ only a hint for the allocator; it might decide to use another
+ register anyways. You may use `current_function_leaf_function' in
+ the definition of the macro, functions that use `REG_N_SETS', to
+ determine if the hard register in question will not be clobbered.
+
+`TARGET_OBJECT_SUFFIX'
+ Define this macro to be a C string representing the suffix for
+ object files on your target machine. If you do not define this
+ macro, GCC will use `.o' as the suffix for object files.
+
+`TARGET_EXECUTABLE_SUFFIX'
+ Define this macro to be a C string representing the suffix to be
+ automatically added to executable files on your target machine.
+ If you do not define this macro, GCC will use the null string as
+ the suffix for executable files.
+
+`COLLECT_EXPORT_LIST'
+ If defined, `collect2' will scan the individual object files
+ specified on its command line and create an export list for the
+ linker. Define this macro for systems like AIX, where the linker
+ discards object files that are not referenced from `main' and uses
+ export lists.
+
+
+ -- Target Hook: bool TARGET_CANNOT_MODIFY_JUMPS_P (void)
+ This target hook returns `true' past the point in which new jump
+ instructions could be created. On machines that require a
+ register for every jump such as the SHmedia ISA of SH5, this point
+ would typically be reload, so this target hook should be defined
+ to a function such as:
+
+ static bool
+ cannot_modify_jumps_past_reload_p ()
+ {
+ return (reload_completed || reload_in_progress);
+ }
-`DECL_THUNK_P'
- This predicate holds if the function is a thunk.
-
- These functions represent stub code that adjusts the `this' pointer
- and then jumps to another function. When the jumped-to function
- returns, control is transferred directly to the caller, without
- returning to the thunk. The first parameter to the thunk is
- always the `this' pointer; the thunk should add `THUNK_DELTA' to
- this value. (The `THUNK_DELTA' is an `int', not an `INTEGER_CST'.)
-
- Then, if `THUNK_VCALL_OFFSET' (an `INTEGER_CST') is nonzero the
- adjusted `this' pointer must be adjusted again. The complete
- calculation is given by the following pseudo-code:
-
- this += THUNK_DELTA
- if (THUNK_VCALL_OFFSET)
- this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET]
-
- Finally, the thunk should jump to the location given by
- `DECL_INITIAL'; this will always be an expression for the address
- of a function.
-
-`DECL_NON_THUNK_FUNCTION_P'
- This predicate holds if the function is _not_ a thunk function.
-
-`GLOBAL_INIT_PRIORITY'
- If either `DECL_GLOBAL_CTOR_P' or `DECL_GLOBAL_DTOR_P' holds, then
- this gives the initialization priority for the function. The
- linker will arrange that all functions for which
- `DECL_GLOBAL_CTOR_P' holds are run in increasing order of priority
- before `main' is called. When the program exits, all functions for
- which `DECL_GLOBAL_DTOR_P' holds are run in the reverse order.
-
-`DECL_ARTIFICIAL'
- This macro holds if the function was implicitly generated by the
- compiler, rather than explicitly declared. In addition to
- implicitly generated class member functions, this macro holds for
- the special functions created to implement static initialization
- and destruction, to compute run-time type information, and so
- forth.
-
-`DECL_ARGUMENTS'
- This macro returns the `PARM_DECL' for the first argument to the
- function. Subsequent `PARM_DECL' nodes can be obtained by
- following the `TREE_CHAIN' links.
-
-`DECL_RESULT'
- This macro returns the `RESULT_DECL' for the function.
-
-`TREE_TYPE'
- This macro returns the `FUNCTION_TYPE' or `METHOD_TYPE' for the
- function.
+\1f
+File: gccint.info, Node: Host Config, Next: Fragments, Prev: Target Macros, Up: Top
+
+11 Host Configuration Headers
+*****************************
+
+Host configuration headers contain macro definitions that describe the
+machine and system on which the compiler is running. They are usually
+unnecessary. Most of the things GCC needs to know about the host
+system can be deduced by the `configure' script.
+
+ If your host does need a special configuration header, it should be
+named `xm-MACHINE.h', where MACHINE is a short mnemonic for the
+machine. Here are some macros which this header can define.
+
+`VMS'
+ Define this macro if the host system is VMS.
+
+`FATAL_EXIT_CODE'
+ A C expression for the status code to be returned when the compiler
+ exits after serious errors. The default is the system-provided
+ macro `EXIT_FAILURE', or `1' if the system doesn't define that
+ macro. Define this macro only if these defaults are incorrect.
+
+`SUCCESS_EXIT_CODE'
+ A C expression for the status code to be returned when the compiler
+ exits without serious errors. (Warnings are not serious errors.)
+ The default is the system-provided macro `EXIT_SUCCESS', or `0' if
+ the system doesn't define that macro. Define this macro only if
+ these defaults are incorrect.
+
+`USE_C_ALLOCA'
+ Define this macro if GCC should use the C implementation of
+ `alloca' provided by `libiberty.a'. This only affects how some
+ parts of the compiler itself allocate memory. It does not change
+ code generation.
+
+ When GCC is built with a compiler other than itself, the C `alloca'
+ is always used. This is because most other implementations have
+ serious bugs. You should define this macro only on a system where
+ no stack-based `alloca' can possibly work. For instance, if a
+ system has a small limit on the size of the stack, GCC's builtin
+ `alloca' will not work reliably.
+
+`HAVE_DOS_BASED_FILE_SYSTEM'
+ Define this macro if the host file system obeys the semantics
+ defined by MS-DOS instead of Unix. DOS file systems are case
+ insensitive, file specifications may begin with a drive letter,
+ and both forward slash and backslash (`/' and `\') are directory
+ separators. If you define this macro, you probably need to define
+ the next three macros too.
+
+`PATH_SEPARATOR'
+ If defined, this macro should expand to a character constant
+ specifying the separator for elements of search paths. The
+ default value is a colon (`:'). DOS-based systems usually use
+ semicolon (`;').
+
+`DIR_SEPARATOR'
+`DIR_SEPARATOR_2'
+ If defined, these macros expand to character constants specifying
+ separators for directory names within a file specification. They
+ are used somewhat inconsistently throughout the compiler. If your
+ system behaves like Unix (only forward slash separates pathnames),
+ define neither of them. If your system behaves like DOS (both
+ forward and backward slash can be used), define `DIR_SEPARATOR' to
+ `/' and `DIR_SEPARATOR_2' to `\'.
+
+`HOST_OBJECT_SUFFIX'
+ Define this macro to be a C string representing the suffix for
+ object files on your host machine. If you do not define this
+ macro, GCC will use `.o' as the suffix for object files.
+
+`HOST_EXECUTABLE_SUFFIX'
+ Define this macro to be a C string representing the suffix for
+ executable files on your host machine. If you do not define this
+ macro, GCC will use the null string as the suffix for executable
+ files.
+
+`HOST_BIT_BUCKET'
+ A pathname defined by the host operating system, which can be
+ opened as a file and written to, but all the information written
+ is discarded. This is commonly known as a "bit bucket" or "null
+ device". If you do not define this macro, GCC will use
+ `/dev/null' as the bit bucket. If the host does not support a bit
+ bucket, define this macro to an invalid filename.
+
+`COLLECT2_HOST_INITIALIZATION'
+ If defined, a C statement (sans semicolon) that performs
+ host-dependent initialization when `collect2' is being initialized.
+
+`GCC_DRIVER_HOST_INITIALIZATION'
+ If defined, a C statement (sans semicolon) that performs
+ host-dependent initialization when a compilation driver is being
+ initialized.
+
+`UPDATE_PATH_HOST_CANONICALIZE (PATH)'
+ If defined, a C statement (sans semicolon) that performs
+ host-dependent canonicalization when a path used in a compilation
+ driver or preprocessor is canonicalized. PATH is a malloc-ed path
+ to be canonicalized. If the C statement does canonicalize PATH
+ into a different buffer, the old path should be freed and the new
+ buffer should have been allocated with malloc.
+
+`DUMPFILE_FORMAT'
+ Define this macro to be a C string representing the format to use
+ for constructing the index part of debugging dump file names. The
+ resultant string must fit in fifteen bytes. The full filename
+ will be the concatenation of: the prefix of the assembler file
+ name, the string resulting from applying this format to an index
+ number, and a string unique to each dump file kind, e.g. `rtl'.
+
+ If you do not define this macro, GCC will use `.%02d.'. You should
+ define this macro if using the default will create an invalid file
+ name.
+
+`SMALL_ARG_MAX'
+ Define this macro if the host system has a small limit on the total
+ size of an argument vector. This causes the driver to take more
+ care not to pass unnecessary arguments to subprocesses.
+
+ In addition, if `configure' generates an incorrect definition of any
+of the macros in `auto-host.h', you can override that definition in a
+host configuration header. If you need to do this, first see if it is
+possible to fix `configure'.
+
+ If you need to define only a few of these macros, and they have
+simple definitions, consider using the `xm_defines' variable in your
+`config.gcc' entry instead of creating a host configuration header.
+*Note System Config::.
+
+\1f
+File: gccint.info, Node: Fragments, Next: Collect2, Prev: Host Config, Up: Top
+
+12 Makefile Fragments
+*********************
+
+When you configure GCC using the `configure' script, it will construct
+the file `Makefile' from the template file `Makefile.in'. When it does
+this, it can incorporate makefile fragments from the `config'
+directory. These are used to set Makefile parameters that are not
+amenable to being calculated by autoconf. The list of fragments to
+incorporate is set by `config.gcc'; *Note System Config::.
+
+ Fragments are named either `t-TARGET' or `x-HOST', depending on
+whether they are relevant to configuring GCC to produce code for a
+particular target, or to configuring GCC to run on a particular host.
+Here TARGET and HOST are mnemonics which usually have some relationship
+to the canonical system name, but no formal connection.
+
+ If these files do not exist, it means nothing needs to be added for a
+given target or host. Most targets need a few `t-TARGET' fragments,
+but needing `x-HOST' fragments is rare.
+
+* Menu:
+
+* Target Fragment:: Writing `t-TARGET' files.
+* Host Fragment:: Writing `x-HOST' files.
+
+\1f
+File: gccint.info, Node: Target Fragment, Next: Host Fragment, Up: Fragments
+
+12.1 Target Makefile Fragments
+==============================
+
+Target makefile fragments can set these Makefile variables.
+
+`LIBGCC2_CFLAGS'
+ Compiler flags to use when compiling `libgcc2.c'.
+
+`LIB2FUNCS_EXTRA'
+ A list of source file names to be compiled or assembled and
+ inserted into `libgcc.a'.
+
+`Floating Point Emulation'
+ To have GCC include software floating point libraries in `libgcc.a'
+ define `FPBIT' and `DPBIT' along with a few rules as follows:
+ # We want fine grained libraries, so use the new code
+ # to build the floating point emulation libraries.
+ FPBIT = fp-bit.c
+ DPBIT = dp-bit.c
+
+
+ fp-bit.c: $(srcdir)/config/fp-bit.c
+ echo '#define FLOAT' > fp-bit.c
+ cat $(srcdir)/config/fp-bit.c >> fp-bit.c
+
+ dp-bit.c: $(srcdir)/config/fp-bit.c
+ cat $(srcdir)/config/fp-bit.c > dp-bit.c
+
+ You may need to provide additional #defines at the beginning of
+ `fp-bit.c' and `dp-bit.c' to control target endianness and other
+ options.
+
+`CRTSTUFF_T_CFLAGS'
+ Special flags used when compiling `crtstuff.c'. *Note
+ Initialization::.
+
+`CRTSTUFF_T_CFLAGS_S'
+ Special flags used when compiling `crtstuff.c' for shared linking.
+ Used if you use `crtbeginS.o' and `crtendS.o' in `EXTRA-PARTS'.
+ *Note Initialization::.
+
+`MULTILIB_OPTIONS'
+ For some targets, invoking GCC in different ways produces objects
+ that can not be linked together. For example, for some targets GCC
+ produces both big and little endian code. For these targets, you
+ must arrange for multiple versions of `libgcc.a' to be compiled,
+ one for each set of incompatible options. When GCC invokes the
+ linker, it arranges to link in the right version of `libgcc.a',
+ based on the command line options used.
+
+ The `MULTILIB_OPTIONS' macro lists the set of options for which
+ special versions of `libgcc.a' must be built. Write options that
+ are mutually incompatible side by side, separated by a slash.
+ Write options that may be used together separated by a space. The
+ build procedure will build all combinations of compatible options.
+
+ For example, if you set `MULTILIB_OPTIONS' to `m68000/m68020
+ msoft-float', `Makefile' will build special versions of `libgcc.a'
+ using the following sets of options: `-m68000', `-m68020',
+ `-msoft-float', `-m68000 -msoft-float', and `-m68020 -msoft-float'.
+
+`MULTILIB_DIRNAMES'
+ If `MULTILIB_OPTIONS' is used, this variable specifies the
+ directory names that should be used to hold the various libraries.
+ Write one element in `MULTILIB_DIRNAMES' for each element in
+ `MULTILIB_OPTIONS'. If `MULTILIB_DIRNAMES' is not used, the
+ default value will be `MULTILIB_OPTIONS', with all slashes treated
+ as spaces.
+
+ For example, if `MULTILIB_OPTIONS' is set to `m68000/m68020
+ msoft-float', then the default value of `MULTILIB_DIRNAMES' is
+ `m68000 m68020 msoft-float'. You may specify a different value if
+ you desire a different set of directory names.
+
+`MULTILIB_MATCHES'
+ Sometimes the same option may be written in two different ways.
+ If an option is listed in `MULTILIB_OPTIONS', GCC needs to know
+ about any synonyms. In that case, set `MULTILIB_MATCHES' to a
+ list of items of the form `option=option' to describe all relevant
+ synonyms. For example, `m68000=mc68000 m68020=mc68020'.
+
+`MULTILIB_EXCEPTIONS'
+ Sometimes when there are multiple sets of `MULTILIB_OPTIONS' being
+ specified, there are combinations that should not be built. In
+ that case, set `MULTILIB_EXCEPTIONS' to be all of the switch
+ exceptions in shell case syntax that should not be built.
+
+ For example, in the PowerPC embedded ABI support, it is not
+ desirable to build libraries compiled with the `-mcall-aix' option
+ and either of the `-fleading-underscore' or `-mlittle' options at
+ the same time. Therefore `MULTILIB_EXCEPTIONS' is set to
+ *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
+
+`MULTILIB_EXTRA_OPTS'
+ Sometimes it is desirable that when building multiple versions of
+ `libgcc.a' certain options should always be passed on to the
+ compiler. In that case, set `MULTILIB_EXTRA_OPTS' to be the list
+ of options to be used for all builds.
+
+\1f
+File: gccint.info, Node: Host Fragment, Prev: Target Fragment, Up: Fragments
+
+12.2 Host Makefile Fragments
+============================
+
+The use of `x-HOST' fragments is discouraged. You should do so only if
+there is no other mechanism to get the behavior desired. Host
+fragments should never forcibly override variables set by the configure
+script, as they may have been adjusted by the user.
+
+ Variables provided for host fragments to set include:
+
+`X_CFLAGS'
+`X_CPPFLAGS'
+ These are extra flags to pass to the C compiler and preprocessor,
+ respectively. They are used both when building GCC, and when
+ compiling things with the just-built GCC.
+
+`XCFLAGS'
+ These are extra flags to use when building the compiler. They are
+ not used when compiling `libgcc.a'. However, they _are_ used when
+ recompiling the compiler with itself in later stages of a
+ bootstrap.
-`TYPE_RAISES_EXCEPTIONS'
- This macro returns the list of exceptions that a (member-)function
- can raise. The returned list, if non `NULL', is comprised of nodes
- whose `TREE_VALUE' represents a type.
+`BOOT_LDFLAGS'
+ Flags to be passed to the linker when recompiling the compiler with
+ itself in later stages of a bootstrap. You might need to use this
+ if, for instance, one of the front ends needs more text space than
+ the linker provides by default.
-`TYPE_NOTHROW_P'
- This predicate holds when the exception-specification of its
- arguments if of the form ``()''.
+`EXTRA_PROGRAMS'
+ A list of additional programs required to use the compiler on this
+ host, which should be compiled with GCC and installed alongside
+ the front ends. If you set this variable, you must also provide
+ rules to build the extra programs.
-`DECL_ARRAY_DELETE_OPERATOR_P'
- This predicate holds if the function an overloaded `operator
- delete[]'.
+\1f
+File: gccint.info, Node: Collect2, Next: Header Dirs, Prev: Fragments, Up: Top
+
+13 `collect2'
+*************
+
+GNU CC uses a utility called `collect2' on nearly all systems to arrange
+to call various initialization functions at start time.
+
+ The program `collect2' works by linking the program once and looking
+through the linker output file for symbols with particular names
+indicating they are constructor functions. If it finds any, it creates
+a new temporary `.c' file containing a table of them, compiles it, and
+links the program a second time including that file.
+
+ The actual calls to the constructors are carried out by a subroutine
+called `__main', which is called (automatically) at the beginning of
+the body of `main' (provided `main' was compiled with GNU CC). Calling
+`__main' is necessary, even when compiling C code, to allow linking C
+and C++ object code together. (If you use `-nostdlib', you get an
+unresolved reference to `__main', since it's defined in the standard
+GCC library. Include `-lgcc' at the end of your compiler command line
+to resolve this reference.)
+
+ The program `collect2' is installed as `ld' in the directory where
+the passes of the compiler are installed. When `collect2' needs to
+find the _real_ `ld', it tries the following file names:
+
+ * `real-ld' in the directories listed in the compiler's search
+ directories.
+
+ * `real-ld' in the directories listed in the environment variable
+ `PATH'.
+
+ * The file specified in the `REAL_LD_FILE_NAME' configuration macro,
+ if specified.
+
+ * `ld' in the compiler's search directories, except that `collect2'
+ will not execute itself recursively.
+
+ * `ld' in `PATH'.
+
+ "The compiler's search directories" means all the directories where
+`gcc' searches for passes of the compiler. This includes directories
+that you specify with `-B'.
+
+ Cross-compilers search a little differently:
+
+ * `real-ld' in the compiler's search directories.
+
+ * `TARGET-real-ld' in `PATH'.
+
+ * The file specified in the `REAL_LD_FILE_NAME' configuration macro,
+ if specified.
+
+ * `ld' in the compiler's search directories.
+
+ * `TARGET-ld' in `PATH'.
+
+ `collect2' explicitly avoids running `ld' using the file name under
+which `collect2' itself was invoked. In fact, it remembers up a list
+of such names--in case one copy of `collect2' finds another copy (or
+version) of `collect2' installed as `ld' in a second place in the
+search path.
+
+ `collect2' searches for the utilities `nm' and `strip' using the
+same algorithm as above for `ld'.
+
+\1f
+File: gccint.info, Node: Header Dirs, Next: Funding, Prev: Collect2, Up: Top
+
+14 Standard Header File Directories
+***********************************
+
+`GCC_INCLUDE_DIR' means the same thing for native and cross. It is
+where GNU CC stores its private include files, and also where GNU CC
+stores the fixed include files. A cross compiled GNU CC runs
+`fixincludes' on the header files in `$(tooldir)/include'. (If the
+cross compilation header files need to be fixed, they must be installed
+before GNU CC is built. If the cross compilation header files are
+already suitable for ISO C and GNU CC, nothing special need be done).
+
+ `GPLUSPLUS_INCLUDE_DIR' means the same thing for native and cross.
+It is where `g++' looks first for header files. The C++ library
+installs only target independent header files in that directory.
+
+ `LOCAL_INCLUDE_DIR' is used only by native compilers. GNU CC
+doesn't install anything there. It is normally `/usr/local/include'.
+This is where local additions to a packaged system should place header
+files.
+
+ `CROSS_INCLUDE_DIR' is used only by cross compilers. GNU CC doesn't
+install anything there.
+
+ `TOOL_INCLUDE_DIR' is used for both native and cross compilers. It
+is the place for other packages to install header files that GNU CC will
+use. For a cross-compiler, this is the equivalent of `/usr/include'.
+When you build a cross-compiler, `fixincludes' processes any header
+files in this directory.
+
+\1f
+File: gccint.info, Node: Funding, Next: GNU Project, Prev: Header Dirs, Up: Top
+
+Funding Free Software
+*********************
+
+If you want to have more free software a few years from now, it makes
+sense for you to help encourage people to contribute funds for its
+development. The most effective approach known is to encourage
+commercial redistributors to donate.
+
+ Users of free software systems can boost the pace of development by
+encouraging for-a-fee distributors to donate part of their selling price
+to free software developers--the Free Software Foundation, and others.
+
+ The way to convince distributors to do this is to demand it and
+expect it from them. So when you compare distributors, judge them
+partly by how much they give to free software development. Show
+distributors they must compete to be the one who gives the most.
+
+ To make this approach work, you must insist on numbers that you can
+compare, such as, "We will donate ten dollars to the Frobnitz project
+for each disk sold." Don't be satisfied with a vague promise, such as
+"A portion of the profits are donated," since it doesn't give a basis
+for comparison.
+
+ Even a precise fraction "of the profits from this disk" is not very
+meaningful, since creative accounting and unrelated business decisions
+can greatly alter what fraction of the sales price counts as profit.
+If the price you pay is $50, ten percent of the profit is probably less
+than a dollar; it might be a few cents, or nothing at all.
+
+ Some redistributors do development work themselves. This is useful
+too; but to keep everyone honest, you need to inquire how much they do,
+and what kind. Some kinds of development make much more long-term
+difference than others. For example, maintaining a separate version of
+a program contributes very little; maintaining the standard version of a
+program for the whole community contributes much. Easy new ports
+contribute little, since someone else would surely do them; difficult
+ports such as adding a new CPU to the GNU Compiler Collection
+contribute more; major new features or packages contribute the most.
+
+ By establishing the idea that supporting further development is "the
+proper thing to do" when distributing free software for a fee, we can
+assure a steady flow of resources into making more free software.
+
+ Copyright (C) 1994 Free Software Foundation, Inc.
+ Verbatim copying and redistribution of this section is permitted
+ without royalty; alteration is not permitted.
+
+\1f
+File: gccint.info, Node: GNU Project, Next: Copying, Prev: Funding, Up: Top
+
+The GNU Project and GNU/Linux
+*****************************
+
+The GNU Project was launched in 1984 to develop a complete Unix-like
+operating system which is free software: the GNU system. (GNU is a
+recursive acronym for "GNU's Not Unix"; it is pronounced "guh-NEW".)
+Variants of the GNU operating system, which use the kernel Linux, are
+now widely used; though these systems are often referred to as "Linux",
+they are more accurately called GNU/Linux systems.
+
+ For more information, see:
+ `http://www.gnu.org/'
+ `http://www.gnu.org/gnu/linux-and-gnu.html'
+
+\1f
+File: gccint.info, Node: Copying, Next: GNU Free Documentation License, Prev: GNU Project, Up: Top
+
+GNU GENERAL PUBLIC LICENSE
+**************************
+
+ Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+Preamble
+========
+
+The licenses for most software are designed to take away your freedom
+to share and change it. By contrast, the GNU General Public License is
+intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it in
+new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+ 0. This License applies to any program or other work which contains a
+ notice placed by the copyright holder saying it may be distributed
+ under the terms of this General Public License. The "Program",
+ below, refers to any such program or work, and a "work based on
+ the Program" means either the Program or any derivative work under
+ copyright law: that is to say, a work containing the Program or a
+ portion of it, either verbatim or with modifications and/or
+ translated into another language. (Hereinafter, translation is
+ included without limitation in the term "modification".) Each
+ licensee is addressed as "you".
+
+ Activities other than copying, distribution and modification are
+ not covered by this License; they are outside its scope. The act
+ of running the Program is not restricted, and the output from the
+ Program is covered only if its contents constitute a work based on
+ the Program (independent of having been made by running the
+ Program). Whether that is true depends on what the Program does.
+
+ 1. You may copy and distribute verbatim copies of the Program's
+ source code as you receive it, in any medium, provided that you
+ conspicuously and appropriately publish on each copy an appropriate
+ copyright notice and disclaimer of warranty; keep intact all the
+ notices that refer to this License and to the absence of any
+ warranty; and give any other recipients of the Program a copy of
+ this License along with the Program.
+
+ You may charge a fee for the physical act of transferring a copy,
+ and you may at your option offer warranty protection in exchange
+ for a fee.
+
+ 2. You may modify your copy or copies of the Program or any portion
+ of it, thus forming a work based on the Program, and copy and
+ distribute such modifications or work under the terms of Section 1
+ above, provided that you also meet all of these conditions:
+
+ a. You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ b. You must cause any work that you distribute or publish, that
+ in whole or in part contains or is derived from the Program
+ or any part thereof, to be licensed as a whole at no charge
+ to all third parties under the terms of this License.
+
+ c. If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the most ordinary way, to print or display
+ an announcement including an appropriate copyright notice and
+ a notice that there is no warranty (or else, saying that you
+ provide a warranty) and that users may redistribute the
+ program under these conditions, and telling the user how to
+ view a copy of this License. (Exception: if the Program
+ itself is interactive but does not normally print such an
+ announcement, your work based on the Program is not required
+ to print an announcement.)
+
+ These requirements apply to the modified work as a whole. If
+ identifiable sections of that work are not derived from the
+ Program, and can be reasonably considered independent and separate
+ works in themselves, then this License, and its terms, do not
+ apply to those sections when you distribute them as separate
+ works. But when you distribute the same sections as part of a
+ whole which is a work based on the Program, the distribution of
+ the whole must be on the terms of this License, whose permissions
+ for other licensees extend to the entire whole, and thus to each
+ and every part regardless of who wrote it.
+
+ Thus, it is not the intent of this section to claim rights or
+ contest your rights to work written entirely by you; rather, the
+ intent is to exercise the right to control the distribution of
+ derivative or collective works based on the Program.
+
+ In addition, mere aggregation of another work not based on the
+ Program with the Program (or with a work based on the Program) on
+ a volume of a storage or distribution medium does not bring the
+ other work under the scope of this License.
+
+ 3. You may copy and distribute the Program (or a work based on it,
+ under Section 2) in object code or executable form under the terms
+ of Sections 1 and 2 above provided that you also do one of the
+ following:
+
+ a. Accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of
+ Sections 1 and 2 above on a medium customarily used for
+ software interchange; or,
+
+ b. Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your
+ cost of physically performing source distribution, a complete
+ machine-readable copy of the corresponding source code, to be
+ distributed under the terms of Sections 1 and 2 above on a
+ medium customarily used for software interchange; or,
+
+ c. Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form with
+ such an offer, in accord with Subsection b above.)
+
+ The source code for a work means the preferred form of the work for
+ making modifications to it. For an executable work, complete
+ source code means all the source code for all modules it contains,
+ plus any associated interface definition files, plus the scripts
+ used to control compilation and installation of the executable.
+ However, as a special exception, the source code distributed need
+ not include anything that is normally distributed (in either
+ source or binary form) with the major components (compiler,
+ kernel, and so on) of the operating system on which the executable
+ runs, unless that component itself accompanies the executable.
+
+ If distribution of executable or object code is made by offering
+ access to copy from a designated place, then offering equivalent
+ access to copy the source code from the same place counts as
+ distribution of the source code, even though third parties are not
+ compelled to copy the source along with the object code.
+
+ 4. You may not copy, modify, sublicense, or distribute the Program
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense or distribute the Program is
+ void, and will automatically terminate your rights under this
+ License. However, parties who have received copies, or rights,
+ from you under this License will not have their licenses
+ terminated so long as such parties remain in full compliance.
+
+ 5. You are not required to accept this License, since you have not
+ signed it. However, nothing else grants you permission to modify
+ or distribute the Program or its derivative works. These actions
+ are prohibited by law if you do not accept this License.
+ Therefore, by modifying or distributing the Program (or any work
+ based on the Program), you indicate your acceptance of this
+ License to do so, and all its terms and conditions for copying,
+ distributing or modifying the Program or works based on it.
+
+ 6. Each time you redistribute the Program (or any work based on the
+ Program), the recipient automatically receives a license from the
+ original licensor to copy, distribute or modify the Program
+ subject to these terms and conditions. You may not impose any
+ further restrictions on the recipients' exercise of the rights
+ granted herein. You are not responsible for enforcing compliance
+ by third parties to this License.
+
+ 7. If, as a consequence of a court judgment or allegation of patent
+ infringement or for any other reason (not limited to patent
+ issues), conditions are imposed on you (whether by court order,
+ agreement or otherwise) that contradict the conditions of this
+ License, they do not excuse you from the conditions of this
+ License. If you cannot distribute so as to satisfy simultaneously
+ your obligations under this License and any other pertinent
+ obligations, then as a consequence you may not distribute the
+ Program at all. For example, if a patent license would not permit
+ royalty-free redistribution of the Program by all those who
+ receive copies directly or indirectly through you, then the only
+ way you could satisfy both it and this License would be to refrain
+ entirely from distribution of the Program.
+
+ If any portion of this section is held invalid or unenforceable
+ under any particular circumstance, the balance of the section is
+ intended to apply and the section as a whole is intended to apply
+ in other circumstances.
+
+ It is not the purpose of this section to induce you to infringe any
+ patents or other property right claims or to contest validity of
+ any such claims; this section has the sole purpose of protecting
+ the integrity of the free software distribution system, which is
+ implemented by public license practices. Many people have made
+ generous contributions to the wide range of software distributed
+ through that system in reliance on consistent application of that
+ system; it is up to the author/donor to decide if he or she is
+ willing to distribute software through any other system and a
+ licensee cannot impose that choice.
+
+ This section is intended to make thoroughly clear what is believed
+ to be a consequence of the rest of this License.
+
+ 8. If the distribution and/or use of the Program is restricted in
+ certain countries either by patents or by copyrighted interfaces,
+ the original copyright holder who places the Program under this
+ License may add an explicit geographical distribution limitation
+ excluding those countries, so that distribution is permitted only
+ in or among countries not thus excluded. In such case, this
+ License incorporates the limitation as if written in the body of
+ this License.
+
+ 9. The Free Software Foundation may publish revised and/or new
+ versions of the General Public License from time to time. Such
+ new versions will be similar in spirit to the present version, but
+ may differ in detail to address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+ Program specifies a version number of this License which applies
+ to it and "any later version", you have the option of following
+ the terms and conditions either of that version or of any later
+ version published by the Free Software Foundation. If the Program
+ does not specify a version number of this License, you may choose
+ any version ever published by the Free Software Foundation.
+
+ 10. If you wish to incorporate parts of the Program into other free
+ programs whose distribution conditions are different, write to the
+ author to ask for permission. For software which is copyrighted
+ by the Free Software Foundation, write to the Free Software
+ Foundation; we sometimes make exceptions for this. Our decision
+ will be guided by the two goals of preserving the free status of
+ all derivatives of our free software and of promoting the sharing
+ and reuse of software generally.
+
+ NO WARRANTY
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+ WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+ LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+ HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+ WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+ NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
+ QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+ PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+ SERVICING, REPAIR OR CORRECTION.
+
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+ WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+ MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
+ LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+ INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+ INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+ DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+ OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
+ OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+ ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+How to Apply These Terms to Your New Programs
+=============================================
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+ ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
+ Copyright (C) YEAR NAME OF AUTHOR
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+
+ Also add information on how to contact you by electronic and paper
+mail.
+
+ If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+ type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+ The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+
+ You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the program,
+if necessary. Here is a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+ `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+ SIGNATURE OF TY COON, 1 April 1989
+ Ty Coon, President of Vice
+
+ This General Public License does not permit incorporating your
+program into proprietary programs. If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library. If this is what you want to do, use the
+GNU Library General Public License instead of this License.