Message ID | 56E4E5D6.4030500@LimeGreenSocks.com |
---|---|
State | New |
Headers | show |
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
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. Most often, the target has only one flags register, and thus is an implied operand of many instructions. In this case, the operand should not be @@ -8105,6 +8106,43 @@ ``not'' @var{flag}, or inverted versions of those above @end table +For builds that don't support flag output operands, this example generates +code to convert the flags to a byte (@code{setc}), then converts the +byte back to flags (@code{if (a)} would generate a @code{testb}): + +@example +char a; + +#ifndef __GCC_ASM_FLAG_OUTPUTS__ + +/* If outputting flags is not supported. */ +asm ("bt $0, %1\n\t" + "setc %0" + : "=q" (a) + : "r" (b) + : "cc"); + +#else + +/* Avoid the redundant setc/testb and use the carry flag directly. */ +asm ("bt $0, %1" + : "=@@ccc" (a) + : "r" (b)); + +#endif + +if (a) + printf ("odd\n"); +else + printf ("even\n"); +@end example + +To see the improvement in the generated output, make sure optimizations +are enabled. + +Note: On the x86 platform, flags are normally considered clobbered by +extended asm whether the @code{"cc"} clobber is specified or not. + @end table @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}. @item "memory" The @code{"memory"} clobber tells the compiler that the assembly code