Add reference for asm-goto

[nbdd0121]

The asm-goto-with-outputs is still unstable, so in the reference it's still mentioned as forbidden by a check rule.

Stabilization PR: rust-lang/rust#133870

[traviscross]

@Amanieu: What do you think?

[ehuss]

@rustbot author

[traviscross]

We reviewed this in the lang call today. Everyone read through it. It looked right. Nobody had any notes.

[traviscross]

In reading this more carefully (especially the lines not changed), I find myself wanting to double check that we're being precise enough now by what we mean by "the asm! block". Previously, when speaking about what happened during execution of "the asm! block", that meant only the execution of the assembly code. But now, given that the label blocks are lexically within the asm! block and may be executed during the execution of the asm! block, it would be reasonable to read "the asm! block" as to include that code also.

So when we say, e.g., that...

• pure: The asm! block has no side effects, must eventually return, and its outputs depend only on its direct inputs (i.e. the values themselves, not what they point to) or values read from memory (unless the nomem options is also set).

...or...

• nomem: The asm! block does not read from or write to any memory accessible outside of the asm! block.

...or...

• readonly: The asm! block does not write to any memory accessible outside of the asm! block.

...or even...

• nostack: The asm! block does not push data to the stack...

...do we mean for these to apply to the label blocks also? I wouldn't think so, but it's rather unclear in reading it.

[nbdd0121]

In reading this more carefully (especially the lines not changed), I find myself wanting to double check that we're being precise enough now by what we mean by "the asm! block". Previously, when speaking about what happened during execution of "the asm! block", that meant only the execution of the assembly code. But now, given that the label blocks are lexically within the asm! block and may be executed during the execution of the asm! block, it would be reasonable to read "the asm! block" as to include that code also.

So when we say, e.g., that...

• pure: The asm! block has no side effects, must eventually return, and its outputs depend only on its direct inputs (i.e. the values themselves, not what they point to) or values read from memory (unless the nomem options is also set).

GCC manual says "Also note that an asm goto statement is always implicitly considered volatile.", although AFAIU it's possible to represent a asm-goto in LLVM without the sideeffect modifier. Clang generates LLVM IR differently for asm goto and asm goto volatile, however LLVM doesn't seem to handle it specially (e.g. function containing a "pure" asm-goto block isn't treated as pure and is not optimised out).

It's not clear what exactly is pure for an asm goto block, since the control flow change is also one of its output. We probably should just forbid pure + label from being used together -- however note that since pure require an output operand, this is currently forbidden without a stable asm_goto_with_outputs feature.

...or...

• nomem: The asm! block does not read from or write to any memory accessible outside of the asm! block.

...or...

• readonly: The asm! block does not write to any memory accessible outside of the asm! block.

...or even...

• nostack: The asm! block does not push data to the stack...

...do we mean for these to apply to the label blocks also? I wouldn't think so, but it's rather unclear in reading it.

These would just mean the assembly themselves.