From 8145e6a0cc1742d77feea78f08a004358ec1e6ea Mon Sep 17 00:00:00 2001 From: Martin Sebor Date: Thu, 25 Oct 2018 16:34:36 +0000 Subject: [PATCH] extend.texi (aligned): Expand attribute description. gcc/ChangeLog: * doc/extend.texi (aligned): Expand attribute description. (Alignment): Rename section. Discuss function arguments. From-SVN: r265498 --- gcc/ChangeLog | 5 +++++ gcc/doc/extend.texi | 55 +++++++++++++++++++++++++++++---------------- 2 files changed, 41 insertions(+), 19 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index f921ceb3f65..174bcbaee4d 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,8 @@ +2018-10-25 Martin Sebor + + * doc/extend.texi (aligned): Expand attribute description. + (Alignment): Rename section. Discuss function arguments. + 2018-10-25 Jan Hubicka * ipa-devirt.c (main_odr_variant): Remove. diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 25c821df776..edf87118147 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -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 function, 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,9 +6020,15 @@ The following attributes are supported on most targets. @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; @@ -6945,9 +6955,13 @@ The following type attributes are supported on most targets. @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,29 +7958,29 @@ You can use the sequence @samp{\e} in a string or character constant to 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. 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. 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,9 +7990,12 @@ 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 -- 2.30.2