Re: extended asm docs - re-written

[Hendrik Greving <hendrik dot greving dot intel at gmail dot com>]

Along these lines, please apologize if this doesn't fit in this
thread, I was looking for what "%=" is doing in inline asm, and
finally found it in final.c (prints insn counter). It would have been
nice to have this documented in the extended inline asm description.
Regards,
Hendrik

On Mon, Apr 29, 2013 at 3:45 PM, dw <limegreensocks@yahoo.com> wrote:
> 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