gcc/doc/gccint/target-macros/support-for-nested-functions.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: support for nested functions, trampolines for nested functions, descriptors for nested functions, nested functions, support for
   7
   8 .. _trampolines:
   9
  10 Support for Nested Functions
  11 ****************************
  12
  13 Taking the address of a nested function requires special compiler
  14 handling to ensure that the static chain register is loaded when
  15 the function is invoked via an indirect call.
  16
  17 GCC has traditionally supported nested functions by creating an
  18 executable :dfn:`trampoline` at run time when the address of a nested
  19 function is taken.  This is a small piece of code which normally
  20 resides on the stack, in the stack frame of the containing function.
  21 The trampoline loads the static chain register and then jumps to the
  22 real address of the nested function.
  23
  24 The use of trampolines requires an executable stack, which is a
  25 security risk.  To avoid this problem, GCC also supports another
  26 strategy: using descriptors for nested functions.  Under this model,
  27 taking the address of a nested function results in a pointer to a
  28 non-executable function descriptor object.  Initializing the static chain
  29 from the descriptor is handled at indirect call sites.
  30
  31 On some targets, including HPPA and IA-64, function descriptors may be
  32 mandated by the ABI or be otherwise handled in a target-specific way
  33 by the back end in its code generation strategy for indirect calls.
  34 GCC also provides its own generic descriptor implementation to support the
  35 :option:`-fno-trampolines` option.  In this case runtime detection of
  36 function descriptors at indirect call sites relies on descriptor
  37 pointers being tagged with a bit that is never set in bare function
  38 addresses.  Since GCC's generic function descriptors are
  39 not ABI-compliant, this option is typically used only on a
  40 per-language basis (notably by Ada) or when it can otherwise be
  41 applied to the whole program.
  42
  43 For languages other than Ada, the ``-ftrampolines`` and
  44 ``-fno-trampolines`` options currently have no effect, and
  45 trampolines are always generated on platforms that need them
  46 for nested functions.
  47
  48 Define the following hook if your backend either implements ABI-specified
  49 descriptor support, or can use GCC's generic descriptor implementation
  50 for nested functions.
  51
  52 .. include:: tm.rst.in
  53   :start-after: [TARGET_CUSTOM_FUNCTION_DESCRIPTORS]
  54   :end-before: [TARGET_CUSTOM_FUNCTION_DESCRIPTORS]
  55
  56
  57 The following macros tell GCC how to generate code to allocate and
  58 initialize an executable trampoline.  You can also use this interface
  59 if your back end needs to create ABI-specified non-executable descriptors; in
  60 this case the "trampoline" created is the descriptor containing data only.
  61
  62 The instructions in an executable trampoline must do two things: load
  63 a constant address into the static chain register, and jump to the real
  64 address of the nested function.  On CISC machines such as the m68k,
  65 this requires two instructions, a move immediate and a jump.  Then the
  66 two addresses exist in the trampoline as word-long immediate operands.
  67 On RISC machines, it is often necessary to load each address into a
  68 register in two parts.  Then pieces of each address form separate
  69 immediate operands.
  70
  71 The code generated to initialize the trampoline must store the variable
  72 parts---the static chain value and the function address---into the
  73 immediate operands of the instructions.  On a CISC machine, this is
  74 simply a matter of copying each address to a memory reference at the
  75 proper offset from the start of the trampoline.  On a RISC machine, it
  76 may be necessary to take out pieces of the address and store them
  77 separately.
  78
  79 .. include:: tm.rst.in
  80   :start-after: [TARGET_ASM_TRAMPOLINE_TEMPLATE]
  81   :end-before: [TARGET_ASM_TRAMPOLINE_TEMPLATE]
  82
  83
  84 .. c:macro:: TRAMPOLINE_SECTION
  85
  86   Return the section into which the trampoline template is to be placed
  87   (see :ref:`sections`).  The default value is ``readonly_data_section``.
  88
  89 .. c:macro:: TRAMPOLINE_SIZE
  90
  91   A C expression for the size in bytes of the trampoline, as an integer.
  92
  93 .. c:macro:: TRAMPOLINE_ALIGNMENT
  94
  95   Alignment required for trampolines, in bits.
  96
  97   If you don't define this macro, the value of ``FUNCTION_ALIGNMENT``
  98   is used for aligning trampolines.
  99
 100 .. include:: tm.rst.in
 101   :start-after: [TARGET_TRAMPOLINE_INIT]
 102   :end-before: [TARGET_TRAMPOLINE_INIT]
 103
 104
 105 .. include:: tm.rst.in
 106   :start-after: [TARGET_EMIT_CALL_BUILTIN___CLEAR_CACHE]
 107   :end-before: [TARGET_EMIT_CALL_BUILTIN___CLEAR_CACHE]
 108
 109
 110 .. include:: tm.rst.in
 111   :start-after: [TARGET_TRAMPOLINE_ADJUST_ADDRESS]
 112   :end-before: [TARGET_TRAMPOLINE_ADJUST_ADDRESS]
 113
 114
 115 Implementing trampolines is difficult on many machines because they have
 116 separate instruction and data caches.  Writing into a stack location
 117 fails to clear the memory in the instruction cache, so when the program
 118 jumps to that location, it executes the old contents.
 119
 120 Here are two possible solutions.  One is to clear the relevant parts of
 121 the instruction cache whenever a trampoline is set up.  The other is to
 122 make all trampolines identical, by having them jump to a standard
 123 subroutine.  The former technique makes trampoline execution faster; the
 124 latter makes initialization faster.
 125
 126 To clear the instruction cache when a trampoline is initialized, define
 127 the following macro.
 128
 129 .. c:macro:: CLEAR_INSN_CACHE (beg, end)
 130
 131   If defined, expands to a C expression clearing the *instruction
 132   cache* in the specified interval.  The definition of this macro would
 133   typically be a series of ``asm`` statements.  Both :samp:`{beg}` and
 134   :samp:`{end}` are pointer expressions.
 135
 136 To use a standard subroutine, define the following macro.  In addition,
 137 you must make sure that the instructions in a trampoline fill an entire
 138 cache line with identical instructions, or else ensure that the
 139 beginning of the trampoline code is always aligned at the same point in
 140 its cache line.  Look in :samp:`m68k.h` as a guide.
 141
 142 .. c:macro:: TRANSFER_FROM_TRAMPOLINE
 143
 144   Define this macro if trampolines need a special subroutine to do their
 145   work.  The macro should expand to a series of ``asm`` statements
 146   which will be compiled with GCC.  They go in a library function named
 147   ``__transfer_from_trampoline``.
 148
 149   If you need to avoid executing the ordinary prologue code of a compiled
 150   C function when you jump to the subroutine, you can do so by placing a
 151   special label of your own in the assembler code.  Use one ``asm``
 152   statement to generate an assembler label, and another to make the label
 153   global.  Then trampolines can use that label to jump directly to your
 154   special assembler code.