[DOC] Add sample for @cc constraint

The docs for the new(-ish) @cc constraint need an example. Attached.

ChangeLog:

2016-03-12  David Wohlferd  <dw@LimeGreenSocks.com>

     * doc/extend.texi: Add sample for @cc constraint

Note that while I have a release on file with FSF, I don't have write 
access to SVN.

dw

Ping?  (link to original post: 
https://gcc.gnu.org/ml/gcc-patches/2016-03/msg00743.html )

This patch adds a sample for a new-to-v6 feature.  Is this not the right 
time for doc improvements?

I considered adding some assembler output.  Something like:

------------------------
Before this feature, you had to write code like this:

    asm("bt $0, %1 ; setc %0" : "=q" (a) : "r" (value) : "cc");
    if (a)

This would generate code like this:

         bt $0, %ebx
         setc %al <--------- Convert flags to byte
         testb   %al, %al <------ Convert byte back to flags
         jne     .L5

Using @cc, this code

    asm("bt $0, %1" : "=@ccc" (a) : "r" (value) );
    if (a)

produces this output:

         bt $0, %ebx
         jc      .L5 <--------- Use the flags directly
----------------

While this helps show the benefit of the feature, it just seemed like 
too much detail.  Showing people the c code and reminding them to enable 
optimizations (what the current patch does) seems like it should be 
sufficient.

dw

On 3/12/2016 8:00 PM, David Wohlferd wrote:
> The docs for the new(-ish) @cc constraint need an example. Attached.
>
> ChangeLog:
>
> 2016-03-12  David Wohlferd  <dw@LimeGreenSocks.com>
>
>     * doc/extend.texi: Add sample for @cc constraint
>
> Note that while I have a release on file with FSF, I don't have write 
> access to SVN.
>
> dw

In principle we probably should have an example, but once again I have 
some problems with the style of the added documentation. I prefer 
concise writing without unnecessary repetition. Any other reviewers can 
of course override me, but the following is my opinion on these changes.

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.

On 03/13/2016 05:00 AM, David Wohlferd wrote:
> Index: extend.texi
> ===================================================================
> --- extend.texi	(revision 234163)
> +++ extend.texi	(working copy)
> @@ -8047,6 +8047,7 @@
>
>   Because of the special nature of the flag output operands, the constraint
>   may not include alternatives.
> +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.

> +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. Hence, reduce the example to this (plus the surrounding setup stuff):

> +/* Avoid the redundant setc/testb and use the carry flag directly.  */
> +asm ("bt $0, %1"
> +  : "=@@ccc" (a)
> +  : "r" (b));
> +
> +#endif

> +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).

>   @anchor{InputOperands}
> @@ -8260,6 +8298,8 @@
>   On other machines, condition code handling is different,
>   and specifying @code{"cc"} has no effect. But
>   it is valid no matter what the target.
> +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?


Bernd

On 03/24/2016 09:00 AM, Bernd Schmidt wrote:
> In principle we probably should have an example, but once again I have
> some problems with the style of the added documentation. I prefer
> concise writing without unnecessary repetition. Any other reviewers can
> of course override me, but the following is my opinion on these changes.
>
> 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.

FAOD, I've been keeping my mouth shut on this patch because I am not at 
all familiar with low-level x86 features, the example makes little sense 
to me, and I can't make any useful suggestions of my own about how to 
improve this section of the documentation.  :-(  Generally, though, I 
agree with Bernd's preference for conciseness and not wandering off into 
side discussions or repetition of material already covered elsewhere.

-Sandra

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

On 03/28/2016 12:03 AM, David Wohlferd wrote:
> 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.

I don't think it's sufficient. I would like executable code that 
verifies that this feature is indeed working as intended.

>  > 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.

Is there any _actual_ problem here? Like, if you combine the output and 
the clobber you run into problems? Looks to me like an explicit "cc" 
clobber is just ignored on x86. We just need to make sure this stays 
working (testcases).

>  >> +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.

My question would be, can this information ever be relevant to users? 
They may notice that their code still works if they omit the "cc", but 
that's not really a habit we want to encourage. I think this is an 
internal implementation detail that doesn't necessarily even have to be 
documented.


Bernd