Embedded Rust

Rust Embassy on STM32: What Compiles, What Runs, and the QEMU Gap

The program compiles. The executor runs under QEMU and prints one line. The full application, with the STM32 HAL initialized and a timer task spawned, compiles cleanly and then stops at embassy_stm32::init() under QEMU, with no further output before the timeout kills it. This guide shows the split exactly as measured: what compiled, what printed, where the run stops, and what a real board is still needed for.

Written November 7, 2026 · Tested with QEMU 8.2.2 · 14 min read

By the end of this guide
  • The program that compiles
  • What runs under QEMU: the executor-only firmware
  • Where the full app stops: the init hang
  • Five fixes the compiler taught

What this guide is

This guide is a split result, and the split is the point. A real Embassy program — one spawned task, a timer, and the STM32 HAL — compiles for the STM32F103C8, with every version pinned and the build returning 0. An executor-only firmware, with no HAL in it, runs under QEMU and prints one line through semihosting. The full program does not run under QEMU. It prints one line before initialization, then nothing, until the 10-second timeout kills QEMU. The timer ticks in the program were never observed anywhere. The board run was never executed: no STM32 board was, and no board run is claimed.

A fourth check, run because the machine list contradicted a banked claim, tried the full app on QEMU's own STM32 machine. It faults immediately. Each result is quoted verbatim below, with the return code of every step.

The reference for the Embassy API used here is the Embassy Book. It states that Embassy is a project to make async/await a first-class option for embedded development, that the executor runs a fixed number of tasks, and that the HALs implement safe Rust APIs for peripherals without depending on the executor. The embassy-stm32 API documentation, version 0.4.0 states that the HAL covers all STM32 families, that a chip is selected with a feature flag, and that a time driver is picked with a time-driver-* feature or left to Embassy with time-driver-any. The program below follows those two sources, with the versions the box actually resolved.

The program that compiles

The full program is one spawned task, a timer, and the HAL. The task waits 500 milliseconds, prints a line, and repeats. The main function prints before initialization, initializes the HAL, spawns the task, and then prints a one-second tick in a loop. None of the lines after initialization were ever observed. They are in the source because the program compiles with them, not because they ran.

Cargo.toml, exactly as built:

TOML
[package]
name = "embassy-app-probe"
version = "0.1.0"
edition = "2021"

[dependencies]
cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
cortex-m-rt = "0.7"
cortex-m-semihosting = "0.5"
embassy-executor = { version = "0.10", features = ["platform-cortex-m", "executor-thread"] }
embassy-time = "0.5"
embassy-stm32 = { version = "0.4", default-features = false, features = ["stm32f103c8", "time-driver-any"] }
panic-halt = "0.2"

[profile.dev]
opt-level = 2

The resolved versions, read from the lockfile today: embassy-stm32 0.4.0, embassy-time 0.5.1, embassy-executor 0.10.0, embassy-executor-macros 0.8.0, stm32-metapac 18.0.0. The lockfile lists 117 packages including the app crate itself, so 116 dependency packages. The build output, read from the file rather than a pipe so the return code is the compiler's:

Output
cargo build --target thumbv7m-none-eabi > build-app.log 2>&1; echo "app build rc=$?"
app build rc=0
    Finished `dev` profile [optimized + debuginfo] target(s) in 0.33s

The binary is 2,154,572 bytes. The ELF check confirms it is a real ARM executable with the sections a Cortex-M boot needs:

Output
target/thumbv7m-none-eabi/debug/embassy-app-probe: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, with debug_info, not stripped
  1 .vector_table   00000400 00000000 00000000 DATA
  2 .text           000020b0 00000400 00000400 TEXT
  4 .data           00000018 20000000 00003790 DATA
  6 .bss            000000b4 20000018 20000018 BSS

The vector table is 0x400 bytes, the text section is 0x20b0 bytes, and the data and BSS sections sit in RAM at 0x20000000. That is a linked firmware image, not a link that silently produced nothing. The distinction matters, because the first version of this probe linked without a link script and produced an ELF with no loadable sections at all. That failure is in the fixes section below.

The build script and linker memory, exactly as built. The build script passes the link script because cortex-m-rt 0.7 does not do it itself:

Rust
fn main() {
    println!("cargo:rustc-link-search={}", std::env::var("CARGO_MANIFEST_DIR").unwrap());
    println!("cargo:rustc-link-arg=-Tlink.x");
    println!("cargo:rerun-if-changed=memory.x");
}
Output
MEMORY
{
  FLASH : ORIGIN = 0x00000000, LENGTH = 256K
  RAM : ORIGIN = 0x20000000, LENGTH = 64K
}

That memory map is the QEMU board's geometry, not the chip's. The real STM32F103C8 has 64K of flash at 0x08000000 and 20K of RAM at 0x20000000, per the STM32F103C8 board documentation, which lists 64KB of flash and 20KB of RAM for the part. The probe uses the QEMU board's map so that QEMU's -kernel option loads the image at all. A real board needs the real map, and the two must never be confused: flashing a binary linked at 0x00000000 onto a chip whose flash starts at 0x08000000 will not boot.

The main source, exactly as built:

Rust
#![no_std]
#![no_main]
use cortex_m_semihosting::hprintln;
use embassy_executor::Spawner;
use embassy_time::{Duration, Timer};
use panic_halt as _;

#[embassy_executor::task]
async fn blinker() {
    loop {
        Timer::after(Duration::from_millis(500)).await;
        hprintln!("embassy-app-ok blink");
    }
}

#[embassy_executor::main]
async fn main(spawner: Spawner) {
    hprintln!("embassy-app-ok pre-init");
    let _p = embassy_stm32::init(Default::default());
    hprintln!("embassy-app-ok init");
    spawner.spawn(blinker().unwrap());
    hprintln!("embassy-app-ok main");
    loop {
        Timer::after(Duration::from_secs(1)).await;
        hprintln!("embassy-app-ok tick");
    }
}

What runs under QEMU: the executor-only firmware

Before the full app, the smaller question was whether anything Embassy-related runs under QEMU at all. The executor-only firmware is a print and a loop: it depends on embassy-executor 0.10.0, prints one line through semihosting, and loops forever. Its Cargo.toml pins cortex-m = "0.7", cortex-m-rt = "0.7", cortex-m-semihosting = "0.5", embassy-executor = "0.10.0", and panic-halt = "0.2", and its main function is four lines:

Rust
#![no_std]
#![no_main]
use cortex_m_rt::entry;
use cortex_m_semihosting::hprintln;
use panic_halt as _;
#[entry]
fn main() -> ! {
    hprintln!("embassy-probe-ok");
    loop {}
}

Rebuilt and run today on the lm3s6965evb machine, with semihosting and no graphics, and a 5-second timeout:

Output
executor build rc=0
Timer with period zero, disabling
embassy-probe-ok
qemu-system-arm: terminating on signal 15 from pid 294052 (timeout)
executor qemu rc=124

The line Timer with period zero, disabling comes from the emulated board's own timer, not from the firmware. The firmware prints embassy-probe-ok and then loops forever, so QEMU is stopped by the timeout, which reports signal 15 and return code 124. That return code is the timeout kill, not a crash and not a successful exit. The firmware loops by design, so there is no exit to wait for. The same applies to every QEMU run in this tutorial: a return code of 124 after the print means the timeout stopped a looping program, and a return code of 124 with no print means the program never got far enough to print.

This run proves two narrow things: the executor crate compiles for the target, and the semihosting print path works under this QEMU machine. It proves nothing about the HAL, the timers, or the board. The next section is where the HAL enters and the run stops.

Where the full app stops: the init hang

The full app, run today under the same machine with a 10-second timeout:

Output
Timer with period zero, disabling
embassy-app-ok pre-init
qemu-system-arm: terminating on signal 15 from pid 294096 (timeout)
app qemu rc=124

One line prints, then nothing. No init, no main, no tick, no blink. The timeout kills QEMU at 10 seconds with return code 124. The hang point was fixed by bisection on 2026-11-06: a run without the pre-init print printed nothing at all before the timeout, and the run with the pre-init print printed exactly that line and nothing more. The print path works — the executor-only firmware proves it — so the program is stuck inside embassy_stm32::init(), between the two prints. The mechanism is the clock setup: initialization waits on STM32 clock-ready bits in registers that the emulated lm3s6965evb board does not implement, so the reads never return the ready state and the wait never completes. The embassy-stm32 API documentation, version 0.4.0 describes init_primary as the function that does the actual initialization of the hardware; on this emulated board that initialization never returns.

The QEMU gap, corrected: the banked probe record said mainline QEMU ships no STM32 machine. That is wrong. QEMU 8.2.2 lists four STM32 machines, netduino2 (Cortex-M3), netduinoplus2 (Cortex-M4), olimex-stm32-h405 (Cortex-M4) and stm32vldiscovery (Cortex-M3). None of them is an STM32F103 board. The full app was tried on stm32vldiscovery today, and it faults before printing anything:

Output
qemu: fatal: Lockup: can't escalate 3 to HardFault (current priority -1)
timeout: the monitored command dumped core
vldiscovery qemu rc=134

The return code is 134, an abort, not the 124 timeout kill. The binary is linked for flash at 0x00000000, while the STM32 machine maps its flash at 0x08000000, so the processor never finds the vector table. The lockup fault is the same diagnostic the first probe recorded for a firmware with no vector table. Rebuilding the app for the discovery board's memory map was not attempted: the chip is not an F103, the HAL feature would change, and the result would no longer be the F103 program this guide is about. The honest statement is narrower than the banked one, and it still holds for this chip: the STM32F103 app has no QEMU run path in QEMU 8.2.2. The lm3s6965evb machine hangs at init, and the one STM32 machine that exists is a different chip with a different memory map.

Five fixes the compiler taught

Each fix below was earned by a failed build in the probes, not guessed from documentation. Every one of them is already in the code above; this section records the error so the reader recognizes it.

  1. cortex-m-rt 0.7 does not pass the link script. Its build script only adds its output directory to the link search path, where it writes link.x. Without a binary-crate build.rs printing cargo:rustc-link-arg=-Tlink.x, the link silently produces an ELF with no loadable sections. The tell is the linker warning that it cannot find the entry symbol _start. The fix is the build.rs shown above, plus a memory.x in the crate root.
  2. hprintln! returns nothing. The semihosting print macro returns (), not a Result. Writing hprintln!("...").unwrap() fails with E0599, no method named unwrap. Drop the unwrap.
  3. The executor 0.10 platform feature is platform-cortex-m. The older name arch-cortex-m does not exist in 0.10, and resolution fails with the compiler listing the real feature. The Embassy Book template for the executor lists platform-cortex-m alongside executor-thread. A guide copied from Embassy 0.8 or 0.9 documentation fails on this exact error.
  4. Spawn takes the unwrapped task. The #[task] function returns a Result, and spawn itself returns nothing, so spawner.spawn(blinker()).unwrap() fails twice: once for the type mismatch and once for unwrapping a unit value. The working form is spawner.spawn(blinker().unwrap()), which is also the form in the book's own example.
  5. A bare cortex-m = "0.7" provides no critical-section implementation. The crate compiles with empty features, and the link then fails on undefined symbols _critical_section_1_0_acquire and _critical_section_1_0_release, because the HAL and the time driver call into the critical-section crate. The fix is to add the critical-section-single-core feature to the cortex-m dependency, as the Cargo.toml above already shows. The book's template lists the same feature. The executor-only firmware linked without it only because nothing it pulled in actually called the critical-section code, so the linker discarded the unreferenced symbols.

One more resolution detail, for the reader who wonders which timer the ticks would use: with time-driver-any on the stm32f103c8 feature, the link pulls in the RTC driver, so the program's timers would run on the real-time clock driver, not on a general-purpose timer. That is a link-time observation, not a run-time one. No tick was observed, so no tick rate is claimed.

What runs on a real board

A real STM32F103C8 board is the only run path for this program. The board run was not executed, and nothing in this guide describes its output. What the box proves is the compile half: the program, the HAL, the executor, and the timer all resolve and link for the right target, and the binary has the sections a Cortex-M3 boot needs. On a board, the steps the book prescribes are a debug probe and probe-rs run --chip STM32F103C8Tx with the real memory map, flash at 0x08000000 and RAM at 0x20000000. The book's own run output for its example shows the probe flashing the board and the program printing its first lines over the debug channel. This guide claims none of that output for its own program, because it was never run on a board. If you run it, the first lines you should see are the pre-init print, then the init print, then the one-second ticks — and if the init print never appears on real hardware, the problem is in the program or the wiring, not in QEMU, because the QEMU hang is an emulation limit, not a program bug.

What this guide does not cover

No sensor is wired here, no peripheral beyond the clock and timer drivers is touched, and no GPIO, I2C, SPI, ADC, or UART code is in the program. The Embassy Book also covers networking, USB, Bluetooth, and a bootloader; none of that is in scope. The book's own template versions are stale — it pins embassy-stm32 0.1.0, embassy-executor 0.6.3, and embassy-time 0.3.2 — so its version numbers were never copied; the versions in this tutorial are the ones the box resolved today. MSVC, other Rust toolchains, and other QEMU versions were not tested. The memory-x feature, which generates memory.x from the chip data, was not used here: the probe writes its own memory.x, because the book warns the generated definition is often not correct for the board in hand.

Checklist

  • Before building for a board, check the target matches the core: the STM32F103C8 is a Cortex-M3, so the target is thumbv7m-none-eabi, and a thumbv7em binary runs on the M3 machine only when it uses no floating-point instructions.
  • Before trusting a link, check the ELF has a vector table: an ELF with no loadable sections means the link script was never passed, and the _start warning is the tell.
  • Before calling hprintln! a result, remember it returns nothing: no unwrap, no question mark.
  • Before copying an executor feature from an old guide, check the name in 0.10: platform-cortex-m, not arch-cortex-m.
  • Before spawning a task, unwrap the task, not the spawn: spawner.spawn(blinker().unwrap()).
  • Before linking a HAL that uses critical sections, enable critical-section-single-core on cortex-m, or the link fails on the acquire and release symbols.
  • Before running firmware under QEMU, check the machine list: the board you need may not exist, and a return code of 124 after the print means the timeout stopped a looping program, not that it crashed.

Sources

  • Embassy Book — Embassy as async/await for embedded development; the executor runs a fixed number of tasks; HALs are standalone and implement blocking and async APIs; the executor template lists platform-cortex-m and executor-thread; the example spawns with spawner.spawn(run().unwrap()); the template enables critical-section-single-core on cortex-m; the time-driver note says to enable time-driver-any on embassy-stm32; the board run uses probe-rs run with the chip from probe-rs chip list.
  • embassy-stm32 API documentation, version 0.4.0 — the HAL covers all STM32 families; the chip is selected with a feature flag; a time-driver-* feature picks the timer, or time-driver-any lets Embassy pick; init_primary does the actual initialization of the hardware.
  • STM32F103C8 board documentation — the part has 64KB of flash and 20KB of RAM, which is the real memory map the probe's QEMU map must not be confused with.

Keep Exploring