diff mbox

[doc] Improve documentation of -fstrict-volatile-bitfields

Message ID 4CC67C52.5000905@codesourcery.com
State New
Headers show

Commit Message

Jie Zhang Oct. 26, 2010, 6:59 a.m. UTC 
This patch replaces "container's type" with "field's type". "Container" 
is confusing. It could be interpreted as the structure containing the 
bit-fields. It also documents the recent change I made to 
-fstrict-volatile-bitfields, i.e. packed attribute takes preference when 
it conflicts with -fstrict-volatile-bitfields because of strict alignment.

Is it OK?

Comments

Richard Kenner Oct. 26, 2010, 12:06 p.m. UTC | #1 
> Is it OK?

Yes, but two minor English issues (both mostly present in the original):

> +If the field has @code{packed} attribute, the access happens without
> +honoring the field type.  If the field doesn't have @code{packed}

"happens" seems an odd word here.  Perhaps "is done" or "is generated" or
(simpler) "the access honors".

> +attribute, the access happens honoring the field type.  Both are under the
>  assumption that the user knows something about the target hardware
>  that GCC is unaware of.

It's best to avoid the passive voice here, so "In both cases, GCC assumes
that the user ... that it is unaware of".

Also, is it really the case that if this switch is specified and both packed
and volatile are specified that volatile is ignored? I didn't see that in
your patch (so maybe it's done elsewhere), but if it is the case, then
I suggest a warning (though that's a separate patch).
diff mbox

Patch


	* doc/invoke.texi: Improve documentation of
	-fstrict-volatile-bitfields.

Index: doc/invoke.texi
===================================================================
--- doc/invoke.texi	(revision 165935)
+++ doc/invoke.texi	(working copy)
@@ -18120,8 +18120,8 @@ 
 @opindex fstrict-volatile-bitfields
 This option should be used if accesses to volatile bitfields (or other
 structure fields, although the compiler usually honors those types
-anyway) should use a single access in a mode of the same size as the
-container's type, aligned to a natural alignment if possible.  For
+anyway) should use a single access of the width of the
+field's type, aligned to a natural alignment if possible.  For
 example, targets with memory-mapped peripheral registers might require
 all such accesses to be 16 bits wide; with this flag the user could
 declare all peripheral bitfields as ``unsigned short'' (assuming short
@@ -18134,9 +18134,11 @@ 
 any portion of the bitfield, or memory-mapped registers unrelated to
 the one being updated.
 
-If the target requires strict alignment, and honoring the container
+If the target requires strict alignment, and honoring the field
 type would require violating this alignment, a warning is issued.
-However, the access happens as the user requested, under the
+If the field has @code{packed} attribute, the access happens without
+honoring the field type.  If the field doesn't have @code{packed}
+attribute, the access happens honoring the field type.  Both are under the
 assumption that the user knows something about the target hardware
 that GCC is unaware of.