This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [DOC PATCH] Rewrite docs for inline asm
- From: dw <limegreensocks at yahoo dot com>
- To: Gerald Pfeifer <gerald at pfeifer dot com>
- Cc: James Greenhalgh <james dot greenhalgh at arm dot com>, gcc-patches at gcc dot gnu dot org, Joseph Myers <joseph at codesourcery dot com>, Hans-Peter Nilsson <hp at bitrange dot com>, Andrew Haley <aph at redhat dot com>, Richard Sandiford <rdsandiford at googlemail dot com>, Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Date: Mon, 05 May 2014 22:12:07 -0700
- Subject: Re: [DOC PATCH] Rewrite docs for inline asm
- Authentication-results: sourceware.org; auth=none
- References: <533F0C97 dot 2010206 at yahoo dot com> <alpine dot BSF dot 2 dot 02 dot 1404081759100 dot 23831 at arjuna dot pair dot com> <5344DAC3 dot 90005 at yahoo dot com> <alpine dot BSF dot 2 dot 02 dot 1404122053010 dot 48644 at arjuna dot pair dot com> <534A5BFD dot 3000906 at yahoo dot com> <alpine dot BSF dot 2 dot 02 dot 1404132037070 dot 39694 at arjuna dot pair dot com> <534B7F38 dot 9010605 at yahoo dot com> <20140425154343 dot GA30738 at arm dot com> <alpine dot LSU dot 2 dot 11 dot 1404251938320 dot 2591 at tuna dot site> <535D8CC3 dot 2000100 at yahoo dot com> <alpine dot LSU dot 2 dot 11 dot 1405031538450 dot 2827 at tuna dot site>
+A combination that works in most places is a newline to break the
+line, plus a tab character to move to the instruction field (written
+as "\n\t").
Will everyone know what an instruction field is? I'm not sure it's
that common of a term.
Hmm. I brought that text across unchanged from the original text. I
know what it means, but only because I've programmed in languages that
require it. I haven't seen an assembler that cares, but my cross
platform experience is weak.
I don't want to get into the business of describing how to format and
write assembler code. That's (well) beyond the scope of this doc.
What would you say to:
A combination that works in most places is a newline to break the
line, plus a tab character (written as "\n\t").
Yep, that sounds good.
Changed.
+operands. To separate the classes of operands, you use colons. Basic
+@code{asm} statements contain no colons. (So, for example,
+@code{asm("int $3")} is Basic @code{asm}, and @code{asm("int $3" : )}
is
+Extended @code{asm}. @pxref{Basic Asm}.)
What does "classes of operands refer to"? This does not seem to be
evident from the context.
Looking at it in context:
asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ :
[Clobbers] ] ] )
Looking at where the colons fall, they separate OutputOperands from
InputOperands and InputOperands from Clobbers. Observation suggests that
makes "OutputOperands", "InputOperands" and "Clobbers" the classes in
question.
On the other hand, I already knew what I meant. If this is unclear,
what would you suggest?
I also guessed what this meant, still I am wondering whether there
might be a better term for this than classes.
While I can think of some alternatives ("groupings?"), none of them seem
any clearer than "classes." asm is doing something unusual here, so
none of the familiar terms apply.
+GCC's optimizer sometimes discards @code{asm} statements if it
determines
+that it has no need for the output variables.
How about just saying "GCC", not referring to the optimizer here?
I'm pretty sure it only happens when running the optimizer.
There is just no such thing as "the GCC optimizer". There are many
optimizations that occur at different phases of translation, and
individual passes, just not one clearly demarked and defined optimizer.
That was behind my comment.
I have modified this (and all other occurrences) to be plural. That
seems to be consistent with the surrounding text when it uses this term.
+@code{DoCheck} routine. By omitting the @code{volatile} qualifier when
it
+isn't needed you allow the optimizer to produce the most efficient code
+possible.
How about "Only including ...when it is really necessary allows the
optimizer", that is, a more positive ("included" instead of "omitting")
approach?
Hmm. How strongly do you feel about this one? I'm ok with the current
text.
The current one text is okay, I just think making this more "active"
and defaulting to _not_ using it as oppoed to assume usage and omitting
in case is a bit better.
The problem is, I'm not convinced that's the way *users* approach it.
In my (still limited) experience, people use volatile simply because
they aren't quite sure what it does. They used it "just to be safe."
And that's true: At worst, including it when it isn't needed produces
inefficient code. Omitting it when it is needed produces incorrect
code. So it -is- safer.
But I want to break people from that mindset. They should understand
what it does and use it appropriately. That's why this 'volatile'
section is so long. I'm hoping that explaining and exampling and subtle
phrasing will move people in the right direction.
Let's queue this with the other "Joseph" changes.
I'm sorry if I'm leaving a mess for you guys to clean up. But even with
these bits unchanged, it's WAY better than it was.
+@headitem Modifier @tab Description @tab Operand @tab masm=att @tab
masm=intel
@code{masm...} ?
You think? It's not really code. How about @option?
Yes! That was me being stuck with too much web page work, where
we only have <code>.
Changed.
Given their involvement from the technical side, I'd suggest that
Andrew or Richard commit the patch after the last final tweaks from
your side.
So, at this point I have:
- Made the modifications described above.
- Updated the web pages on LGS.
- Produced the diff you requested of the changes since the last patch:
http://www.LimeGreenSocks/gcc/g02.zip
- Produced a new .patch file: http://www.LimeGreenSocks/gcc/extend08.zip
Unless I hear otherwise, I will post the updated patch (with a corrected
changelog) on this thread ~24 hours from this post.
It can then be committed as per usual.
dw