[RFA:] alignof documentation shouldn't say it's a recommendation for non-strict-alignment targets

[RFA:] alignof documentation shouldn't say it's a recommendation for non-strict-alignment targets

[Hans-Peter Nilsson]

I've been alerted by a user that the GCC documentation
special-cases !STRICT_ALIGNMENT targets; it says __alignof__
reports "recommended" alignment.  That's bogus; GCC doesn't give
recommendations, it just tells what it does itself.  The
doubtful may find comfort in the comment above c-common.c:
c_alignof_expr: "Implement the __alignof keyword: Return the
minimum required alignment of EXPR, measured in bytes."

And of course, there's no target "recommendation" macro, so
there's no way to pass a recommendation down there from the
target description.  FWIW, I was unable to follow extend.texi
beyond the move to the doc subdir so I don't know where the
wording "recommended" comes from.

Here's a fix, instead hinting that the target ABI may have a say
in the alignment, like happens for x86, but still giving leeway
to port maintainers for increasing the alignment (though it'd
probably clash with a defined ABI).  I considered the @acronym
markup for "ABI", but as that's not done for other occurrences
in this file, it didn't seem appropriate.

Checked with "make info-gcc dvi-gcc" and inspecting the output
and complaints.

Ok to commit to trunk and 4.3?

	* doc/extend.texi (Alignment): Say that the ABI controls
	the __alignof__ for non-strict-alignment targets rather
	than being a recommendation.

Index: extend.texi
===================================================================
--- extend.texi	(revision 133082)
+++ extend.texi	(working copy)
@@ -3380,7 +3380,8 @@ designs, @code{__alignof__ (double)} is 
 
 Some machines never actually require alignment; they allow reference to any
 data type even at an odd address.  For these machines, @code{__alignof__}
-reports the @emph{recommended} alignment of a type.
+reports the smallest alignment that GCC will give 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

brgds, H-P

Re: [RFA:] alignof documentation shouldn't say it's a recommendation for non-strict-alignment targets

[Mark Mitchell]

Hans-Peter Nilsson wrote:

> Ok to commit to trunk and 4.3?
> 
> 	* doc/extend.texi (Alignment): Say that the ABI controls
> 	the __alignof__ for non-strict-alignment targets rather
> 	than being a recommendation.

OK, thanks.

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713