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)

[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).

[tdelabro]

@Amanieu Yeah I saw this thread while doing my researches. Do you suggest I include a link to this issues, or that I delay this #76704 until the resolution of #81088 ?

Imo the best would be for future release on this subject to also amend this section. Is there a way to make sure this happens every time ?

[Amanieu]

I'll make sure the documentation is updated when #81088 is resolved. In the meantime it would be best to add your section to the documentation.

[tdelabro]

My PR is here: #84015

I have question: Why other examples have their #[feature(asm)] line commented ? I make them fail to compile and run in the playground.

# #![feature(asm)]
unsafe {
    asm!("nop");
}

[Amanieu]

That just hides the line. If you click on the eye icon on the top right it will reveal the line.

However it seems that this gets put inside main which makes the attribute ineffective.

We didn't catch this because the tests were disabled on CI (it was using LLVM 9 at the time which didn't support the necessary features for asm!). However since we are now using LLVM 10 on CI you can now remove all the allow_fail so that the examples actually get tested.