flip-link
adds zero-cost stack overflow protection to your embedded programs
The problem
Bare metal Rust programs may not be memory safe in presence of stack overflows. For example, this is the case for Rust programs based on v0.6.x of the cortex-m-rt crate.
The following program, which contains no unsafe code block, can run into undefined behavior if it reaches a stack overflow condition.
// static variables placed in the .bss / .data sections
static FLAG1: AtomicBool = AtomicU32::new(false); // .bss
static FLAG2: AtomicBool = AtomicU32::new(true); // .data
fn main() {
let _x = fib(100);
}
#[inline(never)]
fn fib(n: u32) -> u32 {
// allocate and initialize 4 kilobytes of stack memory
let _use_stack = [0xAA; 1024];
if n < 2 {
1
} else {
fib(n - 1) + fib(n - 2) // recursion
}
}
#[interrupt]
fn interrupt_handler() {
// does some operation with `FLAG1` and `FLAG2`
}
The default memory layout of ARM Cortex-M programs in RAM is shown below.
The function call stack, also known as the "stack", grows downwards on function calls and when local variables (e.g. let x) are created (these variables are also placed on the stack).
If the stack grows too large it collides with the .bss + .data region, which contains all the program's static variables. The collision results in the static variables being overwritten with unrelated data. This can result in the program observing the static variables in an invalid state: for example an AtomicBool may hold the value 3 -- this is undefined behavior because the Rust ABI expects this single-byte variable to be either 0 or 1.
The solution
One potential solution is to change the memory layout of the program and place the stack below the .bss+.data region.
With this flipped memory layout (pictured below) the stack cannot collide with the static variables. Instead it will collide with the boundary of the physical RAM memory region. In the ARM Cortex-M architecture, trying to read or write past the boundaries of the RAM region produces a "hardware exception". The cortex-m-rt crate provides an API to handle this condition: a HardFault exception handler can be defined; this "handler" (function) will be executed when the invalid memory operation is attempted.
flip-link implements this stack overflow solution. Linking your program with flip-link produces the flipped memory layout, which is memory safe in presence of stack overflows.
Architecture support
flip-link is known to work with ARM Cortex-M programs that link to version 0.6.x of the cortex-m-rt crate and are linked using the linker shipped with the Rust toolchain (LLD). At this time, it hasn't been tested with other architectures or runtime crates.
Installation
flip-link is available on crates.io. To install it, run
$ cargo install flip-link
Usage
Change the linker from rust-lld (the default) to flip-link in .cargo/config.toml
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
# (..)
rustflags = [
"-C", "linker=flip-link", # <- add this
# (..)
]
NOTE that if you were using GNU ld or GNU gcc to link your program then this won't work. Support for other linkers is being tracked in issue #1.
Testing
Our CI enforces various checks. You can run them locally to make sure your PR will pass the CI:
cargo fmt --all -- --checkcargo clippy -- --deny warningscargo xtest- This installs the current revision of
flip-linkand runscargo test.
- This installs the current revision of
Support
flip-link is part of the Knurling project, Ferrous Systems' effort at improving tooling used to develop for embedded systems.
If you think that our work is useful, consider sponsoring it via GitHub Sponsors.
License
Licensed under either of
-
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
-
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.
1.1k Jan 6, 2023
300 Dec 11, 2022
253 Dec 31, 2022
457 Dec 22, 2022
47 Jul 23, 2022
1.2k Dec 29, 2022
5 Aug 26, 2022
35k Dec 31, 2022
1.2k Jan 6, 2023
542 Jan 4, 2023
6 Dec 23, 2021
2 Aug 31, 2022
18 Dec 28, 2022
47 May 4, 2022
4.7k Jan 1, 2023
73 Sep 6, 2022
22 Sep 14, 2023
0 Feb 6, 2022