Using and Porting GNU CC

16.7.9: Function Entry and Exit

This section describes the macros that output function entry (prologue) and exit (epilogue) code.

FUNCTION_PROLOGUE (file, size)

A C compound statement that outputs the assembler code for entry to a function. The prologue is responsible for setting up the stack frame, initializing the frame pointer register, saving registers that must be saved, and allocating size additional bytes of storage for the local variables. size is an integer. file is a stdio stream to which the assembler code should be output.

The label for the beginning of the function need not be output by this macro. That has already been done when the macro is run.

To determine which registers to save, the macro can refer to the array regs_ever_live: element r is nonzero if hard register r is used anywhere within the function. This implies the function prologue should save register r, provided it is not one of the call-used registers. (FUNCTION_EPILOGUE must likewise use regs_ever_live.)

On machines that have ``register windows'', the function entry code does not save on the stack the registers that are in the windows, even if they are supposed to be preserved by function calls; instead it takes appropriate steps to ``push'' the register stack, if any non-call-used registers are used in the function.

On machines where functions may or may not have frame-pointers, the function entry code must vary accordingly; it must set up the frame pointer if one is wanted, and not otherwise. To determine whether a frame pointer is in wanted, the macro can refer to the variable frame_pointer_needed. The variable's value will be 1 at run time in a function that needs a frame pointer. See Elimination.

The function entry code is responsible for allocating any stack space required for the function. This stack space consists of the regions listed below. In most cases, these regions are allocated in the order listed, with the last listed region closest to the top of the stack (the lowest address if STACK_GROWS_DOWNWARD is defined, and the highest address if it is not defined). You can use a different order for a machine if doing so is more convenient or required for compatibility reasons. Except in cases where required by standard or by a debugger, there is no reason why the stack layout used by GCC need agree with that used by other compilers for a machine.

• A region of current_function_pretend_args_size bytes of uninitialized space just underneath the first argument arriving on the stack. (This may not be at the very start of the allocated stack region if the calling sequence has pushed anything else since pushing the stack arguments. But usually, on such machines, nothing else has been pushed yet, because the function prologue itself does all the pushing.) This region is used on machines where an argument may be passed partly in registers and partly in memory, and, in some cases to support the features in `varargs.h' and `stdargs.h'.
• An area of memory used to save certain registers used by the function. The size of this area, which may also include space for such things as the return address and pointers to previous stack frames, is machine-specific and usually depends on which registers have been used in the function. Machines with register windows often do not require a save area.
• A region of at least size bytes, possibly rounded up to an allocation boundary, to contain the local variables of the function. On some machines, this region and the save area may occur in the opposite order, with the save area closer to the top of the stack.
• Optionally, when ACCUMULATE_OUTGOING_ARGS is defined, a region of current_function_outgoing_args_size bytes to be used for outgoing argument lists of the function. See Stack Arguments.

Normally, it is necessary for the macros FUNCTION_PROLOGUE and FUNCTION_EPILOGUE to treat leaf functions specially. The C variable leaf_function is nonzero for such a function.

EXIT_IGNORE_STACK

Define this macro as a C expression that is nonzero if the return instruction or the function epilogue ignores the value of the stack pointer; in other words, if it is safe to delete an instruction to adjust the stack pointer before a return from the function.

Note that this macro's value is relevant only for functions for which frame pointers are maintained. It is never safe to delete a final stack adjustment in a function that has no frame pointer, and the compiler knows this regardless of EXIT_IGNORE_STACK.

FUNCTION_EPILOGUE (file, size)

A C compound statement that outputs the assembler code for exit from a function. The epilogue is responsible for restoring the saved registers and stack pointer to their values when the function was called, and returning control to the caller. This macro takes the same arguments as the macro FUNCTION_PROLOGUE, and the registers to restore are determined from regs_ever_live and CALL_USED_REGISTERS in the same way.

On some machines, there is a single instruction that does all the work of returning from the function. On these machines, give that instruction the name `return' and do not define the macro FUNCTION_EPILOGUE at all.

Do not define a pattern named `return' if you want the FUNCTION_EPILOGUE to be used. If you want the target switches to control whether return instructions or epilogues are used, define a `return' pattern with a validity condition that tests the target switches appropriately. If the `return' pattern's validity condition is false, epilogues will be used.

On machines where functions may or may not have frame-pointers, the function exit code must vary accordingly. Sometimes the code for these two cases is completely different. To determine whether a frame pointer is wanted, the macro can refer to the variable frame_pointer_needed. The variable's value will be 1 when compiling a function that needs a frame pointer.

Normally, FUNCTION_PROLOGUE and FUNCTION_EPILOGUE must treat leaf functions specially. The C variable leaf_function is nonzero for such a function. See Leaf Functions.

On some machines, some functions pop their arguments on exit while others leave that for the caller to do. For example, the 68020 when given `-mrtd' pops arguments in functions that take a fixed number of arguments.

Your definition of the macro RETURN_POPS_ARGS decides which functions pop their own arguments. FUNCTION_EPILOGUE needs to know what was decided. The variable that is called current_function_pops_args is the number of bytes of its arguments that a function should pop. See Scalar Return.

DELAY_SLOTS_FOR_EPILOGUE

Define this macro if the function epilogue contains delay slots to which instructions from the rest of the function can be ``moved''. The definition should be a C expression whose value is an integer representing the number of delay slots there.

ELIGIBLE_FOR_EPILOGUE_DELAY (insn, n)

A C expression that returns 1 if insn can be placed in delay slot number n of the epilogue.

The argument n is an integer which identifies the delay slot now being considered (since different slots may have different rules of eligibility). It is never negative and is always less than the number of epilogue delay slots (what DELAY_SLOTS_FOR_EPILOGUE returns). If you reject a particular insn for a given delay slot, in principle, it may be reconsidered for a subsequent delay slot. Also, other insns may (at least in principle) be considered for the so far unfilled delay slot.

The insns accepted to fill the epilogue delay slots are put in an RTL list made with insn_list objects, stored in the variable current_function_epilogue_delay_list. The insn for the first delay slot comes first in the list. Your definition of the macro FUNCTION_EPILOGUE should fill the delay slots by outputting the insns in this list, usually by calling final_scan_insn.

You need not define this macro if you did not define DELAY_SLOTS_FOR_EPILOGUE.