diff --git a/text/2843-llvm-asm.md b/text/2843-llvm-asm.md new file mode 100644 index 00000000000..be29b54e0ce --- /dev/null +++ b/text/2843-llvm-asm.md @@ -0,0 +1,73 @@ +- Feature Name: `llvm_asm` +- Start Date: 2019-12-31 +- RFC PR: [rust-lang/rfcs#2843](https://github.com/rust-lang/rfcs/pull/2843) +- Rust Issue: [rust-lang/rust#70173](https://github.com/rust-lang/rust/issues/70173) + +# Summary +[summary]: #summary + +Deprecate the existing `asm!` macro and provide an identical one called +`llvm_asm!`. The feature gate is also renamed from `asm` to `llvm_asm`. + +Unlike `asm!`, `llvm_asm!` is not intended to ever become stable. + +# Motivation +[motivation]: #motivation + +This change frees up the `asm!` macro so that it can be used for the new +`asm!` macro designed by the inline asm project group while giving existing +users of `asm!` an easy way to keep their code working. + +It may also be useful to have an inline asm implementation available +(on nightly) for architectures that the new `asm!` macro does not support yet. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +The Rust team is currently in the process of redesigning the `asm!` macro. +You should replace all uses of `asm!` with `llvm_asm!` in your code to avoid breakage when the new `asm!` macro is implemented. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +All references to `asm!` inside the compiler will be changed to refer to `llvm_asm!` instead. +`asm!` will become a simple (deprecated) `macro_rules!` which redirects to `llvm_asm!`. +The deprecation warning will advise users that the semantics of `asm!` will change in the future and invite them to use `llvm_asm!` instead. The `llvm_asm!` macro will be guarded by the `llvm_asm` feature gate. + +# Drawbacks +[drawbacks]: #drawbacks + +This change may require people to change their code twice: first to `llvm_asm!`, and then to the new +`asm!` macro once it is implemented. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +We could skip the deprecation period and perform the renaming at the same time the new `asm!` macro +is implemented. However this is guaranteed to break a lot of code using nightly Rust at once without +any transition period. + +# Prior art +[prior-art]: #prior-art + +The D programming language also support 2 forms of inline assembly. The [first one][d-asm] provides an embedded DSL +for inline assembly, which allows direct access to variables in scope and does not require the use of clobbers, but is only available on x86 and x86_64. The [second one][d-llvm-asm] is a raw interface to LLVM's internal inline assembly syntax, which is available on all architectures but only on the LDC backend. + +[d-asm]: https://dlang.org/spec/iasm.html +[d-llvm-asm]: https://wiki.dlang.org/LDC_inline_assembly_expressions + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +None + +# Future possibilities +[future-possibilities]: #future-possibilities + +When the [new `asm!` macro][inline-asm-rfc] is implemented it will replace the current one. This +will break anyone who has not yet transitioned their code to `llvm_asm!`. No +silent miscompilations are expected since the operand separator will be changed +from `:` to `,`, which will guarantee that any existing `asm!` invocations will +fail with a syntax error with the new `asm!` macro. + +[inline-asm-rfc]: https://github.com/rust-lang/rfcs/pull/2873