On 6/30/2014 2:01 PM, Jeff Law wrote:
On 06/30/14 02:18, David Wohlferd wrote:
I don't have permissions to commit this patch, but I do have a release
on file with the FSF.
Problem description:
The text for using Explicit Register Variables is confusing, redundant,
and fails to make certain essential information clear.
Some specific problems:
- There is no reason to call this topic "Explicit Reg Vars" instead of
"Explicit Register Variables."
Agreed.
- Putting text on the "Explicit Register Variables" menu page (instead
of the Global or Local subpages) is redundant, since any text that
describes the usage of Global or Local register variables will have to
be repeated on the individual subpages.
OK.
- Vague promises of features that may some day be available are not
useful in documentation ("Eventually there may be a way of asking the
compiler to").
Can't disagree here. I believe this lame comment has been around for
20 years or longer at this point.
- Vague descriptions of things that "are reported" to work on certain
platforms are not useful ("On the SPARC, there are reports that").
I'd disagree. But what's more important here is the registers that
are available are a function of the ABI and for someone to attempt to
use this feature, they're going to have to be intimately aware of the
ABI of their target.
If we could say "On the SPARC, these registers can be used for" I'd be
tempted to leave it as an example. But saying "Well, someone once said
they thought it might work this way on this one specific platform" is
not helpful for either SPARC or non-SPARC users.
- Describing Local Register Variables as "sometimes convenient for use
with the extended asm feature" misses the point that this is in fact the
ONLY supported use for Local Register Variables.
What makes you believe that this feature is only useful for extended
asms? My recollection is that for the last 20+ years this feature has
served effectively as a pre-allocation of certain function scoped
objects into predetermined registers.
That's great feedback. The existing docs don't even mention that use.
If you have a link (or if you can put together a few sentences)
describing how you could use it for this, I'll add it and re-work the
text. And if you can think of any other common uses, I'd be glad to add
them too.
- Unambiguous statements such as "The following uses are explicitly
/not/ supported" when describing things such as calling Basic asm
discourage people from attempting to misuse the feature.
Not sure I really agree with this either. There's nothing inherently
wrong with someone trying to use a local register variable to try and
optimize code for example.
Umm. Well. Hmm. You haven't said this was a good idea or even that it
would work, so I guess the statement that there's nothing "inherently
wrong" with it is true. However, by explicitly stating it is not
supported, we would be making it clear that when the next release uses
registers in a slightly different way that wipes out all their
"improvements," we can say "we told you that wasn't a supported use of
this feature."
However, I'm prepared to remove or rework this statement if you feel
strongly.
ChangeLog:
2014-06-30 David Wohlferd <d...@limegreensocks.com>
* doc/extend.texi (Explicit Reg Vars): Rewrite and clarify.
* doc/implement-c.texi (Hints implementation): Use new name.
So in summary, I agree with most of what you've done. The question is
how to proceed at this point.
We could extract the non-controversial stuff and install it now and
iterate on the stuff still in the air until it's done. Or we could
iterate on the stuff still in the air and install the final update as
an single commit. I don't care much either way, do you have a
preference?
My preference would be to only do one checkin when we've got it right.
I *almost* sent this as an RFD to the gcc list. But it being such an
obscure area, I wasn't really expecting much response (see
https://gcc.gnu.org/ml/gcc-help/2014-04/msg00124.html for example). The
items listed in my "problem description" were only highlights. As you
have no doubt noticed, nearly all the text on these 2 pages got
modified. If you have feedback on any of the rest of the text, I'd love
to hear it.
dw
