liveBook · Manning

Flip-link

As explained in Embedded Software with Rust

flip-link is a linker wrapper that rearranges embedded memory layouts to place the main stack below other RAM sections and detect downward stack overflow.

flip-link is a linker wrapper that helps detect main-stack overflow in embedded Rust firmware. It rearranges the Cortex-M memory layout so the stack sits at the bottom of RAM, below .bss and .data. The stack still grows downward, toward the RAM boundary instead of toward static data. section 7.4.3

When an overflow writes below RAM to an unmapped address, the write triggers a bus fault rather than silently corrupting static data. The fault identifies the offending instruction, helping a debugger locate the overflow. The layout is changed at link time; the fault occurs when the invalid write happens at runtime. section 7.4.3

cargo install flip-link
# .cargo/config.toml

[target.thumbv7em-none-eabihf]
rustflags = [
    "-C", "linker=flip-link",
    # ...any other rustflags the project already uses
]

Install flip-link and configure rustc to use it as the linker for the target. Preserve any other rustflags the project needs. section 7.4.3

Internally, flip-link calls the real linker, rust-lld by default, twice: first to compute the layout, then to emit the rearranged binary. The standard cortex-m-rt memory.x works without modification, and application source code need not change. section 7.4.3

For useful diagnostics, the HardFault handler—or BusFault handler if separately enabled—must do more than loop indefinitely. It can log the fault, print registers, or break into a debugger; panic-probe and defmt-rtt provide ready-made handlers. section 7.4.3

flip-link protects only the main stack. RTOS task stacks are allocated within RAM, so an individual task overflow does not necessarily reach the bottom-of-RAM boundary. MPU guard regions can provide per-task protection; static stack analysis and software canaries are complementary techniques. section 7.4.3 section 7.5

How Embedded Software with Rust covers it

How deep it goes
Explains the rearranged layout, fault path, linker invocation, configuration, and main-stack limitation.
Examples
Shows installation and Cargo linker configuration for a thumbv7em-none-eabihf target.
What it assumes
Assumes familiarity with linker-defined FLASH and RAM regions and reset initialization of .data and .bss.
What you can do after
Apply it via flip-link to configure main-stack overflow detection and prepare a fault handler for diagnostics.
How it connects
Connects stack overflow detection with linker scripts, fault handlers, static stack analysis, software canaries, and MPU guard regions.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Embedded Software with Rust. The section links point to the parts of the book it draws on.