diff options
Diffstat (limited to 'share/doc/gccint/Trampolines.html')
| -rw-r--r-- | share/doc/gccint/Trampolines.html | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/share/doc/gccint/Trampolines.html b/share/doc/gccint/Trampolines.html new file mode 100644 index 0000000..183a8ee --- /dev/null +++ b/share/doc/gccint/Trampolines.html @@ -0,0 +1,294 @@ +<!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: Trampolines</title> + +<meta name="description" content="GNU Compiler Collection (GCC) Internals: Trampolines"> +<meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Trampolines"> +<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="Target-Macros.html#Target-Macros" rel="up" title="Target Macros"> +<link href="Library-Calls.html#Library-Calls" rel="next" title="Library Calls"> +<link href="Varargs.html#Varargs" rel="previous" title="Varargs"> +<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="Trampolines"></a> +<div class="header"> +<p> +Next: <a href="Library-Calls.html#Library-Calls" accesskey="n" rel="next">Library Calls</a>, Previous: <a href="Varargs.html#Varargs" accesskey="p" rel="previous">Varargs</a>, Up: <a href="Target-Macros.html#Target-Macros" accesskey="u" rel="up">Target Macros</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="Support-for-Nested-Functions"></a> +<h3 class="section">18.11 Support for Nested Functions</h3> +<a name="index-support-for-nested-functions"></a> +<a name="index-trampolines-for-nested-functions"></a> +<a name="index-descriptors-for-nested-functions"></a> +<a name="index-nested-functions_002c-support-for"></a> + +<p>Taking the address of a nested function requires special compiler +handling to ensure that the static chain register is loaded when +the function is invoked via an indirect call. +</p> +<p>GCC has traditionally supported nested functions by creating an +executable <em>trampoline</em> at run time when the address of a nested +function is taken. This is a small piece of code which normally +resides on the stack, in the stack frame of the containing function. +The trampoline loads the static chain register and then jumps to the +real address of the nested function. +</p> +<p>The use of trampolines requires an executable stack, which is a +security risk. To avoid this problem, GCC also supports another +strategy: using descriptors for nested functions. Under this model, +taking the address of a nested function results in a pointer to a +non-executable function descriptor object. Initializing the static chain +from the descriptor is handled at indirect call sites. +</p> +<p>On some targets, including HPPA and IA-64, function descriptors may be +mandated by the ABI or be otherwise handled in a target-specific way +by the back end in its code generation strategy for indirect calls. +GCC also provides its own generic descriptor implementation to support the +<samp>-fno-trampolines</samp> option. In this case runtime detection of +function descriptors at indirect call sites relies on descriptor +pointers being tagged with a bit that is never set in bare function +addresses. Since GCC’s generic function descriptors are +not ABI-compliant, this option is typically used only on a +per-language basis (notably by Ada) or when it can otherwise be +applied to the whole program. +</p> +<p>For languages other than Ada, the <code>-ftrampolines</code> and +<code>-fno-trampolines</code> options currently have no effect, and +trampolines are always generated on platforms that need them +for nested functions. +</p> +<p>Define the following hook if your backend either implements ABI-specified +descriptor support, or can use GCC’s generic descriptor implementation +for nested functions. +</p> +<dl> +<dt><a name="index-TARGET_005fCUSTOM_005fFUNCTION_005fDESCRIPTORS"></a>Target Hook: <em>int</em> <strong>TARGET_CUSTOM_FUNCTION_DESCRIPTORS</strong></dt> +<dd><p>If the target can use GCC’s generic descriptor mechanism for nested +functions, define this hook to a power of 2 representing an unused bit +in function pointers which can be used to differentiate descriptors at +run time. This value gives the number of bytes by which descriptor +pointers are misaligned compared to function pointers. For example, on +targets that require functions to be aligned to a 4-byte boundary, a +value of either 1 or 2 is appropriate unless the architecture already +reserves the bit for another purpose, such as on ARM. +</p> +<p>Define this hook to 0 if the target implements ABI support for +function descriptors in its standard calling sequence, like for example +HPPA or IA-64. +</p> +<p>Using descriptors for nested functions +eliminates the need for trampolines that reside on the stack and require +it to be made executable. +</p></dd></dl> + +<p>The following macros tell GCC how to generate code to allocate and +initialize an executable trampoline. You can also use this interface +if your back end needs to create ABI-specified non-executable descriptors; in +this case the "trampoline" created is the descriptor containing data only. +</p> +<p>The instructions in an executable trampoline must do two things: load +a constant address into the static chain register, and jump to the real +address of the nested function. On CISC machines such as the m68k, +this requires two instructions, a move immediate and a jump. Then the +two addresses exist in the trampoline as word-long immediate operands. +On RISC machines, it is often necessary to load each address into a +register in two parts. Then pieces of each address form separate +immediate operands. +</p> +<p>The code generated to initialize the trampoline must store the variable +parts—the static chain value and the function address—into the +immediate operands of the instructions. On a CISC machine, this is +simply a matter of copying each address to a memory reference at the +proper offset from the start of the trampoline. On a RISC machine, it +may be necessary to take out pieces of the address and store them +separately. +</p> +<dl> +<dt><a name="index-TARGET_005fASM_005fTRAMPOLINE_005fTEMPLATE"></a>Target Hook: <em>void</em> <strong>TARGET_ASM_TRAMPOLINE_TEMPLATE</strong> <em>(FILE *<var>f</var>)</em></dt> +<dd><p>This hook is called by <code>assemble_trampoline_template</code> to output, +on the stream <var>f</var>, assembler code for a block of data that contains +the constant parts of a trampoline. This code should not include a +label—the label is taken care of automatically. +</p> +<p>If you do not define this hook, it means no template is needed +for the target. Do not define this hook on systems where the block move +code to copy the trampoline into place would be larger than the code +to generate it on the spot. +</p></dd></dl> + +<dl> +<dt><a name="index-TRAMPOLINE_005fSECTION"></a>Macro: <strong>TRAMPOLINE_SECTION</strong></dt> +<dd><p>Return the section into which the trampoline template is to be placed +(see <a href="Sections.html#Sections">Sections</a>). The default value is <code>readonly_data_section</code>. +</p></dd></dl> + +<dl> +<dt><a name="index-TRAMPOLINE_005fSIZE"></a>Macro: <strong>TRAMPOLINE_SIZE</strong></dt> +<dd><p>A C expression for the size in bytes of the trampoline, as an integer. +</p></dd></dl> + +<dl> +<dt><a name="index-TRAMPOLINE_005fALIGNMENT"></a>Macro: <strong>TRAMPOLINE_ALIGNMENT</strong></dt> +<dd><p>Alignment required for trampolines, in bits. +</p> +<p>If you don’t define this macro, the value of <code>FUNCTION_ALIGNMENT</code> +is used for aligning trampolines. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fTRAMPOLINE_005fINIT"></a>Target Hook: <em>void</em> <strong>TARGET_TRAMPOLINE_INIT</strong> <em>(rtx <var>m_tramp</var>, tree <var>fndecl</var>, rtx <var>static_chain</var>)</em></dt> +<dd><p>This hook is called to initialize a trampoline. +<var>m_tramp</var> is an RTX for the memory block for the trampoline; <var>fndecl</var> +is the <code>FUNCTION_DECL</code> for the nested function; <var>static_chain</var> is an +RTX for the static chain value that should be passed to the function +when it is called. +</p> +<p>If the target defines <code>TARGET_ASM_TRAMPOLINE_TEMPLATE</code>, then the +first thing this hook should do is emit a block move into <var>m_tramp</var> +from the memory block returned by <code>assemble_trampoline_template</code>. +Note that the block move need only cover the constant parts of the +trampoline. If the target isolates the variable parts of the trampoline +to the end, not all <code>TRAMPOLINE_SIZE</code> bytes need be copied. +</p> +<p>If the target requires any other actions, such as flushing caches +(possibly calling function maybe_emit_call_builtin___clear_cache) or +enabling stack execution, these actions should be performed after +initializing the trampoline proper. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fEMIT_005fCALL_005fBUILTIN_005f_005f_005fCLEAR_005fCACHE"></a>Target Hook: <em>void</em> <strong>TARGET_EMIT_CALL_BUILTIN___CLEAR_CACHE</strong> <em>(rtx <var>begin</var>, rtx <var>end</var>)</em></dt> +<dd><p>On targets that do not define a <code>clear_cache</code> insn expander, +but that define the <code>CLEAR_CACHE_INSN</code> macro, +maybe_emit_call_builtin___clear_cache relies on this target hook +to clear an address range in the instruction cache. +</p> +<p>The default implementation calls the <code>__clear_cache</code> builtin, +taking the assembler name from the builtin declaration. Overriding +definitions may call alternate functions, with alternate calling +conventions, or emit alternate RTX to perform the job. +</p></dd></dl> + +<dl> +<dt><a name="index-TARGET_005fTRAMPOLINE_005fADJUST_005fADDRESS"></a>Target Hook: <em>rtx</em> <strong>TARGET_TRAMPOLINE_ADJUST_ADDRESS</strong> <em>(rtx <var>addr</var>)</em></dt> +<dd><p>This hook should perform any machine-specific adjustment in +the address of the trampoline. Its argument contains the address of the +memory block that was passed to <code>TARGET_TRAMPOLINE_INIT</code>. In case +the address to be used for a function call should be different from the +address at which the template was stored, the different address should +be returned; otherwise <var>addr</var> should be returned unchanged. +If this hook is not defined, <var>addr</var> will be used for function calls. +</p></dd></dl> + +<p>Implementing trampolines is difficult on many machines because they have +separate instruction and data caches. Writing into a stack location +fails to clear the memory in the instruction cache, so when the program +jumps to that location, it executes the old contents. +</p> +<p>Here are two possible solutions. One is to clear the relevant parts of +the instruction cache whenever a trampoline is set up. The other is to +make all trampolines identical, by having them jump to a standard +subroutine. The former technique makes trampoline execution faster; the +latter makes initialization faster. +</p> +<p>To clear the instruction cache when a trampoline is initialized, define +the following macro. +</p> +<dl> +<dt><a name="index-CLEAR_005fINSN_005fCACHE"></a>Macro: <strong>CLEAR_INSN_CACHE</strong> <em>(<var>beg</var>, <var>end</var>)</em></dt> +<dd><p>If defined, expands to a C expression clearing the <em>instruction +cache</em> in the specified interval. The definition of this macro would +typically be a series of <code>asm</code> statements. Both <var>beg</var> and +<var>end</var> are pointer expressions. +</p></dd></dl> + +<p>To use a standard subroutine, define the following macro. In addition, +you must make sure that the instructions in a trampoline fill an entire +cache line with identical instructions, or else ensure that the +beginning of the trampoline code is always aligned at the same point in +its cache line. Look in <samp>m68k.h</samp> as a guide. +</p> +<dl> +<dt><a name="index-TRANSFER_005fFROM_005fTRAMPOLINE"></a>Macro: <strong>TRANSFER_FROM_TRAMPOLINE</strong></dt> +<dd><p>Define this macro if trampolines need a special subroutine to do their +work. The macro should expand to a series of <code>asm</code> statements +which will be compiled with GCC. They go in a library function named +<code>__transfer_from_trampoline</code>. +</p> +<p>If you need to avoid executing the ordinary prologue code of a compiled +C function when you jump to the subroutine, you can do so by placing a +special label of your own in the assembler code. Use one <code>asm</code> +statement to generate an assembler label, and another to make the label +global. Then trampolines can use that label to jump directly to your +special assembler code. +</p></dd></dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Library-Calls.html#Library-Calls" accesskey="n" rel="next">Library Calls</a>, Previous: <a href="Varargs.html#Varargs" accesskey="p" rel="previous">Varargs</a>, Up: <a href="Target-Macros.html#Target-Macros" accesskey="u" rel="up">Target Macros</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> |