QEMU Embedded Simulation

Purpose

Guide agents through QEMU for bare-metal and RTOS firmware: machine selection, loading ELF images, semihosting, peripheral models, and GDB debug — distinct from Linux-focused skills/virtualization/qemu-kvm and skills/kernel-dev/qemu-for-kernel-development.

When to Use

Test Cortex-M firmware without board
CI smoke test for linker script / startup
GDB single-step before OpenOCD on hardware
RISC-V bring-up on virt machine

Workflow

1. ARM Cortex-M (QEMU STM32 boards)

QEMU models a subset of STM32 boards (see qemu.org STM32 docs):

Machine	MCU	Core
`stm32vldiscovery`	STM32F100RBT6	Cortex-M3
`netduino2`	STM32F205RFT6	Cortex-M3
`netduinoplus2`	STM32F405RGT6	Cortex-M4F
`olimex-stm32-h405`	STM32F405RGT6	Cortex-M4F

# stm32vldiscovery — Cortex-M3 (not F4); match -mcpu to the board
arm-none-eabi-gcc -mcpu=cortex-m3 -T linker.ld -o firmware.elf main.c startup.s
qemu-system-arm \
  -machine stm32vldiscovery \
  -kernel firmware.elf \
  -nographic \
  -serial mon:stdio

Boot with -kernel firmware.bin or .elf per QEMU STM32 boot options.

Machine list: qemu-system-arm -machine help. GPIO, DMA, and I2C are not modeled on current QEMU STM32 machines — USART/SPI/ADC/timer are partially supported.

2. Generic ARM virt (Cortex-A test)

qemu-system-aarch64 -machine virt -cpu cortex-a53 -m 128M \
  -kernel firmware.elf -nographic

3. RISC-V bare metal

qemu-system-riscv32 -machine virt -nographic \
  -bios none \
  -kernel firmware.elf

-bios none starts at reset vector without OpenSBI.

4. GDB stub

qemu-system-arm -machine stm32vldiscovery -kernel firmware.elf \
  -S -gdb tcp::3333 -nographic

arm-none-eabi-gdb firmware.elf
(gdb) target remote :3333
(gdb) monitor reset halt
(gdb) load

Pair with skills/embedded/openocd-jtag for on-target workflow.

5. Semihosting (if supported)

qemu-system-arm ... -semihosting-config enable=on,target=native

Allows printf via semihosting syscall — toolchain must be built with semihosting support.

6. Limitations (QEMU STM32 per upstream docs)

Gotcha	Reality
No GPIO in QEMU STM32	GPIO controller not implemented — LED blink tests need hardware or another machine
No DMA / I2C	DMA and I2C missing on STM32 QEMU models
Partial RCC	RCC reset/enable only on F4; not full clock tree
Wrong MCU assumed	`stm32vldiscovery` is F100 M3, not F407 — match CPU flags and linker memory
Timing	Not cycle-accurate vs silicon

Validate on hardware before production sign-off.

7. Agent usage

/qemu-embedded-simulation Run STM32VL discovery firmware in QEMU with GDB on port 3333

Common Problems

Symptom	Cause	Fix
QEMU exits immediately	`main` returned	Loop or `WFI` at end
Wrong entry address	ELF not linked for model	Check `readelf -h` entry
No serial output	Wrong UART model address	Use machine-specific map or semihosting
GDB can't connect	Forgot `-S`	Add `-S -gdb tcp::3333`
HardFault in QEMU	Stack/vector invalid	Fix startup — see baremetal-startup

Related Skills

skills/baremetal/baremetal-startup — vectors and linker script
skills/baremetal/stm32-baremetal — STM32 layout
skills/embedded/openocd-jtag — hardware debug
skills/kernel-dev/qemu-for-kernel-development — Linux kernel in QEMU
skills/platform/riscv-privileged — RISC-V reset and virt