$ show rust-embedded/cortex-m
This repository is the foundational Rust library for bare-metal development on ARM Cortex-M microcontrollers. It provides the essential runtime startup code (cortex-m-rt), low-level peripheral access (cortex-m), and debugging support (cortex-m-semihosting). The codebase implements critical safety mechanisms for embedded systems, such as preventing multiple instances of peripherals via the singleton pattern, ensuring correct stack alignment, and managing exception handling through sophisticated procedural macros. It serves as the bedrock for the Rust embedded ecosystem, enabling safe interaction with hardware registers and interrupt controllers without a standard library or operating system. The architecture is modular, separating the runtime (cortex-m-rt) from the peripheral access layer (cortex-m) and type traits (cortex-m-types). The startup code includes a robust linker script (link.x) that handles memory layout, vector table generation, and RAM initialization in assembly to guarantee correctness before Rust code executes. The repository also includes a comprehensive testsuite that runs on QEMU and physical hardware to validate interrupt handling, critical sections, and stack management across different Cortex-M variants (M0, M3, M4, M7, M33). This is a high-quality, production-grade library maintained by the Rust Embedded community. It demonstrates deep understanding of the ARM architecture, Rust's safety guarantees, and the constraints of embedded development. The code is heavily tested with compile-fail tests to ensure macro-generated code adheres to strict signatures and safety requirements.
The LLM identified 4 files worth highlighting for reuse:
Implements the reset handler and exception dispatching logic. It uses inline assembly to initialize the stack, enable the FPU, and jump to the user entry point. The code carefully manages the vector table, ensuring correct alignment and placement of exception handlers. It also implements the `__ONCE__` static to prevent linking multiple versions of the crate, a critical safety feature for embedded runtimes.
Contains the procedural macros (`entry`, `exception`, `interrupt`) that transform user code into valid Cortex-M handlers. It enforces strict function signatures at compile time, handles `static mut` variables safely by converting them to references, and generates the necessary trampoline functions for exception handling. The macro logic is complex but ensures that unsafe operations are contained and sound.
Defines the `Peripherals` struct which implements a singleton pattern to ensure only one instance of core peripherals (NVIC, SCB, SysTick, etc.) exists. It uses a static flag (`TAKEN`) protected by a critical section to prevent race conditions during initialization. This pattern is essential for preventing undefined behavior in bare-metal systems where multiple instances could lead to hardware conflicts.
Provides a `critical-section` implementation for single-core Cortex-M systems. It disables interrupts globally to protect shared resources, using the PRIMASK register for minimal latency. The implementation is optimized to minimize the time interrupts are disabled, which is crucial for real-time performance in embedded applications.