From patchwork Tue Apr 9 13:35:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Carlotti X-Patchwork-Id: 88244 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 9FC1D386101D for ; Tue, 9 Apr 2024 13:36:43 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from EUR02-DB5-obe.outbound.protection.outlook.com (mail-db5eur02on2073.outbound.protection.outlook.com [40.107.249.73]) by sourceware.org (Postfix) with ESMTPS id 29FC83858C39 for ; Tue, 9 Apr 2024 13:36:04 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 29FC83858C39 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=arm.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 29FC83858C39 Authentication-Results: server2.sourceware.org; arc=pass smtp.remote-ip=40.107.249.73 ARC-Seal: i=3; a=rsa-sha256; d=sourceware.org; s=key; t=1712669767; cv=pass; b=ethL6cVK2i6862R2bRUw5DsHBe2zPKthf3W66IZavfRBaWoqwfOEO0gyqrdpZQwDZ72XHa4GaYUOYpgLrO+qg640DKUe5Hh64fNJnxFRV8q2sCZaTA3N8rHJREUdMhFRInO5gY9ip4q5ylQTNnrZVMxsvzia0KmN0U1a1rAKqKM= ARC-Message-Signature: i=3; a=rsa-sha256; d=sourceware.org; s=key; t=1712669767; c=relaxed/simple; bh=NZzBFS4AuVt7XCLik85nk8uVc13SBcTeI+0tc23uEsg=; h=DKIM-Signature:DKIM-Signature:Date:From:To:Subject:Message-ID: MIME-Version; b=qRPnAoV2GM/dwiyFEdzh/AzkbbbcP/XpteJVv9L04IeI+h3v3769B+NhPgTlbNyrtQYfDebwAMqupvz9jzKP8JD+A3xke9K5vjYmx4WGw38No4mJZpA1z7UHcF3wFmGum8DpDwjf164XU/2y8wr+H3vmHn0GLJDJgjhEI/fGUt0= ARC-Authentication-Results: i=3; server2.sourceware.org ARC-Seal: i=2; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=pass; b=Br0xEJ+uxL5Bl3gzFcrC3yZOwFEIV1fGVWSHLybnV2u8ucqWdZktu0Wm2qXCfOSloZN0u0uCOdwPCLYAit+uY8weGYmn8zVDv+kL0FkGoBm/NGNmi+jhI10KgXM+gGBTxL9LbqYvqceG5bVG+Dl+9RzOUSOu+C6dfK1wuBNm8eg0OS1KG2BAG5vQNOGJ4TZD/a9VYH2b5MGHIoyEx2IGpXlIgkNWAiBTBbB63dMkZLZD24MvE7+JoYsPeB3turmf/eJbph/cKHCqpGLFzb3k7GqDy6tUbG8tD+k8l4YgK/uDnALLQHj/Qu4jlpS5rBGB3ods6BbMVZLAmXehNiXyNg== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=PCiR+PMs2alylN6DeusL2idNxtJWa9lNhy6utQJ3AsU=; b=fZCtTvzaDpKAjQ/wYgfwSfYhcOTPi9UM7rtETaxqRQEVKqugQ52Hw8vOaikhDTiAlFP4tzpjfa92MYiOv0MYdJ26LRBdFln7iUPyLlP624FqUPXAU97vygZ4OG/MVqdu+2p/sT2xhMmuRzdGB4yZOJ0fpVpw6FT/GXaTKAkrkhot8kS/ef9InjWC4TYiStJ9d9ADBmLgx/mH7nm9ytoJzSPwoEFOq/n1x6hpeTc48w6jRYorY7vx7DIyHwuuHG8+DR9PKO9+VMH8MZessaNgAzwpO0hM1mXHiVKOaVMav3vb5dl8By+/pdr2NGfEaP25j3AoRlT92ElMQ/1rMrGxMQ== ARC-Authentication-Results: i=2; mx.microsoft.com 1; spf=pass (sender ip is 63.35.35.123) smtp.rcpttodomain=gcc.gnu.org smtp.mailfrom=arm.com; dmarc=pass (p=none sp=none pct=100) action=none header.from=arm.com; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com; arc=pass (0 oda=1 ltdi=1 spf=[1,1,smtp.mailfrom=arm.com] dkim=[1,1,header.d=arm.com] dmarc=[1,1,header.from=arm.com]) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=PCiR+PMs2alylN6DeusL2idNxtJWa9lNhy6utQJ3AsU=; b=DU2bZtx86s8GZcUhq02Ya7x3/JiP5FxBCRC+TzFfWuRSygBqTI+lcfUunv3xCio9SI8CqruwHm9l/eHMuV2DpMIkCmpxPuJlGpYe2TuRYwNp7w3U+9X5fitHSRpiHmQ4onr3BCvGUVpfP3/1dbTBnjGszUpF5dER42+q+hW3PiU= Received: from AM4PR07CA0011.eurprd07.prod.outlook.com (2603:10a6:205:1::24) by DU2PR08MB10040.eurprd08.prod.outlook.com (2603:10a6:10:49f::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7409.46; Tue, 9 Apr 2024 13:36:01 +0000 Received: from AMS1EPF0000004A.eurprd04.prod.outlook.com (2603:10a6:205:1:cafe::12) by AM4PR07CA0011.outlook.office365.com (2603:10a6:205:1::24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7472.18 via Frontend Transport; Tue, 9 Apr 2024 13:36:01 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.35.35.123) smtp.mailfrom=arm.com; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com;dmarc=pass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 63.35.35.123 as permitted sender) receiver=protection.outlook.com; client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com; pr=C Received: from 64aa7808-outbound-1.mta.getcheckrecipient.com (63.35.35.123) by AMS1EPF0000004A.mail.protection.outlook.com (10.167.16.134) with Microsoft SMTP Server (version=TLS1_3, cipher=TLS_AES_256_GCM_SHA384) id 15.20.7452.22 via Frontend Transport; Tue, 9 Apr 2024 13:36:01 +0000 Received: ("Tessian outbound 9d16f63426bd:v300"); Tue, 09 Apr 2024 13:36:01 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: 119e56ba146ad08e X-CR-MTA-TID: 64aa7808 Received: from 7c9b0e152276.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id 726A54C6-23CD-48EB-B0B6-3D3D7EC38FC8.1; Tue, 09 Apr 2024 13:35:54 +0000 Received: from EUR01-DB5-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 7c9b0e152276.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Tue, 09 Apr 2024 13:35:54 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=c0ZJJgFw6ipdLV/dzaZQNr1XfptUMfH8cR2iNuajDpvBSnryQ4HAiBCFUTZoFn+ivwb5tNa8HH8fgoOmeGbz2+zieMgZaVotS6AVmpgAe2S52x5jv7nktG60ti/fX+biM2FZzZb8vDryd3miN1fcTI5EEC/iS+ievbgXGlxb8gm+Kx0L7RDIFMLtHrBqKwIAI9PTRz7tzK2S82mMKg22iqQRTNFyunNy97IxEuFnYJYmxB+tGJTK3tlE09SUmYBECIqEfGdxEIsXWgBbTJnwmTi6+Cq5hUpSej2n+vb/BkVPa8UD9qvq3/2zYc+cIobQRC5EXtxrl4ekDgWHuSpDMg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=PCiR+PMs2alylN6DeusL2idNxtJWa9lNhy6utQJ3AsU=; b=MpetSchTtRDVqCy6Rna36RaP9M+l9KCI7Ez8ylZgtzQpJ/zG/kD7lj6CipxglQon/dphE2qnS7jr/++u1BwbAyu2T2EqmdGpnZoUV1cujzsTLDEXNbc17Rpve9AKqUy6GGdbtemvc+ADFqe3SZFLQU5W6CxR9kRgNLoNqQwT3kjlupIWe6iGHy9DbiJTTyMPnDrDXJ3jkBkzKZEMLZvcWSc36X8W1CNZ0uK1EFa3GxQE5OCsFPcCYDL5mqMIO30ZLWMwk7T0RvhYRj4+J72SZ3tWV0NYqYTlwYXKqAVtBwYq3dRPxhZsAqMGdDPt4uF4HkuG9PztlD8cW24cvFXJkQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=PCiR+PMs2alylN6DeusL2idNxtJWa9lNhy6utQJ3AsU=; b=DU2bZtx86s8GZcUhq02Ya7x3/JiP5FxBCRC+TzFfWuRSygBqTI+lcfUunv3xCio9SI8CqruwHm9l/eHMuV2DpMIkCmpxPuJlGpYe2TuRYwNp7w3U+9X5fitHSRpiHmQ4onr3BCvGUVpfP3/1dbTBnjGszUpF5dER42+q+hW3PiU= Received: from AS8PR08MB6678.eurprd08.prod.outlook.com (2603:10a6:20b:398::8) by DU0PR08MB8881.eurprd08.prod.outlook.com (2603:10a6:10:47c::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7409.46; Tue, 9 Apr 2024 13:35:51 +0000 Received: from AS8PR08MB6678.eurprd08.prod.outlook.com ([fe80::791b:686b:e7b9:be90]) by AS8PR08MB6678.eurprd08.prod.outlook.com ([fe80::791b:686b:e7b9:be90%5]) with mapi id 15.20.7409.042; Tue, 9 Apr 2024 13:35:51 +0000 Date: Tue, 9 Apr 2024 14:35:48 +0100 From: Andrew Carlotti To: gcc-patches@gcc.gnu.org Subject: [PATCH] docs: Update function multiversioning documentation Message-ID: Content-Disposition: inline X-ClientProxiedBy: LO4P123CA0697.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:37b::12) To AS8PR08MB6678.eurprd08.prod.outlook.com (2603:10a6:20b:398::8) MIME-Version: 1.0 X-MS-TrafficTypeDiagnostic: AS8PR08MB6678:EE_|DU0PR08MB8881:EE_|AMS1EPF0000004A:EE_|DU2PR08MB10040:EE_ x-checkrecipientrouted: true NoDisclaimer: true X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: zlJDyY+H8P95CXptiK7gMamG8CJ5rXtwnUgMcb8bpyTOBSnJFyzelS3SetKHEvbi9G2d7UuvZVTkkKZhjVykitDlaxpEj3K/O/fxTQXue5hDKsdkNaxm97CwX/og97eCgp4ifSckXf0o1S7UobBdVKegasn5CJkQw5gfl/JDXYEaxMM3iYxSKq4QtWZTsOQ/G7+wH5qj85DcnFk4o5aT5wvJmn73sUSy1XqmcBh+XPJH8DPNFeXhbeZ0yyHH00ch6l7MR9lwHbvI8o2YmXJrv4Yc6tbxJkMO1WJNLPACpW0gUwNmun2bepIkRcT8O5BPsZyoejT8FwJksj8O02sucqXUS4WKrRvNoaLQWy3YdcPYUyI8yOtwjetBVzJJ4AxhU0nlbMGwrGFHWrK6IQoQTF04X/r/2jwfceqAYSQsXgV684+XCiRLD9hvz1If+0nBYK8INZ5amWxtVVWl9G0AU4DMC7vT9MnHvcwPMbyytKR9RcRgVmix0vKalD+XoDZGtzHwaHrJDuiPdU8+YSLebhvRAdfZaVlpJ7/thZbIsnplxy+IMumuuWI5FogHo9vg7qKE18dA1rcsyMTMR0+9IymLGKfLX67PpYR+XQvHzqPsYD4W1sE1bkQFT3Az9hQc X-Forefront-Antispam-Report-Untrusted: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:AS8PR08MB6678.eurprd08.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230031)(1800799015)(376005)(366007); DIR:OUT; SFP:1102; X-MS-Exchange-Transport-CrossTenantHeadersStamped: DU0PR08MB8881 X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: AMS1EPF0000004A.eurprd04.prod.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 31ee6e72-3850-4f13-0b5c-08dc5899ff4a X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: PYjhGxb8c30esP/MGgyEt4x/mLjjvRUlNCzKqsUyvTHXJMuDr6J18OnylvoNYncahXSZtkMhQFY1Vp9zCsJgE0ExykfYAHFiv1hMVicPSx4e73xIo68v2MJnkAuKvkyvYwme89VXb7e5Sf19PbjSruXmwSdLDIfhX2hFKYlt2ubWmGT7V4uLdfiFwAtYkH+HTiAeJI937ochnOppxeWOXHLOlJmyLaSeeBA3Jw5yQkB7hr4v3pXM4EeG6V77fJy5cPRR+OxIEkh7FC8iG7KMTdCN1RgMER3m93fP+Eowd8Sepiw0q+wzWNjNyu7EzxcNNyHHV3jAs/5XJZaksu+sIL/GFvnk6+ibsZq+G1MaFkTGILfwOxOdtSeluM0ztHjawRMYo+7S1+nRxYvValKL+Zx6QdId+70Mq0+Z/2gwTgQ2Agu3PuHZYeF6nE2qkqQEkO1vdIqi+/B6FPFMzTcWKpa3uJ4qDC1mtYSX+lEVanvrKPmFNmvWEvk5nuTWqd04/z2ma1W7wCpfgcaZdRWcLSeqnZ0fZYwUKuqsVEW9+1uvVpz2KAgij4Gu0kyfV9PtrxyRT+SKTmjRkzjCQN5i1TAnHMPjjju0NuAwysknUDMviPCWotul67qnDi75yJE6J5jGyKm1MYpeOrf6Frmi1WpnW5b5NPwVAu71KHVmlz8FbfqeO2eBvz7aP02RUDBtd8LcBxMTn/qNunL98kLBZA== X-Forefront-Antispam-Report: CIP:63.35.35.123; CTRY:IE; LANG:en; SCL:1; SRV:; IPV:CAL; SFV:NSPM; H:64aa7808-outbound-1.mta.getcheckrecipient.com; PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com; CAT:NONE; SFS:(13230031)(36860700004)(82310400014)(376005)(1800799015); DIR:OUT; SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 09 Apr 2024 13:36:01.5269 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 31ee6e72-3850-4f13-0b5c-08dc5899ff4a X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d; Ip=[63.35.35.123]; Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com] X-MS-Exchange-CrossTenant-AuthSource: AMS1EPF0000004A.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DU2PR08MB10040 X-Spam-Status: No, score=-10.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, FORGED_SPF_HELO, GIT_PATCH_0, KAM_DMARC_NONE, KAM_SHORT, RCVD_IN_BL_SPAMCOP_NET, RCVD_IN_MSPIKE_H2, SPF_HELO_PASS, SPF_NONE, TXREP, UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org 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. --- I've built and checked the info and dvi outputs. Ok for master? 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 7b54a241a7bfde03ce86571be9486b30bcea6200..78cc7ad2903b61a06b618b82ba7ad52ed42d944a 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -4178,18 +4178,27 @@ 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 attribute may override the original target command-line options, or it may +be combined with them in a target-specific manner. 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 +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. +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. + +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 @code{target("sse4a,arch=amdfam10")}. This is equivalent to @@ -4211,39 +4220,18 @@ 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. - @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 +4722,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{rpres}, @code{sve}, @code{f32mm}, @code{f64mm}, @code{sve2}, +@code{sve2-aes}, @code{sve2-bitperm}, @code{sve2-sha3}, @code{sve2-sm4}, +@code{sme}, @code{memtag}, @code{sb}, @code{predres}, @code{ssbs}, @code{ls64}, +@code{sme-f64f64}, @code{sme-i16i64} and @code{sme2}. + @node AMD GCN Function Attributes @subsection AMD GCN Function Attributes @@ -6278,6 +6286,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 +6889,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 @@ -29430,11 +29449,62 @@ 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 implemented using the STT_GNU_IFUNC symbol type +extension to the ELF standard. This is same mechanism used by the @code{ifunc} +attribute (@pxref{Common Function Attributes}). However, 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. + +Function multiversioning is enabled by annoting 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; this version retains the +original mangled name, and will therefore be called directly by any callers +from translation units compiled without the target version attributes. + +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, with two differences. Firstly, the @code{target_version} attribute +is optional on the default version; the use of multiversioning can be inferred +by the presence of other non-default versions of the function. Secondly, the +original mangled name is used for the dispatched version of the function; this +means that the specialized function versions can be accessed from other +translation units without needing to include the additional versions and +function attributes in header files. + +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 propogate from a versioned +function to its callees, although a callee can still be optimised using the +caller's extra target features if it has been inlined directly into the caller. + +Here is an example of function multiversioning on x86 using the @code{target} +attribute. @smallexample __attribute__ ((target ("default"))) @@ -29474,15 +29544,19 @@ 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 +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 +version qualifies for execution on a particular platform. Other versions +of foo are created by using the same function signature but with a +different target string. The function foo can be called or a pointer to it +can be taken just like a for 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. +Function Multiversioning} for more details of the implementation. + +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}. @node Type Traits @section Type Traits