unstable book: explaining how to properly use labels in inline asm

[tesuji]

We need a section explaining how to properly use labels in inline asm (i.e. only GAS local labels are allowed).

Originally posted in #76675 (comment)

[tesuji]

@rustbot modify labels: T-libs A-inline-assembly F-asm E-easy

[castarco]

Would be OK if I pick this task? @lzutao

[GroteGnoom]

@castarco Are you still working on this? If yes, could you claim it?

[tdelabro]

@GroteGnoom would this do the trick ?
If yes I will claim it and proceed to create the MR

Labels

The compiler is allowed to instantiate multiple copies of the asm! block, for example when the function containing it is inlined in multiple places. As a consequence, you should only use GNU assembler local labels inside inline assembly code. Defining symbols in assembly code may lead to assembler and/or linker errors due to duplicate symbol definitions.

Moreover due to a llvm bug, you cannot use 0 or 1 as label. So only labels in the 2-99 range are allowed.

# #![feature(asm)]
let mut a = 0;
unsafe {
    asm!(
        "mov {0}, 10",
	"2:",
	"sub {0}, 1",
	"cmp {0}, 3",
	"jle 2f",
	"jmp 2b",
	"2:",
	"add {0}, 2",
	out(reg) a
    );
}
assert_eq!(a, 5);

This will decrement a value from 10 to 3, then add 2 and store it in a.

This example show a few thing:

First that the same number can be used as a label multiple time in the same inline block.

Second, that when a numeric label is used as a reference (as an instruction operand, for example), the suffixes b (“backward”) or f (“forward”) should be added to the numeric label. It will then refer to the nearest label defined by this number in this direction.

[GroteGnoom]

@GroteGnoom would this do the trick ?

I don't know, I just wanted to clear up who was working on this issue. I guess you can just claim it anyway, since @castarco didn't respond.

[tdelabro]

@rustbot claim

[Mark-Simulacrum]

cc @Amanieu who's likely good reviewer for the PR, and may be able to give feedback on the preliminary summary above

[Amanieu]

@tdelabro The example looks good!

Keep in mind the documentation may have to change in the future depending on what we decide to do with labels in #81088 (comment).