The Debugger System provides Ghidra's dynamic analysis capabilities through a trace-based architecture that records and displays program execution state. Unlike traditional debuggers that only show the current state, Ghidra's debugger records execution history in a trace database, enabling time-travel debugging and post-mortem analysis.
For detailed information about specific subsystems, see:
The debugger system comprises several interconnected subsystems organized around a central trace database (DBTrace). The architecture separates UI components from the underlying trace storage and agent communication layers.
Title: Debugger System Architecture
Sources: Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/service/tracemgr/DebuggerTraceManagerServicePlugin.java95-96 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java111-149 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/modules/DebuggerModulesProvider.java74-75 Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/DBTrace.java76-136 Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/listing/DBTraceInstructionsView.java47-48
The DebuggerCoordinates class serves as the unified addressing mechanism for the debugger system, identifying a specific point in execution state. Unlike static analysis where an address alone is sufficient, dynamic analysis requires specifying both spatial and temporal coordinates.
| Component | Purpose | Code Entity |
|---|---|---|
| Trace | The recording session | ghidra.trace.model.Trace Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/service/tracemgr/DebuggerTraceManagerServicePlugin.java58 |
| Thread | Execution thread | ghidra.trace.model.thread.TraceThread Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/service/tracemgr/DebuggerTraceManagerServicePlugin.java64 |
| Time/Snap | Point in execution history | long snap Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/modules/DebuggerModulesProvider.java98 |
| Frame | Stack frame level | int frameLevel Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/program/AbstractDBTraceProgramViewListing.java63-64 |
| View | Snapshot perspective | ghidra.trace.model.program.TraceProgramView Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/service/tracemgr/DebuggerTraceManagerServicePlugin.java60 |
The coordinate system is immutable and propagated throughout the UI via events. All UI components synchronize based on coordinate changes. Comparison logic in sameCoordinates ensures UI updates only when relevant state changes Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java44-58
For details, see Trace Database and Coordinates.
Sources: Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java44-58 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/modules/DebuggerModulesProvider.java94-104 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/memory/DebuggerRegionsProvider.java61-72
Ghidra provides specialized UI components for interacting with dynamic execution state. These components extend existing static views but add dynamic traits for location tracking and memory state visualization.
TraceProgramView. It supports PC tracking and automatic disassembly Ghidra/Debug/Debugger/src/test/java/ghidra/app/plugin/core/debug/gui/modules/DebuggerModulesProviderTest.java37For details, see Debugger UI Components.
Sources: Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java111-149 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/modules/DebuggerModulesProvider.java74-182 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/memory/DebuggerRegionsProvider.java59-121
The debugger tracks memory state across time using snapshots. The DBTraceMemoryManager handles the storage of bytes, while DBTraceProgramView provides a Program interface to a specific snapshot Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/program/DBTraceProgramView.java71-81
Title: Memory State and Storage (Natural Language to Code)
Sources: Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/program/DBTraceProgramView.java133 Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/memory/DBTraceMemorySpace.java1 Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/DBTrace.java115
Ghidra integrates with native debuggers (GDB, LLDB, DBG-ENG) through the Trace RMI protocol and Python-based agents. This architecture allows bidirectional state synchronization:
DebuggerTargetService Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java97-98ListenerForTraceChanges monitors thread and object creation within the trace to synchronize the Ghidra UI with the target state Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/service/tracemgr/DebuggerTraceManagerServicePlugin.java107-167DebuggerTraceManagerServicePlugin manages the set of open traces and coordinates activation Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/service/tracemgr/DebuggerTraceManagerServicePlugin.java73-93For details, see Trace RMI Protocol and Debugger Agents.
Sources: Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/service/tracemgr/DebuggerTraceManagerServicePlugin.java73-167 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java97-98
Dynamic analysis is supported by two key services:
DBTraceBreakpointManager Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/DBTrace.java101DebuggerEmulationService allows for time-travel debugging by emulating instructions from a given trace snapshot Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java132-134 This utilizes the Sleigh engine to simulate execution without a live target.For details, see Breakpoints and Emulation.
Sources: Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/DBTrace.java101 Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsProvider.java132-134 Ghidra/Debug/Framework-TraceModeling/src/test/java/ghidra/trace/database/program/DBTraceDisassemblerIntegrationTest.java109-146