21.8.1 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.

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.

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.

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.