From patchwork Thu Oct 25 18:35:26 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Martin Sebor X-Patchwork-Id: 989301 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=gcc.gnu.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=gcc-patches-return-488310-incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b="icHoe7Ur"; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="uII/CzY1"; dkim-atps=neutral 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 42gwmb6nGMz9sDC for ; Fri, 26 Oct 2018 05:35:42 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :subject:to:message-id:date:mime-version:content-type; q=dns; s= default; b=y0z2k1ssDl3L9BqFf/85NJ/+VTIbXYsLxFq1YBx5CNPIO4L4xd2NI TI2ZVBLElTUhCOFYkA4ftd3rdQChhbV+1nkbHxuG0H703jQNSk3bgUPShD55kBg5 ixiECyDcsAu/rv49f8OIiuZvFTGkJY2htAMsw8r5G32JZbiWaWo8f0= 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:from :subject:to:message-id:date:mime-version:content-type; s= default; bh=cQmBSFsDzFqmSwrqiMZUKzDad1Q=; b=icHoe7Urgf4NHFvLL3GS ML3cOUQPu7PaH7r1TWO6i13A00gG32C8+B1r82nWcZ0VNUsycLb1JIlx/VcWEDPL 6ek0s7Edyk6R6ZdEmk/HDxftaGahbyRPOpGQq5eSD239dtXI9pG4L+q/bOQBC3nA 7vjhWSo1HsViCfcRAmRbbL4= Received: (qmail 15435 invoked by alias); 25 Oct 2018 18:35:35 -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 15419 invoked by uid 89); 25 Oct 2018 18:35:34 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-16.7 required=5.0 tests=AWL, BAYES_00, FREEMAIL_FROM, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, SPF_PASS autolearn=ham version=3.3.2 spammy=presently, subsection, jointly, Numbers X-HELO: mail-qt1-f171.google.com Received: from mail-qt1-f171.google.com (HELO mail-qt1-f171.google.com) (209.85.160.171) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 25 Oct 2018 18:35:32 +0000 Received: by mail-qt1-f171.google.com with SMTP id r22-v6so11090791qtm.5 for ; Thu, 25 Oct 2018 11:35:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:subject:to:message-id:date:user-agent:mime-version; bh=x4+3nmxY8yaxd0eiLAnljkU9Ssey0iZZWZd7L1n5H+Q=; b=uII/CzY1xu9BlWBal19CNQ59Ead2LZfh0f9K43MOJ0MYMynIgt4UHGRl7ZZxCmHdex 0St87EBXL+kIoEz+0X5JqDh4OeKo0IOi6wooOfN+bAreqA22X0LIcYD7NYW/bnRfTa/c W2agkCr7plkDnxDBVZqzK7UjEp1Qs2Nz5v+rlO+CrRN1wHw0vX3yRFOyou9koAIsn8Bj Ld+89zockvOOzomAWP6xujzW79tHFxMdSV4LtHelbvpVXN7Jp9OFNkVTdjoQheYdu4OG hiA+ellKEYBbpsAWkhxopcDYLpD/91YO4GpTc3/0n1GgB8vOQ31mp4I4Hem5F4ozajUV oSjw== Received: from localhost.localdomain (184-96-239-209.hlrn.qwest.net. [184.96.239.209]) by smtp.gmail.com with ESMTPSA id f80-v6sm7649728qka.90.2018.10.25.11.35.27 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 25 Oct 2018 11:35:28 -0700 (PDT) From: Martin Sebor Subject: [doc PATCH] clarify attribute optimize and target syntax To: Gcc Patch List Message-ID: <38676b9a-683f-c455-80b3-3c6c5098074d@gmail.com> Date: Thu, 25 Oct 2018 12:35:26 -0600 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 MIME-Version: 1.0 X-IsSubscribed: yes While testing the optimize and target attributes and comparing the results to what the manual describes I noticed that some syntactic forms aren't fully documented for both attributes. Specifically, the optimize attribute doesn't mention that each string argument can be a comma-separated list of -f option suffixes, e.g., like so: __attribute__ ((optimize ("foo,bar"))) void f (void); (The target attribute does mention it.) The attached patch amends the manual to describe this feature consistently and in some detail. While I was there, I also made a few minor changes for consistency: besides adding the full syntactic form of the attribute (including arguments), I removed the quotes around the string argument (typically, in @var{string} the string isn't quoted), and corrected a minor grammatical issue. Martin gcc/ChangeLog: * doc/extend.texi (optimize): Clarify/expand attribute documentation. (target, pragma GCC optimize, pragma GCC target): Ditto. Index: gcc/doc/extend.texi =================================================================== --- gcc/doc/extend.texi (revision 265498) +++ gcc/doc/extend.texi (working copy) @@ -3193,22 +3193,33 @@ the standard C library can be guaranteed not to th with the notable exceptions of @code{qsort} and @code{bsearch} that take function pointer arguments. -@item optimize +@item optimize (@var{level}, @dots{}) +@item optimize (@var{string}, @dots{}) @cindex @code{optimize} function attribute The @code{optimize} attribute is used to specify that a function is to be compiled with different optimization options than specified on the -command line. Arguments can either be numbers or strings. Numbers -are assumed to be an optimization level. Strings that begin with -@code{O} are assumed to be an optimization option, while other options -are assumed to be used with a @code{-f} prefix. You can also use the -@samp{#pragma GCC optimize} pragma to set the optimization options -that affect more than one function. -@xref{Function Specific Option Pragmas}, for details about the -@samp{#pragma GCC optimize} pragma. +command line. Valid arguments are constant non-negative integers and +strings. Each numeric argument specifies an optimization @var{level}. +Each @var{string} argument consists of one or more comma-separated +substrings. Each substring that begins with the letter @code{O} refers +to an optimization option such as @option{-O0} or @option{-Os}. Other +substrings are taken as suffixes to the @code{-f} prefix jointly +forming the name of an optimization option. @xref{Optimize Options}. -This attribute should be used for debugging purposes only. It is not -suitable in production code. +@samp{#pragma GCC optimize} can be used to set optimization options +for more than one function. @xref{Function Specific Option Pragmas}, +for details about the pragma. +Providing multiple strings as arguments separated by commas to specify +multiple options is equivalent to separating the option suffixes with +a comma (@samp{,}) within a single string. Spaces are not permitted +within the strings. + +Not every optimization option that starts with the @var{-f} prefix +specified by the attribute necessarily has an effect on the function. +The @code{optimize} attribute should be used for debugging purposes only. +It is not suitable in production code. + @item patchable_function_entry @cindex @code{patchable_function_entry} function attribute @cindex extra NOP instructions at the function entry point @@ -3361,17 +3372,21 @@ This attribute adds stack protection code to the f flags @option{-fstack-protector}, @option{-fstack-protector-strong} or @option{-fstack-protector-explicit} are set. -@item target (@var{options}) +@item target (@var{string}, @dots{}) @cindex @code{target} function attribute Multiple target back ends implement the @code{target} attribute to specify that a function is to be compiled with different target options than specified on the -command line. This can be used for instance to have functions +command line. One or more strings can be provided as arguments. +Each string consists of one or more comma-separated suffixes to +the @code{-m} prefix jointly forming the name of a machine-dependent +option. @xref{Submodel Options,,Machine-Dependent Options}. + +The @code{target} attribute can be used for instance to have a function compiled with a different ISA (instruction set architecture) than the -default. You can also use the @samp{#pragma GCC target} pragma to set -more than one function to be compiled with specific target options. -@xref{Function Specific Option Pragmas}, for details about the -@samp{#pragma GCC target} pragma. +default. @samp{#pragma GCC target} can be used to specify target-specific +options for more than one function. @xref{Function Specific Option Pragmas}, +for details about the pragma. For instance, on an x86, you could declare one function with the @code{target("sse4.1,arch=core2")} attribute and another with @@ -3389,9 +3404,10 @@ int core2_func (void) __attribute__ ((__target__ ( int sse3_func (void) __attribute__ ((__target__ ("sse3"))); @end smallexample -You can either use multiple -strings separated by commas to specify multiple options, -or separate the options with a comma (@samp{,}) within a single string. +Providing multiple strings as arguments separated by commas to specify +multiple options is equivalent to separating the option suffixes with +a comma (@samp{,}) within a single string. Spaces are not permitted +within the strings. The options supported are specific to each target; refer to @ref{x86 Function Attributes}, @ref{PowerPC Function Attributes}, @@ -22404,30 +22420,32 @@ push_macro} and restored by @code{#pragma pop_macr @subsection Function Specific Option Pragmas @table @code -@item #pragma GCC target (@var{"string"}...) +@item #pragma GCC target (@var{string}, @dots{}) @cindex pragma GCC target -This pragma allows you to set target specific options for functions +This pragma allows you to set target-specific options for functions defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is as -if @code{attribute((target("STRING")))} was specified for that -function. The parenthesis around the options is optional. -@xref{Function Attributes}, for more information about the -@code{target} attribute and the attribute syntax. +specified. Each function that is defined after this point is treated +as if it had been declared with one @code{target(}@var{string}@code{)} +attribute for each @var{string} argument. The parentheses around +the strings in the pragma are optional. @xref{Function Attributes}, +for more information about the @code{target} attribute and the attribute +syntax. The @code{#pragma GCC target} pragma is presently implemented for x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. -@item #pragma GCC optimize (@var{"string"}...) +@item #pragma GCC optimize (@var{string}, @dots{}) @cindex pragma GCC optimize This pragma allows you to set global optimization options for functions defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is as -if @code{attribute((optimize("STRING")))} was specified for that -function. The parenthesis around the options is optional. -@xref{Function Attributes}, for more information about the -@code{optimize} attribute and the attribute syntax. +specified. Each function that is defined after this point is treated +as if it had been declared with one @code{optimize(}@var{string}@code{)} +attribute for each @var{string} argument. The parentheses around +the strings in the pragma are optional. @xref{Function Attributes}, +for more information about the @code{optimize} attribute and the attribute +syntax. @item #pragma GCC push_options @itemx #pragma GCC pop_options