j4flmao/agent-skills/bare-metal-rust

Bare-Metal Rust

Purpose

Rust removes whole classes of firmware bugs (buffer overruns, use-after-free, data races between ISR and main) at compile time while compiling to code comparable with C. This skill shows how to structure a no_std project, share state with interrupts soundly, pick between RTIC, Embassy and a plain superloop, and build/flash/debug with the standard toolchain.

Agent Protocol

Trigger

"embedded rust", "no_std", "cortex-m rust", "embedded-hal", "PAC", "svd2rust", "RTIC", "Embassy", "probe-rs", "defmt".

Input Context

• MCU family and existing HAL crate (e.g. stm32f4xx-hal, nrf-hal, rp2040-hal/embassy-rp, esp-hal)
• Concurrency model wanted (superloop, RTIC, Embassy async)
• Memory budget and whether an allocator is acceptable

Output Artifact

Rust code (main.rs, Cargo.toml, memory.x, .cargo/config.toml) or a review. No file unless requested.

Response Format

Target: {thumbv7em-none-eabihf | riscv32imac-unknown-none-elf | ...}
Stack: {PAC/HAL crate versions} + {RTIC | Embassy | superloop}
Shared state: {mechanism and why it is sound}
Code: {snippet}
Build/flash: {commands}

1. The no_std Environment

• #![no_std] links only core (and optionally alloc if you provide a #[global_allocator]). No threads, files, or heap by default.
• #![no_main] + cortex-m-rt's #[entry] provide the reset handler, vector table and memory.x linker layout.
• You must supply a panic handler: panic-halt, panic-probe (with defmt), or your own #[panic_handler].

#![no_std]
#![no_main]
 
use cortex_m_rt::entry;
use panic_halt as _;
 
#[entry]
fn main() -> ! {
    let dp = pac::Peripherals::take().unwrap();   // singleton: second take() returns None
    // configure clocks/GPIO via the HAL ...
    loop {
        cortex_m::asm::wfi();                     // sleep until an interrupt
    }
}

main returns ! — firmware never returns.

2. Crate Layers

Write drivers against embedded-hal traits so they run on any HAL.

3. Sharing State with Interrupts

static mut requires unsafe for every access, and in the 2024 edition creating references to it is denied by default (static_mut_refs). Use one of:

1. critical-section Mutex — portable, short critical sections:

use core::cell::RefCell;
use critical_section::Mutex;
 
static COUNTER: Mutex<RefCell<u32>> = Mutex::new(RefCell::new(0));
 
#[interrupt]
fn TIM2() {
    critical_section::with(|cs| *COUNTER.borrow_ref_mut(cs) += 1);
}
 
fn read_counter() -> u32 {
    critical_section::with(|cs| *COUNTER.borrow_ref(cs))
}

The CriticalSection token proves interrupts are masked (single core) while borrowing. Provide an implementation via cortex-m's critical-section-single-core feature or your HAL.

1. Atomics (core::sync::atomic) for single words — no masking. Cortex-M0/M0+ lacks CAS (fetch_add etc.); use portable-atomic there.
2. RTIC resources — compile-time priority-ceiling locking (below).
3. Embassy channels/signals (embassy-sync) between async tasks and interrupts.

4. Concurrency Frameworks

5. Memory Without a Heap

• heapless::{Vec, String, spsc::Queue, pool} — fixed capacity in the type (heapless::Vec<u8, 64>).
• static_cell::StaticCell to obtain &'static mut buffers once at startup (common with Embassy).
• If alloc is truly needed, use embedded-alloc with a static arena and handle allocation failure.
• Check stack usage: flip-link puts the stack below .data/.bss so overflow faults instead of silently corrupting statics.

6. Toolchain

# .cargo/config.toml
[build]
target = "thumbv7em-none-eabihf"      # Cortex-M4F/M7
 
[target.thumbv7em-none-eabihf]
runner = "probe-rs run --chip STM32F411CEUx"
rustflags = ["-C", "link-arg=-Tlink.x", "-C", "link-arg=-Tdefmt.x"]

• rustup target add thumbv7em-none-eabihf; cargo run --release flashes and streams logs.
• probe-rs (flash, RTT, GDB server) replaced most OpenOCD workflows; defmt + defmt-rtt give compact deferred-formatted logging.
• Size: cargo size --release (cargo-binutils); set opt-level = "s" or "z", lto = true, codegen-units = 1, panic = "abort" in the release profile.

7. Anti-Patterns

8. Checklist

• [ ] #![no_std], #![no_main], panic handler chosen deliberately
• [ ] Peripherals taken once; ownership moved into drivers/tasks
• [ ] Every ISR-shared value behind a sound primitive (no static mut)
• [ ] No heap, or a bounded allocator with failure handling
• [ ] Release profile optimised; size and stack measured; flip-link enabled
• [ ] Logs via defmt; flashing/debugging via probe-rs