Function-Entry.html 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- Copyright (C) 1988-2017 Free Software Foundation, Inc.
  4. Permission is granted to copy, distribute and/or modify this document
  5. under the terms of the GNU Free Documentation License, Version 1.3 or
  6. any later version published by the Free Software Foundation; with the
  7. Invariant Sections being "Funding Free Software", the Front-Cover
  8. Texts being (a) (see below), and with the Back-Cover Texts being (b)
  9. (see below). A copy of the license is included in the section entitled
  10. "GNU Free Documentation License".
  11. (a) The FSF's Front-Cover Text is:
  12. A GNU Manual
  13. (b) The FSF's Back-Cover Text is:
  14. You have freedom to copy and modify this GNU Manual, like GNU
  15. software. Copies published by the Free Software Foundation raise
  16. funds for GNU development. -->
  17. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  18. <head>
  19. <title>GNU Compiler Collection (GCC) Internals: Function Entry</title>
  20. <meta name="description" content="GNU Compiler Collection (GCC) Internals: Function Entry">
  21. <meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Function Entry">
  22. <meta name="resource-type" content="document">
  23. <meta name="distribution" content="global">
  24. <meta name="Generator" content="makeinfo">
  25. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  26. <link href="index.html#Top" rel="start" title="Top">
  27. <link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
  28. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  29. <link href="Stack-and-Calling.html#Stack-and-Calling" rel="up" title="Stack and Calling">
  30. <link href="Profiling.html#Profiling" rel="next" title="Profiling">
  31. <link href="Caller-Saves.html#Caller-Saves" rel="prev" title="Caller Saves">
  32. <style type="text/css">
  33. <!--
  34. a.summary-letter {text-decoration: none}
  35. blockquote.smallquotation {font-size: smaller}
  36. div.display {margin-left: 3.2em}
  37. div.example {margin-left: 3.2em}
  38. div.indentedblock {margin-left: 3.2em}
  39. div.lisp {margin-left: 3.2em}
  40. div.smalldisplay {margin-left: 3.2em}
  41. div.smallexample {margin-left: 3.2em}
  42. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  43. div.smalllisp {margin-left: 3.2em}
  44. kbd {font-style:oblique}
  45. pre.display {font-family: inherit}
  46. pre.format {font-family: inherit}
  47. pre.menu-comment {font-family: serif}
  48. pre.menu-preformatted {font-family: serif}
  49. pre.smalldisplay {font-family: inherit; font-size: smaller}
  50. pre.smallexample {font-size: smaller}
  51. pre.smallformat {font-family: inherit; font-size: smaller}
  52. pre.smalllisp {font-size: smaller}
  53. span.nocodebreak {white-space:nowrap}
  54. span.nolinebreak {white-space:nowrap}
  55. span.roman {font-family:serif; font-weight:normal}
  56. span.sansserif {font-family:sans-serif; font-weight:normal}
  57. ul.no-bullet {list-style: none}
  58. -->
  59. </style>
  60. </head>
  61. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  62. <a name="Function-Entry"></a>
  63. <div class="header">
  64. <p>
  65. Next: <a href="Profiling.html#Profiling" accesskey="n" rel="next">Profiling</a>, Previous: <a href="Caller-Saves.html#Caller-Saves" accesskey="p" rel="prev">Caller Saves</a>, Up: <a href="Stack-and-Calling.html#Stack-and-Calling" accesskey="u" rel="up">Stack and Calling</a> &nbsp; [<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>
  66. </div>
  67. <hr>
  68. <a name="Function-Entry-and-Exit"></a>
  69. <h4 class="subsection">17.9.11 Function Entry and Exit</h4>
  70. <a name="index-function-entry-and-exit"></a>
  71. <a name="index-prologue"></a>
  72. <a name="index-epilogue"></a>
  73. <p>This section describes the macros that output function entry
  74. (<em>prologue</em>) and exit (<em>epilogue</em>) code.
  75. </p>
  76. <dl>
  77. <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>, HOST_WIDE_INT <var>size</var>)</em></dt>
  78. <dd><p>If defined, a function that outputs the assembler code for entry to a
  79. function. The prologue is responsible for setting up the stack frame,
  80. initializing the frame pointer register, saving registers that must be
  81. saved, and allocating <var>size</var> additional bytes of storage for the
  82. local variables. <var>size</var> is an integer. <var>file</var> is a stdio
  83. stream to which the assembler code should be output.
  84. </p>
  85. <p>The label for the beginning of the function need not be output by this
  86. macro. That has already been done when the macro is run.
  87. </p>
  88. <a name="index-regs_005fever_005flive"></a>
  89. <p>To determine which registers to save, the macro can refer to the array
  90. <code>regs_ever_live</code>: element <var>r</var> is nonzero if hard register
  91. <var>r</var> is used anywhere within the function. This implies the function
  92. prologue should save register <var>r</var>, provided it is not one of the
  93. call-used registers. (<code>TARGET_ASM_FUNCTION_EPILOGUE</code> must likewise use
  94. <code>regs_ever_live</code>.)
  95. </p>
  96. <p>On machines that have &ldquo;register windows&rdquo;, the function entry code does
  97. not save on the stack the registers that are in the windows, even if
  98. they are supposed to be preserved by function calls; instead it takes
  99. appropriate steps to &ldquo;push&rdquo; the register stack, if any non-call-used
  100. registers are used in the function.
  101. </p>
  102. <a name="index-frame_005fpointer_005fneeded"></a>
  103. <p>On machines where functions may or may not have frame-pointers, the
  104. function entry code must vary accordingly; it must set up the frame
  105. pointer if one is wanted, and not otherwise. To determine whether a
  106. frame pointer is in wanted, the macro can refer to the variable
  107. <code>frame_pointer_needed</code>. The variable&rsquo;s value will be 1 at run
  108. time in a function that needs a frame pointer. See <a href="Elimination.html#Elimination">Elimination</a>.
  109. </p>
  110. <p>The function entry code is responsible for allocating any stack space
  111. required for the function. This stack space consists of the regions
  112. listed below. In most cases, these regions are allocated in the
  113. order listed, with the last listed region closest to the top of the
  114. stack (the lowest address if <code>STACK_GROWS_DOWNWARD</code> is defined, and
  115. the highest address if it is not defined). You can use a different order
  116. for a machine if doing so is more convenient or required for
  117. compatibility reasons. Except in cases where required by standard
  118. or by a debugger, there is no reason why the stack layout used by GCC
  119. need agree with that used by other compilers for a machine.
  120. </p></dd></dl>
  121. <dl>
  122. <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>
  123. <dd><p>If defined, a function that outputs assembler code at the end of a
  124. prologue. This should be used when the function prologue is being
  125. emitted as RTL, and you have some extra assembler that needs to be
  126. emitted. See <a href="Standard-Names.html#prologue-instruction-pattern">prologue instruction pattern</a>.
  127. </p></dd></dl>
  128. <dl>
  129. <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>
  130. <dd><p>If defined, a function that outputs assembler code at the start of an
  131. epilogue. This should be used when the function epilogue is being
  132. emitted as RTL, and you have some extra assembler that needs to be
  133. emitted. See <a href="Standard-Names.html#epilogue-instruction-pattern">epilogue instruction pattern</a>.
  134. </p></dd></dl>
  135. <dl>
  136. <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>, HOST_WIDE_INT <var>size</var>)</em></dt>
  137. <dd><p>If defined, a function that outputs the assembler code for exit from a
  138. function. The epilogue is responsible for restoring the saved
  139. registers and stack pointer to their values when the function was
  140. called, and returning control to the caller. This macro takes the
  141. same arguments as the macro <code>TARGET_ASM_FUNCTION_PROLOGUE</code>, and the
  142. registers to restore are determined from <code>regs_ever_live</code> and
  143. <code>CALL_USED_REGISTERS</code> in the same way.
  144. </p>
  145. <p>On some machines, there is a single instruction that does all the work
  146. of returning from the function. On these machines, give that
  147. instruction the name &lsquo;<samp>return</samp>&rsquo; and do not define the macro
  148. <code>TARGET_ASM_FUNCTION_EPILOGUE</code> at all.
  149. </p>
  150. <p>Do not define a pattern named &lsquo;<samp>return</samp>&rsquo; if you want the
  151. <code>TARGET_ASM_FUNCTION_EPILOGUE</code> to be used. If you want the target
  152. switches to control whether return instructions or epilogues are used,
  153. define a &lsquo;<samp>return</samp>&rsquo; pattern with a validity condition that tests the
  154. target switches appropriately. If the &lsquo;<samp>return</samp>&rsquo; pattern&rsquo;s validity
  155. condition is false, epilogues will be used.
  156. </p>
  157. <p>On machines where functions may or may not have frame-pointers, the
  158. function exit code must vary accordingly. Sometimes the code for these
  159. two cases is completely different. To determine whether a frame pointer
  160. is wanted, the macro can refer to the variable
  161. <code>frame_pointer_needed</code>. The variable&rsquo;s value will be 1 when compiling
  162. a function that needs a frame pointer.
  163. </p>
  164. <p>Normally, <code>TARGET_ASM_FUNCTION_PROLOGUE</code> and
  165. <code>TARGET_ASM_FUNCTION_EPILOGUE</code> must treat leaf functions specially.
  166. The C variable <code>current_function_is_leaf</code> is nonzero for such a
  167. function. See <a href="Leaf-Functions.html#Leaf-Functions">Leaf Functions</a>.
  168. </p>
  169. <p>On some machines, some functions pop their arguments on exit while
  170. others leave that for the caller to do. For example, the 68020 when
  171. given <samp>-mrtd</samp> pops arguments in functions that take a fixed
  172. number of arguments.
  173. </p>
  174. <a name="index-pops_005fargs"></a>
  175. <a name="index-crtl_002d_003eargs_002epops_005fargs"></a>
  176. <p>Your definition of the macro <code>RETURN_POPS_ARGS</code> decides which
  177. functions pop their own arguments. <code>TARGET_ASM_FUNCTION_EPILOGUE</code>
  178. needs to know what was decided. The number of bytes of the current
  179. function&rsquo;s arguments that this function should pop is available in
  180. <code>crtl-&gt;args.pops_args</code>. See <a href="Scalar-Return.html#Scalar-Return">Scalar Return</a>.
  181. </p></dd></dl>
  182. <ul>
  183. <li> <a name="index-pretend_005fargs_005fsize"></a>
  184. <a name="index-crtl_002d_003eargs_002epretend_005fargs_005fsize"></a>
  185. A region of <code>crtl-&gt;args.pretend_args_size</code> bytes of
  186. uninitialized space just underneath the first argument arriving on the
  187. stack. (This may not be at the very start of the allocated stack region
  188. if the calling sequence has pushed anything else since pushing the stack
  189. arguments. But usually, on such machines, nothing else has been pushed
  190. yet, because the function prologue itself does all the pushing.) This
  191. region is used on machines where an argument may be passed partly in
  192. registers and partly in memory, and, in some cases to support the
  193. features in <code>&lt;stdarg.h&gt;</code>.
  194. </li><li> An area of memory used to save certain registers used by the function.
  195. The size of this area, which may also include space for such things as
  196. the return address and pointers to previous stack frames, is
  197. machine-specific and usually depends on which registers have been used
  198. in the function. Machines with register windows often do not require
  199. a save area.
  200. </li><li> A region of at least <var>size</var> bytes, possibly rounded up to an allocation
  201. boundary, to contain the local variables of the function. On some machines,
  202. this region and the save area may occur in the opposite order, with the
  203. save area closer to the top of the stack.
  204. </li><li> <a name="index-ACCUMULATE_005fOUTGOING_005fARGS-and-stack-frames"></a>
  205. Optionally, when <code>ACCUMULATE_OUTGOING_ARGS</code> is defined, a region of
  206. <code>crtl-&gt;outgoing_args_size</code> bytes to be used for outgoing
  207. argument lists of the function. See <a href="Stack-Arguments.html#Stack-Arguments">Stack Arguments</a>.
  208. </li></ul>
  209. <dl>
  210. <dt><a name="index-EXIT_005fIGNORE_005fSTACK"></a>Macro: <strong>EXIT_IGNORE_STACK</strong></dt>
  211. <dd><p>Define this macro as a C expression that is nonzero if the return
  212. instruction or the function epilogue ignores the value of the stack
  213. pointer; in other words, if it is safe to delete an instruction to
  214. adjust the stack pointer before a return from the function. The
  215. default is 0.
  216. </p>
  217. <p>Note that this macro&rsquo;s value is relevant only for functions for which
  218. frame pointers are maintained. It is never safe to delete a final
  219. stack adjustment in a function that has no frame pointer, and the
  220. compiler knows this regardless of <code>EXIT_IGNORE_STACK</code>.
  221. </p></dd></dl>
  222. <dl>
  223. <dt><a name="index-EPILOGUE_005fUSES"></a>Macro: <strong>EPILOGUE_USES</strong> <em>(<var>regno</var>)</em></dt>
  224. <dd><p>Define this macro as a C expression that is nonzero for registers that are
  225. used by the epilogue or the &lsquo;<samp>return</samp>&rsquo; pattern. The stack and frame
  226. pointer registers are already assumed to be used as needed.
  227. </p></dd></dl>
  228. <dl>
  229. <dt><a name="index-EH_005fUSES"></a>Macro: <strong>EH_USES</strong> <em>(<var>regno</var>)</em></dt>
  230. <dd><p>Define this macro as a C expression that is nonzero for registers that are
  231. used by the exception handling mechanism, and so should be considered live
  232. on entry to an exception edge.
  233. </p></dd></dl>
  234. <dl>
  235. <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>
  236. <dd><p>A function that outputs the assembler code for a thunk
  237. function, used to implement C++ virtual function calls with multiple
  238. inheritance. The thunk acts as a wrapper around a virtual function,
  239. adjusting the implicit object parameter before handing control off to
  240. the real function.
  241. </p>
  242. <p>First, emit code to add the integer <var>delta</var> to the location that
  243. contains the incoming first argument. Assume that this argument
  244. contains a pointer, and is the one used to pass the <code>this</code> pointer
  245. in C++. This is the incoming argument <em>before</em> the function prologue,
  246. e.g. &lsquo;<samp>%o0</samp>&rsquo; on a sparc. The addition must preserve the values of
  247. all other incoming arguments.
  248. </p>
  249. <p>Then, if <var>vcall_offset</var> is nonzero, an additional adjustment should be
  250. made after adding <code>delta</code>. In particular, if <var>p</var> is the
  251. adjusted pointer, the following adjustment should be made:
  252. </p>
  253. <div class="smallexample">
  254. <pre class="smallexample">p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)]
  255. </pre></div>
  256. <p>After the additions, emit code to jump to <var>function</var>, which is a
  257. <code>FUNCTION_DECL</code>. This is a direct pure jump, not a call, and does
  258. not touch the return address. Hence returning from <var>FUNCTION</var> will
  259. return to whoever called the current &lsquo;<samp>thunk</samp>&rsquo;.
  260. </p>
  261. <p>The effect must be as if <var>function</var> had been called directly with
  262. the adjusted first argument. This macro is responsible for emitting all
  263. of the code for a thunk function; <code>TARGET_ASM_FUNCTION_PROLOGUE</code>
  264. and <code>TARGET_ASM_FUNCTION_EPILOGUE</code> are not invoked.
  265. </p>
  266. <p>The <var>thunk_fndecl</var> is redundant. (<var>delta</var> and <var>function</var>
  267. have already been extracted from it.) It might possibly be useful on
  268. some targets, but probably not.
  269. </p>
  270. <p>If you do not define this macro, the target-independent code in the C++
  271. front end will generate a less efficient heavyweight thunk that calls
  272. <var>function</var> instead of jumping to it. The generic approach does
  273. not support varargs.
  274. </p></dd></dl>
  275. <dl>
  276. <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>
  277. <dd><p>A function that returns true if TARGET_ASM_OUTPUT_MI_THUNK would be able
  278. to output the assembler code for the thunk function specified by the
  279. arguments it is passed, and false otherwise. In the latter case, the
  280. generic approach will be used by the C++ front end, with the limitations
  281. previously exposed.
  282. </p></dd></dl>
  283. <hr>
  284. <div class="header">
  285. <p>
  286. Next: <a href="Profiling.html#Profiling" accesskey="n" rel="next">Profiling</a>, Previous: <a href="Caller-Saves.html#Caller-Saves" accesskey="p" rel="prev">Caller Saves</a>, Up: <a href="Stack-and-Calling.html#Stack-and-Calling" accesskey="u" rel="up">Stack and Calling</a> &nbsp; [<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>
  287. </div>
  288. </body>
  289. </html>