From b2de4950df09c1ec47b1b19eff62745e86663204 Mon Sep 17 00:00:00 2001 From: Carlos O'Donell Date: Wed, 16 Mar 2016 05:00:58 +0000 Subject: [PATCH] Cleanup and expand on the 'leaf' function attribute documentation. Describe the problems that a user might face with indirect functions and ELF symbol interposition. gcc/ChangeLog: 2016-03-16 Carlos O'Donell Sandra Loosemore * doc/extend.texi (Common Function Attributes): Describe ifunc impact on leaf attribute. Mention ELF interposition problems. Co-Authored-By: Sandra Loosemore From-SVN: r234247 --- gcc/ChangeLog | 6 +++++ gcc/doc/extend.texi | 57 +++++++++++++++++++++++++++------------------ 2 files changed, 40 insertions(+), 23 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 7359f0b483e..68fcd05c07a 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,9 @@ +2016-03-16 Carlos O'Donell + Sandra Loosemore + + * doc/extend.texi (Common Function Attributes): Describe ifunc impact + on leaf attribute. Mention ELF interposition problems. + 2016-03-16 Alan Modra PR rtl-optimization/69195 diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index bdb43ba4ace..8fddb34a7e3 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2772,29 +2772,40 @@ refer to the following subsections for details. @item leaf @cindex @code{leaf} function attribute -Calls to external functions with this attribute must return to the current -compilation unit only by return or by exception handling. In particular, leaf -functions are not allowed to call callback function passed to it from the current -compilation unit or directly call functions exported by the unit or longjmp -into the unit. Leaf function might still call functions from other compilation -units and thus they are not necessarily leaf in the sense that they contain no -function calls at all. - -The attribute is intended for library functions to improve dataflow analysis. -The compiler takes the hint that any data not escaping the current compilation unit can -not be used or modified by the leaf function. For example, the @code{sin} function -is a leaf function, but @code{qsort} is not. - -Note that leaf functions might invoke signals and signal handlers might be -defined in the current compilation unit and use static variables. The only -compliant way to write such a signal handler is to declare such variables -@code{volatile}. - -The attribute has no effect on functions defined within the current compilation -unit. This is to allow easy merging of multiple compilation units into one, -for example, by using the link-time optimization. For this reason the -attribute is not allowed on types to annotate indirect calls. - +Calls to external functions with this attribute must return to the +current compilation unit only by return or by exception handling. In +particular, a leaf function is not allowed to invoke callback functions +passed to it from the current compilation unit, directly call functions +exported by the unit, or @code{longjmp} into the unit. Leaf functions +might still call functions from other compilation units and thus they +are not necessarily leaf in the sense that they contain no function +calls at all. + +The attribute is intended for library functions to improve dataflow +analysis. The compiler takes the hint that any data not escaping the +current compilation unit cannot be used or modified by the leaf +function. For example, the @code{sin} function is a leaf function, but +@code{qsort} is not. + +Note that leaf functions might indirectly run a signal handler defined +in the current compilation unit that uses static variables. Similarly, +when lazy symbol resolution is in effect, leaf functions might invoke +indirect functions whose resolver function or implementation function is +defined in the current compilation unit and uses static variables. There +is no standard-compliant way to write such a signal handler, resolver +function, or implementation function, and the best that you can do is to +remove the @code{leaf} attribute or mark all such static variables +@code{volatile}. Lastly, for ELF-based systems that support symbol +interposition, care should be taken that functions defined in the +current compilation unit do not unexpectedly interpose other symbols +based on the defined standards mode and defined feature test macros; +otherwise an inadvertent callback would be added. + +The attribute has no effect on functions defined within the current +compilation unit. This is to allow easy merging of multiple compilation +units into one, for example, by using the link-time optimization. For +this reason the attribute is not allowed on types to annotate indirect +calls. @item malloc @cindex @code{malloc} function attribute -- 2.30.2