+++ /dev/null
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-
-\1f
-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.
-
-\1f
-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.
-
-
-\1f
-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.
-
-
-\1f
-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.
-
projects / msp430-gcc.git / blobdiff