X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=gcc%2Fdoc%2Fgccint.info-3;h=7ea83ea8831515ed335d2427b0109e82c99ad5f3;hb=5a5369932a08c074943c94407697a5813002fd31;hp=c9d948a8055758e1b27dacfcb6bfc3cc19d254d3;hpb=aaf7afc53d3ed4f6c811f6ec493d857ea0459573;p=msp430-gcc.git diff --git a/gcc/doc/gccint.info-3 b/gcc/doc/gccint.info-3 index c9d948a8..7ea83ea8 100644 --- a/gcc/doc/gccint.info-3 +++ b/gcc/doc/gccint.info-3 @@ -1,4 +1,4 @@ -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 @@ -33,864 +33,6220 @@ software. Copies published by the Free Software Foundation raise funds for GNU development.  -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. + + +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'. - - -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. + + +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'. + + + +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. + + +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. + + + +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. + + + +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. + + +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. + + +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. + + +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 `' and + `'. + + * 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. + + +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. + + + +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. + + +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 `' and `' 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 `' differs from traditional `' 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. + + +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. + + +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. + + +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. + + +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)) + + + +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. + + +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. + + +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. + + +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. + + +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. - - -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. - - - -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. - - - -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 - `""'. - -`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. - - - -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. + + +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__'. + + +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. + + +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. + + +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. + + +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. + + +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'. + + +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. + + +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. + + +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. + + +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'. + + +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.  -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 ---------------- + +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'. + +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'. 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.) + +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. + +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. + +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. + +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. + +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. + +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. + +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 + . + + 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()' and `#pragma weak [=]' + 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. + +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::. + + +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. + + +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. + + +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[]'. + +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'. + + +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. + + +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. + + +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' + + +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.