# STM32F401RE Zephyr mutex debugging sample

A standalone teaching example, not customer firmware. The default build deliberately
acquires locks in opposite order. `FIX_LOCK_ORDER=ON` makes both workers acquire A then B.

Full tutorial: https://simantic.com/stm32-simulator
Markdown: https://simantic.com/stm32-simulator.md

## Build environment

Install Zephyr's host dependencies and SDK 1.0.1 with the Arm toolchain:
https://docs.zephyrproject.org/latest/develop/getting_started/index.html
The verified build used west 1.5.0 and Python 3.12. To create a separate pinned workspace,
run these commands with west installed in an activated Python virtual environment:

```sh
west init -m https://github.com/zephyrproject-rtos/zephyr --mr ab92232cfcd1362ee481ba06197fda7d6613aff5 zephyr-walkthrough
cd zephyr-walkthrough
west update
west zephyr-export
python3 -m pip install -r zephyr/scripts/requirements.txt
```

This is a pinned Zephyr development revision (4.4.99). Extract this sample into the
workspace. Set ZEPHYR_SDK_INSTALL_DIR if your SDK is not automatically discovered.
Keep the ELF symbols. Add the SDK's gnu/arm-zephyr-eabi/bin directory to PATH for nm.

```sh
west build -b nucleo_f401re stm32-zephyr-deadlock -d build-bug --pristine
west build -b nucleo_f401re stm32-zephyr-deadlock -d build-fixed --pristine -- -DFIX_LOCK_ORDER=ON
```

If a local compiler-cache launcher causes a build failure, disable it with
`-DUSE_CCACHE=0 -DCMAKE_C_COMPILER_LAUNCHER= -DCMAKE_CXX_COMPILER_LAUNCHER=`
after the west command's `--`. These host-specific options were used for verification.

## Run and check

Install sim and sign in as described at https://simantic.com/docs#installation.
Each run needs network access for account validation; `sim models` works offline.

```sh
sim STM32F401RE run --elf build-bug/zephyr/zephyr.elf --timeout 1 --ascii --only-messages --output bug-uart.txt
sim STM32F401RE run --elf build-fixed/zephyr/zephyr.elf --timeout 1 --ascii --only-messages --output fixed-uart.txt --expect 'RESULT: PASS' --expect-absent 'RESULT: FAIL'
```

The buggy build reports `RESULT: FAIL (workers incomplete)`; the fixed build reports
`RESULT: PASS`. The first command intentionally does not assert success. Applying
the second command's assertions to the buggy ELF exits 1.

Use `--trace-symbol z_impl_k_mutex_lock --trace-symbol z_impl_k_mutex_unlock`
and redirect stdout to a trace file. With --output set, UART is separate from the
function trace. In sim 0.8.11, --trace-out is a GPIO-edge file, not a symbol trace.

Verified November 5, 2026 with sim 0.8.11 (build 0e3e0a82) on macOS Arm64, using
the built-in STM32F401RE model. Evidence and SHA-256 hashes are in
evidence/verification.json. ELFs are not included; build the source above.
Addresses and virtual timestamps can change between builds. This checks functional
behavior; it is not a cycle-accurate silicon measurement.

The sample source and build files are MIT licensed. Zephyr and its modules retain
their own licenses; they are fetched separately, not included in this archive.
