qemu-embedded-simulation

name	qemu-embedded-simulation
description	QEMU embedded simulation skill for bare-metal MCU testing. Use when running ARM/RISC-V firmware in QEMU, selecting machine models, loading -kernel ELF, or GDB debugging without hardware. Activates on queries about QEMU bare metal, qemu-system-arm -kernel, STM32 QEMU machine, RISC-V virt, or firmware simulation.

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