esp-rs/riscv-atomic-emulation-trap

An atomic emulation trap handler for non atomic RISCV targets

RISC-V atomic emulation trap handler

A replacement trap handler to emulate the atomic extension on silicon that does not have it.

Usage

We need to tell the Rust compiler to enable atomic code generation. We can achieve this by either setting some rustflags, like so

rustflags = [
# enable the atomic codegen option for RISCV
"-C", "target-feature=+a",
# tell the core library have atomics even though it's not specified in the target definition
"--cfg", "target_has_atomic_load_store",
"--cfg", 'target_has_atomic_load_store="8"',
"--cfg", 'target_has_atomic_load_store="16"',
"--cfg", 'target_has_atomic_load_store="32"',
"--cfg", 'target_has_atomic_load_store="ptr"',
# enable cas
"--cfg", "target_has_atomic",
"--cfg", 'target_has_atomic="8"',
"--cfg", 'target_has_atomic="16"',
"--cfg", 'target_has_atomic="32"',
"--cfg", 'target_has_atomic="ptr"',
]

or it is also possible to compile for a similiar target that has the atomic extension enabled. For example, a riscv32imc could use the riscv32imac target.

Finally, include this line in main.rs

use riscv_atomic_emulation_trap as _;

How it works

The final binary will have (atomic) instructions that the hardware does not support; when the hardware finds on of these instructions it will trap, this is where this crate comes in.

This crate overrides the default trap handler of the riscv-rt crate. By doing so it is possible to decode the instruction, check if is an instruction we can emulate, emulate it, and finally move the pc (program counter) forward to continue on with the program. Any instructions that cannot be emulated will be reported to the users exception handler.

Advantages of this crate

• Non-invasive. Other atomic emulation solutions require their dependancy in third party crates. However with this crate you just have to include it in your final binary.

Disadvantages of this crate

• Peformance penalty associated with context switching, emulating the instruction, then restoring the modified context. Based on limiting testing, you can expect a 2-4x slower execution compared to natively supported instructions.

Usage with riscv_rt

By default the riscv_rt does not store enough of the registers to perform atomic emulation when an exception occurs. You must override the trapping behavior to capture platform registers x0-x31. You can see an example of how this was done in v0.3 of this crate

riscv-atomic-emulation-trap's Issues

IllegalInstruction exception when using `embassy` in release mode

I opened an issue in embassy for this but I believe it actually belongs here.
Here is a minimally reproducible example.

Now, my understanding of all of this is very limited so take what I say with a grain of salt, but it appears as though either the atomics are not actually properly emulated, or that there is some sort of low level safety issue happening.

I have been able to confirm that if I don't use embassy and just try using a combination of core::sync::atomic and critical_section::Mutex and do stuff, I wasn't able to reproduce the issue. So using embassy appears to be the best way to reproduce the bug.

The bug only occurs when compiling for the -imac instruction set, and only when embassy is built with opt-level = 1 or higher. This code works as expected in opt-level = 0.

In case its helpful, here is some additional context from the esp-rs matrix server, where @Dirbaio did some digging into alternative workarounds that might make the trap handler obsolete. Please note that regardless, there is still a bug in the atomic trap handler

Incompatibility with portable-atomic

-imc targets that use this crate and add target-feature=+a (i.e. at least ESP32-C2, ESP32-C3) can't use portable-atomic. This is starting to become painful as atomic-polyfill is deprecated and the ecosystem has started moving away from it.