# STM32 simulator: run firmware without a board

Canonical: https://simantic.com/stm32-simulator
Verified: November 5, 2026. Simantic CLI 0.8.11.

**To run STM32 firmware without a board**, build an Arm ELF for a supported MCU,
install the Simantic CLI, sign in, and run:

```sh
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](#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](/examples/stm32-zephyr-deadlock.zip)
or inspect [main.c](/examples/stm32-zephyr-deadlock/src/main.c).

## 1. Get the tools and build the firmware

You need a [Simantic account](https://app.simantic.com/signup), 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](/docs#installation):

```sh
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](/docs#authentication).

You also need a working [Zephyr development environment](https://docs.zephyrproject.org/latest/develop/getting_started/index.html),
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](/examples/stm32-zephyr-deadlock/README.md) 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:

```sh
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:

```sh
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):

```text
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](/docs/guide#debugging-with-evidence):
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:

```text
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:

```sh
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:

```sh
cat bug-trace.txt
```

For a shorter view, extract the timestamp, function and first argument (`r0`):

```sh
awk '/\(TRACE\)/ { print $1, $3, $5 }' bug-trace.txt
```

Our captured run produced:

```text
[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`:

```sh
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](/examples/stm32-zephyr-deadlock/evidence/bug-trace.txt)
and [console output](/examples/stm32-zephyr-deadlock/evidence/bug-uart.txt).
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:

```sh
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:

```text
[progress] worker_a=1 worker_b=1
RESULT: PASS
```

The [fixed trace](/examples/stm32-zephyr-deadlock/evidence/fixed-trace.txt)
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:

```sh
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:

```sh
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](/examples/stm32-zephyr-deadlock/evidence/verification.json)
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:

```sh
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](/docs#simulate) covers running your image, and the
[model-listing instructions](/docs#models) 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](/stm32-simulator.md) contains
this same tutorial for tools that prefer plain text.

**Next:** [run your own firmware](/docs#simulate),
[try Cloud Sim in the browser](/cloud-sim), or
[check the simulation validation standard](/validation).
