mohitmishra786/qemu-embedded-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