[doc PATCH] document when GCC ignores attribute aligned

[Martin Sebor <msebor at gmail dot com>]

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

gcc/ChangeLog:

	* doc/extend.texi (attribute aligned): Expand.

gcc/testsuite/ChangeLog:

	* gcc.target/i386/attr-aligned-2.c: New test.
	* gcc.target/i386/falign-functions-3.c: New test.

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
+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 
Index: gcc/testsuite/gcc.target/i386/attr-aligned-2.c
===================================================================
--- gcc/testsuite/gcc.target/i386/attr-aligned-2.c	(nonexistent)
+++ gcc/testsuite/gcc.target/i386/attr-aligned-2.c	(working copy)
@@ -0,0 +1,28 @@
+/* Verify that valid alignment on either a function declaration
+   or a definition has the expected effect and overrides -Os.
+   { dg-do compile }
+   { dg-options "-Os" }  */
+
+#define ALIGN(n)         __attribute__ ((aligned (n)))
+
+/* No alignment specified (to cause the subsequent instruction
+   to be at an odd boundary due to -Os).  */
+void f (void) { }
+
+void f4 (void);
+
+ALIGN (4)
+void f4 (void) { }
+
+/* { dg-final { scan-assembler ".align 4\n\t.globl\tf4" } } */
+
+
+void g (void) { }
+
+
+ALIGN (4)
+void g4 (void);
+
+void g4 (void) { }
+
+/* { dg-final { scan-assembler ".align 4\n\t.globl\tg4" } } */
Index: gcc/testsuite/gcc.target/i386/falign-functions-3.c
===================================================================
--- gcc/testsuite/gcc.target/i386/falign-functions-3.c	(nonexistent)
+++ gcc/testsuite/gcc.target/i386/falign-functions-3.c	(working copy)
@@ -0,0 +1,23 @@
+/* Verify that attribute aligned overrides the effect of -falign-functions.
+   (But see PR 88345 showing that -Os overrides -falign-functions.)
+   The test may need to be adjusted if/when GCC implements PR 88231.
+  { dg-do compile }
+  { dg-options "-O2 -falign-functions=32" } */
+
+#define ALIGN(n)         __attribute__ ((aligned (n)))
+
+ALIGN (4)
+void f4 (void) { }
+
+/* { dg-final { scan-assembler ".align 4\n\t.globl\tf4" } } */
+
+
+void f32 (void) { }
+
+/* { dg-final { scan-assembler ".p2align 5\n\t.globl\tf32" } } */
+
+
+ALIGN (64)
+void f64 (void) { }
+
+/* { dg-final { scan-assembler ".align 64\n\t.globl\tf64" } } */