Skip to main content
skill CX Codex

qemu-embedded-simulation — Claude Code skill: setup and use

The qemu-embedded-simulation skill guides QEMU runs of bare-metal ARM and RISC-V firmware and GDB sessions. Use it to test firmware without a board.

MIT 389 installs ★ 298 updated 2026-06-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mohitmishra786/low-level-dev-skills --skill qemu-embedded-simulation -a claude-code
Open on GitHub

What qemu-embedded-simulation does

The skill walks through choosing a QEMU machine, loading an ELF image, and attaching GDB. Its examples cover STM32 boards, ARM virt, and RISC-V virt; it also explains semihosting for printf when the toolchain supports it.

STM32 models lack GPIO, DMA, and I2C support, while USART, SPI, ADC, and timers are only partly modeled. LED blink tests therefore need a board or a different machine. QEMU timing also differs from the actual chip, so validate the firmware on hardware before production sign-off.

What it helps with

  • choose a QEMU machine for an STM32 board
  • load an ARM or RISC-V firmware ELF
  • smoke-test firmware without a physical board
  • attach GDB to a running simulation
  • diagnose missing UART output

Example prompts for the agent

  • Run firmware.elf for stm32vldiscovery in QEMU and set up GDB on port 3333.
  • Check why my RISC-V firmware.elf does not start on the virt machine.
  • Find out why my STM32 firmware produces no UART output in QEMU.

How to install qemu-embedded-simulation

1Skills CLI (Vercel)

npx skills add mohitmishra786/low-level-dev-skills --skill qemu-embedded-simulation -a claude-code

2Manually: put the files in place

~/.claude/skills/qemu-embedded-simulation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/qemu-embedded-simulation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about qemu-embedded-simulation

How do I install qemu-embedded-simulation in Claude Code?

Run npx skills add mohitmishra786/low-level-dev-skills --skill qemu-embedded-simulation -a claude-code. The skill file is placed at ~/.claude/skills/qemu-embedded-simulation/SKILL.md.

What does qemu-embedded-simulation do?

It guides QEMU setup for bare-metal ARM and RISC-V firmware, including machine selection, ELF loading, and GDB debugging.

Can I test STM32 GPIO in QEMU?

No. GPIO is not implemented in the STM32 models, so LED blink tests need physical hardware or another machine.

Source text

SKILL.md · MIT
---
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](https://www.qemu.org/docs/master/system/arm/stm32.html)):

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

```bash
# 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)

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

### 3. RISC-V bare metal

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

`-bios none` starts at reset vector without OpenSBI.

### 4. GDB stub

```bash
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)

```bash
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

© mohitmishra786 · MIT · mohitmishra786/low-level-dev-skills

Similar skills

All skills for Testing and QA →

From the same set140

The whole set →
uart-serial-baremetal uart-serial-baremetal configures bare-metal UART and USART drivers for serial debug consoles, baud calculation, and interrupt I/O. CX Codex +1 391installs kernel-concurrency kernel-concurrency is a Claude Code skill that helps select a Linux kernel synchronization primitive: spinlock, mutex, RCU, seqlock, or completion. CX Codex +1 391installs gpu-memory-model gpu-memory-model explains GPU execution and memory hierarchy under SIMT. Helps debug warp divergence, bank conflicts, and coalescing issues in compute kernels. CX Codex +1 391installs compiler-frontend A skill for building compiler frontends, from tokenization and parsing to type checks and LLVM IR generation. Useful for a language, DSL, or interpreter. CX Codex +1 390installs kernel-memory-management kernel-memory-management — a skill that walks an AI agent through Linux kernel allocation: kmalloc vs vmalloc vs page allocator, GFP flags, zones and OOM debugging. CX Codex +1 388installs cuda-debugging Walks the agent through CUDA debugging: cuda-gdb, Compute Sanitizer, GPU core dumps, error codes 700 and 702. Useful when a kernel crashes or returns wrong values. CX Codex +1 386installs llvm-ir-and-passes llvm-ir-and-passes teaches the agent to read LLVM IR, understand SSA form, and navigate optimization passes. Useful when tracing what -O2 changed or preparing to write a custom pass. CX Codex +1 384installs spi-i2c-baremetal The spi-i2c-baremetal skill guides bare-metal SPI and I2C driver work, from register reads to bus troubleshooting. Use it when bringing up sensors, flash, or displays. CX Codex +1 384installs

Project sponsors

Companies that keep this analytics open