diff options
Diffstat (limited to 'share/doc/gccint/Function-Entry.html')
| -rw-r--r-- | share/doc/gccint/Function-Entry.html | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/share/doc/gccint/Function-Entry.html b/share/doc/gccint/Function-Entry.html new file mode 100644 index 0000000..a07765d --- /dev/null +++ b/share/doc/gccint/Function-Entry.html @@ -0,0 +1,326 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 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.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "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. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>GNU Compiler Collection (GCC) Internals: Function Entry</title> + +<meta name="description" content="GNU Compiler Collection (GCC) Internals: Function Entry"> +<meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Function Entry"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Stack-and-Calling.html#Stack-and-Calling" rel="up" title="Stack and Calling"> +<link href="Profiling.html#Profiling" rel="next" title="Profiling"> +<link href="Caller-Saves.html#Caller-Saves" rel="previous" title="Caller Saves"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Function-Entry"></a> +<div class="header"> +<p> +Next: <a href="Profiling.html#Profiling" accesskey="n" rel="next">Profiling</a>, Previous: <a href="Caller-Saves.html#Caller-Saves" accesskey="p" rel="previous">Caller Saves</a>, Up: <a href="Stack-and-Calling.html#Stack-and-Calling" accesskey="u" rel="up">Stack and Calling</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Function-Entry-and-Exit"></a> +<h4 class="subsection">18.9.11 Function Entry and Exit</h4> +<a name="index-function-entry-and-exit"></a> +<a name="index-prologue"></a> +<a name="index-epilogue"></a> + +<p>This section describes the macros that output function entry +(<em>prologue</em>) and exit (<em>epilogue</em>) code. +</p> +<dl> +<dt><a name="index-TARGET_005fASM_005fPRINT_005fPATCHABLE_005fFUNCTION_005fENTRY"></a>Target Hook: <em>void</em> <strong>TARGET_ASM_PRINT_PATCHABLE_FUNCTION_ENTRY</strong> <em>(FILE *<var>file</var>, unsigned HOST_WIDE_INT <var>patch_area_size</var>, bool <var>record_p</var>)</em></dt> +<dd><p>Generate a patchable area at the function start, consisting of +<var>patch_area_size</var> NOP instructions. If the target supports named +sections and if <var>record_p</var> is true, insert a pointer to the current +location in the table of patchable functions. The default implementation +of the hook places the table of pointers in the special section named +<code>__patchable_function_entries</code>. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fASM_005fFUNCTION_005fPROLOGUE"></a>Target Hook: <em>void</em> <strong>TARGET_ASM_FUNCTION_PROLOGUE</strong> <em>(FILE *<var>file</var>)</em></dt> +<dd><p>If defined, a function 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 <var>size</var> additional bytes of storage for the +local variables. <var>file</var> is a stdio stream to which the assembler +code should be output. +</p> +<p>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. +</p> +<a name="index-regs_005fever_005flive"></a> +<p>To determine which registers to save, the macro can refer to the array +<code>regs_ever_live</code>: element <var>r</var> is nonzero if hard register +<var>r</var> is used anywhere within the function. This implies the function +prologue should save register <var>r</var>, provided it is not one of the +call-used registers. (<code>TARGET_ASM_FUNCTION_EPILOGUE</code> must likewise use +<code>regs_ever_live</code>.) +</p> +<p>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. +</p> +<a name="index-frame_005fpointer_005fneeded"></a> +<p>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 +<code>frame_pointer_needed</code>. The variable’s value will be 1 at run +time in a function that needs a frame pointer. See <a href="Elimination.html#Elimination">Elimination</a>. +</p> +<p>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 <code>STACK_GROWS_DOWNWARD</code> 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. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fASM_005fFUNCTION_005fEND_005fPROLOGUE"></a>Target Hook: <em>void</em> <strong>TARGET_ASM_FUNCTION_END_PROLOGUE</strong> <em>(FILE *<var>file</var>)</em></dt> +<dd><p>If defined, a function that outputs assembler code at the end of a +prologue. This should be used when the function prologue is being +emitted as RTL, and you have some extra assembler that needs to be +emitted. See <a href="Standard-Names.html#prologue-instruction-pattern">prologue instruction pattern</a>. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fASM_005fFUNCTION_005fBEGIN_005fEPILOGUE"></a>Target Hook: <em>void</em> <strong>TARGET_ASM_FUNCTION_BEGIN_EPILOGUE</strong> <em>(FILE *<var>file</var>)</em></dt> +<dd><p>If defined, a function that outputs assembler code at the start of an +epilogue. This should be used when the function epilogue is being +emitted as RTL, and you have some extra assembler that needs to be +emitted. See <a href="Standard-Names.html#epilogue-instruction-pattern">epilogue instruction pattern</a>. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fASM_005fFUNCTION_005fEPILOGUE"></a>Target Hook: <em>void</em> <strong>TARGET_ASM_FUNCTION_EPILOGUE</strong> <em>(FILE *<var>file</var>)</em></dt> +<dd><p>If defined, a function 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 argument as the macro <code>TARGET_ASM_FUNCTION_PROLOGUE</code>, and the +registers to restore are determined from <code>regs_ever_live</code> and +<code>CALL_USED_REGISTERS</code> in the same way. +</p> +<p>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 ‘<samp>return</samp>’ and do not define the macro +<code>TARGET_ASM_FUNCTION_EPILOGUE</code> at all. +</p> +<p>Do not define a pattern named ‘<samp>return</samp>’ if you want the +<code>TARGET_ASM_FUNCTION_EPILOGUE</code> to be used. If you want the target +switches to control whether return instructions or epilogues are used, +define a ‘<samp>return</samp>’ pattern with a validity condition that tests the +target switches appropriately. If the ‘<samp>return</samp>’ pattern’s validity +condition is false, epilogues will be used. +</p> +<p>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 +<code>frame_pointer_needed</code>. The variable’s value will be 1 when compiling +a function that needs a frame pointer. +</p> +<p>Normally, <code>TARGET_ASM_FUNCTION_PROLOGUE</code> and +<code>TARGET_ASM_FUNCTION_EPILOGUE</code> must treat leaf functions specially. +The C variable <code>current_function_is_leaf</code> is nonzero for such a +function. See <a href="Leaf-Functions.html#Leaf-Functions">Leaf Functions</a>. +</p> +<p>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 <samp>-mrtd</samp> pops arguments in functions that take a fixed +number of arguments. +</p> +<a name="index-pops_005fargs"></a> +<a name="index-crtl_002d_003eargs_002epops_005fargs"></a> +<p>Your definition of the macro <code>RETURN_POPS_ARGS</code> decides which +functions pop their own arguments. <code>TARGET_ASM_FUNCTION_EPILOGUE</code> +needs to know what was decided. The number of bytes of the current +function’s arguments that this function should pop is available in +<code>crtl->args.pops_args</code>. See <a href="Scalar-Return.html#Scalar-Return">Scalar Return</a>. +</p></dd></dl> + +<ul> +<li> <a name="index-pretend_005fargs_005fsize"></a> +<a name="index-crtl_002d_003eargs_002epretend_005fargs_005fsize"></a> +A region of <code>crtl->args.pretend_args_size</code> 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 <code><stdarg.h></code>. + +</li><li> 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. + +</li><li> A region of at least <var>size</var> 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. + +</li><li> <a name="index-ACCUMULATE_005fOUTGOING_005fARGS-and-stack-frames"></a> +Optionally, when <code>ACCUMULATE_OUTGOING_ARGS</code> is defined, a region of +<code>crtl->outgoing_args_size</code> bytes to be used for outgoing +argument lists of the function. See <a href="Stack-Arguments.html#Stack-Arguments">Stack Arguments</a>. +</li></ul> + +<dl> +<dt><a name="index-EXIT_005fIGNORE_005fSTACK"></a>Macro: <strong>EXIT_IGNORE_STACK</strong></dt> +<dd><p>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. The +default is 0. +</p> +<p>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 <code>EXIT_IGNORE_STACK</code>. +</p></dd></dl> + +<dl> +<dt><a name="index-EPILOGUE_005fUSES"></a>Macro: <strong>EPILOGUE_USES</strong> <em>(<var>regno</var>)</em></dt> +<dd><p>Define this macro as a C expression that is nonzero for registers that are +used by the epilogue or the ‘<samp>return</samp>’ pattern. The stack and frame +pointer registers are already assumed to be used as needed. +</p></dd></dl> + +<dl> +<dt><a name="index-EH_005fUSES"></a>Macro: <strong>EH_USES</strong> <em>(<var>regno</var>)</em></dt> +<dd><p>Define this macro as a C expression that is nonzero for registers that are +used by the exception handling mechanism, and so should be considered live +on entry to an exception edge. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fASM_005fOUTPUT_005fMI_005fTHUNK"></a>Target Hook: <em>void</em> <strong>TARGET_ASM_OUTPUT_MI_THUNK</strong> <em>(FILE *<var>file</var>, tree <var>thunk_fndecl</var>, HOST_WIDE_INT <var>delta</var>, HOST_WIDE_INT <var>vcall_offset</var>, tree <var>function</var>)</em></dt> +<dd><p>A function that outputs the assembler code for a thunk +function, used to implement C++ virtual function calls with multiple +inheritance. The thunk acts as a wrapper around a virtual function, +adjusting the implicit object parameter before handing control off to +the real function. +</p> +<p>First, emit code to add the integer <var>delta</var> to the location that +contains the incoming first argument. Assume that this argument +contains a pointer, and is the one used to pass the <code>this</code> pointer +in C++. This is the incoming argument <em>before</em> the function prologue, +e.g. ‘<samp>%o0</samp>’ on a sparc. The addition must preserve the values of +all other incoming arguments. +</p> +<p>Then, if <var>vcall_offset</var> is nonzero, an additional adjustment should be +made after adding <code>delta</code>. In particular, if <var>p</var> is the +adjusted pointer, the following adjustment should be made: +</p> +<div class="smallexample"> +<pre class="smallexample">p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] +</pre></div> + +<p>After the additions, emit code to jump to <var>function</var>, which is a +<code>FUNCTION_DECL</code>. This is a direct pure jump, not a call, and does +not touch the return address. Hence returning from <var>FUNCTION</var> will +return to whoever called the current ‘<samp>thunk</samp>’. +</p> +<p>The effect must be as if <var>function</var> had been called directly with +the adjusted first argument. This macro is responsible for emitting all +of the code for a thunk function; <code>TARGET_ASM_FUNCTION_PROLOGUE</code> +and <code>TARGET_ASM_FUNCTION_EPILOGUE</code> are not invoked. +</p> +<p>The <var>thunk_fndecl</var> is redundant. (<var>delta</var> and <var>function</var> +have already been extracted from it.) It might possibly be useful on +some targets, but probably not. +</p> +<p>If you do not define this macro, the target-independent code in the C++ +front end will generate a less efficient heavyweight thunk that calls +<var>function</var> instead of jumping to it. The generic approach does +not support varargs. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fASM_005fCAN_005fOUTPUT_005fMI_005fTHUNK"></a>Target Hook: <em>bool</em> <strong>TARGET_ASM_CAN_OUTPUT_MI_THUNK</strong> <em>(const_tree <var>thunk_fndecl</var>, HOST_WIDE_INT <var>delta</var>, HOST_WIDE_INT <var>vcall_offset</var>, const_tree <var>function</var>)</em></dt> +<dd><p>A function that returns true if TARGET_ASM_OUTPUT_MI_THUNK would be able +to output the assembler code for the thunk function specified by the +arguments it is passed, and false otherwise. In the latter case, the +generic approach will be used by the C++ front end, with the limitations +previously exposed. +</p></dd></dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Profiling.html#Profiling" accesskey="n" rel="next">Profiling</a>, Previous: <a href="Caller-Saves.html#Caller-Saves" accesskey="p" rel="previous">Caller Saves</a>, Up: <a href="Stack-and-Calling.html#Stack-and-Calling" accesskey="u" rel="up">Stack and Calling</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |