Stable assembly operations

[japaric]

Triage(2018-08-21)

A pre-RFC discussing what should go in core::arch::arm have been opened in #184

Update - 2018-07-27

Intrinsics like __NOP are now available in core::arch::arm. Path towards stabilization is being discussed in rust-lang/stdarch#518 (comment).

Help wanted

We are looking for someone / people to help us write an RFC on stabilization of the ARM Cortex intrinsics in core::arch::arm. Details in #63 (comment).

---

One of the features that ties embedded development to the nightly channel is the asm! macro, and
by extension the global_asm! macro.

In some cases it's possible to turn an unstable asm! call into a stable FFI call that invokes some
subroutine that comes from a pre-compiled external assembly file. This alternative comes at the cost
of a function call overhead per asm! invocation.

In other cases the function call overhead of the FFI call breaks the intended semantics of the
original asm! call; this can be seen when reading registers like the Program Counter (PC) or the
Link Register (LR).

The asm! feature is hard to stabilize because it's directly tied to LLVM; rustc literally passes
the contents of asm! invocations to LLVM's internal assembler. It's not possible to guarantee that
the syntax of LLVM assembly won't change across LLVM releases so stabilizing the asm! feature in
its current form is not possible.

This ticket is about exploring making operations that require assembly available on the stable
channel. This proposal is not about stabilizing the asm! macro itself.

The main idea is that everything that requires assembly and can be implemented as external assembly
files should use that approach. For everything that requires inlining the assembly operation the
proposal is that the core crate will provide such functionality.

This idea is not unlike what's currently being done in stdsimd land: core::arch provides
functions that are thin wrappers around unstable LLVM intrinsics that provide SIMD functionality.
Similarly core::asm (module up for bikeshedding) would provide functionality that requires asm!
but in a stable fashion. Example below:

mod asm {
    mod arm {
        #[inline(always)]
        #[stable]
        pub fn pc() -> u32 {
            let r;
            unsafe { asm!("mov $0,R15" : "=r"(r) ::: "volatile") }
            r
        }

        #[inline(always)]
        #[stable]
        pub fn lr() -> u32 {
            let r;
            unsafe { asm!("mov $0,R14" : "=r"(r) ::: "volatile") }
            r
        }
    }
}

This way the functionality can be preserved across LLVM upgrades; the maintainers of the core
crate would update the implementation to match the current LLVM assembly syntax.

TODO (outdated)

• Come up with a list of assembly operations that are used in practice and that would need to be
  provided in core::asm.
  • I would appreciate some help making a Proof of Concept PR against cortex-m that moves
    most of the assembly operations to external assembly files by enabling some Cargo feature. What can't be moved to assembly files would be a candidate for inclusion in core::asm.
  • AVR
  • MSP430
  • RISCV

• The team will bring up this idea to the lang / compiler team during the Rust All Hands event.

cc @gnzlbg @nagisa could we get your thoughts on this? does this sound feasible, or does this sound
like a bad idea?

cc @dvc94ch @dylanmckay @pftbest could you help me identify assembly operations that require inline assemly on AVR, MSP430 and RICSV?

[gnzlbg]

Is there any sequence of instructions for which a single call to an asm! macro containing the whole sequence is not equivalent to a sequence of asm! macro calls with one call per instruction?

I am thinking here about compiling in debug mode without optimizations were the code generated might differ, potentially in ways that break it.

[nagisa]

I’ve always been a strong proponent of the "intrinsic" functions that map down to a single instruction. For example, instead of writing asm!("cpsid" ...), you’d call the function that would do the same, look the same and behave mostly the same as the asm call. Not only it is harder to mess up using these intrinsics, but compiler also gets more information about the code.

Of course they have their downsides, but for most of the use cases in embedded, intrinsics are more than sufficient. In my experience using the IAR toolchain, which exposes such intrinsics for most of the important instructions, I’ve only had to maintain assembly to implement exactly two things: atomic byte increment and the context switch handler. Both of them implemented in an external assembly file.

I believe that we could work on adding intrinsics to rustc (LLVM doesn’t have a platform intrinsic for ARM cpsid, for example, but it has a llvm.returnaddress for lr, llvm.read_cycle_counter for cycle count and llvm.read_register to read arbitrary registers) and then the wrappers to stdsimd.

... So basically, what your proposal says.

[nagisa]

@gnzlbg yes, compiler is free to insert whatever code it wishes between the separate asm! statements to satisfy the constraints. For example it could decide to spill and reload the registers between two asm! calls.

[gnzlbg]

Thanks @nagisa that makes sense.

So my opinion is that it only makes sense to do this after we have stabilized inline assembly, which kind of defeats the point of doing this in the first place.

IIUC the idea behind this is that if we expose the hardware ISA via intrinsics then nothing will break if LLVM changes the syntax or semantics of inline assembly because we will be able to fix this in core.

But this is the problem: core will break.

That is, somebody will need to fix core, and the amount of work required to fix core is linearly proportional to the usage of inline assembly within core. This might be a lot of work already, but if we go this route that will turn into a titanic amount of work.

The same would happen if we decided to add another backed to rustc and had to reimplement all usages of inline assembly in "Cretonne-syntax".

So IMO the only way to make upgrading to a new syntax/backend realistic is to turn the porting effort from O(N) in the usage of inline assembly to O(1).

The only way I can think of to achieve this is to stabilize the inline assembly macro enough (e.g. like this https://internals.rust-lang.org/t/pre-rfc-inline-assembly/6443), so that upgrading can be done in Rust by "just" mapping Rust's inline assembly syntax to whatever syntax a new or upgraded backed uses. This will be a lot of work, but at least its independent from how often inline assembly is used.

Once we are there, we might just as well stabilize inline assembly instead of pursuing this. Libraries that implement this can be developed in the ecosystem, and "core" intrinsics can continue to be added to stdsimd which already exposes some intrinsics via inline assembly (some core stdsimd modules like run-time feature detection are built around inline assembly).

Then there is also the issue that two consecutive asm! calls allow LLVM to insert code in between. This might not matter often in practice, but sounds a bit brittle to me.

[nagisa]

The intrinsics would be implemented in the backend, rather than libcore. While it is true, that it would increase burden when upgrading a backend, it wouldn’t be any greater than the burden of adapting whatever we stabilise as our inline assembly implementation.

[nagisa]

Then there is also the issue that two consecutive asm! calls allow LLVM to insert code in between. This might not matter often in practice, but sounds a bit brittle to me.

With volatile assembly statements, the "code" would be limited to code that would be necessary to satisfy the constraints of the asm! statements. So, I think just moves from and to memory.

[dvc94ch]

why can't global_asm! be stabilized? Isn't that just like an external assembly file?

for riscv it would be quite a few intrinsics I believe. this is what I'm doing to r/w csr regs:

#[cfg(target_arch = "riscv")]
macro_rules! csr_asm {
    ($op:ident, $csr:expr, $value:expr) => (
        {
            let res: usize;
            unsafe {
                asm!(concat!(stringify!($op), " $0, ", stringify!($csr), ", $1")
                     : "=r"(res)
                     : "r"($value)
                     :
                     : "volatile");
            }
            res
        }
    )
}

the $csr value isn't an operand that can be loaded from a register, so there would need to be an intrinsic for each csr.

[jcsoo]

For reference, here is ARM's C Language Extensions 2.0 document:

ARM® C Language Extensions Release 2.0

I believe these were implemented by ARM's in-house compilers and by GCC according to this page: 6.59.7 ARM C Language Extensions (ACLE)

I believe that the stdsimd group knows about the NEON extensions but probably hasn't put much thought into other ARM intrinsics. Having a standard to point to should make it easier to get them implemented.

For instance, section "8.4 Hints" describe wfi, wfe, sev, sevl, yield, and dbg. "8.7" describes nop, which I think already has a LLVM intrinsic defined since pretty much all instruction sets have some variant of that instruction. "10.1 Special Registers" cover a variety of special registers.

[dylanmckay]

could you help me identify assembly operations that require inline assemly on AVR

I've taken a look over the full instruction set listing, here's what stands out

Assembly operations that are often required for nontrivial programs:

• cli/sli instructions to globally enable or disable interrupts

Somewhat more obscure stuff:

• If watchdog timers are enabled by the programmer, the wdr instruction to be executed regularly otherwise the chip will immediately reset. WDR is short for "watchdog timer reset"
• The des instruction for DES encryption. Most existing software would do this in, well, software, so not major
• The sleep instruction - a la std::thread::yield()

Unlike AVR-GCC, LLVM transparently handles accesses to and from program memory, meaning that that whole class of operations doesn't require asm! magic.

Although currently unimplemented, I believe LLVM's atomic intrinsics directly could be mapped to the RMW atomic instructions (FWIW these map to something like cli; <operation>; sei

[gnzlbg]

I believe that the stdsimd group knows about the NEON extensions but probably hasn't put much thought into other ARM intrinsics.

stdsimd does offer some v7 and v8 intrinsics, at least rev and rbit.

[japaric]

I discussed this with @alexcrichton during Rust All Hands and he said he was fine with adding an stable API for assembly ops that have an unstable implementation (e.g. inline asm!). We'll make an RFC for the ARM Cortex-M ops, but first we have to figure out exactly what ops need to be inlined (will likely be less than 10 ops, maybe just 5 or so).

[gnzlbg]

@japaric would those go into std::arch ?