[DOC Patch] Add sample for @cc constraint

[David Wohlferd]

Thanks for the feedback.  While I agree with some of this, there are 
parts that I want to defend.  If after explaining why I did what I did 
you still feel it should be changed, I'm prepared to do that.

On 3/24/2016 8:00 AM, Bernd Schmidt wrote:
 > More problematic than a lack of documentation is that I haven't been 
able to find an executable testcase. If you could adapt your example for 
use in gcc.target/i386, that would be even more important.

It looks like Richard included some "scan-assembler" statements in the 
suites with the original checkin 
(https://gcc.gnu.org/viewcvs/gcc?view=revision&revision=225122). Is that 
not sufficient?  If not, I'm certainly prepared to create a couple 
executable cases for the next rev of this patch.

 >> +Do not clobber flags if they are being used as outputs.
 >
 > I don't think the manual should point out the obvious. I'd be 
surprised if this wasn't documented or at least strongly implied 
elsewhere for normal operands.

Well, *I* thought it was obvious, because it is both documented and 
implied elsewhere.

However, the compiler doesn't see it that way.  Normally, attempting to 
overlap 'clobbers' and 'outputs' generates compile errors, but not when 
outputting and clobbering flags.  I filed pr68095 about this (including 
a rough draft at a patch), but apparently not everyone sees this the way 
I do.

Outputting flags is new to v6, so changing the compiler to reject 
overlaps before the feature is ever released would be ideal.  If we try 
to patch this in v7, will it get rejected because it would break 
backward compatibility?

If we aren't going to change the code, then I decided it needed to be 
hammered home in the docs.  Because someday someone is going to want to 
do something more with flags, but they won't be able to because it will 
break backward compatibility with all the people who have written this 
the "obviously wrong" way.  Hopefully this text will serve as 
justification for that future someone to do it anyway.

That said, I'm ok with any of:

1) Leave this text in.
2) Remove the text and add the compiler check to v6.
3) Remove the text and add the compiler check to v7.
4) Leave the text in v6, then in v7: remove the text and add the 
compiler check.
5) (Reluctantly) remove the text and hope this never becomes a problem.

I'll update the patch with whichever option seems best.  If it were my 
choice to make, I'd go with #4 (followed by 3, 1, 5).  2 would actually 
be the best, but probably isn't realistic at this late date.

 >> +For builds that don't support flag output operands,
 >
 > This feels strange, we should just be documenting the capabilities of 
this feature. Other parts of the docs already show what to do without it.

While I liked using the #define to contrast how this used to work (not 
sure where you think we show this?) with how the feature makes things 
better, I think I prefer the shorter example you are proposing.  I'll 
change this in the next rev of the patch.

 >> +Note: On the x86 platform, flags are normally considered clobbered by
 >> +extended asm whether the @code{"cc"} clobber is specified or not.
 >
 > Is it really necessary or helpful to mention that here? Not only is 
it not strictly correct (an output operand is not also considered 
clobbered), but to me it breaks the flow because you're left wondering 
how that sentence relates to the example (it doesn't).

The problem I am trying to fix here is that on x86, the "cc" is implicit 
for all extended asm statements, whether it is specified or not and 
whether there is a flags output or not.  However, that fact isn't 
documented anywhere.  So, where does that info go?  It could go right by 
the docs for "cc", but since this behavior only applies to x86, that 
would make the docs there messy.

Since the 'output flags' section already has an x86-specific section, 
that seemed like a plausible place to put it.  But no matter where I put 
it in that section, it always looks weird for exactly the reasons you state.

I'll try moving it up by the "cc" clobber in the next rev.  Let me know 
what you think.

 >> +For platform-specific uses of flags, see also
 >> +@ref{FlagOutputOperands,Flag Output Operands}.
 >
 > Is this likely to be helpful? Someone who's looking at how to use 
flag outputs probably isn't looking in the "Clobbers" section?

People reading about "cc" may be interested in knowing that you can do 
something with flags other than clobbering them.  And of course this 
lets us put the note about "x86 always clobbers flags" in that other 
section.

dw