To run STM32 firmware without a board, build an Arm ELF for a supported MCU, install the Simantic CLI, sign in, and run:
sim STM32F401RE run --elf build/zephyr/zephyr.elf --timeout 1 --ascii
This tutorial uses an STM32F401RE simulator to boot Zephyr, reproduce a mutex deadlock, and verify the fix. You run the compiled MCU firmware on your computer; no development board or debug probe is needed. Simantic models the CPU, interrupts, memory, and peripherals the firmware uses.
Already have an ELF? Go to run your own STM32 firmware. For a complete experiment with source and expected output, follow the steps below.
How can STM32 firmware run without a board?
An ELF contains the program’s machine code and information about where it belongs in memory. A simulator loads it into a modeled address space and executes its Arm instructions. Models of the interrupt controller, timers and peripherals provide the behavior the firmware interacts with.
For this example, Zephyr needs to boot, schedule threads, wake them after a sleep, and send output through UART2. Modeling those interactions lets us investigate the program’s lock ordering without a physical board. Your own firmware may need additional peripherals: choosing an Arm CPU alone is not enough to model every STM32.
Simulation is useful for observing software behavior; electrical effects and precise hardware timing still need separate checks. Here, the question is concrete: why do two workers stop completing their work even though the RTOS still runs?
What is an RTOS deadlock?
An RTOS schedules independent threads of work. A mutex protects a shared resource by allowing one thread to own the lock at a time. If thread A holds one mutex while waiting for a second, and thread B holds the second while waiting for the first, neither can proceed. That circular wait is a deadlock.
The rest of the system can still be alive: a console or monitor thread may keep running. A boot banner therefore tells you much less than whether the workers completed. We will check both, then inspect the calls that connect the symptom to its cause.
Start here: download the sample source or inspect main.c.
1. Get the tools and build the firmware
You need a Simantic account, the CLI, and a Zephyr build environment. The simulation runs locally, but each run checks your account over the network. The CLI supports macOS on Apple Silicon and Linux x86-64; Windows uses WSL2. This walkthrough was checked on sim 0.8.11 (build 0e3e0a82) on macOS Arm64, on November 5, 2026. Other platforms were not exercised for this article.
Install and sign in using the CLI installation instructions:
curl -fsSL https://simantic.com/install | sh
sim login
sim --version
sim models
If the installer already signed you in, the separate login is unnecessary. Keep credentials out of source files and logs. On a headless machine use the headless sign-in instructions.
You also need a working Zephyr development environment,
including west, CMake, Ninja, Python and the Arm Zephyr SDK toolchain. The verified
build used Zephyr commit ab92232cfcd1362ee481ba06197fda7d6613aff5 (4.4.99 development
tree), SDK 1.0.1 and west 1.5.0. The download’s README includes the
pinned workspace setup. This is a pinned development revision, not a claim that
any Zephyr release produces identical output.
Other Zephyr versions may change kernel symbols and trace output.
From your Zephyr workspace, download and build the example:
curl -fLO https://simantic.com/examples/stm32-zephyr-deadlock.zip
unzip stm32-zephyr-deadlock.zip
west build -b nucleo_f401re stm32-zephyr-deadlock -d build-bug --pristine
The result is build-bug/zephyr/zephyr.elf. Keep the ELF with its symbols; the
debugging steps use them to locate the kernel’s mutex functions. The app enables
thread names and monitoring, but does not add a trace recorder library.
2. Boot Zephyr on the simulated STM32F401RE
Use sim models to confirm the target names built into your installed simulator. For this example:
sim STM32F401RE run --elf build-bug/zephyr/zephyr.elf \
--timeout 1 --ascii --only-messages --output bug-uart.txt
cat bug-uart.txt
--timeout 1 runs one second of virtual time. It is not a one-second wall-clock
deadline. The sample checks progress after a 500 ms sleep. Expect these lines
(the Zephyr banner depends on the build):
STM32F401RE: Zephyr mutex debugging
[progress] worker_a=0 worker_b=0
RESULT: FAIL (workers incomplete)
That is the intended failure. Zephyr boots and its monitor thread runs, but neither worker completes. A successful simulator process exit does not mean the firmware passed; check the firmware’s result marker.
3. Trace the calls that explain the hang
This follows the debugging-with-evidence procedure:
keep a baseline, choose an observation that tests a hypothesis, and compare the
failure with a corrected run. For version-matched run and recording instructions,
use sim docs show guide and sim docs show record; both work without a login.
The two workers acquire two mutexes in opposite order:
worker_a: lock A → sleep 50 ms → lock B → unlock B → unlock A
worker_b: lock B → sleep 50 ms → lock A → unlock A → unlock B
The sleep deliberately gives the other worker an opportunity to take its first lock. This makes a circular-wait bug easy to reproduce. It does not mean the simulator automatically discovers every possible thread interleaving.
Run the same ELF again, tracing mutex entry points:
sim STM32F401RE run --elf build-bug/zephyr/zephyr.elf \
--timeout 1 --ascii --only-messages --output bug-uart.txt \
--trace-symbol z_impl_k_mutex_lock \
--trace-symbol z_impl_k_mutex_unlock \
> bug-trace.txt
These hooks print function entries to standard output while simulation continues;
UART goes to the file named by --output. No breakpoint or additional guest-side
logging is needed. Read the trace:
cat bug-trace.txt
For a shorter view, extract the timestamp, function and first argument (r0):
awk '/\(TRACE\)/ { print $1, $3, $5 }' bug-trace.txt
Our captured run produced:
[0.009190812s] z_impl_k_mutex_lock r0=0x2000006c
[0.009210621s] z_impl_k_mutex_lock r0=0x20000080
[0.059309621s] z_impl_k_mutex_lock r0=0x20000080
[0.059328359s] z_impl_k_mutex_lock r0=0x2000006c
There are four lock calls and no unlock calls during the recorded second. Find out
which mutex each address names with the SDK’s arm-zephyr-eabi-nm:
arm-zephyr-eabi-nm build-bug/zephyr/zephyr.elf | grep -E 'lock_[ab]$'
In this build, lock_a is 0x2000006c and lock_b is 0x20000080.
Addresses and exact timestamps may differ after rebuilding. On this Arm target,
the first function argument is in r0: the mutex pointer.
The diagnosis combines trace and source. The trace establishes the call order
and lack of unlocks. The source establishes that each worker holds its first lock
while requesting the other with K_FOREVER. The progress check confirms that
neither worker completed. Together, they explain the circular wait. Function-entry
records alone do not report mutex ownership or prove that a lock call returned.
You can inspect the captured failing trace and console output. Idle alone is not evidence of a bug: a worker can finish its work and sleep. Check completion, source, and trace together.
4. Fix the lock order and verify the result
Have both workers acquire A before B. The sample includes that change behind a build option so you can compare the two versions:
west build -b nucleo_f401re stm32-zephyr-deadlock -d build-fixed --pristine -- -DFIX_LOCK_ORDER=ON
sim STM32F401RE run --elf build-fixed/zephyr/zephyr.elf \
--timeout 1 --ascii --only-messages --output fixed-uart.txt \
--trace-symbol z_impl_k_mutex_lock \
--trace-symbol z_impl_k_mutex_unlock \
> fixed-trace.txt
Now worker B waits for A before it can acquire B. Worker A can finish and release both locks; worker B then proceeds. The verified output is:
[progress] worker_a=1 worker_b=1
RESULT: PASS
The fixed trace contains four lock calls and four unlock calls. Compare it to the failure instead of treating the result marker as the entire explanation.
Make this a regression check:
grep -qx 'RESULT: PASS' fixed-uart.txt && ! grep -q 'RESULT: FAIL' fixed-uart.txt
The check fails if the pass marker is missing or any failure marker appears. It checks this sample’s completion condition, not all RTOS behavior. For an automated check, let the CLI return a failure status if the result is missing or the firmware reports failure:
sim STM32F401RE run --elf build-fixed/zephyr/zephyr.elf \
--timeout 1 --ascii --expect 'RESULT: PASS' --expect-absent 'RESULT: FAIL'
The deliberately buggy build should fail this same check. Pin the simulator and firmware versions in CI and provide credentials through your secret store; each run still needs network access for account validation.
Scope and reproducibility
This exercise checks Zephyr boot, UART2 console output, timed sleeps, two threads and mutex behavior on an STM32F401RE model. It does not validate the board’s full peripheral set, electrical behavior, cycle-accurate timing or every scheduling interleaving. Run hardware tests for those parts of your system.
The published UART and function traces were captured with sim 0.8.11 using the built-in STM32F401RE target and the two ELFs rebuilt from this sample on November 5, 2026. The verification manifest records the tested versions and SHA-256 hashes. The timestamps are virtual time, not measurements of silicon speed. New simulator or toolchain releases can change addresses and timestamps; compare the completion result and lock order.
Run your own STM32 firmware
Choose a completion condition you can observe: a worker finishing a transaction, a message reaching its consumer, or an initialization sequence reaching its next step. Build for your supported MCU, keep the ELF symbols, and run long enough for that condition to occur. For another supported STM32F401RE application:
sim STM32F401RE run --elf ./build/zephyr/zephyr.elf \
--timeout 5 --ascii --only-messages --output firmware-uart.txt
If progress stops, trace the functions around the missing step. For a suspected mutex problem, reuse the lock and unlock hooks above. For a queue or driver, choose the relevant symbols from your ELF. Compare the trace with the source, make one change, and rerun the same completion check.
The CLI reference covers running your image, and the model-listing instructions help you select a target. The question to carry into the next investigation is: what should happen next, and what observation would tell me why it did not?
Troubleshooting
- Credentials missing or invalid: run
sim loginand confirm that the host can reach the service.sim modelslisting a chip does not prove that a run is authenticated. - Unknown MCU: use
sim models; a shared Cortex-M core does not make every STM32 peripheral map interchangeable. Match the firmware build to the specific model. - No UART output: keep
--ascii, check the ELF and console configuration, and allow enough virtual time. This sample uses Zephyr’s UART2 console. - Symbol not found: keep an unstripped ELF and check it with
arm-zephyr-eabi-nm. A different Zephyr version may rename or inline functions. - Unexpected process success on the buggy sample: a completed simulation can
contain a firmware failure. Use
--expectand--expect-absentfor an automated verdict.
For agents running this experiment, --record ./run also writes a searchable
JSONL evidence directory. Read its runs.jsonl, uart.jsonl, and README.md,
including what was not recorded. Function-entry text is captured separately with
--trace-symbol as shown above. The Markdown version contains
this same tutorial for tools that prefer plain text.
Next: run your own firmware, try Cloud Sim in the browser, or check the simulation validation standard.