From patchwork Thu Oct 25 03:54:56 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Martin Sebor X-Patchwork-Id: 988897 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-488254-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="TaxlfCbq"; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="KyK50xab"; 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 42gYDf6KHGz9sDC for ; Thu, 25 Oct 2018 14:55:11 +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:to :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=aie3wom9df03NW00zL8fAxeCDUrT4SDXwHgPE/RN94LdiixAGr XcJlGJnc4OmoXzEQQB8V1LSSMw0aryzi3DF3na8ZIrwN9lHjJe8jVZ/LZf8Qyh9Y 0bf4roK12od58kCTGhIkYH8mURCt9UjFHaxJppscarARGso3oEiTEkuuk= 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:to :from:subject:message-id:date:mime-version:content-type; s= default; bh=SC8GlO97PuQWl7/pzr+waLaGLHw=; b=TaxlfCbqhJt549dgN/sj N9E5sGPOzne1MpXDxsAhqeJWMRhRejZzTm9EAX14q/MMcxNkLFh/tAfLwsdvF9Cb +/5Uf4QVKf94dLAdoUXbWml6cGYmgw+R+TAUH+IbZfl3f5FVqQebpBH7GntYDRu4 PlwW7Xt0Gmkm9DbQzY3f9xY= Received: (qmail 49987 invoked by alias); 25 Oct 2018 03:55:04 -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 49972 invoked by uid 89); 25 Oct 2018 03:55:03 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-16.8 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=designs, Dollar, _alignof, _Alignof X-HELO: mail-qt1-f170.google.com Received: from mail-qt1-f170.google.com (HELO mail-qt1-f170.google.com) (209.85.160.170) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 25 Oct 2018 03:55:01 +0000 Received: by mail-qt1-f170.google.com with SMTP id z2-v6so8328737qts.1 for ; Wed, 24 Oct 2018 20:55:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=to:from:subject:message-id:date:user-agent:mime-version; bh=oIERY7a4wcui5ycBcTrt5ojBjPIGr6ROS8HbzI5Ghro=; b=KyK50xabxmE5pUsUEyIAhsj/g/sVwLFKXuuypd3jVD/rv5e/g4cpEL7cvN2tmQZva2 lzNLeVMcLX3Mh6ys3Z420klF8iFiHISQDEnGnvlq9dq5qCSnbwYcFrWr8gdYvOIrgfqI sq13dGjkNSjbsiM42n/G61pdFo6oqXNo5X5DbFAWTXIq5KPWamREcm9TMp1VowMODv2d g/bRANJJUuWuTfpNhNjmCSXwUugQnW5z1AnH/CZ3pL77JAgL4VqonZxr2AbxXPqjkZGy bZsYv/W3ZSGhq9mflAP1gXRUnXqeiapmB+++68guNMSaerxLmM1AjVZZYDe04b43FtE/ Unzw== Received: from localhost.localdomain (184-96-239-209.hlrn.qwest.net. [184.96.239.209]) by smtp.gmail.com with ESMTPSA id n30-v6sm4450389qte.37.2018.10.24.20.54.58 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 24 Oct 2018 20:54:58 -0700 (PDT) To: Gcc Patch List From: Martin Sebor Subject: [doc PATCH] expand attribute aligned and __alignof__ Message-ID: <49bcf094-371f-67ee-fbd3-b2cae27cea62@gmail.com> Date: Wed, 24 Oct 2018 21:54:56 -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 The manual doesn't document the effects of attribute aligned with no argument. The __alignof__ section also doesn't discuss the effect of the operator on functions, and doesn't mention that it's okay to use void as an argument. The attached patch adds entries for the attribute form with no argument and text describing its effects, plus a description of __alignof__ with functions and void. Martin gcc/ChangeLog: * doc/extend.texi (aligned): Expand attribute description. (Alignment): Rename section. Discuss function arguments. Index: gcc/doc/extend.texi =================================================================== --- gcc/doc/extend.texi (revision 265478) +++ gcc/doc/extend.texi (working copy) @@ -66,7 +66,7 @@ extensions, accepted by GCC in C90 mode and in C++ * C++ Comments:: C++ comments are recognized. * Dollar Signs:: Dollar sign is allowed in identifiers. * Character Escapes:: @samp{\e} stands for the character @key{ESC}. -* Alignment:: Inquiring about the alignment of a type or variable. +* Alignment:: Determining the alignment of a functiom, type or variable. * Inline:: Defining inline functions (as fast as macros). * Volatiles:: What constitutes an access to a volatile object. * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. @@ -2380,10 +2380,14 @@ is not defined in the same translation unit. This attribute requires assembler and object file support, and may not be available on all targets. -@item aligned (@var{alignment}) +@item aligned +@itemx aligned (@var{alignment}) @cindex @code{aligned} function attribute -This attribute specifies a minimum alignment for the function, -measured in bytes. +The @code{aligned} attribute specifies a minimum alignment for +the function, measured in bytes. When specified, @var{alignment} must +be an integer constant power of 2. Specifying no @var{alignment} argument +implies the maximum alignment for the target, which is often, but by no +means always, 8 or 16 bytes. You cannot use this attribute to decrease the alignment of a function, only to increase it. However, when you explicitly specify a function @@ -6016,10 +6020,16 @@ The following attributes are supported on most tar @table @code @cindex @code{aligned} variable attribute -@item aligned (@var{alignment}) -This attribute specifies a minimum alignment for the variable or -structure field, measured in bytes. For example, the declaration: +@item aligned +@itemx aligned (@var{alignment}) +The @code{aligned} attribute specifies a minimum alignment for the variable +or structure field, measured in bytes. When specified, @var{alignment} must +be an integer constant power of 2. Specifying no @var{alignment} argument +implies the maximum alignment for the target, which is often, but by no +means always, 8 or 16 bytes. +For example, the declaration: + @smallexample int x __attribute__ ((aligned (16))) = 0; @end smallexample @@ -6945,9 +6955,13 @@ The following type attributes are supported on mos @table @code @cindex @code{aligned} type attribute -@item aligned (@var{alignment}) -This attribute specifies a minimum alignment (in bytes) for variables -of the specified type. For example, the declarations: +@item aligned +@itemx aligned (@var{alignment}) +The @code{aligned} attribute specifies a minimum alignment (in bytes) for +variables of the specified type. When specified, @var{alignment} must be +a power of 2. Specifying no @var{alignment} argument implies the maximum +alignment for the target, which is often, but by no means always, 8 or 16 +bytes. For example, the declarations: @smallexample struct S @{ short f[3]; @} __attribute__ ((aligned (8))); @@ -7944,14 +7958,14 @@ You can use the sequence @samp{\e} in a string or stand for the ASCII character @key{ESC}. @node Alignment -@section Inquiring on Alignment of Types or Variables +@section Determining the Alignment of Functions, Types or Variables @cindex alignment @cindex type alignment @cindex variable alignment -The keyword @code{__alignof__} allows you to inquire about how an object -is aligned, or the minimum alignment usually required by a type. Its -syntax is just like @code{sizeof}. +The keyword @code{__alignof__} determines the alignment requirement of +a function, object, or a type, or the minimum alignment usually required +by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. For example, if the target machine requires a @code{double} value to be aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. @@ -7958,7 +7972,7 @@ aligned on an 8-byte boundary, then @code{__aligno This is true on many RISC machines. On more traditional machine designs, @code{__alignof__ (double)} is 4 or even 2. -Some machines never actually require alignment; they allow reference to any +Some machines never actually require alignment; they allow references to any data type even at an odd address. For these machines, @code{__alignof__} reports the smallest alignment that GCC gives the data type, usually as mandated by the target ABI. @@ -7965,8 +7979,8 @@ mandated by the target ABI. If the operand of @code{__alignof__} is an lvalue rather than a type, its value is the required alignment for its type, taking into account -any minimum alignment specified with GCC's @code{__attribute__} -extension (@pxref{Variable Attributes}). For example, after this +any minimum alignment specified by attribute @code{aligned} +(@pxref{Common Variable Attributes}). For example, after this declaration: @smallexample @@ -7976,10 +7990,13 @@ struct foo @{ int x; char y; @} foo1; @noindent the value of @code{__alignof__ (foo1.y)} is 1, even though its actual alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. +It is an error to ask for the alignment of an incomplete type other +than @code{void}. -It is an error to ask for the alignment of an incomplete type. +If the operand of the @code{__alignof__} expression is a function, +the expression evaluates to the alignment of the function which may +be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). - @node Inline @section An Inline Function is As Fast As a Macro @cindex inline functions