A debugging and instruction tracing tool for LoongArch binaries.

The debug_test program executes LoongArch ELF binaries with detailed instruction-by-instruction tracing, register state monitoring, and optional objdump comparison. This tool is invaluable for debugging emulator behavior and understanding program execution.

From the project root:

mkdir build && cd build
cmake ..
make

The debugger binary will be located at build/tests/debug_test.

debug_test [options] <binary>

Basic execution with full tracing:

./debug_test program.elf

Limit execution to 1 million instructions with short output:

./debug_test --max-instructions 1000000 --short program.elf

Quiet mode with hidden registers:

./debug_test -q -r program.elf

Compare with objdump disassembly:

./debug_test --compare-objdump program.elf

Allocate more memory:

./debug_test --memory 512 program.elf

The debugger provides detailed execution traces:

Starting execution at PC=0x120000790

PC=0x120000790  addi.d  $sp, $sp, -48     ($sp = 0x40003ff0)
  $sp = 0x40003ff0
PC=0x120000794  st.d    $ra, $sp, 40      (MEM[0x40004018] = 0x0)
  $ra = 0x0

Each instruction shows:

• Program counter (PC)
• Disassembly with operands
• Computed result (for relevant instructions)
• Affected register values

On platforms without getopt_long support, configuration can be done via environment variables:

Example (Windows):

set MAX_INSTRUCTIONS=1000000
set SHORT=1
debug_test.exe program.elf

Example (Unix):

QUIET=1 SHORT=1 ./debug_test program.elf

Verify instruction decoder and execution correctness:

./debug_test --compare-objdump test_program.elf

Count instructions for specific programs:

./debug_test --max-instructions 0 --short benchmark.elf

Trace execution to find bugs in LoongArch binaries:

./debug_test --verbose program.elf 2>&1 | less

Automate execution verification:

./debug_test --quiet --short test.elf && echo "PASS" || echo "FAIL"

The debugger is used in continuous integration for instruction validation. See the GitHub Actions workflows for automated testing.

Ensure the binary path is correct and the file exists.

The guest program triggered an exception (invalid memory access, illegal instruction, etc.). Check the PC and register state in the error output.

The program exceeded the instruction limit. Increase with --max-instructions or use 0 for unlimited execution.

If using --compare-objdump, ensure loongarch64-linux-gnu-objdump is installed:

sudo apt-get install binutils-loongarch64-linux-gnu

The debugger wraps Machine with DebugMachine, which:

1. Hooks into instruction execution
2. Disassembles each instruction
3. Tracks register changes
4. Formats output for human readability

This is built on top of the core emulation library, providing a debugging layer without modifying the fast path.

• Unit Tests - Automated testing framework
• Emulator CLI - Production emulator
• API Documentation - Library integration guide