Request for discussion: Rewrite of inline assembler docs

[dw]

On 2/27/2014 9:35 AM, Andi Kleen wrote:
> Andrew Haley <aph@redhat.com> writes:
>
>> 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.
>
> It would be nice if you could include some discussion of the LTO
> reference problems.
>
> Something like:
>
> It is not legal to reference a static variable or function symbol from
> the assembler code, as the compiler may optimize unused symbols
> away. For inline asm in functions these should be referred as "m" input
> arguments. For top level asm the referenced symbol should be made global
> and marked with __attribute__((externally_visible)) .

What would you say to something like this:

"Since GCC does not parse the asm, it has no visibility of any static 
variables or functions it references.  This may result in those symbols 
getting discarded by GCC as unused.  To avoid this problem, list the 
symbols as inputs or outputs."

> And another common problem:
>
> For top level asm there is no guarantee the compiler outputs the
> statements in order.

Well, basic asm (which is the only thing you can use at top level) 
already says:

"Do not expect a sequence of |asm| statements to remain perfectly 
consecutive after compilation. To ensure that assembler instructions 
maintain their order, use a single |asm| statement containing multiple 
instructions. Note that GCC's optimizer can move |asm| statements 
relative to other code, including across jumps. "

Is something more needed?

> [unless -fno-toplevel-reorder is specified, but I'm not should mention that]
>
> -Andi