Crate riscv_atomic_emulation_trap

source ·
Expand description

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

Constants

Functions

  • atomic_emulation⚠
    Takes the program counter address that triggered the exception and an array of registers at point of exception with PLATFORM_REGISTER_LEN length. Returns true if the instruction was atomic and was emulated, false otherwise.
  • is_atomic_instruction
    Checks if the instruction is an atomic one.