git
/
gcc
mirror of git://gcc.gnu.org/git/gcc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

target.def (custom_function_descriptors): Improve documentation. 

2018-08-30  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* target.def (custom_function_descriptors): Improve documentation.
	* doc/tm.texi.in (Trampolines): Expand discussion of function
	descriptors and move TARGET_CUSTOM_FUNCTION_DESCRIPTORS to the
	beginning of the section.
	* doc/tm.texi: Regenerated.

From-SVN: r263999
This commit is contained in:
Sandra Loosemore 2018-08-30 17:02:37 -04:00 committed by Sandra Loosemore
parent 429331b676
commit 92b6df436d
4 changed files with 144 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
gcc/ChangeLog
View File

@ -1,3 +1,11 @@
2018-08-30 Sandra Loosemore <sandra@codesourcery.com>
* target.def (custom_function_descriptors): Improve documentation.
* doc/tm.texi.in (Trampolines): Expand discussion of function
descriptors and move TARGET_CUSTOM_FUNCTION_DESCRIPTORS to the
beginning of the section.
* doc/tm.texi: Regenerated.
2018-08-30 Jose E. Marchesi <jose.marchesi@oracle.com>
* cfg.h (class auto_edge_flag): Spell out the template-id of the

102
gcc/doc/tm.texi
View File

@ -5267,24 +5267,78 @@ into the stack. Arguments meaning is similar to
@end deftypefn
@node Trampolines
@section Trampolines for Nested Functions
@section Support for Nested Functions
@cindex support for nested functions
@cindex trampolines for nested functions
@cindex nested functions, trampolines for
@cindex descriptors for nested functions
@cindex nested functions, support for
A @dfn{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.
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.
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.
GCC has traditionally supported nested functions by creating an
executable @dfn{trampoline} 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.
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.
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
@option{-fno-trampolines} 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.
Define the following hook if your backend either implements ABI-specified
descriptor support, or can use GCC's generic descriptor implementation
for nested functions.
@deftypevr {Target Hook} int TARGET_CUSTOM_FUNCTION_DESCRIPTORS
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.
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.
Using descriptors for nested functions
eliminates the need for trampolines that reside on the stack and require
it to be made executable.
@end deftypevr
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.
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.
The code generated to initialize the trampoline must store the variable
parts---the static chain value and the function address---into the
@ -5351,24 +5405,6 @@ be returned; otherwise @var{addr} should be returned unchanged.
If this hook is not defined, @var{addr} will be used for function calls.
@end deftypefn
@deftypevr {Target Hook} int TARGET_CUSTOM_FUNCTION_DESCRIPTORS
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.
@end deftypevr
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

69
gcc/doc/tm.texi.in
View File

@ -3766,24 +3766,61 @@ These machine description macros help implement varargs:
@hook TARGET_SETUP_INCOMING_VARARG_BOUNDS
@node Trampolines
@section Trampolines for Nested Functions
@section Support for Nested Functions
@cindex support for nested functions
@cindex trampolines for nested functions
@cindex nested functions, trampolines for
@cindex descriptors for nested functions
@cindex nested functions, support for
A @dfn{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.
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.
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.
GCC has traditionally supported nested functions by creating an
executable @dfn{trampoline} 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.
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.
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
@option{-fno-trampolines} 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.
Define the following hook if your backend either implements ABI-specified
descriptor support, or can use GCC's generic descriptor implementation
for nested functions.
@hook TARGET_CUSTOM_FUNCTION_DESCRIPTORS
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.
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.
The code generated to initialize the trampoline must store the variable
parts---the static chain value and the function address---into the
@ -3815,8 +3852,6 @@ is used for aligning trampolines.
@hook TARGET_TRAMPOLINE_ADJUST_ADDRESS
@hook TARGET_CUSTOM_FUNCTION_DESCRIPTORS
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

29
gcc/target.def
View File

@ -4985,21 +4985,22 @@ If this hook is not defined, @var{addr} will be used for function calls.",
DEFHOOKPOD
(custom_function_descriptors,
"This hook should be defined to a power of 2 if the target will benefit\n\
from the use of custom descriptors for nested functions instead of the\n\
standard trampolines. Such descriptors are created at run time on the\n\
stack and made up of data only, but they are non-standard so the generated\n\
code must be prepared to deal with them. This hook should be defined to 0\n\
if the target uses function descriptors for its standard calling sequence,\n\
like for example HP-PA or IA-64. Using descriptors for nested functions\n\
eliminates the need for trampolines that reside on the stack and require\n\
it to be made executable.\n\
"If the target can use GCC's generic descriptor mechanism for nested\n\
functions, define this hook to a power of 2 representing an unused bit\n\
in function pointers which can be used to differentiate descriptors at\n\
run time. This value gives the number of bytes by which descriptor\n\
pointers are misaligned compared to function pointers. For example, on\n\
targets that require functions to be aligned to a 4-byte boundary, a\n\
value of either 1 or 2 is appropriate unless the architecture already\n\
reserves the bit for another purpose, such as on ARM.\n\
\n\
The value of the macro is used to parameterize the run-time identification\n\
scheme implemented to distinguish descriptors from function addresses: it\n\
gives the number of bytes by which their address is misaligned compared\n\
with function addresses. The value of 1 will generally work, unless it is\n\
already reserved by the target for another purpose, like for example on ARM.",\
Define this hook to 0 if the target implements ABI support for\n\
function descriptors in its standard calling sequence, like for example\n\
HPPA or IA-64.\n\
\n\
Using descriptors for nested functions\n\
eliminates the need for trampolines that reside on the stack and require\n\
it to be made executable.",\
int, -1)
/* Return the number of bytes of its own arguments that a function