blob: c7bcfc7df0507c6a39605aa8adf0e5a3475db0c3 [file] [view] [edit]
<!--* freshness: { reviewed: '2026-10-12' } *-->
# Zxdb Client Library (`zxdb/client`)
`zxdb/client` is the UI-independent library for building debugger frontends. It
connects to a target `debug_agent`, models running processes, threads, and stack
frames, and exposes APIs to inspect and control target execution.
## Main Objects
The client object model orders classes from largest to smallest scope.
### Session
`Session` is the top-level connection object. It manages the connection to the
remote system (`Connect`, `Disconnect`, `OpenMinidump`) and dispatches incoming
`debug_ipc` notifications.
To initialize the debugger client, create a `Session` on a thread with an active
`debug::MessageLoop` (`//src/developer/debug/shared`). `Session` owns the
`RemoteAPI` instance, which unit tests often mock via `MockRemoteAPI`.
### System
`System` represents global target OS state on the client. It owns the list of
`Target`, `Breakpoint`, `Filter`, and `SymbolServer` objects. `Session` and
`System` have a 1:1 relationship (`Session` owns connection state, while
`System` owns target OS state).
### Target
`Target` is a container for a debuggable process and its configuration (such as
command-line arguments) across process runs. A `Target` may or may not have a
running process at any moment, and `System` always keeps at least one `Target`.
When the process runs, `Target::GetProcess()` returns its active `Process`
object.
### Process
`Process` represents a live attached or running process on the target. It owns
the running `Thread` objects and exposes APIs to read and write memory or pause
and continue all threads.
In the console UI, the `process` noun refers to a `Target` (which can be idle or
running), whereas `client::Process` always represents a live process.
### Thread
`Thread` represents a live thread inside a `Process`. It owns a `Stack` and
drives thread stepping through `ThreadController` instances. `Thread` populates
its `Stack` when it stops on an exception, though initial process or thread
start exceptions may have an empty stack.
### Stack
`Stack` manages the backtrace of a stopped `Thread`, including physical stack
frames and synthetic inline function frames.
When a thread stops on an exception, `debug_agent` sends only the top 1 to 2
stack frames so internal stepping controllers avoid full stack unwinds. Callers
that need the full backtrace must call `Stack::SyncFrames` asynchronously.
### Frame
`Frame` represents a single stack frame (either a physical frame or an inline
function call). Callers evaluate expressions and inspect local variables in the
context of a frame through `Frame::GetEvalContext()`.
## Other Objects
### Breakpoint
`System` owns all `Breakpoint` objects globally. A breakpoint can scope itself
to a specific `Target` or `Thread`, but the `Breakpoint` instance itself remains
owned by `System`.
### Filter
`Filter` watches for matching process names, job KOIDs, or component
monikers/URLs and attaches automatically when a match starts.
## Thread Control
`ThreadController` subclasses implement thread stepping policies. To step a
thread, construct the desired `ThreadController` subclass and pass it to
`Thread::ContinueWith`. The controller inspects stop exceptions and continues or
stops the thread:
- `FinishThreadController`: Runs until the current stack frame returns.
- `StepOverThreadController`: Steps over function calls on the current line.
- `StepThreadController`: Steps into source lines or machine instructions.
- `UntilThreadController`: Runs until execution reaches a target address.
`Thread` nests controllers on a stack so a thread can handle nested steps and
still stop when the outer step-over finishes.
## Expressions
`zxdb/expr` evaluates expressions and variables using an `EvalContext`. Callers
normally get this `EvalContext` from `Frame::GetEvalContext()`, which provides
access to local variables, registers, and process memory.
## Interface
Public headers expose these client classes and observers:
- `zxdb::ClientObject`: Base class for all client objects holding a pointer to
the owning `Session` (`client_object.h`).
- `zxdb::Session`, `zxdb::SessionConnectionInfo`, `zxdb::SessionConnectionType`:
Top-level connection manager (`Connect`, `Disconnect`, `OpenMinidump`,
`OnStreamReadable`) owning `System`, `ArchInfo`, and `RemoteAPI`
(`session.h`).
- `zxdb::RemoteAPI`, `zxdb::MinidumpRemoteAPI`: Asynchronous `debug_ipc`
request/reply interface and its Crashpad minidump implementation
(`remote_api.h`, `minidump_remote_api.h`).
- `zxdb::System`, `zxdb::SystemObserver`: Global system state manager for
`Target`, `Breakpoint`, `Filter`, `SymbolServer`, `SystemSymbols`, and
`DownloadManager` (`Pause`, `Continue`, `CancelAllThreadControllers`)
(`system.h`, `system_observer.h`).
- `zxdb::Target`, `zxdb::TargetObserver`: Holder for a debuggable process and
its configuration (`State::kNone`, `kStarting`, `kAttaching`, `kRunning`,
`Launch`, `Kill`, `Attach`, `Detach`, `GetProcess`, `GetSymbols`) (`target.h`,
`target_observer.h`).
- `zxdb::Process`, `zxdb::ProcessObserver`: Live process model (`GetTarget`,
`GetKoid`, `GetName`, `GetComponentInfo`, `GetSymbols`, `GetModules`,
`GetAspace`, `GetThreads`, `SyncThreads`, `Pause`, `Continue`,
`ContinueUntil`, `ReadMemory`, `WriteMemory`, `LoadInfoHandleTable`,
`GetAsyncTaskProvidersForLanguage`) (`process.h`).
- `zxdb::Thread`, `zxdb::ThreadObserver`: Live thread model (`GetProcess`,
`GetKoid`, `GetState`, `GetBlockedReason`, `CurrentStopInfo`, `Pause`,
`Continue`, `ContinueWith`, `AddController`, `AddPostStopTask`,
`CancelAllThreadControllers`, `ResumeFromAsyncThreadController`, `JumpTo`,
`StepInstructions`, `GetStack`, `GetAsyncTaskTree`) (`thread.h`).
- `zxdb::Stack`, `zxdb::Stack::Delegate`: Stopped thread backtrace manager for
frame synchronization (`SyncFrames`), inline frame expansion, and
`FrameFingerprint` computation (`stack.h`).
- `zxdb::Frame`: Physical or inline stack frame interface (`GetThread`,
`IsInline`, `GetPhysicalFrame`, `GetLocation`, `GetAddress`, `GetTrust`,
`GetRegisterCategorySync`, `GetRegisterCategoryAsync`, `WriteRegister`,
`GetSymbolDataProvider`, `GetEvalContext`, `GetSourceFileProvider`)
(`frame.h`).
- `zxdb::AsyncTask`, `zxdb::AsyncTaskProvider`, `zxdb::AsyncTaskTree`,
`zxdb::FuchsiaAsyncRustTaskProvider`: Interfaces and tree container for
inspecting async tasks (such as Rust futures) on a `Thread` (`async_task.h`,
`async_task_tree.h`).
- `zxdb::Breakpoint`, `zxdb::BreakpointSettings`, `zxdb::BreakpointLocation`,
`zxdb::BreakpointObserver`, `zxdb::ExecutionScope`: Global and scoped
breakpoints with per-process `BreakpointLocation` controls (`breakpoint.h`,
`breakpoint_settings.h`, `breakpoint_location.h`).
- `zxdb::Filter`: Process, component, and job attach filter synchronized with
`debug_agent` (`filter.h`).
- `zxdb::ThreadController`, `zxdb::StepThreadController`,
`zxdb::StepIntoThreadController`, `zxdb::StepOverThreadController`,
`zxdb::FinishThreadController`, `zxdb::FinishPhysicalFrameThreadController`,
`zxdb::UntilThreadController`, `zxdb::UntilProcessController`,
`zxdb::CallFunctionThreadController`: Composable controllers for thread
stepping, finishing, running until addresses, and calling target functions
(`thread_controller.h`).
- `zxdb::SettingStore`, `zxdb::MapSettingStore`, `zxdb::SettingSchema`,
`zxdb::SettingValue`, `zxdb::SettingStoreObserver`: Schema-validated
hierarchical configuration store for `System`, `Target`, `Thread`,
`Breakpoint`, and `Filter` (`setting_store.h`).
- `zxdb::MemoryDump`, `zxdb::Disassembler`, `zxdb::SymbolServer`,
`zxdb::ArchInfo`, `zxdb::PrettyStackManager`: Memory dump container, LLVM
instruction disassembler, symbol server client, architecture descriptor, and
frame globbing manager.
## Invariants
Callers and implementations must preserve these invariants:
- `Session` and `System` maintain a 1:1 lifecycle correspondence, and `Session`
owns the `System` instance.
- `System` always contains at least one `Target`. `System::DeleteTarget` fails
if the target is running or is the only remaining `Target` in `System`.
- A `Target` persists across process runs (`State::kNone`, `kStarting`,
`kAttaching`, `kRunning`). A `Process` object exists only while a process is
active, and `Process::GetTarget()` is never null.
- Containers own the raw pointers returned by `System::GetTargets`,
`System::GetBreakpoints`, `System::GetFilters`, `System::GetSymbolServers`,
`Process::GetThreads`, and `Breakpoint::GetLocations`. Never cache those raw
pointers across message loop turns. Use `fxl::WeakPtr` instead.
- On thread exception stops, `debug_agent` sends only the top 1 to 2 stack
frames. Call `Stack::SyncFrames` asynchronously for full backtraces, and never
assume `Stack` is non-empty on an exception stop.
- `Frame::GetRegisterCategorySync` guarantees synchronous availability only for
general registers. Call `Frame::GetRegisterCategoryAsync` on the top frame for
other register categories, and call `Frame::WriteRegister` only on the top
physical frame.
- Active `ThreadController` instances evaluate thread stops via `OnThreadStop`
returning `StopOp`. `kFuture` takes highest precedence (waiting for
`Thread::ResumeFromAsyncThreadController`), `kStopDone` beats `kContinue`, and
the thread stops if all controllers return `kUnexpected`.
- `Process` bounds `stdout_` and `stderr_` capture buffers to
`Process::kMaxIOBufferSize` (1 MiB) using circular deques.
## Side Effects
`zxdb/client` produces these IPC, file I/O, and target side effects:
- Serializes `debug_ipc` messages over `debug::StreamBuffer` and
`debug::BufferedFD` to talk to the remote `debug_agent`.
- Mutates remote target state over IPC by starting, attaching, detaching, and
killing processes, and by suspending or resuming threads. Also writes memory
(`Process::WriteMemory`), writes CPU registers (`Frame::WriteRegister`,
`Thread::JumpTo`), sets breakpoints, and calls target functions
(`CallFunctionThreadController`).
- Reads local Crashpad minidumps (`MinidumpRemoteAPI`), reads local symbols and
source files (`SourceFileProviderImpl`), and downloads debug symbols
(`DownloadManager`, `SymbolServer`).
- Posts asynchronous tasks to `debug::MessageLoop` and notifies `Session`,
`System`, `Target`, `Process`, `Thread`, `Breakpoint`, `Download`,
`Component`, and `SettingStore` observers.
- Emits debugger usage telemetry events through `AnalyticsReporter`.
## Verification
Run these commands to build and test `zxdb/client`:
- Build: `fx build //src/developer/debug/zxdb/client`
- Test: `fx test zxdb_tests`