--- gcc/gcc.info-21 2018/04/24 18:12:56 1.1.1.2 +++ gcc/gcc.info-21 2018/04/24 18:42:52 1.1.1.5 @@ -1,12 +1,13 @@ -This is Info file gcc.info, produced by Makeinfo-1.54 from the input -file gcc.texi. +This is Info file gcc.info, produced by Makeinfo version 1.67 from the +input file gcc.texi. This file documents the use and the internals of the GNU compiler. - Published by the Free Software Foundation 675 Massachusetts Avenue -Cambridge, MA 02139 USA + Published by the Free Software Foundation 59 Temple Place - Suite 330 +Boston, MA 02111-1307 USA - Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc. + Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -14,827 +15,913 @@ preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also -that the sections entitled "GNU General Public License" and "Protect -Your Freedom--Fight `Look And Feel'" are included exactly as in the -original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this -one. +that the sections entitled "GNU General Public License," "Funding for +Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the sections entitled "GNU General Public -License" and "Protect Your Freedom--Fight `Look And Feel'", and this -permission notice, may be included in translations approved by the Free -Software Foundation instead of in the original English. +License," "Funding for Free Software," and "Protect Your Freedom--Fight +`Look And Feel'", and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English. + + +File: gcc.info, Node: Register Arguments, Next: Scalar Return, Prev: Stack Arguments, Up: Stack and Calling + +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. + + The value of the expression should either be 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 usual way to make the ANSI 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 non-zero 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. + +`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, 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. + +`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)' + 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. + + 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_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 GNU CC. + 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. + +`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. + + +File: gcc.info, Node: Scalar Return, Next: Aggregate Return, Prev: Register Arguments, Up: Stack and Calling + +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). + + 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: gcc.info, Node: Aggregate Return, Next: Caller Saves, Prev: Scalar Return, Up: Stack and Calling + +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. - -File: gcc.info, Node: Macros for Initialization, Next: Instruction Output, Prev: Initialization, Up: Assembler Format - -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 for the assembler operation to - identify the following data as initialization code. If not - defined, GNU CC 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. - -`ASM_OUTPUT_CONSTRUCTOR (STREAM, NAME)' - Define this macro as a C statement to output on the stream STREAM - the assembler code to arrange to call the function named NAME at - initialization time. - - Assume that NAME is the name of a C function generated - automatically by the compiler. This function takes no arguments. - Use the function `assemble_name' to output the name NAME; this - performs any system-specific syntactic transformations such as - adding an underscore. - - If you don't define this macro, nothing special is output to - arrange to call the function. This is correct when the function - will be called in some other manner--for example, by means of the - `collect2' program, which looks through the symbol table to find - these functions by their names. - -`ASM_OUTPUT_DESTRUCTOR (STREAM, NAME)' - This is like `ASM_OUTPUT_CONSTRUCTOR' but used for termination - functions rather than initialization functions. - - 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'. - -`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'. - - -File: gcc.info, Node: Instruction Output, Next: Dispatch Tables, Prev: Macros for Initialization, Up: Assembler Format - -Output of Assembler Instructions --------------------------------- - -`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_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. - -`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. - -`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 langauge dialect to - use, with zero as the first variant. - - If this macro is defined, you may use - `{option0|option1|option2...}' constructs in the output templates - of patterns (*note Output Template::.) or in the first argument of - `asm_fprintf'. This construct outputs `option0', `option1' or - `option2', etc., if the value of `ASSEMBLER_DIALECT' is zero, one - or two, etc. Any special characters within these strings retain - their usual meaning. - - 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 assemble 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: gcc.info, Node: Dispatch Tables, Next: Alignment Output, Prev: Instruction Output, Up: Assembler Format - -Output of Dispatch Tables -------------------------- - -`ASM_OUTPUT_ADDR_DIFF_ELT (STREAM, VALUE, REL)' - This macro should be provided on machines where the addresses in a - dispatch table are relative to the table's own address. - - The definition should be 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) - -`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. + This macro has effect in `-fpcc-struct-return' mode, but it does + nothing when you use `-freg-struct-return' mode.  -File: gcc.info, Node: Alignment Output, Prev: Dispatch Tables, Up: Assembler Format +File: gcc.info, Node: Caller Saves, Next: Function Entry, Prev: Aggregate Return, Up: Stack and Calling -Assembler Commands for Alignment +Caller-Saves Register Allocation -------------------------------- -`ASM_OUTPUT_ALIGN_CODE (FILE)' - A C expression to output text to align the location counter in the - way that is desirable at a point in the code that is reached only - by jumping. - - 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. - -`ASM_OUTPUT_LOOP_ALIGN (FILE)' - A C expression to output text to align the location counter in the - way that is desirable at the beginning of a loop. - - 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. - -`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 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'. - - -File: gcc.info, Node: Debugging Info, Next: Cross-compilation, Prev: Assembler Format, Up: Target Macros - -Controlling Debugging Information Format -======================================== - -* Menu: - -* 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. - - -File: gcc.info, Node: All Debuggers, Next: DBX Options, Up: Debugging Info - -Macros Affecting All Debugging Formats --------------------------------------- - -`DBX_REGISTER_NUMBER (REGNO)' - A C expression that returns the DBX register number for the - compiler register number REGNO. In simple cases, the value of this - expression may 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 GNU CC, 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 GNU CC - produces when the user specifies `-g' or `-ggdb'. Define this if - you have arranged for GNU CC to support more than one format of - debugging output. Currently, the allowable values are `DBX_DEBUG', - `SDB_DEBUG', `DWARF_DEBUG', and `XCOFF_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', or `-gxcoff'. - - -File: gcc.info, Node: DBX Options, Next: DBX Hooks, Prev: All Debuggers, Up: Debugging Info - -Specific Options for DBX Output -------------------------------- - -`DBX_DEBUGGING_INFO' - Define this macro if GNU CC should produce debugging output for DBX - in response to the `-g' option. - -`XCOFF_DEBUGGING_INFO' - Define this macro if GNU CC 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 GNU CC 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 naming the assembler pseudo op to use instead - of `.stabs' to define an ordinary debugging symbol. If you don't - define this macro, `.stabs' is used. This macro applies only to - DBX debugging information format. - -`ASM_STABD_OP' - A C string constant naming the assembler pseudo op to use instead - of `.stabd' to define a debugging symbol whose value is the current - location. If you don't define this macro, `.stabd' is used. This - macro applies only to DBX debugging information format. - -`ASM_STABN_OP' - A C string constant naming the assembler pseudo op to use instead - of `.stabn' to define a debugging symbol with no name. If you - don't define this macro, `.stabn' 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. - - -File: gcc.info, Node: DBX Hooks, Next: File Names and DBX, Prev: DBX Options, Up: Debugging Info - -Open-Ended 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_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); - ... - } - - -File: gcc.info, Node: File Names and DBX, Next: SDB and DWARF, Prev: DBX Hooks, Up: Debugging Info - -File Names in DBX Format ------------------------- - -`DBX_WORKING_DIRECTORY' - Define this if DBX wants to have the current directory recorded in - each object file. - - Note that the working directory is always recorded if GDB - extensions are enabled. - -`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. - - This macro need not be defined if the standard form of output for - DBX debugging information is appropriate. - -`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. - - This macro need not be defined if the standard form of output for - DBX debugging information is appropriate. - -`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. - - If you don't define this macro, nothing special is output at the - end of compilation, which is correct for most machines. - -`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. - - This macro need not be defined if the standard form of output for - DBX debugging information is appropriate. - - -File: gcc.info, Node: SDB and DWARF, Prev: File Names and DBX, Up: Debugging Info - -Macros for SDB and DWARF Output -------------------------------- - -`SDB_DEBUGGING_INFO' - Define this macro if GNU CC should produce COFF-style debugging - output for SDB in response to the `-g' option. - -`DWARF_DEBUGGING_INFO' - Define this macro if GNU CC should produce dwarf format debugging - output in response to the `-g' option. - -`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. - - -File: gcc.info, Node: Cross-compilation, Next: Misc, Prev: Debugging Info, Up: Target Macros - -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)' - 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. + If you enable it, GNU CC 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. This macro enables `-fcaller-saves' by + default. Eventually that option will be enabled by default on all + machines and both the option and this macro will be eliminated. + +`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'. + + +File: gcc.info, Node: Function Entry, Next: Profiling, Prev: Caller Saves, Up: Stack and Calling + +Function Entry and Exit +----------------------- + + This section describes the macros that output function entry +("prologue") and exit ("epilogue") code. + +`FUNCTION_PROLOGUE (FILE, SIZE)' + A C compound statement 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. (`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. + + * A region of `current_function_pretend_args_size' bytes of + uninitialized space just underneath the first argument + arriving on the stack. (This may not be at the very start of + the allocated stack region if the calling sequence has pushed + anything else since pushing the stack arguments. But + usually, on such machines, nothing else has been pushed yet, + because the function prologue itself does all the pushing.) + This region is used on machines where an argument may be + passed partly in registers and partly in memory, and, in some + cases to support the features in `varargs.h' and `stdargs.h'. + + * An area of memory used to save certain registers used by the + function. The size of this area, which may also include + space for such things as the return address and pointers to + previous stack frames, is machine-specific and usually + depends on which registers have been used in the function. + Machines with register windows often do not require a save + area. + + * A region of at least SIZE bytes, possibly rounded up to an + allocation boundary, to contain the local variables of the + function. On some machines, this region and the save area + may occur in the opposite order, with the save area closer to + the top of the stack. + + * Optionally, when `ACCUMULATE_OUTGOING_ARGS' is defined, a + region of `current_function_outgoing_args_size' bytes to be + used for outgoing argument lists of the function. *Note + Stack Arguments::. + + Normally, it is necessary for the macros `FUNCTION_PROLOGUE' and + `FUNCTION_EPILOGUE' to treat leaf functions specially. The C + variable `leaf_function' 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'. + +`FUNCTION_EPILOGUE (FILE, SIZE)' + A C compound statement 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 `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 + `FUNCTION_EPILOGUE' at all. + + Do not define a pattern named `return' if you want the + `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, `FUNCTION_PROLOGUE' and `FUNCTION_EPILOGUE' must treat + leaf functions specially. The C variable `leaf_function' 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. `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::. + +`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 + `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'. + + +File: gcc.info, Node: Profiling, Prev: Function Entry, Up: Stack and Calling + +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'. Before + calling, the assembler code must load the address of a counter + variable into a register where `mcount' expects to find the + address. The name of this variable is `LP' followed by the number + LABELNO, so you would generate the name using `LP%d' in a + `fprintf'. + + The details of how the address should be passed to `mcount' are + determined by your operating system environment, not by GNU CC. 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. + +`PROFILE_BEFORE_PROLOGUE' + Define this macro if the code for function profiling should come + before the function prologue. Normally, the profiling code comes + after. + +`FUNCTION_BLOCK_PROFILER (FILE, LABELNO)' + A C statement or compound statement to output to FILE some + assembler code to initialize basic-block profiling for the current + object module. This code should call the subroutine + `__bb_init_func' once per object module, passing it as its sole + argument the address of a block allocated in the object module. + + The name of the block is a local symbol made with this statement: + + ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 0); + + Of course, since you are writing the definition of + `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you + can take a short cut in the definition of this macro and use the + name that you know will result. + + The first word of this block is a flag which will be nonzero if the + object module has already been initialized. So test this word + first, and do not call `__bb_init_func' if the flag is nonzero. + +`BLOCK_PROFILER (FILE, BLOCKNO)' + A C statement or compound statement to increment the count + associated with the basic block number BLOCKNO. Basic blocks are + numbered separately from zero within each compilation. The count + associated with block number BLOCKNO is at index BLOCKNO in a + vector of words; the name of this array is a local symbol made + with this statement: + + ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 2); + + Of course, since you are writing the definition of + `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you + can take a short cut in the definition of this macro and use the + name that you know will result. + +`BLOCK_PROFILER_CODE' + A C function or functions which are needed in the library to + support block profiling. + + +File: gcc.info, Node: Varargs, Next: Trampolines, Prev: Stack and Calling, Up: Target Macros + +Implementing the Varargs Macros +=============================== + + GNU CC comes with an implementation of `varargs.h' and `stdarg.h' +that work without change on machines that pass arguments on the stack. +Other machines require their own implementations of varargs, and the +two machine independent header files must have conditionals to include +it. + + ANSI `stdarg.h' differs from traditional `varargs.h' mainly in the +calling convention for `va_start'. The traditional implementation +takes just one argument, which is the variable in which to store the +argument pointer. The ANSI 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 ANSI + 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 (ARGS)' + 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'. + + The argument ARGS is a `tree_list' containing the arguments that + were passed to `__builtin_saveregs'. + + If this macro is not defined, the compiler will output an ordinary + call to the library function `__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 obtain after processing of 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 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. With this macro defined, + the NAMED argument is always true for named arguments, and false + for unnamed arguments. If this is not defined, but + `SETUP_INCOMING_VARARGS' is defined, then all arguments are + treated as named. Otherwise, all named arguments except the last + are treated as named. + + +File: gcc.info, Node: Trampolines, Next: Library Calls, Prev: Varargs, Up: Target Macros + +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 GNU CC 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. + +`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. + +`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 `FUNCTION_PROLOGUE' and `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 GNU CC. 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.