From c9aa0b93a8e39ee838eef9d86c3e2a27ed29df09 Mon Sep 17 00:00:00 2001 From: Sandra Loosemore Date: Fri, 1 Jan 2016 18:54:10 -0500 Subject: [PATCH] extend.texi (Common Function Attributes): Move to correct alphabetization of table. 2016-01-01 Sandra Loosemore gcc/ * doc/extend.texi (Common Function Attributes) : Move to correct alphabetization of table. Copy-edit and correct markup. : Likewise. : Likewise. : Likewise. * doc/invoke.texi (Optimize Options) <-fstack-protector-explicit>: Correct punctuation. (Code Gen Options) <-fno-plt>: Copy-edit. From-SVN: r232030 --- gcc/ChangeLog | 12 +++++ gcc/doc/extend.texi | 115 +++++++++++++++++++++++--------------------- gcc/doc/invoke.texi | 23 +++++---- 3 files changed, 83 insertions(+), 67 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 8b1fd2d3536..a19bbfecc21 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,15 @@ +2016-01-01 Sandra Loosemore + + * doc/extend.texi (Common Function Attributes) : Move + to correct alphabetization of table. Copy-edit and correct + markup. + : Likewise. + : Likewise. + : Likewise. + * doc/invoke.texi (Optimize Options) <-fstack-protector-explicit>: + Correct punctuation. + (Code Gen Options) <-fno-plt>: Copy-edit. + 2016-01-01 Bernd Edlinger PR target/68917 diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 65b6a96f1d6..0f36d4b1924 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2932,6 +2932,36 @@ my_memcpy (void *dest, const void *src, size_t len) __attribute__((nonnull)); @end smallexample +@item noplt +@cindex @code{noplt} function attribute +The @code{noplt} attribute is the counterpart to option @option{-fno-plt}. +Calls to functions marked with this attribute in position-independent code +do not use the PLT. + +@smallexample +@group +/* Externally defined function foo. */ +int foo () __attribute__ ((noplt)); + +int +main (/* @r{@dots{}} */) +@{ + /* @r{@dots{}} */ + foo (); + /* @r{@dots{}} */ +@} +@end group +@end smallexample + +The @code{noplt} attribute on function @code{foo} +tells the compiler to assume that +the function @code{foo} is externally defined and that the call to +@code{foo} must avoid the PLT +in position-independent code. + +In position-dependent code, a few targets also convert calls to +functions that are marked to not use the PLT to use the GOT instead. + @item noreturn @cindex @code{noreturn} function attribute @cindex functions that never return @@ -2977,35 +3007,6 @@ the standard C library can be guaranteed not to throw an exception with the notable exceptions of @code{qsort} and @code{bsearch} that take function pointer arguments. -@item noplt -@cindex @code{noplt} function attribute -The @code{noplt} attribute is the counterpart to option @option{-fno-plt} and -does not use PLT for calls to functions marked with this attribute in position -independent code. - -@smallexample -@group -/* Externally defined function foo. */ -int foo () __attribute__ ((noplt)); - -int -main (/* @r{@dots{}} */) -@{ - /* @r{@dots{}} */ - foo (); - /* @r{@dots{}} */ -@} -@end group -@end smallexample - -The @code{noplt} attribute on function foo tells the compiler to assume that -the function foo is externally defined and the call to foo must avoid the PLT -in position independent code. - -Additionally, a few targets also convert calls to those functions that are -marked to not use the PLT to use the GOT instead for non-position independent -code. - @item optimize @cindex @code{optimize} function attribute The @code{optimize} attribute is used to specify that a function is to @@ -3120,44 +3121,35 @@ with a copy that redefines NULL appropriately. The warnings for missing or incorrect sentinels are enabled with @option{-Wformat}. -@item stack_protect -@cindex @code{stack_protect} function attribute -This function attribute make a stack protection of the function if -flags @option{fstack-protector} or @option{fstack-protector-strong} -or @option{fstack-protector-explicit} are set. - -@item target_clones (@var{options}) -@cindex @code{target_clones} function attribute -The @code{target_clones} attribute is used to specify that a function is to -be cloned into multiple versions compiled with different target options -than specified on the command line. The supported options and restrictions -are the same as for @code{target} attribute. - -For instance on an x86, you could compile a function with -@code{target_clones("sse4.1,avx")}. It will create 2 function clones, -one compiled with @option{-msse4.1} and another with @option{-mavx}. -At the function call it will create resolver @code{ifunc}, that will -dynamically call a clone suitable for current architecture. - @item simd @itemx simd("@var{mask}") -@cindex @code{simd} function attribute. +@cindex @code{simd} function attribute This attribute enables creation of one or more function versions that can process multiple arguments using SIMD instructions from a single invocation. Specifying this attribute allows compiler to assume that such versions are available at link time (provided in the same or another translation unit). Generated versions are -target dependent and described in corresponding Vector ABI document. For +target-dependent and described in the corresponding Vector ABI document. For x86_64 target this document can be found @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}. + +The optional argument @var{mask} may have the value +@code{notinbranch} or @code{inbranch}, +and instructs the compiler to generate non-masked or masked +clones correspondingly. By default, all clones are generated. + The attribute should not be used together with Cilk Plus @code{vector} attribute on the same function. -If the attribute is specified and @code{#pragma omp declare simd} -present on a declaration and @code{-fopenmp} or @code{-fopenmp-simd} + +If the attribute is specified and @code{#pragma omp declare simd} is +present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd} switch is specified, then the attribute is ignored. -The optional argument @var{mask} may have "notinbranch" or "inbranch" -value and instructs the compiler to generate non-masked or masked -clones correspondingly. By default, all clones are generated. + +@item stack_protect +@cindex @code{stack_protect} function attribute +This attribute adds stack protection code to the function if +flags @option{-fstack-protector}, @option{-fstack-protector-strong} +or @option{-fstack-protector-explicit} are set. @item target (@var{options}) @cindex @code{target} function attribute @@ -3196,6 +3188,19 @@ Function Attributes}, @ref{PowerPC Function Attributes}, @ref{ARM Function Attributes},and @ref{Nios II Function Attributes}, for details. +@item target_clones (@var{options}) +@cindex @code{target_clones} function attribute +The @code{target_clones} attribute is used to specify that a function +be cloned into multiple versions compiled with different target options +than specified on the command line. The supported options and restrictions +are the same as for @code{target} attribute. + +For instance, on an x86, you could compile a function with +@code{target_clones("sse4.1,avx")}. GCC creates two function clones, +one compiled with @option{-msse4.1} and another with @option{-mavx}. +It also creates a resolver function (see the @code{ifunc} attribute +above) that dynamically selects a clone suitable for current architecture. + @item unused @cindex @code{unused} function attribute This attribute, attached to a function, means that the function is meant diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index b85f9b5942d..178c530b169 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -10284,7 +10284,7 @@ references to local frame addresses. @item -fstack-protector-explicit @opindex fstack-protector-explicit Like @option{-fstack-protector} but only protects those functions which -have the @code{stack_protect} attribute +have the @code{stack_protect} attribute. @item -fstdarg-opt @opindex fstdarg-opt @@ -24418,21 +24418,20 @@ for @option{-fpie} and 2 for @option{-fPIE}. @item -fno-plt @opindex fno-plt -Do not use PLT for external function calls in position-independent code. -Instead, load callee address at call site from GOT and branch to it. +Do not use the PLT for external function calls in position-independent code. +Instead, load the callee address at call sites from the GOT and branch to it. This leads to more efficient code by eliminating PLT stubs and exposing -GOT load to optimizations. On architectures such as 32-bit x86 where -PLT stubs expect GOT pointer in a specific register, this gives more -register allocation freedom to the compiler. Lazy binding requires PLT: +GOT loads to optimizations. On architectures such as 32-bit x86 where +PLT stubs expect the GOT pointer in a specific register, this gives more +register allocation freedom to the compiler. +Lazy binding requires use of the PLT; with @option{-fno-plt} all external symbols are resolved at load time. -Alternatively, function attribute @code{noplt} can be used to avoid PLT -for calls to specific external functions by marking those functions with -this attribute. +Alternatively, the function attribute @code{noplt} can be used to avoid calls +through the PLT for specific external functions. -Additionally, a few targets also convert calls to those functions that are -marked to not use the PLT to use the GOT instead for non-position independent -code. +In position-dependent code, a few targets also convert calls to +functions that are marked to not use the PLT to use the GOT instead. @item -fno-jump-tables @opindex fno-jump-tables