Request for discussion: Rewrite of inline assembler docs

[dw]

On 2/27/2014 4:22 AM, Kyrill Tkachov wrote:
> On 27/02/14 11:07, Andrew Haley wrote:
>> Over the years there has been a great deal of traffic on these lists
>> caused by misunderstandings of GCC's inline assembler.  That's partly
>> because it's inherently tricky, but the existing documentation needs
>> to be improved.
>>
>> dw <limegreensocks@yahoo.com> has done a fairly thorough reworking of
>> the documentation.  I've helped a bit.
>>
>> Section 6.41 of the GCC manual has been rewritten.  It has become:
>>
>> 6.41 How to Use Inline Assembly Language in C Code
>> 6.41.1 Basic Asm - Assembler Instructions with No Operands
>> 6.41.2 Extended Asm - Assembler Instructions with C Expression Operands
>>
>> We could simply post the patch to GCC-patches and have at it, but I
>> think it's better to discuss the document here first.  You can read it
>> at
>>
>> http://www.LimeGreenSocks.com/gcc/Basic-Asm.html
>> http://www.LimeGreenSocks.com/gcc/Extended-Asm.html
>> http://www.LimeGreenSocks.com/gcc/extend04.zip (contains .texi, .patch,
>> and affected html pages)
>>
>> All comments are very welcome.
> Hi Andrew, dw,
>
> Thanks for doing this!

Thanks for taking the time to review it.

>
> In the Extended Asm documentation: Other format strings section:
> "'%=' outputs a number that is unique to each instruction in the 
> entire compilation."
>
> I find the term 'instruction' to be confusing here. From what I 
> understand the number is unique to each asm statement, which may 
> contain multiple assembly instructions. IMHO it would be clearer to 
> say "unique to each asm statement"

I'm not sure your text quite gets us there either.  If (as Richard 
suggests), the asm can get duplicated, I'd expect each to get a unique 
value for %=.  And I'd want to be clear about what happens if you do 
#define DO_SOMETHING asm("%=":).

How would you feel about:

"'%=' outputs a number that is unique to each instance of the asm 
statement in the entire compilation."

>
> Kyrill
>
>
>>
>> Andrew.
>>
>
>
>