MU Debugger User Guide

MU Debugger is a post-mortem debugger and QEMU-based emulation tool for XCENA’s MU cores.
It supports live debugging and coredump analysis with GDB or LLDB.

Installation

Before installing mu_debugger, make sure that PXL (Parallel Xceleration Library) is installed and properly configured in your environment.
To install all dependencies and build the required components, simply run:

./install.sh

Usage

The debugger can be launched using the provided mu_debugger binary.

Basic command

mu_debugger [options]

Options:
  --elf <file>          Path to MU ELF or binary
  --core <file>         Path to XCENA coredump file
  --server <qemu|xcena|none>      Server to run (default: none)
  --client <gdb|lldb>        Debugger client to run (default: gdb)
  --port <port>         Port for GDB server (default: 1234)
  --silent              Run in silent mode (default: off)
  --config <file>      Path to configuration file (default: empty)
  --help                     Show this help message
  If coredump is not specified, the script will run a live debugging session.

`.xcoredump` Format

An .xcoredump file is a XCENA-specific post-mortem coredump that captures the internal state of MU cores at a specific point in time. It typically includes:

General-purpose registers (GPRs)
Program counter (PC)
Memory image (full or partial)
Thread context information
Device metadata

Example: Post-mortem debugging with `.xcoredump`

This mode analyzes the captured core state in read-only mode.
You can inspect memory, registers, and stack traces, but you cannot modify the context.

mu_debugger --elf sample/elf --core sample/sample.xcoredump

Example: Post-mortem debugging with `.xcoredump` + QEMU Emulation

This mode combines .xcoredump analysis with QEMU hardware emulation.
It enables step execution, memory patching, and context manipulation.

mu_debugger --elf sample/elf --core sample/sample.xcoredump --server qemu

Example: Analysis Report

You can quickly generate a human-readable summary from a .xcoredump file using the built-in parser script:

python3 src/coredump_parser.py sample/sample.xcoredump --elf sample/elf

Example: Live Debugging with XCENA GDB Stub (planned)

This mode will connect to a live MU core over the XCENA debug interface.
This feature is under development and not yet available.

mu_debugger --elf sample.elf --server xcena

Launch in VSCode

You can integrate mu_debugger into Visual Studio Code for seamless debugging with GDB.
This setup allows you to use .xcoredump-based debugging directly through the IDE.

Configure ELF and Coredump path in vscode.cfg file.
```
 elf=sample/elf
 coredump=sample/sample.xcoredump
```
This file is automatically loaded at runtime to configure the debugging session.
Open Debug Panel
Open Run and Debug tab (Ctrl + Shift + D), and select session to launch.
Start Debugging Press F5 or click Start Debugging to launch the session.
The debugger will automatically load the ELF and .xcoredump, and attach GDB to the emulated target.