X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=gcc%2Fdoc%2Fgccint.info-15;fp=gcc%2Fdoc%2Fgccint.info-15;h=0000000000000000000000000000000000000000;hb=5a5369932a08c074943c94407697a5813002fd31;hp=1fac3115526086044c2a7905c172205893fc6a6f;hpb=aaf7afc53d3ed4f6c811f6ec493d857ea0459573;p=msp430-gcc.git diff --git a/gcc/doc/gccint.info-15 b/gcc/doc/gccint.info-15 deleted file mode 100644 index 1fac3115..00000000 --- a/gcc/doc/gccint.info-15 +++ /dev/null @@ -1,1058 +0,0 @@ -This is doc/gccint.info, produced by makeinfo version 4.5 from -doc/gccint.texi. - -INFO-DIR-SECTION Programming -START-INFO-DIR-ENTRY -* gccint: (gccint). Internals of the GNU Compiler Collection. -END-INFO-DIR-ENTRY - This file documents the internals of the GNU compilers. - - Published by the Free Software Foundation -59 Temple Place - Suite 330 -Boston, MA 02111-1307 USA - - Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "GNU General Public License" and "Funding Free -Software", the Front-Cover texts being (a) (see below), and with the -Back-Cover Texts being (b) (see below). A copy of the license is -included in the section entitled "GNU Free Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - -File: gccint.info, Node: Frame Layout, Next: Exception Handling, Up: Stack and Calling - -Basic Stack Layout ------------------- - - Here is the basic stack layout. - -`STACK_GROWS_DOWNWARD' - Define this macro if pushing a word onto the stack moves the stack - pointer to a smaller address. - - When we say, "define this macro if ...," it means that the - compiler checks this macro only with `#ifdef' so the precise - definition used does not matter. - -`STACK_PUSH_CODE' - This macro defines the operation used when something is pushed on - the stack. In RTL, a push operation will be `(set (mem - (STACK_PUSH_CODE (reg sp))) ...)' - - The choices are `PRE_DEC', `POST_DEC', `PRE_INC', and `POST_INC'. - Which of these is correct depends on the stack direction and on - whether the stack pointer points to the last item on the stack or - whether it points to the space for the next item on the stack. - - The default is `PRE_DEC' when `STACK_GROWS_DOWNWARD' is defined, - which is almost always right, and `PRE_INC' otherwise, which is - often wrong. - -`FRAME_GROWS_DOWNWARD' - Define this macro if the addresses of local variable slots are at - negative offsets from the frame pointer. - -`ARGS_GROW_DOWNWARD' - Define this macro if successive arguments to a function occupy - decreasing addresses on the stack. - -`STARTING_FRAME_OFFSET' - Offset from the frame pointer to the first local variable slot to - be allocated. - - If `FRAME_GROWS_DOWNWARD', find the next slot's offset by - subtracting the first slot's length from `STARTING_FRAME_OFFSET'. - Otherwise, it is found by adding the length of the first slot to - the value `STARTING_FRAME_OFFSET'. - -`STACK_POINTER_OFFSET' - Offset from the stack pointer register to the first location at - which outgoing arguments are placed. If not specified, the - default value of zero is used. This is the proper value for most - machines. - - If `ARGS_GROW_DOWNWARD', this is the offset to the location above - the first location at which outgoing arguments are placed. - -`FIRST_PARM_OFFSET (FUNDECL)' - Offset from the argument pointer register to the first argument's - address. On some machines it may depend on the data type of the - function. - - If `ARGS_GROW_DOWNWARD', this is the offset to the location above - the first argument's address. - -`STACK_DYNAMIC_OFFSET (FUNDECL)' - Offset from the stack pointer register to an item dynamically - allocated on the stack, e.g., by `alloca'. - - The default value for this macro is `STACK_POINTER_OFFSET' plus the - length of the outgoing arguments. The default is correct for most - machines. See `function.c' for details. - -`DYNAMIC_CHAIN_ADDRESS (FRAMEADDR)' - A C expression whose value is RTL representing the address in a - stack frame where the pointer to the caller's frame is stored. - Assume that FRAMEADDR is an RTL expression for the address of the - stack frame itself. - - If you don't define this macro, the default is to return the value - of FRAMEADDR--that is, the stack frame address is also the address - of the stack word that points to the previous frame. - -`SETUP_FRAME_ADDRESSES' - If defined, a C expression that produces the machine-specific code - to setup the stack so that arbitrary frames can be accessed. For - example, on the Sparc, we must flush all of the register windows - to the stack before we can access arbitrary stack frames. You - will seldom need to define this macro. - -`BUILTIN_SETJMP_FRAME_VALUE' - If defined, a C expression that contains an rtx that is used to - store the address of the current frame into the built in `setjmp' - buffer. The default value, `virtual_stack_vars_rtx', is correct - for most machines. One reason you may need to define this macro - is if `hard_frame_pointer_rtx' is the appropriate value on your - machine. - -`RETURN_ADDR_RTX (COUNT, FRAMEADDR)' - A C expression whose value is RTL representing the value of the - return address for the frame COUNT steps up from the current - frame, after the prologue. FRAMEADDR is the frame pointer of the - COUNT frame, or the frame pointer of the COUNT - 1 frame if - `RETURN_ADDR_IN_PREVIOUS_FRAME' is defined. - - The value of the expression must always be the correct address when - COUNT is zero, but may be `NULL_RTX' if there is not way to - determine the return address of other frames. - -`RETURN_ADDR_IN_PREVIOUS_FRAME' - Define this if the return address of a particular stack frame is - accessed from the frame pointer of the previous stack frame. - -`INCOMING_RETURN_ADDR_RTX' - A C expression whose value is RTL representing the location of the - incoming return address at the beginning of any function, before - the prologue. This RTL is either a `REG', indicating that the - return value is saved in `REG', or a `MEM' representing a location - in the stack. - - You only need to define this macro if you want to support call - frame debugging information like that provided by DWARF 2. - - If this RTL is a `REG', you should also define - `DWARF_FRAME_RETURN_COLUMN' to `DWARF_FRAME_REGNUM (REGNO)'. - -`INCOMING_FRAME_SP_OFFSET' - A C expression whose value is an integer giving the offset, in - bytes, from the value of the stack pointer register to the top of - the stack frame at the beginning of any function, before the - prologue. The top of the frame is defined to be the value of the - stack pointer in the previous frame, just before the call - instruction. - - You only need to define this macro if you want to support call - frame debugging information like that provided by DWARF 2. - -`ARG_POINTER_CFA_OFFSET (FUNDECL)' - A C expression whose value is an integer giving the offset, in - bytes, from the argument pointer to the canonical frame address - (cfa). The final value should coincide with that calculated by - `INCOMING_FRAME_SP_OFFSET'. Which is unfortunately not usable - during virtual register instantiation. - - The default value for this macro is `FIRST_PARM_OFFSET (fundecl)', - which is correct for most machines; in general, the arguments are - found immediately before the stack frame. Note that this is not - the case on some targets that save registers into the caller's - frame, such as SPARC and rs6000, and so such targets need to - define this macro. - - You only need to define this macro if the default is incorrect, - and you want to support call frame debugging information like that - provided by DWARF 2. - -`SMALL_STACK' - Define this macro if the stack size for the target is very small. - This has the effect of disabling gcc's built-in `alloca', though - `__builtin_alloca' is not affected. - - -File: gccint.info, Node: Exception Handling, Next: Stack Checking, Prev: Frame Layout, Up: Stack and Calling - -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 - -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. - -`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 - -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 - -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 - -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 - -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 - -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. -