Skip to content

Guest Debugging

To debug Xbox executables themselves, enable the guest GDB server within xemu by appending -s to the startup commands and optionally appending -S to start in a paused state; this will listen on localhost port 1234 by default.


Qemu's monitor can be accessed via the backtick shortcut on your keyboard or via DebugMonitor from within the xemu menu. It's not required to enable the GDB server to use.

To quickly diagnose a crash in guest code, one might execute the following GDB commands:

  • Dump the CPU state via info registers to determine EIP
  • Disassemble 20 instructions at a virtual address via x/20i 0xADDRESS
  • Dump 100 bytes of memory from a virtual address via x/100 0xADDRESS

IDA (Windows)

Load Binaries (Optional)

Open the target binary in IDA. Multiple binaries (mcpx, 1bl, 2bl, kernel, xbe) can be loaded via FileLoad fileAdditional binary file... in the case you wish to observe the full boot process.

Connect Debugger

In the IDA menu, go to DebuggerAttachRemote GDB Debugger and specify localhost on port 1234.

Underneath Debug optionsSet specific optionsMemory map, right-click Insert and specify FFFFFFFE (limitation if using the x86 version) for the end address, then click OK 5 times to save.

Debug Defines

The following debug defines may be of interest when building; they'll print additional information to the console window.

#DEFINE Source File Purpose
DEBUG_NV2A hw/xbox/nv2a/debug.h Graphics
DEBUG_NV2A_FEATURES hw/xbox/nv2a/debug.h Graphics
DEBUG_SMBUS hw/i2c/smbus_slave.c HAL
DEBUG_CUSB hw/xbox/chihiro-usb.c Input
DEBUG_XID hw/xbox/xid.c Input
DEBUG_MCPX hw/xbox/mcpx/apu.c Audio
DEBUG_DSP hw/xbox/mcpx/dsp/dsp.c Audio


A more advanced version of logging can be accomplished via qemu's tracing infrastructure. Review the trace-events files within the source tree to see what's supported. See also QEMU user documentation for more details.

Runtime Usage (preferred)

Launch xemu from a console window (cmd.exe,, bash, etc...; whichever is appropriate for your OS).

Open the monitor via DebugMonitor in the xemu menu.

Enter trace-event <trace_event> on to turn on an event, trace-event <trace_event> off to turn one off, replacing <trace_event> with the name of the event you wish to toggle.

Examine the console where you launched xemu; trace messages will be written to STDERR.

The nv2a events are particularly interesting when debugging graphics issues, specifically the nv2a_pgraph_* subset. These may be toggled all at once using a wildcard. For example, trace-event nv2a_pgraph_* on will turn them all on.

Compile-Time Usage (alternate)

Append --debug --enable-trace-backends=simple to the xemu build args to enable.

Edit the global /tmp/events file with things you intend to match on.

$ rm /tmp/events
$ echo cd_read_sector* >> /tmp/events
$ echo ide_* >> /tmp/events
$ echo ide_atapi_* >> /tmp/events
$ echo ahci* >> /tmp/events
$ cat /tmp/events

Then append --trace events=/tmp/events to the xemu runtime arguments. Once finished, run python ./scripts/ trace-events-all trace-#### replacing #### with the created trace log's ID.