I have responded (inline of course<g>) to your comments. In each case
I've tried to lay out why I did what I did. If after reading this you
feel that my approach is wrong, let me know and we'll see if we can find
a balance.
I've only had a very brief look at the page so far (as others have said,
there is a lot there).
I'm going to ask a favor. As you read thru the doc, consider this
statement and decide if you are prepared to agree with it:
"All the technical details in this doc appear to be correct and
consistent with my understanding and experience with how inline asm works."
Yes, it may be that you find specific issues that need to be fixed
(Andrew has already found a few) which I'll try to address. And you may
want to add some caveats about your level of expertise. But when we're
done, I'm hoping you can give these docs that kind of endorsement. If
several people are willing to make that kind of statement, it's likely
to make the doc maintainers (who probably aren't inline asm experts
themselves) more comfortable accepting the patch.
But one thing I note is that you seem to have
examples from a variety of target processors, which is a very nice
point, but that you are not very clear about /which/ processor is used
in each example. It can also help to say what the assembly instructions
actually /do/.
I'm trying to tread a very fine line here. Picture 3 books: On the
left is a gcc reference book that *only* describes what how the asm
instruction works. On the right is a book that *only* describes how to
write assembler. And in between is a book that provides tricks, tips,
and optimizations about the best way to use the asm instruction to get
the best possible assembler output.
All 3 books are important. People really need all three to get the most
out of this feature. But when I wrote this text I specifically decided
against trying to squeeze books 2 & 3 into the gcc docs. So while I
have absolutely no idea what the "frob" instruction does (I copied the
frob example verbatim from the existing docs), I'm not convinced that
docs on gcc's asm instruction are the right place to describe it. If
frobbing(?) is important to you, you either need to already understand
what it is and how it works, or find an opcode reference for your platform.
Now, all that said, it's impossible to write examples and not do this to
some degree. Have I hit the right degree? Maybe not. More, if the lack
of description about the actual assembler results in the samples not
being useful, then clearly something must be done. I will say that in
my case I was able to work out how to use the asm goto, despite my
disappointing lack of frob-ish knowledge.
Mostly the samples in the doc are there to illustrate a point, rather
than to provide particularly useful code.
I think a lot of people looking for help with inline assembly will be
people working with embedded processors - it is more common for "normal"
programmers to have to do a little bit of inline assembly in the
embedded world.
I'm not going to disagree with you. However I will say that you are not
the first person to say that your specific platform is the one most
people need help with.
So it is good to include examples for such processors.
You might like to look at
<http://www.nongnu.org/avr-libc/user-manual/inline_asm.html> for
inspiration.
While I copied the existing examples for vax, powerpc, etc into my new
doc without running them, I would really prefer to be able to run the
samples before putting them in the docs. And I know squat about
embedded processors. Is this something you are willing to help do?
One thing I think would be nice for the complex examples is to show the
actual generated assembly code (from the ".s" file, or from an assembly
listing file).
I both absolutely agree, and think you are totally wrong. Speaking for
myself, I would find assembly listings in "intel" format for the x64 to
be very helpful. "att" listing for the powerpc, not so much.
Also, you remarked upon the length of the docs. While you didn't say
anything specifically negative, both you and Andrew are correct that all
this is pretty long (~13 pages if you print it). Adding opcode
tutorials, samples for more platforms, and assembly listings certainly
isn't going to make it any shorter. At some point you need to start
thinking about breaking the content up some more (see books 2 & 3 above).
While it's easy to say "let's put more stuff in the docs," more is not
always better. Eventually the essential information can become buried.
I think the gcc docs should stick to being a reference. Perhaps the gcc
wiki could be used to hold some of this additional information? If so,
perhaps even some of the existing content could be moved there.
I would also like to see a lot more emphasis on symbolic names (%[var]
rather than %0) - I think it is a style that can be more intelligible,
and is therefore often the best choice. /Writing/ inline assembly is
often quite hard - but /reading/ it is often even harder. Names rather
than numbers can help here.
Once I came to understand how the symbolic names worked, I began using
them exclusively for my own code. In fact, I describe them in the doc
as "more readable or more maintainable." (Ok, yes I hedged a bit, but I
didn't want to start some sort of style war.)
However, as you have pointed out, one of the biggest challenges with asm
is reading someone else's code. And, so far at least, my experience
shows that most examples and existing code use the numbers. I would
think the contradiction between what people see in the code they are
maintaining and docs that primarily use names might be confusing.
That said, if the docs go heavy towards the symbolic names, perhaps more
new code will use them, and I agree with you: that's a good thing.
Does anyone else have some opinions about symbolic names? And when you
reply, answer both based on what you know today, and what you needed
when you started.
dw
