A trampoline is a small piece of code that is created at run time when the address of a nested function is taken. It normally resides on the stack, in the stack frame of the containing function. These macros tell GCC how to generate code to allocate and initialize a trampoline.
The instructions in the 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.
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.
This hook is called by
assemble_trampoline_template to output,
on the stream f, 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.
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.
Return the section into which the trampoline template is to be placed
(see Sections). The default value is
A C expression for the size in bytes of the trampoline, as an integer.
Alignment required for trampolines, in bits.
If you don’t define this macro, the value of
is used for aligning trampolines.
This hook is called to initialize a trampoline.
m_tramp is an RTX for the memory block for the trampoline; fndecl
FUNCTION_DECL for the nested function; static_chain is an
RTX for the static chain value that should be passed to the function
when it is called.
If the target defines
TARGET_ASM_TRAMPOLINE_TEMPLATE, then the
first thing this hook should do is emit a block move into m_tramp
from the memory block returned by
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
TRAMPOLINE_SIZE bytes need be copied.
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.
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
TARGET_TRAMPOLINE_INIT. 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 addr should be returned unchanged.
If this hook is not defined, addr will be used for function calls.
This hook should be defined to a power of 2 if the target will benefit from the use of custom descriptors for nested functions instead of the standard trampolines. Such descriptors are created at run time on the stack and made up of data only, but they are non-standard so the generated code must be prepared to deal with them. This hook should be defined to 0 if the target uses function descriptors for its standard calling sequence, like for example HP-PA or IA-64. Using descriptors for nested functions eliminates the need for trampolines that reside on the stack and require it to be made executable.
The value of the macro is used to parameterize the run-time identification scheme implemented to distinguish descriptors from function addresses: it gives the number of bytes by which their address is misaligned compared with function addresses. The value of 1 will generally work, unless it is already reserved by the target for another purpose, like for example on ARM.
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.
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.
To clear the instruction cache when a trampoline is initialized, define the following macro.
If defined, expands to a C expression clearing the instruction
cache in the specified interval. The definition of this macro would
typically be a series of
asm statements. Both beg and
end are both pointer expressions.
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 m68k.h as a guide.
Define this macro if trampolines need a special subroutine to do their
work. The macro should expand to a series of
which will be compiled with GCC. They go in a library function named
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
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.