Inline assembly

[Amanieu]

A redesigned asm! macro, with a path to stabilization.

Rendered

Thanks to everyone involved in the inline asm project group for their feedback which helped make this RFC possible!

The discussion in this thread has grown rather large, so a new thread has been opened at #2873 where the discussion should continue.

[bstrie]

The initial implementation of this feature will focus on the ARM, x86 and RISC-V architectures.

A reasonable question to ask of this would be "is there anything in the design of this feature that precludes support for additional architectures, or is the feature sufficiently general that we do not (to the best of our ability) foresee any difficulty supporting additional architectures in a backwards-compatible way?" For example, elsewhere the document discusses how registers are highly architecture-specific; are registers the only place we would expect such different behavior, or are there other potential points of divergence? (I'm also not suggesting that we answer this question in the summary; perhaps in the Future Possibilities section.)

[Amanieu]

Yes, register definitions are basically the only thing needed to add support for a new architecture. This should be fairly straightforward once the basic infrastructure for inline asm is implemented.

[petrochenkov]

register definitions are basically the only thing needed to add support for a new architecture. This should be fairly straightforward

Unless it's something alien, like e.g. Intel GPU ISA 😄

[nagisa]

In practice the backend must have the inline assembly support for said target too. Not all of them do.

[bstrie]

It is also possible to specify different variables for the input and output parts of an inout operand

What sort of pattern necessitates the existence of this construction? Under what circumstances would one find themselves reaching for this? Does this need to exist if the same behavior can be achieved by either a mov inside the assembly or a let outside of it?

[nagisa]

Similarly what happens to the "input" end of the variable? Is it considered "move"d? If it is Copy, is it copied before the invocation of asm! (the same way as function calls would work?)

[Amanieu]

One of the main uses for this is to indicate an input register which is clobbered. This is represented as inout(reg) some_val => _.

[Amanieu]

Currently only Copy types are supported as asm operands. But otherwise the input part is essentially treated the same way as a function argument.

[joshtriplett]

@bstrie Even if you could do it with a mov instruction, telling the compiler where you left the variable's value allows the compiler to just treat that as the new location of the variable, which means the resulting assembly won't need a mov at all.

[bstrie]

The only exception is on x86 where the Intel syntax is used instead of GCC's AT&T syntax.

Can we see an example of Intel syntax being used with this macro?

[Amanieu]

All examples in this RFC use Intel syntax.

[joshtriplett]

In order to aid in mechanical translation of code, could we expose the appropriate syntax flags here, so that people can ask for AT&T syntax on x86, for instance? (That would make it easy for others to implement an asm_att! macro, for instance.)

And, of course, the alternatives section should mention the possibility of using AT&T syntax on all platforms and providing a flag for Intel syntax, in which case people could easily implement an asm_intel! macro for Intel syntax.

[Amanieu]

This is tricky to support reliably. In particular, GCC requires that all asm code in a compilation unit use the same syntax, so this would at least exclude the possibility of inline asm support with a GCC backend.

I would prefer if we simply chose a single asm syntax and stuck with it. Also note that this only affects x86 which has 2 asm syntaxes. Every other architecture only has a single standardized asm syntax.

[Lokathor]

Could it be a crate level setting, since each crate is a single translation unit?

[Amanieu]

I don't think that a crate-level setting will be enough if you take LTO into account. And even then, a crate-level setting won't work with inline functions.

[comex]

No need for that. You can switch syntaxes on-the-fly using assembler directives, .att_syntax and .intel_syntax noprefix: example.

Edit: This is supported by both GNU as and LLVM's assembler.

[Amanieu]

The issue is more with the register placeholders, since GCC needs to know whether to emit eax or %eax.

[comex]

Oh... good point. For the record, this only affects a hypothetical GCC backend, not LLVM, which supports inteldialect per asm block.

I suppose such a backend could always tell GCC to compile in Intel mode, and then just add the %s and $s itself.

[joshtriplett]

@Amanieu GCC supports prefixed registers even when in Intel syntax mode, and even with noprefix; noprefix just makes the prefixes optional. So a hypothetical GCC backend can (and should) always emit prefixes like % and $, always leave GCC in AT&T mode, and just wrap assembly blocks that use Intel syntax in .intel_syntax noprefix and .att_syntax.

[bstrie]

operand_expr := expr / "_" / expr "=>" expr / expr "=>" "_"

Should the exprs in this line be idents, or do we really support arbitrary expressions in all these locations?

[Amanieu]

We do want these to be full expressions. This allows for example using my_struct.field as an asm operand.

[bstrie]

its return type is defined as ! (never)

Ordinarily does asm! have a return type of ()?

[jonas-schievink]

Also, is there any difference between using noreturn and putting a call to unreachable_unchecked after the asm! block?

[Amanieu]

Yes, asm! has a return type of ().

Also, is there any difference between using noreturn and putting a call to unreachable_unchecked after the asm! block?

If you look at the "Mapping to LLVM IR" section, you'll see that's exactly what it does.

[jonas-schievink]

Yes, I saw this:

If the noreturn flag is set then an unreachable LLVM instruction is inserted after the asm invocation.

But I think unreachable_unchecked will result in the same code (modulo inlining, etc.). Do you think this has a performance impact, or is there another reason other than brevity to prefer the noreturn modifier?

[Amanieu]

I added the noreturn flag because I feel that it makes it more explicit that the asm never returns.

[Amanieu]

The main advantage is that the compiler handles name mangling for you.

[mark-i-m]

IMO, the main advantage is that it is inline, which is much easier to read than jumping to another file and makes it easier to deal with things like accessing globals or modifying rust variables.

@roblabla Is this documented somewhere? I've used a lot of naked functions with function calls etc, and it seems to work fine as long as your asm sets up the stack properly.

[mark-i-m]

Btw, I'm glad to discuss naked fn further, but perhaps we should do it in the tracking issue instead?

[bjorn3]

IMO, the main advantage is that it is inline, which is much easier to read than jumping to another file

You don't have to place global_asm!(); in a different file.

and makes it easier to deal with things like accessing globals or modifying rust variables.

👍

I've used a lot of naked functions with function calls etc, and it seems to work fine as long as your asm sets up the stack properly.

One example is the Redox interrupt handling.

[roblabla]

@mark-i-m

it is generally unsafe to write anything but inline assembly inside a naked function. The LLVM language reference describes this feature as having "very system-specific consequences", which the programmer must be aware of.

• https://github.com/rust-lang/rfcs/pull/1201/files#diff-e089b5aa9b57392ee8a5efa292856d1eR74

And

It is easy to quietly generate wrong code in naked functions, such as by causing the compiler to allocate stack space for temporaries where none were anticipated. There is currently no restriction on writing Rust statements inside a naked function, while most compilers supporting similar features either require or strongly recommend that authors write only inline assembly inside naked functions to ensure no code is generated that assumes a particular stack layout. It may be desirable to place further restrictions on what statements are permitted in the body of a naked function, such as permitting only asm!
statements.

• https://github.com/rust-lang/rfcs/pull/1201/files#diff-e089b5aa9b57392ee8a5efa292856d1eR200

There is an open PR to amend the naked fn RFC to explicitly deny various common misuses of it. Let's move naked function discussion there.

[matklad]

As someone who hasn't really used inline assembly in any language, I have a stupid question about how this feature works as a whole. I think I inferred this from RFC text, but I am not sure my understanding is correct (perhaps this is a content for the future user-level docs?).

This is how I think asm works, is this right ballpark?

So, what we fundamentally hope to achieve here is an ability to insert arbitrary instruction sequences into the generated machine code. I naively expect the solution along the lines of D DSL: we invent a syntax for specifying arbitrary instructions, and compiler produces the binary for us. From this point of view, specifying assembly as a string literal seems very odd.

Now, the reason why this doesn't work too well is that there are numerous fundamentally different CPU architectures (which are themselves moving targets), with fundamentally different institutions, and it is unreasonable to expect that the compiler would fully support all of them. Instead, we rely on the fact that each architecture has a dedicated external tool, an assembler, which is capable of turning assembler-specific syntax into machine code. Compiler more or less invokes the assembler as a black box. Compiler does not understand what mov in ""mov {}, 5" means. The only thing compiler needs to know is the interface. That's why the RFC rigorously specifies the grammar for register specification and flags, but doesn't actually tell us, what can be written between "".

However (and I think this is not spelled out explicitly, or have I just missed it?) we also ship a specific assembler (namely llvm assembler), with specific syntax, which rustc will use for asm! calls. So, to learn what I can actually put into "", I will need to read the docs of this assembler to understand the syntax, and then maybe the docs for the specific CPU/instruction set, to learn which instructions are available and provide which semantics.

Is this all at least somewhat reasonable description of the reality? :)

[Ixrec]

My understanding of past inline asm discussions is that the biggest issue was always the stability and portability implications of supporting inline asm at all (and to a lesser extent of exposing LLVM's asm syntax, which thankfully is no longer being proposed). Unless the Rust teams think these issues are now self-evident, we should probably make some explicit statements about them in the RFC.

Specifically, I think all of the following are intended to be true:

• The syntax of an asm!() invocation is part of the Rust language grammar, and would go into a future Rust spec, so all Rust compilers must be able to parse it. I'm not sure if this has any practical consequences today, but presumably we want to leave the door open for doing something like #[cfg(backend = "llvm")] where an asm!() might need to get parsed just so it can be discarded successfully.
• No Rust compiler is required to "actually implement" asm!(), because asm!()'s semantics are inherently target-specific and cannot be specified terms of any Rust Abstract Machine. Also, implementing asm!() for one target/backend combination does not require implementing it for any other target/backend combinations. Every toolchain gets to choose exactly how much inline asm it does or doesn't provide, independently of rustc, and still be a spec-compliant Rust compiler.
• rustc will commit to providing asm!() on the architectures listed in this RFC for as long as LLVM provides any sort of inline asm feature that makes this feasible to implement. So if LLVM makes backwards incompatible changes to its inline asm, rustc will be committed to adapt to those changes as part of its regular LLVM upgrades.
• But because LLVM has no stability promise on its inline asm (that hasn't changed, right?), and in theory could simply delete that feature without our consent, rustc cannot unconditionally guarantee stability for inline asm the way it can for most other language features (unless we do something "crazy" like fork LLVM or make Cranelift part of rustc). Or does this non-stability come from the system assemblers, and LLVM is just a middleman?
• At this time, we are not making any guarantees about alternate backends for rustc. So rustc is allowed to add backends that have no inline asm support. And if Cranelift ever provides inline asm, making stable versions of rustc use it would constitute an additional stability commitment (i.e. it'd need an RFC or an FCP on a PR).

If I am correct and all of these are intended, I think at least some of them should be made explicit in the RFC. Especially that part in bold.

Also, should we consider how this interacts with the target tier policy? At first blush, I would think any changes to inline asm support on tier 3 targets require no special approval, but any changes to inline asm support on tier 1 and 2 targets probably should get... I dunno, compiler team approval? And be included in release notes?

---

As for what's actually in the feature proposal, I have no objections, and (as another person who's never used inline asm in anger) @matklad's elaboration of the constraints matches my understanding of the constraints involved.

[Amanieu]

@matklad Yes, that sounds about right.

[mark-i-m]

But because LLVM has no stability promise on its inline asm (that hasn't changed, right?), and in theory could simply delete that feature without our consent, rustc cannot unconditionally guarantee stability for inline asm the way it can for most other language features (unless we do something "crazy" like fork LLVM or make Cranelift part of rustc).

In theory, yes, I think, but in practice, I would be pretty shocked if any mature C compiler (e.g. clang) dropped support for inline assembly, and since LLVM is the backend for clang, it's hard to imagine LLVM dropping support altogether.

That said, I'm not sure how stable the LLVM asm interface is. I haven't seen it change in the last few years though...

[Ixrec]

In theory, yes, I think, but in practice, I would be pretty shocked if any mature C compiler (e.g. clang) dropped support for inline assembly, and since LLVM is the backend for clang, it's hard to imagine LLVM dropping support altogether.

That said, I'm not sure how stable the LLVM asm interface is. I haven't seen it change in the last few years though...

I completely agree that it's "stable in practice", but since this has always been the thing explicitly cited by Rust teams in past inline asm discussions to answer "why isn't inline asm on stable yet?", it seems like something we need an official statement on.

I'm hoping the answer is that they were specifically concerned about LLVM changing their inline asm syntax (because independently specifying our own syntax completely solves that), or about muddying the messaging on Rust's stability promise too close to 1.0 (which I'd assume is no longer a concern), but I just don't know for sure.

[Amanieu]

• The syntax of an asm!() invocation is part of the Rust language grammar, and would go into a future Rust spec, so all Rust compilers must be able to parse it. I'm not sure if this has any practical consequences today, but presumably we want to leave the door open for doing something like #[cfg(backend = "llvm")] where an asm!() might need to get parsed just so it can be discarded successfully.

• No Rust compiler is required to "actually implement" asm!(), because asm!()'s semantics are inherently target-specific and cannot be specified terms of any Rust Abstract Machine. Also, implementing asm!() for one target/backend combination does not require implementing it for any other target/backend combinations. Every toolchain gets to choose exactly how much inline asm it does or doesn't provide, independently of rustc, and still be a spec-compliant Rust compiler.

• At this time, we are not making any guarantees about alternate backends for rustc. So rustc is allowed to add backends that have no inline asm support. And if Cranelift ever provides inline asm, making stable versions of rustc use it would constitute an additional stability commitment (i.e. it'd need an RFC or an FCP on a PR).

The intent is that all backends will supports asm!() in some form. If the backend doesn't support inline assembly natively then it can fall back to invoking an external assembler and generate an out-of-line call to the compiled asm blob. See the "Difficulty of support" section in the RFC for an example of how this would work.

• rustc will commit to providing asm!() on the architectures listed in this RFC for as long as LLVM provides any sort of inline asm feature that makes this feasible to implement. So if LLVM makes backwards incompatible changes to its inline asm, rustc will be committed to adapt to those changes as part of its regular LLVM upgrades.

• But because LLVM has no stability promise on its inline asm (that hasn't changed, right?), and in theory could simply delete that feature without our consent, rustc cannot unconditionally guarantee stability for inline asm the way it can for most other language features (unless we do something "crazy" like fork LLVM or make Cranelift part of rustc). Or does this non-stability come from the system assemblers, and LLVM is just a middleman?

There are two distinct parts to LLVM's inline assembly support:

• The first part is the constraint specification, which is the syntax that LLVM uses to specify operands in the asm code. AFAIK this isn't stable, but this RFC does not expose any of this directly, so this is fine.
• The second part is how the final asm string is interpreted, after all the string substitution to insert register names is completed. This is done by LLVM's integrated assembler, which implements the GNU assembler syntax (e.g. .section directive). We do expose this directly, but this is fine since non-LLVM backends can use an external GNU assembler to parse the generated asm code.

Finally, LLVM doesn't exist in a vacuum. As @mark-i-m said, clang is a big user, but keep in mind that Rust itself is also a big user of LLVM. Once Rust gets stable inline assembly support, LLVM will have a strong incentive to keep this support working correctly.

[recmo]

It's very common to have instructions (like add or mov) that accept inputs as both registers or memory. Specifying this as a rm constraint allows the compiler to do better register allocation/spilling.

That being said, LLVM currently ignores any freedom in the constraints and always picks memory:

Thus, it simply tries to make a choice that’s most likely to compile, not one that will be optimal performance. (e.g., given “rm”, it’ll always choose to use memory, not registers).

• LLVM LangRef 9 Section 'Constraint codes'

[Amanieu]

Also LLVM only really supports memory addressing modes for inline asm on x86. On ARM/AArch64 it will just perform the address calculation and put the result in a register.

[recmo]

This would be super useful for Intel ADCX/ADOX instructions for multi-precision integer math like in this assembly multiplication routine. Here it would be useful if I could specify the carry and overflow flags as inputs/outputs.

This is in line with what the LLVM instrinsics for these instructions do. See core::arch::x86_64::_addcarryx_u64.

Unfortunately, again it seems like LLVM just ignores it. As mentioned in rust-lang/stdarch#666 (comment), there is an open LLVM issue and it does not seem easy:

The X86 backend isn't currently set up to model the C flag and O flag separately. We model all of the flags as one register. Because of this we can't interleave the flag dependencies. We would need to do something about that before it makes sense to implement _addcarryx_u64 as anything other than plain adc.

• LLVM #41546

I would have used intrinsics instead of asm if it wasn't for this issue.

[comex]

I’m a little surprised this is already being RFCed. I was expecting we’d come up with a prototype implementation as a procedural macro first, within the working group. This could serve two purposes:

• If it supported transforming asm! to external assembly, it would serve as proof that that transformation is possible, settling the controversy over Cranelift. It could also serve as a basis for the actual implementation of that in rustc.
• It would let us get hands-on experience with what the new syntax feels like to use, and iterate on it if desired.

...Well, I say “we”, but I haven’t been contributing other than responding in some GitHub threads. I really appreciate the energy investment in moving this forward! I just think it might be good to start on that before finalizing the design… though I guess that can still happen before stabilization.

Edit: And I haven’t even expressed my wish for an implementation before, so I can’t really complain. I just thought we were still in a somewhat early phase in the working group.

[LukasKalbertodt]

As a general note: I'd like more "this is UB!" explanations in several places. Maybe the guide-level section could use a complete subsection explicitly explaining again that many things can lead to UB.

Currently only in a few places it explicitly says "UB". In most places it just says "you cannot" and "you must" and that the compiler can assume something. While people used to inline assembly will most certainly know that all of this is about UB, newcomers might not and might instead expect a compiler error or something.

[LukasKalbertodt]

I was actually confused by the name noreturn. I initially assumed this meant that there is no ret instruction (or similar) in the assembly. How about using diverging or diverge as the name instead?

[Amanieu]

I feel that noreturn expresses this better: execution never returns from the asm block.

[TethysSvensson]

Why does ip have aliases if it is unusable?

[Amanieu]

So that the compiler can provide better error messages ("unknown register" vs "disallowed register").

[TethysSvensson]

I am confused about this list. It is written as though it is an exhaustive list, and even goes so far as to mention a register only used in a fairly recent instruction set extension (k0 for x86).

Wouldn't it make more sense to just list a few examples here and keep an up-to-date list in the documentation?

[Amanieu]

The documentation for inline assembly will most likely be a verbatim copy of the contents of this RFC.

[TethysSvensson]

One of the problems I have with the current asm!() macro is that it does not at all feel like the error reporting story is on the same level of quality as the rest of rustc. See e.g. rust-lang/rust#15402

If I accidentally use reg here instead of "eax", will I get poor error messages from deep inside the belly of LLVM?

[roblabla]

Worth noting that your specific example won't be possible anymore, since as noted in the RFC, the input/output parameters will only accept raw numeric types (and pointers where it makes sense). Your wrapper struct would get rejected by the type checker.

There are other types of weird "low-level" llvm errors that can get reported when the feature is misused though. Notably, I remember getting really weird aborts when misusing constraints. Rustc will probably need to sanitize them before passing it to LLVM, making sure they make sense. Some things on the top of my head:

• Using the same named register twice as an input parameter (it's UB, LLVM accepts it and will either abort or does something weird)
• Using the same named register as both a clobber and an input or an output (UB, LLVM generates garbage, sometimes aborts)

[Amanieu]

The specification in this RFC and the validation it requires should eliminate the possibility of any LLVM internal error. For example, the RFC explicitly says this:

It is a compile-time error to use the same explicit register two input operand or two output operands.

[TethysSvensson]

In this case, the out instruction must use the al, ax or eax register per the instruction set reference.

If I accidentally wrote reg instead of "eax" in the example, would the error message be of the same quality as normal rust error messages (or at least using the same infrastructure wrt highlighting the span in question etc)?

Another concern is that it would potentially compile some of the time, when LLVM happens to allocate eax as its register of choice. Would that be possible?

[Amanieu]

If I accidentally wrote reg instead of "eax" in the example, would the error message be of the same quality as normal rust error messages (or at least using the same infrastructure wrt highlighting the span in question etc)?

LLVM has support for sending error messages from inline assembly back to rustc so that they can be displayed through rustc's normal error message functionality. This already works with the current asm! macro: https://play.rust-lang.org/?version=nightly&mode=release&edition=2018&gist=e5d9c3c74edc6e02858ec965abfd4d98

Another concern is that it would potentially compile some of the time, when LLVM happens to allocate eax as its register of choice. Would that be possible?

Yes it would sometimes compile fine and sometimes not, depending on the register selected by LLVM. There isn't much we can do about that.

[khimru]

More than cryptic error messages I fear silent errors without any error messages.

See here: https://godbolt.org/z/5d0MxL

As you can see if you would pass one-byte variable and request an "r" constraint (instead of "q" or "Q" constraint) LLVM is all to happy to make a mess out of your assembler (note how LLVM tries to return both y1 and y4 in the same eax register).

Will rustcc be able to detect and report that somehow?

[Amanieu]

That seems to be a bug in LLVM. It should not allocate the *H registers for inline assembly.

[amosonn]

The emitted code is correct, though: after the assembly block, it first stores al somewhere else, only then ah in the entire eax register. Technically, since you only asked for the short registers, you shouldn't have a way to e.g. zero-extend one of them and clobber the other. Should this be a strict guarantee, that you don't get the *h registers?

[Amanieu]

Yes, the way this RFC is currently written the *h registers are never chosen for operands (and I don't intend to change it).

The reason why I argue that LLVM's behavior is buggy is that Clang's inline asm is designed to emulate GCC's inline asm, and GCC never allocates *h for register operands.

I will submit a fix to LLVM as part of the asm! work.

[valarauca]

Small comment on source/destination semantics.

[valarauca]

Does this imply that x86 will use the format of mnemonic destination, source (like Intel Syntax) while every other platform will use mnemonic source, destination (like AT&T/GAS)? Because that'll extremely hurt portability/readability.

[Amanieu]

Every other architecture already uses mnemonic destination, source. x86 is the exception with AT&T syntax that reverses this order.

[valarauca]

Okay, so every platform is standardized to mnemonic dst, src?

This is a bit confusing, as I'm not sure if the Rust-Source is being specified, or the IR which is being transferred to the compiler.

So does this imply that on non-x86 platforms rustc will be responsible for re-ordering mnemonic arguments to the backend?

[Amanieu]

There is no reordering needed, all non-x86 platforms already use the correct ordering. The Intel/ATT syntax split is only a thing on x86.

[Amanieu]

I’m a little surprised this is already being RFCed. I was expecting we’d come up with a prototype implementation as a procedural macro first, within the working group.

Unfortunately we can't implement this with just a proc macro that wraps the existing asm! implementation because we need type information for validation and to emit the correct template modifiers for LLVM.