From patchwork Fri Jul 17 12:37:22 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kyrylo Tkachov X-Patchwork-Id: 497111 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 31C641401B5 for ; Fri, 17 Jul 2015 22:37:40 +1000 (AEST) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b=xxvjOHQY; dkim-atps=neutral DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :message-id:date:from:mime-version:to:cc:subject:references :in-reply-to:content-type; q=dns; s=default; b=MS52MyVnyjGbTEUJW fQJargL31kLa43wda/Kte69rYEzw9iGbslfuWNtf1tZPDYxMmphmyJ2URqEjSOD2 MoNh0RA92d4n+UI7O6A14YKhybV19cWog0G3XfkXYi3wYkyk4UxdKN1T3BS6xD0d pX7sHwR0DS3hPTThJrk3E0bUgA= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :message-id:date:from:mime-version:to:cc:subject:references :in-reply-to:content-type; s=default; bh=0WUh9sseNJ8jly8dOxBoi3M AydA=; b=xxvjOHQYqctiAs8Y9Qforbk9esTcJBULNht5QxeXdwQ4R+NjgRATs8l 58Pl9GWGOI2DJFQNX+ihTkH2ALqGDI6JgTzq/AWO4CZDZFeEg0M8sWFSPPMliBja TgDHsrAMU/3NnUte/9ybGsTiOrqfceOsyKMVyoKJW6pk7/5GQHUk= Received: (qmail 54180 invoked by alias); 17 Jul 2015 12:37:31 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 52797 invoked by uid 89); 17 Jul 2015 12:37:31 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.7 required=5.0 tests=AWL, BAYES_00, SPF_PASS autolearn=ham version=3.3.2 X-HELO: eu-smtp-delivery-143.mimecast.com Received: from eu-smtp-delivery-143.mimecast.com (HELO eu-smtp-delivery-143.mimecast.com) (207.82.80.143) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 17 Jul 2015 12:37:28 +0000 Received: from cam-owa2.Emea.Arm.com (fw-tnat.cambridge.arm.com [217.140.96.140]) by eu-smtp-1.mimecast.com with ESMTP id uk-mta-28-p_CvC3g2QH-YfUPVEkJjpA-1; Fri, 17 Jul 2015 13:37:22 +0100 Received: from [10.2.207.50] ([10.1.2.79]) by cam-owa2.Emea.Arm.com with Microsoft SMTPSVC(6.0.3790.3959); Fri, 17 Jul 2015 13:37:22 +0100 Message-ID: <55A8F702.2010602@arm.com> Date: Fri, 17 Jul 2015 13:37:22 +0100 From: Kyrill Tkachov User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.2.0 MIME-Version: 1.0 To: Sandra Loosemore CC: GCC Patches , Marcus Shawcroft , Richard Earnshaw , James Greenhalgh Subject: Re: [PATCH][doc][13/14] Document AArch64 target attributes and pragmas References: <55A7CBEE.9060706@arm.com> <55A874CE.80205@codesourcery.com> In-Reply-To: <55A874CE.80205@codesourcery.com> X-MC-Unique: p_CvC3g2QH-YfUPVEkJjpA-1 X-IsSubscribed: yes Hi Sandra, On 17/07/15 04:21, Sandra Loosemore wrote: > On 07/16/2015 09:21 AM, Kyrill Tkachov wrote: >> Hi all, >> >> This patch adds the documentation for the AArch64 target attributes and >> pragmas. >> >> Ok for trunk? > The content looks OK, but I have a bunch of nit-picky comments about > grammar, typos, markup, etc.... Thanks for the detailed feedback! Here's an updated version. Thanks, Kyrill 2015-07-17 Kyrylo Tkachov * doc/extend.texi (AArch64 Function Attributes): New node. (AArch64 Pragmas): Likewise. > >> +The following target-specific function attributes are available for >> +the AArch64 target and for the most part mirror the behavior of similar >> +command line options, but on a per-function basis: > s/command line option/command-line option/g > > It would be good to add a cross-reference to the section where the > command-line options are documented. I recommend splitting the > introductory sentence into two, like: > > The following target-specific function attributes are available for the > AArch64 target. For the most part, these options mirror the behavior of > similar command-line options (@pxref{AArch64 Options}), but on a > per-function basis. > >> + >> +@table @code >> +@item general-regs-only >> +@cindex @code{general-regs-only} function attribute, AArch64 >> +Indicates that no floating point or AdvancedSIMD registers should be > s/floating point/floating-point/ > s/AdvancedSIMD/Advanced SIMD/ > >> +used when generating code for this function. If the function explicitly >> +uses floating point code, then the compiler will give an error. This is > s/floating point code/floating-point code/ > s/will give/gives/ > >> +the same behavior as that of the command line option >> +@code{-mgeneral-regs-only}. > Please use @option markup instead of @code on option names throughout > this patch. > >> +@item cmodel= >> +@cindex @code{cmodel=} function attribute, AArch64 >> +Indicates that code should be generated for a particular code model for >> +this function. The behaviour and permissible arguments are the same as > s/behaviour/behavior/ > > (We prefer to consistently use American spellings throughout the GCC > documentation.) > >> +@item strict-align >> +@cindex @code{strit-align} function attribute, AArch64 > s/strit-align/strict-align/ > >> +The above target attributes can be specified as follows: >> + >> +@smallexample >> +__attribute__((target(""))) >> +int >> +f (int a) >> +@{ >> + return a + 5; >> +@} >> +@end smallexample >> + >> +where @code{} is one of the attribute strings specified above. > s//@var{attr-string}/g > >> +In this example @code{target("+crc+nocrypto")} will enable the @code{crc} >> +extension and disable the @code{crypto} extension for the function @code{foo} > s/will enable/enables/ > s/disable/disables/ > >> +is valid and will compile function @code{foo} for ARMv8-A with @code{crc} >> +and @code{crypto} extensions and tune it for @code{cortex-a53}. > s/will compile/compiles/ > s/tune/tunes/ > >> +@code{-mcpu=} optio or the @code{cpu=} attribute conflicts with the > s/optio/option/ > >> @@ -18159,6 +18299,19 @@ for further explanation. >> * Loop-Specific Pragmas:: >> @end menu >> >> +@node AArch64 Pragmas >> +@subsection AArch64 Pragmas >> + >> +The pragmas defined by the AArch64 target correspond to the AArch64 >> +target function attributes. They can be specified as below: >> +@smallexample >> +#pragma GCC target("") >> +@end smallexample >> + >> +where @code{} can be any string accepted as an AArch64 target >> +attribute. @xref{AArch64 Function Attributes} for more details >> +on the permissible values of @code{}. > s//@var{string}/g > > -Sandra > > commit 39b05898be3e1d91fed37db4192dd10c373c1418 Author: Kyrylo Tkachov Date: Fri May 22 12:06:10 2015 +0100 [doc][13/N] Document AArch64 target attributes and pragmas diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index b18d8fb..180d9e9 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2191,6 +2191,7 @@ GCC plugins may provide their own attributes. @menu * Common Function Attributes:: +* AArch64 Function Attributes:: * ARC Function Attributes:: * ARM Function Attributes:: * AVR Function Attributes:: @@ -3322,6 +3323,145 @@ easier to pack regions. @c This is the end of the target-independent attribute table +@node AArch64 Function Attributes +@subsection AArch64 Function Attributes + +The following target-specific function attributes are available for the +AArch64 target. For the most part, these options mirror the behavior of +similar command-line options (@pxref{AArch64 Options}), but on a +per-function basis. + +@table @code +@item general-regs-only +@cindex @code{general-regs-only} function attribute, AArch64 +Indicates that no floating-point or Advanced SIMD registers should be +used when generating code for this function. If the function explicitly +uses floating-point code, then the compiler gives an error. This is +the same behavior as that of the command line option +@option{-mgeneral-regs-only}. + +@item fix-cortex-a53-835769 +@cindex @code{fix-cortex-a53-835769} function attribute, AArch64 +Indicates that the workaround for the Cortex-A53 erratum 835769 should be +applied to this function. To explicitly disable the workaround for this +function specify the negated form: @code{no-fix-cortex-a53-835769}. +This corresponds to the behavior of the command line options +@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}. + +@item cmodel= +@cindex @code{cmodel=} function attribute, AArch64 +Indicates that code should be generated for a particular code model for +this function. The behavior and permissible arguments are the same as +for the command line option @option{-mcmodel=}. + +@item strict-align +@cindex @code{strict-align} function attribute, AArch64 +Indicates that the compiler should not assume that unaligned memory references +are handled by the system. The behavior is the same as for the command-line +option @option{-mstrict-align}. + +@item omit-leaf-frame-pointer +@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64 +Indicates that the frame pointer should be omitted for a leaf function call. +To keep the frame pointer, the inverse attribute +@code{no-omit-leaf-frame-pointer} can be specified. These attributes have +the same behavior as the command-line options @option{-momit-leaf-frame-pointer} +and @option{-mno-omit-leaf-frame-pointer}. + +@item tls-dialect= +@cindex @code{tls-dialect=} function attribute, AArch64 +Specifies the TLS dialect to use for this function. The behavior and +permissible arguments are the same as for the command-line option +@option{-mtls-dialect=}. + +@item arch= +@cindex @code{arch=} function attribute, AArch64 +Specifies the architecture version and architectural extensions to use +for this function. The behavior and permissible arguments are the same as +for the @option{-march=} command-line option. + +@item tune= +@cindex @code{tune=} function attribute, AArch64 +Specifies the core for which to tune the performance of this function. +The behavior and permissible arguments are the same as for the @option{-mtune=} +command-line option. + +@item cpu= +@cindex @code{cpu=} function attribute, AArch64 +Specifies the core for which to tune the performance of this function and also +whose architectural features to use. The behavior and valid arguments are the +same as for the @option{-mcpu=} command-line option. + +@end table + +The above target attributes can be specified as follows: + +@smallexample +__attribute__((target("@var{attr-string}"))) +int +f (int a) +@{ + return a + 5; +@} +@end smallexample + +where @var{@var{attr-string}} is one of the attribute strings specified above. + +Additionally, the architectural extension string may be specified on its +own. This can be used to turn on and off particular architectural extensions +without having to specify a particular architecture version or core. Example: + +@smallexample +__attribute__((target("+crc+nocrypto"))) +int +foo (int a) +@{ + return a + 5; +@} +@end smallexample + +In this example @code{target("+crc+nocrypto")} enables the @code{crc} +extension and disables the @code{crypto} extension for the function @code{foo} +without modifying an existing @option{-march=} or @option{-mcpu} option. + +Multiple target function attributes can be specified by separating them with +a comma. For example: +@smallexample +__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53"))) +int +foo (int a) +@{ + return a + 5; +@} +@end smallexample + +is valid and compiles function @code{foo} for ARMv8-A with @code{crc} +and @code{crypto} extensions and tunes it for @code{cortex-a53}. + +@subsubsection Inlining rules +Specifying target attributes on individual functions or performing link-time +optimization across translation units compiled with different target options +can affect function inlining rules: + +In particular, a caller function can inline a callee function only if the +architectural features available to the callee are a subset of the features +available to the caller. +For example: A function @code{foo} compiled with @option{-march=armv8-a+crc}, +or tagged with the equivalent @code{arch=armv8-a+crc} attribute, +can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc} +because the all the architectural features that function @code{bar} requires +are available to function @code{foo}. Conversely, function @code{bar} cannot +inline function @code{foo}. + +Additionally inlining a function compiled with @option{-mstrict-align} into a +function compiled without @code{-mstrict-align} is not allowed. +However, inlining a function compiled without @option{-mstrict-align} into a +function compiled with @option{-mstrict-align} is allowed. + +Note that CPU tuning options and attributes such as the @option{-mcpu=}, +@option{-mtune=} do not inhibit inlining unless the CPU specified by the +@option{-mcpu=} option or the @option{cpu=} attribute conflicts with the +architectural feature rules specified above. @node ARC Function Attributes @subsection ARC Function Attributes @@ -18164,6 +18304,7 @@ we do not recommend the use of pragmas; @xref{Function Attributes}, for further explanation. @menu +* AArch64 Pragmas:: * ARM Pragmas:: * M32C Pragmas:: * MeP Pragmas:: @@ -18180,6 +18321,19 @@ for further explanation. * Loop-Specific Pragmas:: @end menu +@node AArch64 Pragmas +@subsection AArch64 Pragmas + +The pragmas defined by the AArch64 target correspond to the AArch64 +target function attributes. They can be specified as below: +@smallexample +#pragma GCC target("") +@end smallexample + +where @code{@var{string}} can be any string accepted as an AArch64 target +attribute. @xref{AArch64 Function Attributes}, for more details +on the permissible values of @code{}. + @node ARM Pragmas @subsection ARM Pragmas