The Embedded Rust Book

Beyond manual Mutex<RefCell<Option<T>>> patterns, several frameworks provide more efficient or ergonomic concurrency models:

RTIC (Real Time Interrupt-driven Concurrency)

RTIC uses static priorities to manage resource access. It tracks access to static mut variables (resources) at compile time, ensuring safety without the runtime overhead of RefCell or constant critical sections. It also supports:

• async tasks via an asynchronous executor.
• Message passing.
• Scheduled tasks.

Embassy

Embassy is an ecosystem focused on Rust's async/await syntax. It provides:

• An asynchronous executor supporting most MCU architectures.
• A Time library.
• Various HAL libraries.
• embassy-sync for synchronization primitives.

RTOS (Real-Time Operating Systems)

Traditional models like FreeRTOS or ChibiOS use threads and multitasking:

• Cooperative multitasking: Threads yield control.
• Preemptive multitasking: The OS swaps threads based on timers or interrupts.

Multi-core Concurrency

On multi-core systems, single-core critical sections (like cortex_m::interrupt::Mutex) are insufficient. You must use synchronization primitives designed for SMP (Symmetric Multi-Processing), which typically rely on atomic instructions to maintain atomicity across all cores.

Typestate programming is a design pattern where the current state of an object is encoded directly into its type. This allows you to use Rust's type system to enforce valid state transitions and prevent invalid operations at compile time.

In this pattern, different stages of an object's lifecycle are represented by different structs. For example, a Builder struct might represent an "unconfigured" state, while the final product struct represents a "ready to use" state. You transition between these states by calling methods that consume the current type and return a new type.

// A simplified example of state transition via types
pub mod foo_module {
    pub struct Foo {
        inner: u32,
    }

    pub struct FooBuilder {
        a: u32,
        b: u32,
    }

    impl FooBuilder {
        pub fn new(starter: u32) -> Self {
            Self { a: starter, b: starter }
        }

        pub fn double_a(self) -> Self {
            Self { a: self.a * 2, b: self.b }
        }

        pub fn into_foo(self) -> Foo {
            Foo { inner: self.a + self.b }
        }
    }
}

fn main() {
    // The type changes from FooBuilder -> Foo through method calls
    let x = foo_module::FooBuilder::new(10)
        .double_a()
        .into_foo();

    println!("{:#?}", x);
}

Hardware peripherals are typically controlled by writing to memory-mapped registers. A common way to expose this in Rust is to create a wrapper structure around a peripheral register block (often generated by tools like svd2rust).

While this approach provides a convenient API for modifying individual bits or fields, it has a significant drawback: it does not enforce the hardware's state machine logic. A simple bit-manipulation API allows a user to set fields that are invalid for the current mode (e.g., setting an output_mode while the pin is configured as an input), which can lead to undefined behavior on some hardware.

/// GPIO interface
struct GpioConfig {
    /// GPIO Configuration structure generated by svd2rust
    periph: GPIO_CONFIG,
}

impl GpioConfig {
    pub fn set_enable(&mut self, is_enabled: bool) {
        self.periph.modify(|_r, w| {
            w.enable().set_bit(is_enabled)
        });
    }

    pub fn set_direction(&mut self, is_output: bool) {
        self.periph.modify(|_r, w| {
            w.direction().set_bit(is_output)
        });
    }

    pub fn set_input_mode(&mut self, variant: InputMode) {
        self.periph.modify(|_r, w| {
            w.input_mode().variant(variant)
        });
    }

    pub fn set_output_mode(&mut self, is_high: bool) {
        self.periph.modify(|_r, w| {
            w.output_mode.set_bit(is_high)
        });
    }

    pub fn get_input_status(&self) -> bool {
        self.periph.read().input_status().bit_is_set()
    }
}

While ZSTs are efficient for static assignments, applications often require runtime flexibility (e.g., passing pins to functions that don't know the specific pin at compile time). HALs should provide type erasure methods to move pin properties from compile-time to runtime.

Typically, this involves a hierarchy of erasure:

1. erase_pin(): Converts a specific pin (e.g., PA0) into a generic port-pin type (e.g., PA).
2. erase_port(): Converts a port-pin type into a fully generic Pin type that tracks both port and pin number at runtime.

/// Port A, pin 0.
pub struct PA0;

impl PA0 {
    pub fn erase_pin(self) -> PA {
        PA { pin: 0 }
    }
}

/// A pin on port A.
pub struct PA {
    /// The pin number.
    pin: u8,
}

impl PA {
    pub fn erase_port(self) -> Pin {
        Pin {
            port: Port::A,
            pin: self.pin,
        }
    }
}

pub struct Pin {
    port: Port,
    pin: u8,
    // (these fields can be packed to reduce the memory footprint)
}

enum Port {
    A,
    B,
    C,
    D,
}

Microcontrollers typically use a real and linear address space (e.g., 0x0000_0000 to 0xFFFF_FFFF for 32-bit systems) without the virtual memory re-mapping provided by an MMU (Memory Management Unit) found in desktop systems.

In this linear space, different regions are assigned to different hardware components:

• RAM: Located at specific address ranges (e.g., 0x2000_0000).
• Flash ROM: Located at specific address ranges (e.g., 0x0000_0000).
• Peripherals: Instead of leaving the gaps between RAM and Flash empty, designers map peripheral interfaces to these remaining memory locations.

To interact with a peripheral, you write data to a specific memory address. This address acts as a hardware API. For example, writing a specific bit pattern to a configuration register address will change the hardware's behavior (like setting a SPI frequency) instead of storing data in RAM.