QEMU
In this topic:
Quick start
Debug an embedded application in QEMU without physical hardware:
1. Create a winIDEA workspace with GDB client as the Debugger.
2. Configure a Launch that starts QEMU automatically.
3. Connect winIDEA to QEMU over a GDB server socket.
4. Start the session with Debug > Download.
QEMU starts automatically when you begin a debug session. winIDEA connects to it and you can set breakpoints, inspect memory, and step through code the same as on real hardware.
Overview
This guide shows how to connect winIDEA to a QEMU virtual machine to debug an embedded application without physical hardware. QEMU acts as the target; winIDEA connects to it over a GDB server socket.
When to use this guide
•You want to debug firmware before hardware is available
•You are running automated tests in CI where no physical board is attached
•You want to reproduce a bug in a controlled, repeatable environment
Before you start
Requirements
•QEMU installed and available on your PATH (or note the full path to the executable)
•winIDEA 9.21.313 or newer
•winIDEA vECU license
Steps
Step 1: Create a winIDEA workspace with GDB Client
winIDEA needs to know it will talk to a GDB server.
1. Open winIDEA and create a new workspace.
2. In the New Workspace dialog select GDB Client as the Debugger and click Create.
The Basic Session Configuration dialog opens.
Step 2: Select the device and symbol file
The symbol file maps addresses to source lines and variable names. Without it you can run the simulation but cannot see source-level debug information.
1. In the Basic Session Configuration dialog, select your target device.
2. Under Symbol file, browse to the ELF file of the application you want to debug.
3. Click Switch to Full at the bottom of the dialog to access the full configuration.
Step 3: Add a QEMU launch configuration
A Launch configuration tells winIDEA to start QEMU automatically when you begin a debug session. Without this, you would have to start QEMU manually in a separate terminal before every session.
1. Go to the Launches tab and add a new launch configuration.
2. Give it a name (e.g., qemu_launch).
3. Select Custom configuration type.
4. Fill in the fields:
• Executable: full path to the QEMU binary (e.g., C:\Program Files\qemu\qemu-system-arm.exe)
• Command line: QEMU flags for your target.
o-M flag is used to specify the simulated machine.
oUse -kernel to specify the download file you wish to simulate. You can use winIDEA macro $(DefaultDownloadFile) to automatically reference the file you specified earlier.
oEnable gdb connections and specify the port using -gdb tcp::<port>. Remember the port configuration (in this example 2012), as you will need it later.
Read the QEMU documentation for other relevant flags. Run qemu-system-arm --machine help for a full list.
5. Disable Wait for completion. QEMU keeps running for the duration of the debug session, so winIDEA must not wait for the process to exit.
The launch configuration is saved. winIDEA will start QEMU with these parameters each time you begin a debug session.
Step 4: Configure the GDB connection
This tells winIDEA where QEMU's GDB server is listening.
1. Go to GDB > Options.
2. Set the debug location to Local.
3. Enable GDB connects to gdbserver.
4. Enter localhost as the host and 2012 as the port (or whichever port you chose in Step 3).
5. Confirm the settings.
winIDEA will connect to QEMU's GDB server on that port when a debug session starts.
Step 5: Start the debug session
Select Debug > Download in winIDEA.
The QEMU window appears. winIDEA connects and the application pauses at startup. The winIDEA status bar shows STOP.
You can now set breakpoints, inspect memory and registers, and step through source code.
Troubleshooting
QEMU window does not appear and winIDEA times out
winIDEA waits for QEMU to open the GDB port. If QEMU fails to start, the wait times out.
1. Copy the command line from the launch configuration.
2. If you used $(DefaultDownloadFile), replace it with the full path to your ELF file.
3. Run the command in a terminal and read the output for errors.
If that does not work:
•Check the machine type: run qemu-system-<arch> --machine help and confirm your -M value is in the list.
•Check whether the port is already in use:
oWindows: netstat -an | findstr 2012
oLinux: ss -ltn | grep 2012
Source files are not found after connecting
If the application was built on a different machine, the paths in the debug symbols do not match your local file system.
Tell winIDEA where to find the source files. Refer to Locate the source code.
More resources
•Debugging - full reference for winIDEA debug features
•Operating systems - OS-aware debugging (threads, tasks, stacks)
•winIDEA SDK - automate this workflow with Python scripts
