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 login and confirm that the host can reach the service. sim models listing 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 --expect and --expect-absent for 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.