[doc] document when GCC ignores attribute aligned

Last week we agreed to clarify that attribute aligned on a function
can decrease its alignment if it hasn't been previously declared
with one.  Attached is this change.

Besides the above, I also mention that the attribute specifies
the alignment of the first instruction of the function (in case
that wasn't obvious) , and that it has no effect in the absence
of a definition.

I wrote some tests to convince myself this actually works as
I expected.  Where it does I add those tests to the testsuite
via this patch.  Where it doesn't I opened a bug (PR 88345).

Martin

On 12/3/18 8:23 PM, Martin Sebor wrote:
> Last week we agreed to clarify that attribute aligned on a function
> can decrease its alignment if it hasn't been previously declared
> with one.  Attached is this change.
> 
> Besides the above, I also mention that the attribute specifies
> the alignment of the first instruction of the function (in case
> that wasn't obvious) , and that it has no effect in the absence
> of a definition.
> 
> I wrote some tests to convince myself this actually works as
> I expected.  Where it does I add those tests to the testsuite
> via this patch.  Where it doesn't I opened a bug (PR 88345).
> 
> Martin

> Index: gcc/doc/extend.texi
> ===================================================================
> --- gcc/doc/extend.texi	(revision 266766)
> +++ gcc/doc/extend.texi	(working copy)
> @@ -2386,16 +2386,20 @@ and may not be available on all targets.
>  @itemx aligned (@var{alignment})
>  @cindex @code{aligned} function attribute
>  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.
> +the first instruction of the function, measured in bytes.  When specified,
> +@var{alignment} must be an integer constant power of 2.  Specifying no
> +@var{alignment} argument implies the ideal alignment for the target,
> +which is often, but by no means always, 8 or 16 bytes.  The attribute

I think you might as well delete the end of the sentence starting with 
"which is often...".  It adds words but no useful information.  (Maybe 
it's 8 bytes, maybe it's 16 bytes, maybe it's something else....)

> +has no effect when a definition for the function is not provided in
> +the same translation unit.
>  
> -You cannot use this attribute to decrease the alignment of a function,
> -only to increase it.  However, when you explicitly specify a function
> -alignment this overrides the effect of the
> -@option{-falign-functions} (@pxref{Optimize Options}) option for this
> -function.
> +The attribute cannot be used to decrease the alignment of a function
> +previously declared with a more restrictive alignment; only to increase
> +it.  Attempts to do otherwise are diagnosed.  Some targets specify
> +a minimum default alignment for functions that is greater than 1.  On
> +such targets, specifying a less restrictive alignment is silently ignored.
> +Using the attribute overrides the effect of the @option{-falign-functions}
> +(@pxref{Optimize Options}) option for this function.
>  
>  Note that the effectiveness of @code{aligned} attributes may be
>  limited by inherent limitations in the system linker 

This patch is OK with the above nit fixed.

-Sandra

On 12/4/18 12:20 AM, Sandra Loosemore wrote:
> On 12/3/18 8:23 PM, Martin Sebor wrote:
>> Last week we agreed to clarify that attribute aligned on a function
>> can decrease its alignment if it hasn't been previously declared
>> with one.  Attached is this change.
>>
>> Besides the above, I also mention that the attribute specifies
>> the alignment of the first instruction of the function (in case
>> that wasn't obvious) , and that it has no effect in the absence
>> of a definition.
>>
>> I wrote some tests to convince myself this actually works as
>> I expected.  Where it does I add those tests to the testsuite
>> via this patch.  Where it doesn't I opened a bug (PR 88345).
>>
>> Martin
> 
>> Index: gcc/doc/extend.texi
>> ===================================================================
>> --- gcc/doc/extend.texi    (revision 266766)
>> +++ gcc/doc/extend.texi    (working copy)
>> @@ -2386,16 +2386,20 @@ and may not be available on all targets.
>>  @itemx aligned (@var{alignment})
>>  @cindex @code{aligned} function attribute
>>  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.
>> +the first instruction of the function, measured in bytes.  When 
>> specified,
>> +@var{alignment} must be an integer constant power of 2.  Specifying no
>> +@var{alignment} argument implies the ideal alignment for the target,
>> +which is often, but by no means always, 8 or 16 bytes.  The attribute
> 
> I think you might as well delete the end of the sentence starting with 
> "which is often...".  It adds words but no useful information.  (Maybe 
> it's 8 bytes, maybe it's 16 bytes, maybe it's something else....)

I added those words in r265498.  I was hoping to give people
an idea of roughly what they might expect because I couldn't
think of a good way to find out.  But since then I realized
that the __alignof__ operator can be used to query this
alignment and I agree that the sentence isn't helpful anymore
(maybe it never really was).  I've replaced it with a reference
to __alignof__ instead and checked in r266792.

Martin

> 
>> +has no effect when a definition for the function is not provided in
>> +the same translation unit.
>>
>> -You cannot use this attribute to decrease the alignment of a function,
>> -only to increase it.  However, when you explicitly specify a function
>> -alignment this overrides the effect of the
>> -@option{-falign-functions} (@pxref{Optimize Options}) option for this
>> -function.
>> +The attribute cannot be used to decrease the alignment of a function
>> +previously declared with a more restrictive alignment; only to increase
>> +it.  Attempts to do otherwise are diagnosed.  Some targets specify
>> +a minimum default alignment for functions that is greater than 1.  On
>> +such targets, specifying a less restrictive alignment is silently 
>> ignored.
>> +Using the attribute overrides the effect of the 
>> @option{-falign-functions}
>> +(@pxref{Optimize Options}) option for this function.
>>
>>  Note that the effectiveness of @code{aligned} attributes may be
>>  limited by inherent limitations in the system linker 
> 
> This patch is OK with the above nit fixed.
> 
> -Sandra