This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [doc] Improve documentation of -fstrict-volatile-bitfields
- From: Jie Zhang <jie at codesourcery dot com>
- To: Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Cc: gcc-patches at gcc dot gnu dot org, mark at codesourcery dot com
- Date: Tue, 26 Oct 2010 23:58:33 +0800
- Subject: Re: [doc] Improve documentation of -fstrict-volatile-bitfields
- References: <4CC67C52.5000905@codesourcery.com> <11010261206.AA03335@vlsi1.ultra.nyu.edu>
On 10/26/2010 08:06 PM, Richard Kenner wrote:
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".
I modified my patch to use the first one you suggested.
+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".
Chnanged as you suggested.
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).
Yes, I did the change recently by another patch:
http://gcc.gnu.org/ml/gcc-patches/2010-10/msg01821.html
And there has been a warning for that in the patch.
The updated patch is attached. OK now?
Regards,
--
Jie Zhang
CodeSourcery
* doc/invoke.texi: Improve documentation of
-fstrict-volatile-bitfields.
Index: doc/invoke.texi
===================================================================
--- doc/invoke.texi (revision 165969)
+++ 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,11 +18134,13 @@
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
-assumption that the user knows something about the target hardware
-that GCC is unaware of.
+If the field has @code{packed} attribute, the access is done without
+honoring the field type. If the field doesn't have @code{packed}
+attribute, the access is done honoring the field type. In both cases,
+GCC assumes that the user knows something about the target hardware
+that it is unaware of.
The default value of this option is determined by the application binary
interface for the target processor.