Request for discussion: Rewrite of inline assembler docs

[dw]

On 2/27/2014 8:12 PM, Andi Kleen wrote:
> dw<limegreensocks@yahoo.com>  writes:
>> 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."
> output makes no sense I think, only input.

For static functions, yes.  However won't static data have the same 
problem?  And static data could be input or output.

> You still need the part about the top-level asm, where input
> doesn't work.

Accessing variables from Basic asm has more problems than this. If you 
are inside a function that accesses globals from both asm and C, the 
results will probably be a mess.  That's why the current docs for Basic 
asm say:

"Safely accessing C data and calling functions from Basic |asm| is more 
complex than it may appear. To access C data, it is better to use 
Extended |asm|. "

However, you are right, more is needed.  How about:

"For asm blocks outside of functions (which must be Basic asm), be aware 
that 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."

>>> 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?
> Yes it should be made clear that this applies to top-level asm
> too.

I believe what you call "top level" the docs call "Basic asm." This same 
statement is in both sections.

> -Andi