* [PATCH v2] docs: Update function multiversioning documentation
@ 2024-04-30 16:10 Andrew Carlotti
2024-05-06 11:31 ` [PING gcc-14?][PATCH " Andrew Carlotti
2024-06-10 16:08 ` [PING][PATCH " Andrew Carlotti
0 siblings, 2 replies; 6+ messages in thread
From: Andrew Carlotti @ 2024-04-30 16:10 UTC (permalink / raw)
To: gcc-patches
Cc: Richard Biener, Richard Sandiford, Michael Meissner,
Sandra Loosemore, Jakub Jelinek
Add target_version attribute to Common Function Attributes and update
target and target_clones documentation. Move shared detail and examples
to the Function Multiversioning page. Add target-specific details to
target-specific pages.
---
Changes since v1:
- Various typo fixes.
- Reordered content in 'Function multiversioning' section to put implementation
details at the end (as suggested in review).
- Dropped links to outdated wiki page, and a couple of other unhelpful
sentences that the previous version preserved.
I've built and rechecked the info output. Ok for master? And is this ok for
the GCC-14 branch too?
gcc/ChangeLog:
* doc/extend.texi (Common Function Attributes): Update target
and target_clones documentation, and add target_version.
(AArch64 Function Attributes): Add ACLE reference and list
supported features.
(PowerPC Function Attributes): List supported features.
(x86 Function Attributes): Mention function multiversioning.
(Function Multiversioning): Update, and move shared detail here.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index e290265d68d33f86a7e7ee9882cc0fd6bed00143..fefac70b5fffc350bf23db74a8fc88fa3bb99bd5 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -4178,17 +4178,16 @@ and @option{-Wanalyzer-tainted-size}.
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. The original target command-line options are ignored.
-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}.
-
+command line. One or more strings can be provided as arguments.
The @code{target} attribute can be used for instance to have a function
compiled with a different ISA (instruction set architecture) than the
-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.
+default.
+
+The options supported by the @code{target} attribute are specific to each
+target; refer to @ref{x86 Function Attributes}, @ref{PowerPC Function
+Attributes}, @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
+@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
+for details.
For instance, on an x86, you could declare one function with the
@code{target("sse4.1,arch=core2")} attribute and another with
@@ -4211,39 +4210,26 @@ 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},
-@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
-@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
-for details.
+@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.
+
+On x86, the @code{target} attribute can also be used to create multiple
+versions of a function, compiled with different target-specific options.
+@xref{Function Multiversioning} for more details.
@cindex @code{target_clones} function attribute
@item target_clones (@var{options})
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}.
-
-On a PowerPC, you can compile a function with
-@code{target_clones("cpu=power9,default")}. GCC will create two
-function clones, one compiled with @option{-mcpu=power9} and another
-with the default options. GCC must be configured to use GLIBC 2.23 or
-newer in order to use the @code{target_clones} attribute.
-
-It also creates a resolver function (see
-the @code{ifunc} attribute above) that dynamically selects a clone
-suitable for current architecture. The resolver is created only if there
-is a usage of a function with @code{target_clones} attribute.
-
-Note that any subsequent call of a function without @code{target_clone}
-from a @code{target_clone} caller will not lead to copying
-(target clone) of the called function.
-If you want to enforce such behaviour,
-we recommend declaring the calling function with the @code{flatten} attribute?
+should be cloned into multiple versions compiled with different target options
+than specified on the command line. @xref{Function Multiversioning} for more
+details.
+
+@cindex @code{target_version} function attribute
+@item target_version (@var{options})
+The @code{target_version} attribute is used on AArch64 to create multiple
+versions of a function, compiled with different target-specific options.
+@xref{Function Multiversioning} for more details.
@cindex @code{unavailable} function attribute
@item unavailable
@@ -4734,6 +4720,26 @@ Note that CPU tuning options and attributes such as the @option{-mcpu=},
@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
architectural feature rules specified above.
+@subsubsection Function multiversioning
+The @code{target_version} and @code{target_clones} attributes can be used to
+specify multiple versions of a function. Each version enables the specified
+set of architecture extensions, in addition to any extensions that were already
+enabled at the command line or using @code{target} attributes. For general
+details, @pxref{Function Multiversioning}. There are further AArch64-specific
+details available in the
+@uref{https://github.com/ARM-software/acle/blob/main/main/acle.md#function-multi-versioning,
+Arm C Language Extensions (ACLE) specification}.
+
+Some aspects of the ACLE specification are not yet supported. In particular,
+the currently supported feature names are @code{rng}, @code{flagm}, @code{lse},
+@code{fp}, @code{simd}, @code{dotprod}, @code{sm4}, @code{rdma}, @code{rdm}
+(alias of @code{rdma}), @code{crc}, @code{sha2}, @code{sha3}, @code{aes},
+@code{fp16}, @code{fp16fml}, @code{rcpc}, @code{rcpc3}, @code{i8mm},
+@code{bf16}, @code{sve}, @code{f32mm}, @code{f64mm}, @code{sve2},
+@code{sve2-aes}, @code{sve2-bitperm}, @code{sve2-sha3}, @code{sve2-sm4},
+@code{sme}, @code{sb}, @code{predres}, @code{sme-f64f64}, @code{sme-i16i64} and
+@code{sme2}.
+
@node AMD GCN Function Attributes
@subsection AMD GCN Function Attributes
@@ -6278,6 +6284,15 @@ default tuning specified on the command line.
On the PowerPC, the inliner does not inline a
function that has different target options than the caller, unless the
callee has a subset of the target options of the caller.
+
+@cindex @code{target_clones} function attribute
+@item target_clones (@var{options})
+The @code{target_clones} attribute can be used to create multiple versions of a
+function for different supported architectures, with one version for each
+specifier in the options list. One of these version specifiers must be the
+@code{default} version. The other supported target specifiers are
+@code{cpu=power6}, @code{cpu=power7}, @code{cpu=power8}, @code{cpu=power9} and
+@code{cpu=power10}. For more details, @pxref{Function Multiversioning}.
@end table
@node RISC-V Function Attributes
@@ -6872,7 +6887,9 @@ will crash if the wrong kind of handler is used.
@cindex @code{target} function attribute
@item target (@var{options})
As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
+allows specification of target-specific compilation options. It can also be
+used to create multiple versions of a single function
+(@pxref{Function Multiversioning}).
On the x86, the following options are allowed:
@table @samp
@@ -29431,11 +29448,58 @@ For the effects of the @code{hot} attribute on functions, see
@section Function Multiversioning
@cindex function versions
-With the GNU C++ front end, for x86 targets, you may specify multiple
-versions of a function, where each function is specialized for a
-specific target feature. At runtime, the appropriate version of the
-function is automatically executed depending on the characteristics of
-the execution platform. Here is an example.
+On some targets it is possible to specify multiple versions of a function,
+where each version of the function is specialized for a different set of target
+features. At runtime, characteristics of the execution platform are checked,
+and the most appropriate version of the function is chosen to be executed
+depending on the available architecture features. One of the versions will be
+a "default" version, which will be chosen if none of the criteria for the other
+versions are met.
+
+Function multiversioning is enabled by annotating the function versions with one
+of three function attributes.
+
+The @code{target} attribute can be used on x86 targets. Multiversioning with
+the @code{target} attribute is supported only in the C++ frontend. One version
+must be explicitly labelled as the "default" version. The @code{target}
+attributes will normally need to be included in any header file declarations,
+to ensure that the correct function version is called from all translation
+units. In translation units that don't include declarations with
+the @code{target} attributes, any callers will always call the "default"
+version directly.
+
+The @code{target_version} attribute can be used on AArch64 targets.
+Multiversioning with the @code{target_version} attribute is supported only in
+the C++ frontend. This attribute behaves similarly to the @code{target}
+attribute. However, callers in any translation unit will always use the
+versioned function, even if the @code{target_version} attributes aren't
+included in that translation unit. This means that header files don't need to
+include the @code{target_version} attributes, and the function can use a single
+header file declaration (as if it were a normal unversioned function).
+
+The @code{target_clones} attribute can be used on AArch64, PowerPC and x86
+targets. It behaves similarly to the @code{target_version} attribute, except
+that only one copy of the function is included in the source file. The
+attribute takes a list of version specifiers and produces one copy of the
+function for each specifier. This is useful in cases where the compiler is
+capable of generating optimized code (with autovectorization, for example)
+using architecture features enabled only in the more specialized function
+versions. For example, on PowerPC, compiling a function with
+@code{target_clones("default,cpu=power9")} will create two function clones -
+one compiled with @option{-mcpu=power9}, and another with the default options.
+The @code{target_clones} attribute is available in the C, C++, D and Ada
+frontends.
+
+Function multiversioning attributes do not propagate from a versioned
+function to its callees, although a callee can still be optimised using the
+caller's extra target features if it is inlined directly into the caller.
+
+For details of the target options supported on each target, refer to
+@ref{AArch64 Function Attributes}, @ref{PowerPC Function Attributes},
+and @ref{x86 Function Attributes}.
+
+Here is an example of function multiversioning on x86 using the @code{target}
+attribute.
@smallexample
__attribute__ ((target ("default")))
@@ -29474,16 +29538,28 @@ int main ()
@}
@end smallexample
-In the above example, four versions of function foo are created. The
-first version of foo with the target attribute "default" is the default
-version. This version gets executed when no other target specific
-version qualifies for execution on a particular platform. A new version
-of foo is created by using the same function signature but with a
-different target string. Function foo is called or a pointer to it is
-taken just like a regular function. GCC takes care of doing the
-dispatching to call the right version at runtime. Refer to the
-@uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
-Function Multiversioning} for more details.
+In the above example, four versions of function foo are created. The first
+version of @samp{foo}, with the target attribute @samp{"default"}, is the
+default version. This version gets executed when no other target specific
+version qualifies for execution on a particular platform. Other versions of
+@samp{foo} are created by using the same function signature but with a
+different target string. The function @samp{foo} can be called or a pointer to
+it can be taken just like for a regular function. GCC takes care of doing the
+dispatching to call the right version at runtime.
+
+Function multiversioning is implemented using the STT_GNU_IFUNC symbol type
+extension to the ELF standard. This is the same mechanism used by the
+@code{ifunc} attribute (@pxref{Common Function Attributes}). However, in this
+case the compiler automatically generates a resolver function that checks which
+features are available at runtime. This resolver uses GLIBC's hardware
+capability bits, and therefore requires GCC to be configured to use GLIBC 2.23
+or newer. The resolver is run once at startup, and the resulting function
+pointer is then stored in the dynamic symbol table. When using the
+@code{target_version} or @code{target_clones} attributes, the resolved ifunc
+symbol uses the normal symbol name. When using the @code{target} attribute,
+the normal symbol name is instead used by the default function version (which
+is why @code{target} attributes for multiversioning need to be included in any
+header file declarations as well).
@node Type Traits
@section Type Traits
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PING gcc-14?][PATCH v2] docs: Update function multiversioning documentation
2024-04-30 16:10 [PATCH v2] docs: Update function multiversioning documentation Andrew Carlotti
@ 2024-05-06 11:31 ` Andrew Carlotti
2024-06-10 16:08 ` [PING][PATCH " Andrew Carlotti
1 sibling, 0 replies; 6+ messages in thread
From: Andrew Carlotti @ 2024-05-06 11:31 UTC (permalink / raw)
To: gcc-patches
Cc: Richard Biener, Richard Sandiford, Michael Meissner,
Sandra Loosemore, Jakub Jelinek
Is this patch ok? I was hoping to get it merged before 14.1 releases, if it's
not yet too late for that.
On Tue, Apr 30, 2024 at 05:10:45PM +0100, Andrew Carlotti wrote:
> Add target_version attribute to Common Function Attributes and update
> target and target_clones documentation. Move shared detail and examples
> to the Function Multiversioning page. Add target-specific details to
> target-specific pages.
>
> ---
>
> Changes since v1:
> - Various typo fixes.
> - Reordered content in 'Function multiversioning' section to put implementation
> details at the end (as suggested in review).
> - Dropped links to outdated wiki page, and a couple of other unhelpful
> sentences that the previous version preserved.
>
> I've built and rechecked the info output. Ok for master? And is this ok for
> the GCC-14 branch too?
>
> gcc/ChangeLog:
>
> * doc/extend.texi (Common Function Attributes): Update target
> and target_clones documentation, and add target_version.
> (AArch64 Function Attributes): Add ACLE reference and list
> supported features.
> (PowerPC Function Attributes): List supported features.
> (x86 Function Attributes): Mention function multiversioning.
> (Function Multiversioning): Update, and move shared detail here.
>
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index e290265d68d33f86a7e7ee9882cc0fd6bed00143..fefac70b5fffc350bf23db74a8fc88fa3bb99bd5 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -4178,17 +4178,16 @@ and @option{-Wanalyzer-tainted-size}.
> 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. The original target command-line options are ignored.
> -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}.
> -
> +command line. One or more strings can be provided as arguments.
> The @code{target} attribute can be used for instance to have a function
> compiled with a different ISA (instruction set architecture) than the
> -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.
> +default.
> +
> +The options supported by the @code{target} attribute are specific to each
> +target; refer to @ref{x86 Function Attributes}, @ref{PowerPC Function
> +Attributes}, @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> +@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> +for details.
>
> For instance, on an x86, you could declare one function with the
> @code{target("sse4.1,arch=core2")} attribute and another with
> @@ -4211,39 +4210,26 @@ 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},
> -@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> -@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> -for details.
> +@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.
> +
> +On x86, the @code{target} attribute can also be used to create multiple
> +versions of a function, compiled with different target-specific options.
> +@xref{Function Multiversioning} for more details.
>
> @cindex @code{target_clones} function attribute
> @item target_clones (@var{options})
> 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}.
> -
> -On a PowerPC, you can compile a function with
> -@code{target_clones("cpu=power9,default")}. GCC will create two
> -function clones, one compiled with @option{-mcpu=power9} and another
> -with the default options. GCC must be configured to use GLIBC 2.23 or
> -newer in order to use the @code{target_clones} attribute.
> -
> -It also creates a resolver function (see
> -the @code{ifunc} attribute above) that dynamically selects a clone
> -suitable for current architecture. The resolver is created only if there
> -is a usage of a function with @code{target_clones} attribute.
> -
> -Note that any subsequent call of a function without @code{target_clone}
> -from a @code{target_clone} caller will not lead to copying
> -(target clone) of the called function.
> -If you want to enforce such behaviour,
> -we recommend declaring the calling function with the @code{flatten} attribute?
> +should be cloned into multiple versions compiled with different target options
> +than specified on the command line. @xref{Function Multiversioning} for more
> +details.
> +
> +@cindex @code{target_version} function attribute
> +@item target_version (@var{options})
> +The @code{target_version} attribute is used on AArch64 to create multiple
> +versions of a function, compiled with different target-specific options.
> +@xref{Function Multiversioning} for more details.
>
> @cindex @code{unavailable} function attribute
> @item unavailable
> @@ -4734,6 +4720,26 @@ Note that CPU tuning options and attributes such as the @option{-mcpu=},
> @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
> architectural feature rules specified above.
>
> +@subsubsection Function multiversioning
> +The @code{target_version} and @code{target_clones} attributes can be used to
> +specify multiple versions of a function. Each version enables the specified
> +set of architecture extensions, in addition to any extensions that were already
> +enabled at the command line or using @code{target} attributes. For general
> +details, @pxref{Function Multiversioning}. There are further AArch64-specific
> +details available in the
> +@uref{https://github.com/ARM-software/acle/blob/main/main/acle.md#function-multi-versioning,
> +Arm C Language Extensions (ACLE) specification}.
> +
> +Some aspects of the ACLE specification are not yet supported. In particular,
> +the currently supported feature names are @code{rng}, @code{flagm}, @code{lse},
> +@code{fp}, @code{simd}, @code{dotprod}, @code{sm4}, @code{rdma}, @code{rdm}
> +(alias of @code{rdma}), @code{crc}, @code{sha2}, @code{sha3}, @code{aes},
> +@code{fp16}, @code{fp16fml}, @code{rcpc}, @code{rcpc3}, @code{i8mm},
> +@code{bf16}, @code{sve}, @code{f32mm}, @code{f64mm}, @code{sve2},
> +@code{sve2-aes}, @code{sve2-bitperm}, @code{sve2-sha3}, @code{sve2-sm4},
> +@code{sme}, @code{sb}, @code{predres}, @code{sme-f64f64}, @code{sme-i16i64} and
> +@code{sme2}.
> +
> @node AMD GCN Function Attributes
> @subsection AMD GCN Function Attributes
>
> @@ -6278,6 +6284,15 @@ default tuning specified on the command line.
> On the PowerPC, the inliner does not inline a
> function that has different target options than the caller, unless the
> callee has a subset of the target options of the caller.
> +
> +@cindex @code{target_clones} function attribute
> +@item target_clones (@var{options})
> +The @code{target_clones} attribute can be used to create multiple versions of a
> +function for different supported architectures, with one version for each
> +specifier in the options list. One of these version specifiers must be the
> +@code{default} version. The other supported target specifiers are
> +@code{cpu=power6}, @code{cpu=power7}, @code{cpu=power8}, @code{cpu=power9} and
> +@code{cpu=power10}. For more details, @pxref{Function Multiversioning}.
> @end table
>
> @node RISC-V Function Attributes
> @@ -6872,7 +6887,9 @@ will crash if the wrong kind of handler is used.
> @cindex @code{target} function attribute
> @item target (@var{options})
> As discussed in @ref{Common Function Attributes}, this attribute
> -allows specification of target-specific compilation options.
> +allows specification of target-specific compilation options. It can also be
> +used to create multiple versions of a single function
> +(@pxref{Function Multiversioning}).
>
> On the x86, the following options are allowed:
> @table @samp
> @@ -29431,11 +29448,58 @@ For the effects of the @code{hot} attribute on functions, see
> @section Function Multiversioning
> @cindex function versions
>
> -With the GNU C++ front end, for x86 targets, you may specify multiple
> -versions of a function, where each function is specialized for a
> -specific target feature. At runtime, the appropriate version of the
> -function is automatically executed depending on the characteristics of
> -the execution platform. Here is an example.
> +On some targets it is possible to specify multiple versions of a function,
> +where each version of the function is specialized for a different set of target
> +features. At runtime, characteristics of the execution platform are checked,
> +and the most appropriate version of the function is chosen to be executed
> +depending on the available architecture features. One of the versions will be
> +a "default" version, which will be chosen if none of the criteria for the other
> +versions are met.
> +
> +Function multiversioning is enabled by annotating the function versions with one
> +of three function attributes.
> +
> +The @code{target} attribute can be used on x86 targets. Multiversioning with
> +the @code{target} attribute is supported only in the C++ frontend. One version
> +must be explicitly labelled as the "default" version. The @code{target}
> +attributes will normally need to be included in any header file declarations,
> +to ensure that the correct function version is called from all translation
> +units. In translation units that don't include declarations with
> +the @code{target} attributes, any callers will always call the "default"
> +version directly.
> +
> +The @code{target_version} attribute can be used on AArch64 targets.
> +Multiversioning with the @code{target_version} attribute is supported only in
> +the C++ frontend. This attribute behaves similarly to the @code{target}
> +attribute. However, callers in any translation unit will always use the
> +versioned function, even if the @code{target_version} attributes aren't
> +included in that translation unit. This means that header files don't need to
> +include the @code{target_version} attributes, and the function can use a single
> +header file declaration (as if it were a normal unversioned function).
> +
> +The @code{target_clones} attribute can be used on AArch64, PowerPC and x86
> +targets. It behaves similarly to the @code{target_version} attribute, except
> +that only one copy of the function is included in the source file. The
> +attribute takes a list of version specifiers and produces one copy of the
> +function for each specifier. This is useful in cases where the compiler is
> +capable of generating optimized code (with autovectorization, for example)
> +using architecture features enabled only in the more specialized function
> +versions. For example, on PowerPC, compiling a function with
> +@code{target_clones("default,cpu=power9")} will create two function clones -
> +one compiled with @option{-mcpu=power9}, and another with the default options.
> +The @code{target_clones} attribute is available in the C, C++, D and Ada
> +frontends.
> +
> +Function multiversioning attributes do not propagate from a versioned
> +function to its callees, although a callee can still be optimised using the
> +caller's extra target features if it is inlined directly into the caller.
> +
> +For details of the target options supported on each target, refer to
> +@ref{AArch64 Function Attributes}, @ref{PowerPC Function Attributes},
> +and @ref{x86 Function Attributes}.
> +
> +Here is an example of function multiversioning on x86 using the @code{target}
> +attribute.
>
> @smallexample
> __attribute__ ((target ("default")))
> @@ -29474,16 +29538,28 @@ int main ()
> @}
> @end smallexample
>
> -In the above example, four versions of function foo are created. The
> -first version of foo with the target attribute "default" is the default
> -version. This version gets executed when no other target specific
> -version qualifies for execution on a particular platform. A new version
> -of foo is created by using the same function signature but with a
> -different target string. Function foo is called or a pointer to it is
> -taken just like a regular function. GCC takes care of doing the
> -dispatching to call the right version at runtime. Refer to the
> -@uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
> -Function Multiversioning} for more details.
> +In the above example, four versions of function foo are created. The first
> +version of @samp{foo}, with the target attribute @samp{"default"}, is the
> +default version. This version gets executed when no other target specific
> +version qualifies for execution on a particular platform. Other versions of
> +@samp{foo} are created by using the same function signature but with a
> +different target string. The function @samp{foo} can be called or a pointer to
> +it can be taken just like for a regular function. GCC takes care of doing the
> +dispatching to call the right version at runtime.
> +
> +Function multiversioning is implemented using the STT_GNU_IFUNC symbol type
> +extension to the ELF standard. This is the same mechanism used by the
> +@code{ifunc} attribute (@pxref{Common Function Attributes}). However, in this
> +case the compiler automatically generates a resolver function that checks which
> +features are available at runtime. This resolver uses GLIBC's hardware
> +capability bits, and therefore requires GCC to be configured to use GLIBC 2.23
> +or newer. The resolver is run once at startup, and the resulting function
> +pointer is then stored in the dynamic symbol table. When using the
> +@code{target_version} or @code{target_clones} attributes, the resolved ifunc
> +symbol uses the normal symbol name. When using the @code{target} attribute,
> +the normal symbol name is instead used by the default function version (which
> +is why @code{target} attributes for multiversioning need to be included in any
> +header file declarations as well).
>
> @node Type Traits
> @section Type Traits
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PING][PATCH v2] docs: Update function multiversioning documentation
2024-04-30 16:10 [PATCH v2] docs: Update function multiversioning documentation Andrew Carlotti
2024-05-06 11:31 ` [PING gcc-14?][PATCH " Andrew Carlotti
@ 2024-06-10 16:08 ` Andrew Carlotti
2024-07-10 12:09 ` [PING^3][PATCH " Andrew Carlotti
1 sibling, 1 reply; 6+ messages in thread
From: Andrew Carlotti @ 2024-06-10 16:08 UTC (permalink / raw)
To: gcc-patches
Cc: Richard Biener, Richard Sandiford, Michael Meissner,
Sandra Loosemore, Jakub Jelinek
On Tue, Apr 30, 2024 at 05:10:45PM +0100, Andrew Carlotti wrote:
> Add target_version attribute to Common Function Attributes and update
> target and target_clones documentation. Move shared detail and examples
> to the Function Multiversioning page. Add target-specific details to
> target-specific pages.
>
> ---
>
> Changes since v1:
> - Various typo fixes.
> - Reordered content in 'Function multiversioning' section to put implementation
> details at the end (as suggested in review).
> - Dropped links to outdated wiki page, and a couple of other unhelpful
> sentences that the previous version preserved.
>
> I've built and rechecked the info output. Ok for master? And is this ok for
> the GCC-14 branch too?
>
> gcc/ChangeLog:
>
> * doc/extend.texi (Common Function Attributes): Update target
> and target_clones documentation, and add target_version.
> (AArch64 Function Attributes): Add ACLE reference and list
> supported features.
> (PowerPC Function Attributes): List supported features.
> (x86 Function Attributes): Mention function multiversioning.
> (Function Multiversioning): Update, and move shared detail here.
>
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index e290265d68d33f86a7e7ee9882cc0fd6bed00143..fefac70b5fffc350bf23db74a8fc88fa3bb99bd5 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -4178,17 +4178,16 @@ and @option{-Wanalyzer-tainted-size}.
> 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. The original target command-line options are ignored.
> -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}.
> -
> +command line. One or more strings can be provided as arguments.
> The @code{target} attribute can be used for instance to have a function
> compiled with a different ISA (instruction set architecture) than the
> -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.
> +default.
> +
> +The options supported by the @code{target} attribute are specific to each
> +target; refer to @ref{x86 Function Attributes}, @ref{PowerPC Function
> +Attributes}, @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> +@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> +for details.
>
> For instance, on an x86, you could declare one function with the
> @code{target("sse4.1,arch=core2")} attribute and another with
> @@ -4211,39 +4210,26 @@ 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},
> -@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> -@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> -for details.
> +@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.
> +
> +On x86, the @code{target} attribute can also be used to create multiple
> +versions of a function, compiled with different target-specific options.
> +@xref{Function Multiversioning} for more details.
>
> @cindex @code{target_clones} function attribute
> @item target_clones (@var{options})
> 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}.
> -
> -On a PowerPC, you can compile a function with
> -@code{target_clones("cpu=power9,default")}. GCC will create two
> -function clones, one compiled with @option{-mcpu=power9} and another
> -with the default options. GCC must be configured to use GLIBC 2.23 or
> -newer in order to use the @code{target_clones} attribute.
> -
> -It also creates a resolver function (see
> -the @code{ifunc} attribute above) that dynamically selects a clone
> -suitable for current architecture. The resolver is created only if there
> -is a usage of a function with @code{target_clones} attribute.
> -
> -Note that any subsequent call of a function without @code{target_clone}
> -from a @code{target_clone} caller will not lead to copying
> -(target clone) of the called function.
> -If you want to enforce such behaviour,
> -we recommend declaring the calling function with the @code{flatten} attribute?
> +should be cloned into multiple versions compiled with different target options
> +than specified on the command line. @xref{Function Multiversioning} for more
> +details.
> +
> +@cindex @code{target_version} function attribute
> +@item target_version (@var{options})
> +The @code{target_version} attribute is used on AArch64 to create multiple
> +versions of a function, compiled with different target-specific options.
> +@xref{Function Multiversioning} for more details.
>
> @cindex @code{unavailable} function attribute
> @item unavailable
> @@ -4734,6 +4720,26 @@ Note that CPU tuning options and attributes such as the @option{-mcpu=},
> @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
> architectural feature rules specified above.
>
> +@subsubsection Function multiversioning
> +The @code{target_version} and @code{target_clones} attributes can be used to
> +specify multiple versions of a function. Each version enables the specified
> +set of architecture extensions, in addition to any extensions that were already
> +enabled at the command line or using @code{target} attributes. For general
> +details, @pxref{Function Multiversioning}. There are further AArch64-specific
> +details available in the
> +@uref{https://github.com/ARM-software/acle/blob/main/main/acle.md#function-multi-versioning,
> +Arm C Language Extensions (ACLE) specification}.
> +
> +Some aspects of the ACLE specification are not yet supported. In particular,
> +the currently supported feature names are @code{rng}, @code{flagm}, @code{lse},
> +@code{fp}, @code{simd}, @code{dotprod}, @code{sm4}, @code{rdma}, @code{rdm}
> +(alias of @code{rdma}), @code{crc}, @code{sha2}, @code{sha3}, @code{aes},
> +@code{fp16}, @code{fp16fml}, @code{rcpc}, @code{rcpc3}, @code{i8mm},
> +@code{bf16}, @code{sve}, @code{f32mm}, @code{f64mm}, @code{sve2},
> +@code{sve2-aes}, @code{sve2-bitperm}, @code{sve2-sha3}, @code{sve2-sm4},
> +@code{sme}, @code{sb}, @code{predres}, @code{sme-f64f64}, @code{sme-i16i64} and
> +@code{sme2}.
> +
> @node AMD GCN Function Attributes
> @subsection AMD GCN Function Attributes
>
> @@ -6278,6 +6284,15 @@ default tuning specified on the command line.
> On the PowerPC, the inliner does not inline a
> function that has different target options than the caller, unless the
> callee has a subset of the target options of the caller.
> +
> +@cindex @code{target_clones} function attribute
> +@item target_clones (@var{options})
> +The @code{target_clones} attribute can be used to create multiple versions of a
> +function for different supported architectures, with one version for each
> +specifier in the options list. One of these version specifiers must be the
> +@code{default} version. The other supported target specifiers are
> +@code{cpu=power6}, @code{cpu=power7}, @code{cpu=power8}, @code{cpu=power9} and
> +@code{cpu=power10}. For more details, @pxref{Function Multiversioning}.
> @end table
>
> @node RISC-V Function Attributes
> @@ -6872,7 +6887,9 @@ will crash if the wrong kind of handler is used.
> @cindex @code{target} function attribute
> @item target (@var{options})
> As discussed in @ref{Common Function Attributes}, this attribute
> -allows specification of target-specific compilation options.
> +allows specification of target-specific compilation options. It can also be
> +used to create multiple versions of a single function
> +(@pxref{Function Multiversioning}).
>
> On the x86, the following options are allowed:
> @table @samp
> @@ -29431,11 +29448,58 @@ For the effects of the @code{hot} attribute on functions, see
> @section Function Multiversioning
> @cindex function versions
>
> -With the GNU C++ front end, for x86 targets, you may specify multiple
> -versions of a function, where each function is specialized for a
> -specific target feature. At runtime, the appropriate version of the
> -function is automatically executed depending on the characteristics of
> -the execution platform. Here is an example.
> +On some targets it is possible to specify multiple versions of a function,
> +where each version of the function is specialized for a different set of target
> +features. At runtime, characteristics of the execution platform are checked,
> +and the most appropriate version of the function is chosen to be executed
> +depending on the available architecture features. One of the versions will be
> +a "default" version, which will be chosen if none of the criteria for the other
> +versions are met.
> +
> +Function multiversioning is enabled by annotating the function versions with one
> +of three function attributes.
> +
> +The @code{target} attribute can be used on x86 targets. Multiversioning with
> +the @code{target} attribute is supported only in the C++ frontend. One version
> +must be explicitly labelled as the "default" version. The @code{target}
> +attributes will normally need to be included in any header file declarations,
> +to ensure that the correct function version is called from all translation
> +units. In translation units that don't include declarations with
> +the @code{target} attributes, any callers will always call the "default"
> +version directly.
> +
> +The @code{target_version} attribute can be used on AArch64 targets.
> +Multiversioning with the @code{target_version} attribute is supported only in
> +the C++ frontend. This attribute behaves similarly to the @code{target}
> +attribute. However, callers in any translation unit will always use the
> +versioned function, even if the @code{target_version} attributes aren't
> +included in that translation unit. This means that header files don't need to
> +include the @code{target_version} attributes, and the function can use a single
> +header file declaration (as if it were a normal unversioned function).
> +
> +The @code{target_clones} attribute can be used on AArch64, PowerPC and x86
> +targets. It behaves similarly to the @code{target_version} attribute, except
> +that only one copy of the function is included in the source file. The
> +attribute takes a list of version specifiers and produces one copy of the
> +function for each specifier. This is useful in cases where the compiler is
> +capable of generating optimized code (with autovectorization, for example)
> +using architecture features enabled only in the more specialized function
> +versions. For example, on PowerPC, compiling a function with
> +@code{target_clones("default,cpu=power9")} will create two function clones -
> +one compiled with @option{-mcpu=power9}, and another with the default options.
> +The @code{target_clones} attribute is available in the C, C++, D and Ada
> +frontends.
> +
> +Function multiversioning attributes do not propagate from a versioned
> +function to its callees, although a callee can still be optimised using the
> +caller's extra target features if it is inlined directly into the caller.
> +
> +For details of the target options supported on each target, refer to
> +@ref{AArch64 Function Attributes}, @ref{PowerPC Function Attributes},
> +and @ref{x86 Function Attributes}.
> +
> +Here is an example of function multiversioning on x86 using the @code{target}
> +attribute.
>
> @smallexample
> __attribute__ ((target ("default")))
> @@ -29474,16 +29538,28 @@ int main ()
> @}
> @end smallexample
>
> -In the above example, four versions of function foo are created. The
> -first version of foo with the target attribute "default" is the default
> -version. This version gets executed when no other target specific
> -version qualifies for execution on a particular platform. A new version
> -of foo is created by using the same function signature but with a
> -different target string. Function foo is called or a pointer to it is
> -taken just like a regular function. GCC takes care of doing the
> -dispatching to call the right version at runtime. Refer to the
> -@uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
> -Function Multiversioning} for more details.
> +In the above example, four versions of function foo are created. The first
> +version of @samp{foo}, with the target attribute @samp{"default"}, is the
> +default version. This version gets executed when no other target specific
> +version qualifies for execution on a particular platform. Other versions of
> +@samp{foo} are created by using the same function signature but with a
> +different target string. The function @samp{foo} can be called or a pointer to
> +it can be taken just like for a regular function. GCC takes care of doing the
> +dispatching to call the right version at runtime.
> +
> +Function multiversioning is implemented using the STT_GNU_IFUNC symbol type
> +extension to the ELF standard. This is the same mechanism used by the
> +@code{ifunc} attribute (@pxref{Common Function Attributes}). However, in this
> +case the compiler automatically generates a resolver function that checks which
> +features are available at runtime. This resolver uses GLIBC's hardware
> +capability bits, and therefore requires GCC to be configured to use GLIBC 2.23
> +or newer. The resolver is run once at startup, and the resulting function
> +pointer is then stored in the dynamic symbol table. When using the
> +@code{target_version} or @code{target_clones} attributes, the resolved ifunc
> +symbol uses the normal symbol name. When using the @code{target} attribute,
> +the normal symbol name is instead used by the default function version (which
> +is why @code{target} attributes for multiversioning need to be included in any
> +header file declarations as well).
>
> @node Type Traits
> @section Type Traits
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PING^3][PATCH v2] docs: Update function multiversioning documentation
2024-06-10 16:08 ` [PING][PATCH " Andrew Carlotti
@ 2024-07-10 12:09 ` Andrew Carlotti
2024-08-13 17:18 ` [PING^4][PATCH " Andrew Carlotti
0 siblings, 1 reply; 6+ messages in thread
From: Andrew Carlotti @ 2024-07-10 12:09 UTC (permalink / raw)
To: gcc-patches
Cc: Richard Biener, Richard Sandiford, Michael Meissner,
Sandra Loosemore, Jakub Jelinek
On Mon, Jun 10, 2024 at 05:08:21PM +0100, Andrew Carlotti wrote:
>
> On Tue, Apr 30, 2024 at 05:10:45PM +0100, Andrew Carlotti wrote:
> > Add target_version attribute to Common Function Attributes and update
> > target and target_clones documentation. Move shared detail and examples
> > to the Function Multiversioning page. Add target-specific details to
> > target-specific pages.
> >
> > ---
> >
> > Changes since v1:
> > - Various typo fixes.
> > - Reordered content in 'Function multiversioning' section to put implementation
> > details at the end (as suggested in review).
> > - Dropped links to outdated wiki page, and a couple of other unhelpful
> > sentences that the previous version preserved.
> >
> > I've built and rechecked the info output. Ok for master? And is this ok for
> > the GCC-14 branch too?
> >
> > gcc/ChangeLog:
> >
> > * doc/extend.texi (Common Function Attributes): Update target
> > and target_clones documentation, and add target_version.
> > (AArch64 Function Attributes): Add ACLE reference and list
> > supported features.
> > (PowerPC Function Attributes): List supported features.
> > (x86 Function Attributes): Mention function multiversioning.
> > (Function Multiversioning): Update, and move shared detail here.
> >
> >
> > diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> > index e290265d68d33f86a7e7ee9882cc0fd6bed00143..fefac70b5fffc350bf23db74a8fc88fa3bb99bd5 100644
> > --- a/gcc/doc/extend.texi
> > +++ b/gcc/doc/extend.texi
> > @@ -4178,17 +4178,16 @@ and @option{-Wanalyzer-tainted-size}.
> > 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. The original target command-line options are ignored.
> > -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}.
> > -
> > +command line. One or more strings can be provided as arguments.
> > The @code{target} attribute can be used for instance to have a function
> > compiled with a different ISA (instruction set architecture) than the
> > -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.
> > +default.
> > +
> > +The options supported by the @code{target} attribute are specific to each
> > +target; refer to @ref{x86 Function Attributes}, @ref{PowerPC Function
> > +Attributes}, @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> > +@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> > +for details.
> >
> > For instance, on an x86, you could declare one function with the
> > @code{target("sse4.1,arch=core2")} attribute and another with
> > @@ -4211,39 +4210,26 @@ 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},
> > -@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> > -@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> > -for details.
> > +@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.
> > +
> > +On x86, the @code{target} attribute can also be used to create multiple
> > +versions of a function, compiled with different target-specific options.
> > +@xref{Function Multiversioning} for more details.
> >
> > @cindex @code{target_clones} function attribute
> > @item target_clones (@var{options})
> > 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}.
> > -
> > -On a PowerPC, you can compile a function with
> > -@code{target_clones("cpu=power9,default")}. GCC will create two
> > -function clones, one compiled with @option{-mcpu=power9} and another
> > -with the default options. GCC must be configured to use GLIBC 2.23 or
> > -newer in order to use the @code{target_clones} attribute.
> > -
> > -It also creates a resolver function (see
> > -the @code{ifunc} attribute above) that dynamically selects a clone
> > -suitable for current architecture. The resolver is created only if there
> > -is a usage of a function with @code{target_clones} attribute.
> > -
> > -Note that any subsequent call of a function without @code{target_clone}
> > -from a @code{target_clone} caller will not lead to copying
> > -(target clone) of the called function.
> > -If you want to enforce such behaviour,
> > -we recommend declaring the calling function with the @code{flatten} attribute?
> > +should be cloned into multiple versions compiled with different target options
> > +than specified on the command line. @xref{Function Multiversioning} for more
> > +details.
> > +
> > +@cindex @code{target_version} function attribute
> > +@item target_version (@var{options})
> > +The @code{target_version} attribute is used on AArch64 to create multiple
> > +versions of a function, compiled with different target-specific options.
> > +@xref{Function Multiversioning} for more details.
> >
> > @cindex @code{unavailable} function attribute
> > @item unavailable
> > @@ -4734,6 +4720,26 @@ Note that CPU tuning options and attributes such as the @option{-mcpu=},
> > @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
> > architectural feature rules specified above.
> >
> > +@subsubsection Function multiversioning
> > +The @code{target_version} and @code{target_clones} attributes can be used to
> > +specify multiple versions of a function. Each version enables the specified
> > +set of architecture extensions, in addition to any extensions that were already
> > +enabled at the command line or using @code{target} attributes. For general
> > +details, @pxref{Function Multiversioning}. There are further AArch64-specific
> > +details available in the
> > +@uref{https://github.com/ARM-software/acle/blob/main/main/acle.md#function-multi-versioning,
> > +Arm C Language Extensions (ACLE) specification}.
> > +
> > +Some aspects of the ACLE specification are not yet supported. In particular,
> > +the currently supported feature names are @code{rng}, @code{flagm}, @code{lse},
> > +@code{fp}, @code{simd}, @code{dotprod}, @code{sm4}, @code{rdma}, @code{rdm}
> > +(alias of @code{rdma}), @code{crc}, @code{sha2}, @code{sha3}, @code{aes},
> > +@code{fp16}, @code{fp16fml}, @code{rcpc}, @code{rcpc3}, @code{i8mm},
> > +@code{bf16}, @code{sve}, @code{f32mm}, @code{f64mm}, @code{sve2},
> > +@code{sve2-aes}, @code{sve2-bitperm}, @code{sve2-sha3}, @code{sve2-sm4},
> > +@code{sme}, @code{sb}, @code{predres}, @code{sme-f64f64}, @code{sme-i16i64} and
> > +@code{sme2}.
> > +
> > @node AMD GCN Function Attributes
> > @subsection AMD GCN Function Attributes
> >
> > @@ -6278,6 +6284,15 @@ default tuning specified on the command line.
> > On the PowerPC, the inliner does not inline a
> > function that has different target options than the caller, unless the
> > callee has a subset of the target options of the caller.
> > +
> > +@cindex @code{target_clones} function attribute
> > +@item target_clones (@var{options})
> > +The @code{target_clones} attribute can be used to create multiple versions of a
> > +function for different supported architectures, with one version for each
> > +specifier in the options list. One of these version specifiers must be the
> > +@code{default} version. The other supported target specifiers are
> > +@code{cpu=power6}, @code{cpu=power7}, @code{cpu=power8}, @code{cpu=power9} and
> > +@code{cpu=power10}. For more details, @pxref{Function Multiversioning}.
> > @end table
> >
> > @node RISC-V Function Attributes
> > @@ -6872,7 +6887,9 @@ will crash if the wrong kind of handler is used.
> > @cindex @code{target} function attribute
> > @item target (@var{options})
> > As discussed in @ref{Common Function Attributes}, this attribute
> > -allows specification of target-specific compilation options.
> > +allows specification of target-specific compilation options. It can also be
> > +used to create multiple versions of a single function
> > +(@pxref{Function Multiversioning}).
> >
> > On the x86, the following options are allowed:
> > @table @samp
> > @@ -29431,11 +29448,58 @@ For the effects of the @code{hot} attribute on functions, see
> > @section Function Multiversioning
> > @cindex function versions
> >
> > -With the GNU C++ front end, for x86 targets, you may specify multiple
> > -versions of a function, where each function is specialized for a
> > -specific target feature. At runtime, the appropriate version of the
> > -function is automatically executed depending on the characteristics of
> > -the execution platform. Here is an example.
> > +On some targets it is possible to specify multiple versions of a function,
> > +where each version of the function is specialized for a different set of target
> > +features. At runtime, characteristics of the execution platform are checked,
> > +and the most appropriate version of the function is chosen to be executed
> > +depending on the available architecture features. One of the versions will be
> > +a "default" version, which will be chosen if none of the criteria for the other
> > +versions are met.
> > +
> > +Function multiversioning is enabled by annotating the function versions with one
> > +of three function attributes.
> > +
> > +The @code{target} attribute can be used on x86 targets. Multiversioning with
> > +the @code{target} attribute is supported only in the C++ frontend. One version
> > +must be explicitly labelled as the "default" version. The @code{target}
> > +attributes will normally need to be included in any header file declarations,
> > +to ensure that the correct function version is called from all translation
> > +units. In translation units that don't include declarations with
> > +the @code{target} attributes, any callers will always call the "default"
> > +version directly.
> > +
> > +The @code{target_version} attribute can be used on AArch64 targets.
> > +Multiversioning with the @code{target_version} attribute is supported only in
> > +the C++ frontend. This attribute behaves similarly to the @code{target}
> > +attribute. However, callers in any translation unit will always use the
> > +versioned function, even if the @code{target_version} attributes aren't
> > +included in that translation unit. This means that header files don't need to
> > +include the @code{target_version} attributes, and the function can use a single
> > +header file declaration (as if it were a normal unversioned function).
> > +
> > +The @code{target_clones} attribute can be used on AArch64, PowerPC and x86
> > +targets. It behaves similarly to the @code{target_version} attribute, except
> > +that only one copy of the function is included in the source file. The
> > +attribute takes a list of version specifiers and produces one copy of the
> > +function for each specifier. This is useful in cases where the compiler is
> > +capable of generating optimized code (with autovectorization, for example)
> > +using architecture features enabled only in the more specialized function
> > +versions. For example, on PowerPC, compiling a function with
> > +@code{target_clones("default,cpu=power9")} will create two function clones -
> > +one compiled with @option{-mcpu=power9}, and another with the default options.
> > +The @code{target_clones} attribute is available in the C, C++, D and Ada
> > +frontends.
> > +
> > +Function multiversioning attributes do not propagate from a versioned
> > +function to its callees, although a callee can still be optimised using the
> > +caller's extra target features if it is inlined directly into the caller.
> > +
> > +For details of the target options supported on each target, refer to
> > +@ref{AArch64 Function Attributes}, @ref{PowerPC Function Attributes},
> > +and @ref{x86 Function Attributes}.
> > +
> > +Here is an example of function multiversioning on x86 using the @code{target}
> > +attribute.
> >
> > @smallexample
> > __attribute__ ((target ("default")))
> > @@ -29474,16 +29538,28 @@ int main ()
> > @}
> > @end smallexample
> >
> > -In the above example, four versions of function foo are created. The
> > -first version of foo with the target attribute "default" is the default
> > -version. This version gets executed when no other target specific
> > -version qualifies for execution on a particular platform. A new version
> > -of foo is created by using the same function signature but with a
> > -different target string. Function foo is called or a pointer to it is
> > -taken just like a regular function. GCC takes care of doing the
> > -dispatching to call the right version at runtime. Refer to the
> > -@uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
> > -Function Multiversioning} for more details.
> > +In the above example, four versions of function foo are created. The first
> > +version of @samp{foo}, with the target attribute @samp{"default"}, is the
> > +default version. This version gets executed when no other target specific
> > +version qualifies for execution on a particular platform. Other versions of
> > +@samp{foo} are created by using the same function signature but with a
> > +different target string. The function @samp{foo} can be called or a pointer to
> > +it can be taken just like for a regular function. GCC takes care of doing the
> > +dispatching to call the right version at runtime.
> > +
> > +Function multiversioning is implemented using the STT_GNU_IFUNC symbol type
> > +extension to the ELF standard. This is the same mechanism used by the
> > +@code{ifunc} attribute (@pxref{Common Function Attributes}). However, in this
> > +case the compiler automatically generates a resolver function that checks which
> > +features are available at runtime. This resolver uses GLIBC's hardware
> > +capability bits, and therefore requires GCC to be configured to use GLIBC 2.23
> > +or newer. The resolver is run once at startup, and the resulting function
> > +pointer is then stored in the dynamic symbol table. When using the
> > +@code{target_version} or @code{target_clones} attributes, the resolved ifunc
> > +symbol uses the normal symbol name. When using the @code{target} attribute,
> > +the normal symbol name is instead used by the default function version (which
> > +is why @code{target} attributes for multiversioning need to be included in any
> > +header file declarations as well).
> >
> > @node Type Traits
> > @section Type Traits
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PING^4][PATCH v2] docs: Update function multiversioning documentation
2024-07-10 12:09 ` [PING^3][PATCH " Andrew Carlotti
@ 2024-08-13 17:18 ` Andrew Carlotti
2024-08-14 3:53 ` Sandra Loosemore
0 siblings, 1 reply; 6+ messages in thread
From: Andrew Carlotti @ 2024-08-13 17:18 UTC (permalink / raw)
To: gcc-patches
Cc: Richard Biener, Richard Sandiford, Michael Meissner,
Sandra Loosemore, Jakub Jelinek, Joseph Myers, Gerald Pfeifer
I'm still waiting for review for this patch. I've asked Richard Sandiford
about it, and he'd like a docs maintainer to review the patch (so I've cc'd the
rest of them now as well).
On Wed, Jul 10, 2024 at 01:09:41PM +0100, Andrew Carlotti wrote:
>
> On Mon, Jun 10, 2024 at 05:08:21PM +0100, Andrew Carlotti wrote:
> >
> > On Tue, Apr 30, 2024 at 05:10:45PM +0100, Andrew Carlotti wrote:
> > > Add target_version attribute to Common Function Attributes and update
> > > target and target_clones documentation. Move shared detail and examples
> > > to the Function Multiversioning page. Add target-specific details to
> > > target-specific pages.
> > >
> > > ---
> > >
> > > Changes since v1:
> > > - Various typo fixes.
> > > - Reordered content in 'Function multiversioning' section to put implementation
> > > details at the end (as suggested in review).
> > > - Dropped links to outdated wiki page, and a couple of other unhelpful
> > > sentences that the previous version preserved.
> > >
> > > I've built and rechecked the info output. Ok for master? And is this ok for
> > > the GCC-14 branch too?
> > >
> > > gcc/ChangeLog:
> > >
> > > * doc/extend.texi (Common Function Attributes): Update target
> > > and target_clones documentation, and add target_version.
> > > (AArch64 Function Attributes): Add ACLE reference and list
> > > supported features.
> > > (PowerPC Function Attributes): List supported features.
> > > (x86 Function Attributes): Mention function multiversioning.
> > > (Function Multiversioning): Update, and move shared detail here.
> > >
> > >
> > > diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> > > index e290265d68d33f86a7e7ee9882cc0fd6bed00143..fefac70b5fffc350bf23db74a8fc88fa3bb99bd5 100644
> > > --- a/gcc/doc/extend.texi
> > > +++ b/gcc/doc/extend.texi
> > > @@ -4178,17 +4178,16 @@ and @option{-Wanalyzer-tainted-size}.
> > > 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. The original target command-line options are ignored.
> > > -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}.
> > > -
> > > +command line. One or more strings can be provided as arguments.
> > > The @code{target} attribute can be used for instance to have a function
> > > compiled with a different ISA (instruction set architecture) than the
> > > -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.
> > > +default.
> > > +
> > > +The options supported by the @code{target} attribute are specific to each
> > > +target; refer to @ref{x86 Function Attributes}, @ref{PowerPC Function
> > > +Attributes}, @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> > > +@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> > > +for details.
> > >
> > > For instance, on an x86, you could declare one function with the
> > > @code{target("sse4.1,arch=core2")} attribute and another with
> > > @@ -4211,39 +4210,26 @@ 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},
> > > -@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
> > > -@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
> > > -for details.
> > > +@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.
> > > +
> > > +On x86, the @code{target} attribute can also be used to create multiple
> > > +versions of a function, compiled with different target-specific options.
> > > +@xref{Function Multiversioning} for more details.
> > >
> > > @cindex @code{target_clones} function attribute
> > > @item target_clones (@var{options})
> > > 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}.
> > > -
> > > -On a PowerPC, you can compile a function with
> > > -@code{target_clones("cpu=power9,default")}. GCC will create two
> > > -function clones, one compiled with @option{-mcpu=power9} and another
> > > -with the default options. GCC must be configured to use GLIBC 2.23 or
> > > -newer in order to use the @code{target_clones} attribute.
> > > -
> > > -It also creates a resolver function (see
> > > -the @code{ifunc} attribute above) that dynamically selects a clone
> > > -suitable for current architecture. The resolver is created only if there
> > > -is a usage of a function with @code{target_clones} attribute.
> > > -
> > > -Note that any subsequent call of a function without @code{target_clone}
> > > -from a @code{target_clone} caller will not lead to copying
> > > -(target clone) of the called function.
> > > -If you want to enforce such behaviour,
> > > -we recommend declaring the calling function with the @code{flatten} attribute?
> > > +should be cloned into multiple versions compiled with different target options
> > > +than specified on the command line. @xref{Function Multiversioning} for more
> > > +details.
> > > +
> > > +@cindex @code{target_version} function attribute
> > > +@item target_version (@var{options})
> > > +The @code{target_version} attribute is used on AArch64 to create multiple
> > > +versions of a function, compiled with different target-specific options.
> > > +@xref{Function Multiversioning} for more details.
> > >
> > > @cindex @code{unavailable} function attribute
> > > @item unavailable
> > > @@ -4734,6 +4720,26 @@ Note that CPU tuning options and attributes such as the @option{-mcpu=},
> > > @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
> > > architectural feature rules specified above.
> > >
> > > +@subsubsection Function multiversioning
> > > +The @code{target_version} and @code{target_clones} attributes can be used to
> > > +specify multiple versions of a function. Each version enables the specified
> > > +set of architecture extensions, in addition to any extensions that were already
> > > +enabled at the command line or using @code{target} attributes. For general
> > > +details, @pxref{Function Multiversioning}. There are further AArch64-specific
> > > +details available in the
> > > +@uref{https://github.com/ARM-software/acle/blob/main/main/acle.md#function-multi-versioning,
> > > +Arm C Language Extensions (ACLE) specification}.
> > > +
> > > +Some aspects of the ACLE specification are not yet supported. In particular,
> > > +the currently supported feature names are @code{rng}, @code{flagm}, @code{lse},
> > > +@code{fp}, @code{simd}, @code{dotprod}, @code{sm4}, @code{rdma}, @code{rdm}
> > > +(alias of @code{rdma}), @code{crc}, @code{sha2}, @code{sha3}, @code{aes},
> > > +@code{fp16}, @code{fp16fml}, @code{rcpc}, @code{rcpc3}, @code{i8mm},
> > > +@code{bf16}, @code{sve}, @code{f32mm}, @code{f64mm}, @code{sve2},
> > > +@code{sve2-aes}, @code{sve2-bitperm}, @code{sve2-sha3}, @code{sve2-sm4},
> > > +@code{sme}, @code{sb}, @code{predres}, @code{sme-f64f64}, @code{sme-i16i64} and
> > > +@code{sme2}.
> > > +
> > > @node AMD GCN Function Attributes
> > > @subsection AMD GCN Function Attributes
> > >
> > > @@ -6278,6 +6284,15 @@ default tuning specified on the command line.
> > > On the PowerPC, the inliner does not inline a
> > > function that has different target options than the caller, unless the
> > > callee has a subset of the target options of the caller.
> > > +
> > > +@cindex @code{target_clones} function attribute
> > > +@item target_clones (@var{options})
> > > +The @code{target_clones} attribute can be used to create multiple versions of a
> > > +function for different supported architectures, with one version for each
> > > +specifier in the options list. One of these version specifiers must be the
> > > +@code{default} version. The other supported target specifiers are
> > > +@code{cpu=power6}, @code{cpu=power7}, @code{cpu=power8}, @code{cpu=power9} and
> > > +@code{cpu=power10}. For more details, @pxref{Function Multiversioning}.
> > > @end table
> > >
> > > @node RISC-V Function Attributes
> > > @@ -6872,7 +6887,9 @@ will crash if the wrong kind of handler is used.
> > > @cindex @code{target} function attribute
> > > @item target (@var{options})
> > > As discussed in @ref{Common Function Attributes}, this attribute
> > > -allows specification of target-specific compilation options.
> > > +allows specification of target-specific compilation options. It can also be
> > > +used to create multiple versions of a single function
> > > +(@pxref{Function Multiversioning}).
> > >
> > > On the x86, the following options are allowed:
> > > @table @samp
> > > @@ -29431,11 +29448,58 @@ For the effects of the @code{hot} attribute on functions, see
> > > @section Function Multiversioning
> > > @cindex function versions
> > >
> > > -With the GNU C++ front end, for x86 targets, you may specify multiple
> > > -versions of a function, where each function is specialized for a
> > > -specific target feature. At runtime, the appropriate version of the
> > > -function is automatically executed depending on the characteristics of
> > > -the execution platform. Here is an example.
> > > +On some targets it is possible to specify multiple versions of a function,
> > > +where each version of the function is specialized for a different set of target
> > > +features. At runtime, characteristics of the execution platform are checked,
> > > +and the most appropriate version of the function is chosen to be executed
> > > +depending on the available architecture features. One of the versions will be
> > > +a "default" version, which will be chosen if none of the criteria for the other
> > > +versions are met.
> > > +
> > > +Function multiversioning is enabled by annotating the function versions with one
> > > +of three function attributes.
> > > +
> > > +The @code{target} attribute can be used on x86 targets. Multiversioning with
> > > +the @code{target} attribute is supported only in the C++ frontend. One version
> > > +must be explicitly labelled as the "default" version. The @code{target}
> > > +attributes will normally need to be included in any header file declarations,
> > > +to ensure that the correct function version is called from all translation
> > > +units. In translation units that don't include declarations with
> > > +the @code{target} attributes, any callers will always call the "default"
> > > +version directly.
> > > +
> > > +The @code{target_version} attribute can be used on AArch64 targets.
> > > +Multiversioning with the @code{target_version} attribute is supported only in
> > > +the C++ frontend. This attribute behaves similarly to the @code{target}
> > > +attribute. However, callers in any translation unit will always use the
> > > +versioned function, even if the @code{target_version} attributes aren't
> > > +included in that translation unit. This means that header files don't need to
> > > +include the @code{target_version} attributes, and the function can use a single
> > > +header file declaration (as if it were a normal unversioned function).
> > > +
> > > +The @code{target_clones} attribute can be used on AArch64, PowerPC and x86
> > > +targets. It behaves similarly to the @code{target_version} attribute, except
> > > +that only one copy of the function is included in the source file. The
> > > +attribute takes a list of version specifiers and produces one copy of the
> > > +function for each specifier. This is useful in cases where the compiler is
> > > +capable of generating optimized code (with autovectorization, for example)
> > > +using architecture features enabled only in the more specialized function
> > > +versions. For example, on PowerPC, compiling a function with
> > > +@code{target_clones("default,cpu=power9")} will create two function clones -
> > > +one compiled with @option{-mcpu=power9}, and another with the default options.
> > > +The @code{target_clones} attribute is available in the C, C++, D and Ada
> > > +frontends.
> > > +
> > > +Function multiversioning attributes do not propagate from a versioned
> > > +function to its callees, although a callee can still be optimised using the
> > > +caller's extra target features if it is inlined directly into the caller.
> > > +
> > > +For details of the target options supported on each target, refer to
> > > +@ref{AArch64 Function Attributes}, @ref{PowerPC Function Attributes},
> > > +and @ref{x86 Function Attributes}.
> > > +
> > > +Here is an example of function multiversioning on x86 using the @code{target}
> > > +attribute.
> > >
> > > @smallexample
> > > __attribute__ ((target ("default")))
> > > @@ -29474,16 +29538,28 @@ int main ()
> > > @}
> > > @end smallexample
> > >
> > > -In the above example, four versions of function foo are created. The
> > > -first version of foo with the target attribute "default" is the default
> > > -version. This version gets executed when no other target specific
> > > -version qualifies for execution on a particular platform. A new version
> > > -of foo is created by using the same function signature but with a
> > > -different target string. Function foo is called or a pointer to it is
> > > -taken just like a regular function. GCC takes care of doing the
> > > -dispatching to call the right version at runtime. Refer to the
> > > -@uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
> > > -Function Multiversioning} for more details.
> > > +In the above example, four versions of function foo are created. The first
> > > +version of @samp{foo}, with the target attribute @samp{"default"}, is the
> > > +default version. This version gets executed when no other target specific
> > > +version qualifies for execution on a particular platform. Other versions of
> > > +@samp{foo} are created by using the same function signature but with a
> > > +different target string. The function @samp{foo} can be called or a pointer to
> > > +it can be taken just like for a regular function. GCC takes care of doing the
> > > +dispatching to call the right version at runtime.
> > > +
> > > +Function multiversioning is implemented using the STT_GNU_IFUNC symbol type
> > > +extension to the ELF standard. This is the same mechanism used by the
> > > +@code{ifunc} attribute (@pxref{Common Function Attributes}). However, in this
> > > +case the compiler automatically generates a resolver function that checks which
> > > +features are available at runtime. This resolver uses GLIBC's hardware
> > > +capability bits, and therefore requires GCC to be configured to use GLIBC 2.23
> > > +or newer. The resolver is run once at startup, and the resulting function
> > > +pointer is then stored in the dynamic symbol table. When using the
> > > +@code{target_version} or @code{target_clones} attributes, the resolved ifunc
> > > +symbol uses the normal symbol name. When using the @code{target} attribute,
> > > +the normal symbol name is instead used by the default function version (which
> > > +is why @code{target} attributes for multiversioning need to be included in any
> > > +header file declarations as well).
> > >
> > > @node Type Traits
> > > @section Type Traits
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PING^4][PATCH v2] docs: Update function multiversioning documentation
2024-08-13 17:18 ` [PING^4][PATCH " Andrew Carlotti
@ 2024-08-14 3:53 ` Sandra Loosemore
0 siblings, 0 replies; 6+ messages in thread
From: Sandra Loosemore @ 2024-08-14 3:53 UTC (permalink / raw)
To: Andrew Carlotti, gcc-patches
Cc: Richard Biener, Richard Sandiford, Michael Meissner,
Jakub Jelinek, Joseph Myers, Gerald Pfeifer
On 8/13/24 11:18, Andrew Carlotti wrote:
> I'm still waiting for review for this patch. I've asked Richard
> Sandiford about it, and he'd like a docs maintainer to review the
> patch (so I've cc'd the rest of them now as well).
I'm sorry, I've seen this patch go by before, but every time I've looked
at it I get confused by which patch hunk belongs to which section, and
tracking which are just moving text around and which are new, and I
haven't had the time to build the manual with the patch and compare the
changed sections. So I can't comment right now on whether the
organization changes are OK.
Not being familiar with the functionality, I don't think I have anything
intelligent to say about it from a technical perspective, either. Has
someone else reviewed this for correctness already?
I did look it over again for other problems, and this is what jumped out
at me.
The reference to a requirement for ELF and GLIBC 2.23 buried in an
implementation details discussion concerns me. If this feature doesn't
work on non-ELF or non-GLIBC targets (Windows, bare-metal, Android...)
that's not an implementation detail, it's user-visible restriction and
needs to be documented up front.
Please get rid of all the future tense ("will") and write in the present
tense, assuming all the documented functionality is presently
implemented. :-)
There are multiple places where you need to do
s/at runtime/at run time/g
per https://gcc.gnu.org/codingconventions.html#Spelling
Also please
s/target specific version/target-specific version/
In this paragraph:
> +In the above example, four versions of function foo are created. The first
> +version of @samp{foo}, with the target attribute @samp{"default"}, is the
> +default version. This version gets executed when no other target specific
> +version qualifies for execution on a particular platform. Other versions of
> +@samp{foo} are created by using the same function signature but with a
> +different target string. The function @samp{foo} can be called or a pointer to
> +it can be taken just like for a regular function. GCC takes care of doing the
> +dispatching to call the right version at runtime.
I believe all of these @samp{} things should be @code{}, and you missed
adding markup to the first instance of "foo".
And here
> +Function multiversioning is implemented using the STT_GNU_IFUNC symbol type
@code{STT_GNU_IFUNC}, please.
-Sandra
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2024-08-14 3:53 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-04-30 16:10 [PATCH v2] docs: Update function multiversioning documentation Andrew Carlotti
2024-05-06 11:31 ` [PING gcc-14?][PATCH " Andrew Carlotti
2024-06-10 16:08 ` [PING][PATCH " Andrew Carlotti
2024-07-10 12:09 ` [PING^3][PATCH " Andrew Carlotti
2024-08-13 17:18 ` [PING^4][PATCH " Andrew Carlotti
2024-08-14 3:53 ` Sandra Loosemore
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).