visus
/
toolchain-gcc-arm-embedded


			
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2020 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 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Trampolines (GNU Compiler Collection (GCC) Internals)</title>

<meta name="description" content="Trampolines (GNU Compiler Collection (GCC) Internals)">
<meta name="keywords" content="Trampolines (GNU Compiler Collection (GCC) Internals)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<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="prev" title="Varargs">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
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.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<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="prev">Varargs</a>, Up: <a href="Target-Macros.html#Target-Macros" accesskey="u" rel="up">Target Macros</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>
</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&rsquo;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>Define the following hook if your backend either implements ABI-specified
descriptor support, or can use GCC&rsquo;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&rsquo;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 &quot;trampoline&quot; 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&mdash;the static chain value and the function address&mdash;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&mdash;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&rsquo;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 or
enabling stack execution, these actions should be performed after
initializing the trampoline proper.
</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 both 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="prev">Varargs</a>, Up: <a href="Target-Macros.html#Target-Macros" accesskey="u" rel="up">Target Macros</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>
</div>


</body>
</html>