From d2bfc447e80b028f860149439e48544d967af685 Mon Sep 17 00:00:00 2001 From: Martin Sebor Date: Tue, 30 Oct 2018 15:46:07 +0000 Subject: [PATCH] extend.texi (optimize): Clarify/expand attribute documentation. gcc/ChangeLog: * doc/extend.texi (optimize): Clarify/expand attribute documentation. (target, pragma GCC optimize, pragma GCC target): Ditto. From-SVN: r265631 --- gcc/ChangeLog | 5 +++ gcc/doc/extend.texi | 86 +++++++++++++++++++++++++++------------------ 2 files changed, 57 insertions(+), 34 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index af5e1542618..851502e5ba0 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,8 @@ +2018-10-30 Martin Sebor + + * doc/extend.texi (optimize): Clarify/expand attribute documentation. + (target, pragma GCC optimize, pragma GCC target): Ditto. + 2018-10-30 Jonathan Wakely * doc/extend.texi: Fix prototype and description of diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 4dbb2da39e4..e2b9ee11a54 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -3193,21 +3193,32 @@ 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 optimize +@item optimize (@var{level}, @dots{}) +@item optimize (@var{string}, @dots{}) @cindex @code{optimize} function attribute The @code{optimize} attribute is used to specify that a function is to be compiled with different optimization options than specified on the -command line. Arguments can either be numbers or strings. Numbers -are assumed to be an optimization level. Strings that begin with -@code{O} are assumed to be an optimization option, while other options -are assumed to be used with a @code{-f} prefix. You can also use the -@samp{#pragma GCC optimize} pragma to set the optimization options -that affect more than one function. -@xref{Function Specific Option Pragmas}, for details about the -@samp{#pragma GCC optimize} pragma. - -This attribute should be used for debugging purposes only. It is not -suitable in production code. +command line. Valid arguments are constant non-negative integers and +strings. Each numeric argument specifies an optimization @var{level}. +Each @var{string} argument consists of one or more comma-separated +substrings. Each substring that begins with the letter @code{O} refers +to an optimization option such as @option{-O0} or @option{-Os}. Other +substrings are taken as suffixes to the @code{-f} prefix jointly +forming the name of an optimization option. @xref{Optimize Options}. + +@samp{#pragma GCC optimize} can be used to set optimization options +for more than one function. @xref{Function Specific Option Pragmas}, +for details about the pragma. + +Providing multiple strings as arguments separated by commas to specify +multiple options is equivalent to separating the option suffixes with +a comma (@samp{,}) within a single string. Spaces are not permitted +within the strings. + +Not every optimization option that starts with the @var{-f} prefix +specified by the attribute necessarily has an effect on the function. +The @code{optimize} attribute should be used for debugging purposes only. +It is not suitable in production code. @item patchable_function_entry @cindex @code{patchable_function_entry} function attribute @@ -3361,17 +3372,21 @@ 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}) +@item target (@var{string}, @dots{}) @cindex @code{target} function attribute Multiple target back ends implement the @code{target} attribute to specify that a function is to be compiled with different target options than specified on the -command line. This can be used for instance to have functions +command line. One or more strings can be provided as arguments. +Each string consists of one or more comma-separated suffixes to +the @code{-m} prefix jointly forming the name of a machine-dependent +option. @xref{Submodel Options,,Machine-Dependent Options}. + +The @code{target} attribute can be used for instance to have a function compiled with a different ISA (instruction set architecture) than the -default. You can also use the @samp{#pragma GCC target} pragma to set -more than one function to be compiled with specific target options. -@xref{Function Specific Option Pragmas}, for details about the -@samp{#pragma GCC target} pragma. +default. @samp{#pragma GCC target} can be used to specify target-specific +options for more than one function. @xref{Function Specific Option Pragmas}, +for details about the pragma. For instance, on an x86, you could declare one function with the @code{target("sse4.1,arch=core2")} attribute and another with @@ -3389,9 +3404,10 @@ int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); int sse3_func (void) __attribute__ ((__target__ ("sse3"))); @end smallexample -You can either use multiple -strings separated by commas to specify multiple options, -or separate the options with a comma (@samp{,}) within a single string. +Providing multiple strings as arguments separated by commas to specify +multiple options is equivalent to separating the option suffixes with +a comma (@samp{,}) within a single string. Spaces are not permitted +within the strings. The options supported are specific to each target; refer to @ref{x86 Function Attributes}, @ref{PowerPC Function Attributes}, @@ -22404,30 +22420,32 @@ push_macro} and restored by @code{#pragma pop_macro}. @subsection Function Specific Option Pragmas @table @code -@item #pragma GCC target (@var{"string"}...) +@item #pragma GCC target (@var{string}, @dots{}) @cindex pragma GCC target -This pragma allows you to set target specific options for functions +This pragma allows you to set target-specific options for functions defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is as -if @code{attribute((target("STRING")))} was specified for that -function. The parenthesis around the options is optional. -@xref{Function Attributes}, for more information about the -@code{target} attribute and the attribute syntax. +specified. Each function that is defined after this point is treated +as if it had been declared with one @code{target(}@var{string}@code{)} +attribute for each @var{string} argument. The parentheses around +the strings in the pragma are optional. @xref{Function Attributes}, +for more information about the @code{target} attribute and the attribute +syntax. The @code{#pragma GCC target} pragma is presently implemented for x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. -@item #pragma GCC optimize (@var{"string"}...) +@item #pragma GCC optimize (@var{string}, @dots{}) @cindex pragma GCC optimize This pragma allows you to set global optimization options for functions defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is as -if @code{attribute((optimize("STRING")))} was specified for that -function. The parenthesis around the options is optional. -@xref{Function Attributes}, for more information about the -@code{optimize} attribute and the attribute syntax. +specified. Each function that is defined after this point is treated +as if it had been declared with one @code{optimize(}@var{string}@code{)} +attribute for each @var{string} argument. The parentheses around +the strings in the pragma are optional. @xref{Function Attributes}, +for more information about the @code{optimize} attribute and the attribute +syntax. @item #pragma GCC push_options @itemx #pragma GCC pop_options -- 2.30.2