Google GitGoogle Git
Sign in
fuchsia/fuchsia/main/./src/developer/debug/debug_agent
tree: 20bbc897b9796dce5f34a3326cc177dee11d86ab [search]
  1. integration_tests/
  2. meta/
  3. posix/
  4. test_data/
  5. testing/
  6. align.cc
  7. align.h
  8. align_unittest.cc
  9. aligned_chunk.cc
  10. aligned_chunk.h
  11. aligned_chunk_unittest.cc
  12. arch.h
  13. arch_arm64.cc
  14. arch_arm64_unittest.cc
  15. arch_types.h
  16. arch_x64.cc
  17. arch_x64_unittest.cc
  18. automation_handler.cc
  19. automation_handler.h
  20. automation_instruction_executor.cc
  21. automation_instruction_executor.h
  22. automation_instruction_executor_unittest.cc
  23. backtrace_utils.cc
  24. backtrace_utils.h
  25. binary_launcher.h
  26. breakpoint.cc
  27. breakpoint.h
  28. breakpoint_unittest.cc
  29. BUILD.bazel
  30. BUILD.gn
  31. component_manager.cc
  32. component_manager.h
  33. debug_agent.cc
  34. debug_agent.h
  35. debug_agent_observer.h
  36. debug_agent_server.cc
  37. debug_agent_server.h
  38. debug_agent_server_unittest.cc
  39. debug_agent_unittest.cc
  40. debug_registers.h
  41. debug_registers_arm64.cc
  42. debug_registers_arm64_unittest.cc
  43. debug_registers_x64.cc
  44. debug_registers_x64_unittest.cc
  45. debugged_job.cc
  46. debugged_job.h
  47. debugged_job_unittest.cc
  48. debugged_process.cc
  49. debugged_process.h
  50. debugged_process_unittest.cc
  51. debugged_thread.cc
  52. debugged_thread.h
  53. debugged_thread_breakpoint_unittest.cc
  54. debugged_thread_unittest.cc
  55. elf_utils.cc
  56. elf_utils.h
  57. elf_utils_unittest.cc
  58. exception_handle.h
  59. filter.cc
  60. filter.h
  61. filter_unittest.cc
  62. general_registers.cc
  63. general_registers.h
  64. hardware_breakpoint.cc
  65. hardware_breakpoint.h
  66. hardware_breakpoint_unittest.cc
  67. job_exception_channel_type.h
  68. job_exception_observer.h
  69. job_handle.cc
  70. job_handle.h
  71. launcher.cc
  72. launcher.h
  73. launcher_unittest.cc
  74. limbo_provider.h
  75. linux_arch.h
  76. linux_arch_arm64.cc
  77. linux_arch_x64.cc
  78. linux_binary_launcher.cc
  79. linux_binary_launcher.h
  80. linux_component_manager.cc
  81. linux_component_manager.h
  82. linux_exception_handle.cc
  83. linux_exception_handle.h
  84. linux_job_handle.cc
  85. linux_job_handle.h
  86. linux_limbo_provider.h
  87. linux_process_handle.cc
  88. linux_process_handle.h
  89. linux_suspend_handle.h
  90. linux_system_interface.cc
  91. linux_system_interface.h
  92. linux_task.cc
  93. linux_task.h
  94. linux_task_observer.h
  95. linux_thread_handle.cc
  96. linux_thread_handle.h
  97. linux_utils.cc
  98. linux_utils.h
  99. linux_utils_unittest.cc
  100. local_stream_backend.cc
  101. local_stream_backend.h
  102. main.cc
  103. main_launcher.cc
  104. minidump_iterator.cc
  105. minidump_iterator.h
  106. minidump_iterator_unittest.cc
  107. mock_component_manager.cc
  108. mock_component_manager.h
  109. mock_debug_agent_harness.cc
  110. mock_debug_agent_harness.h
  111. mock_exception_handle.h
  112. mock_job_handle.cc
  113. mock_job_handle.h
  114. mock_limbo_provider.cc
  115. mock_limbo_provider.h
  116. mock_process.cc
  117. mock_process.h
  118. mock_process_breakpoint.h
  119. mock_process_handle.cc
  120. mock_process_handle.h
  121. mock_stream_backend.h
  122. mock_suspend_handle.h
  123. mock_system_interface.cc
  124. mock_system_interface.h
  125. mock_thread.cc
  126. mock_thread.h
  127. mock_thread_handle.cc
  128. mock_thread_handle.h
  129. module_list.cc
  130. module_list.h
  131. process_breakpoint.cc
  132. process_breakpoint.h
  133. process_handle.h
  134. process_handle_observer.h
  135. process_info_iterator.cc
  136. process_info_iterator.h
  137. process_info_iterator_unittest.cc
  138. README.md
  139. remote_api.h
  140. remote_api_adapter.cc
  141. remote_api_adapter.h
  142. software_breakpoint.cc
  143. software_breakpoint.h
  144. software_breakpoint_unittest.cc
  145. stdio_handles.h
  146. suspend_handle.h
  147. system_interface.cc
  148. system_interface.h
  149. system_interface_unittest.cc
  150. test_realm.cc
  151. test_realm.h
  152. test_utils.h
  153. thread_handle.h
  154. time.h
  155. time_zircon_unittest.cc
  156. unwind.cc
  157. unwind.h
  158. unwind_unittest.cc
  159. watchpoint.cc
  160. watchpoint.h
  161. watchpoint_info.h
  162. watchpoint_unittest.cc
  163. zircon_arch.cc
  164. zircon_arch.h
  165. zircon_arch_arm64.cc
  166. zircon_arch_x64.cc
  167. zircon_binary_launcher.cc
  168. zircon_binary_launcher.h
  169. zircon_component_manager.cc
  170. zircon_component_manager.h
  171. zircon_exception_handle.cc
  172. zircon_exception_handle.h
  173. zircon_job_handle.cc
  174. zircon_job_handle.h
  175. zircon_job_handle_unittest.cc
  176. zircon_limbo_provider.cc
  177. zircon_limbo_provider.h
  178. zircon_limbo_provider_unittest.cc
  179. zircon_process_handle.cc
  180. zircon_process_handle.h
  181. zircon_suspend_handle.cc
  182. zircon_suspend_handle.h
  183. zircon_system_interface.cc
  184. zircon_system_interface.h
  185. zircon_system_interface_unittest.cc
  186. zircon_thread_handle.cc
  187. zircon_thread_handle.h
  188. zircon_utils.cc
  189. zircon_utils.h
  190. zxdb_test_app.cc
src/developer/debug/debug_agent/README.md

Debug Agent (debug_agent)

debug_agent is the target-side backend stub for the Fuchsia debugger. It runs on the target Fuchsia system (and experimentally on Linux hosts). It communicates over debug_ipc (../ipc) with the zxdb frontend (../zxdb) on the developer's workstation.

User Documentation

Read the debugger setup and usage guides for user-facing workflows.

Manual Testing

Test these four workflows whenever you edit process attachment or component starting:

  • run-component fuchsia-pkg://fuchsia.com/debug_agent#meta/debug_agent.cm (or another component URL).
  • attach some_filter when a matching process already exists.
  • attach some_filter before a matching process starts.
  • attach 56421 to attach by numeric PID/KOID (debug_agent uses separate code paths for PID and filter attachment).

Interface

Public headers expose these core classes and helpers:

  • debug_agent::DebugAgent / debug_agent::DebugAgentOptions: Core backend state machine managing attached jobs, processes, breakpoints, filters, and RemoteAPI dispatch (debug_agent.h).
  • debug_agent::DebugAgentServer: fuchsia.debugger.DebugAgent FIDL server that bridges FIDL requests and FilterIterator attachment into DebugAgent (debug_agent_server.h).
  • debug_agent::DebuggedJob / debug_agent::DebuggedJobCreateInfo: Job exception channel observer that intercepts newly starting processes (debugged_job.h).
  • debug_agent::DebuggedProcess / debug_agent::DebuggedProcessCreateInfo: Per-process state controller managing threads, memory access, module notifications, stdout/stderr capture, and serialized breakpoint step-over queues (debugged_process.h).
  • debug_agent::DebuggedThread: Per-thread execution state, suspension ref-counting (ClientSuspend, InternalSuspend), single-stepping, and register/exception handling (debugged_thread.h).
  • debug_agent::Breakpoint / debug_agent::ProcessBreakpoint: Logical (Breakpoint) and per-process address/range (ProcessBreakpoint) breakpoint abstractions (breakpoint.h, process_breakpoint.h).
  • debug_agent::SoftwareBreakpoint, debug_agent::HardwareBreakpoint, debug_agent::Watchpoint: Concrete ProcessBreakpoint subclasses for instruction-patching traps, CPU debug register breakpoints, and memory read/write watchpoints (software_breakpoint.h, hardware_breakpoint.h, watchpoint.h).
  • debug_agent::RemoteAPI / debug_agent::RemoteAPIAdapter: Abstract RPC handler interface for debug_ipc requests and stream dispatch adapter (remote_api.h, remote_api_adapter.h).
  • debug_agent::SystemInterface / debug_agent::ZirconSystemInterface: Abstract and Zircon-backed representations of the target job tree, component manager, and limbo provider (system_interface.h, zircon_system_interface.h).
  • debug_agent::ComponentManager: Component lifecycle event listener, test runner (fuchsia.test.manager), and component matcher (component_manager.h).
  • debug_agent::LimboProvider: Interface to ProcessLimbo for inspecting, claiming, and releasing crashed processes waiting in limbo (limbo_provider.h).
  • debug_agent::ExceptionHandle: Wrapper around a kernel exception token and its resolution state (exception_handle.h).
  • debug_agent::Filter: Job, process name, and component moniker/URL filter matcher (filter.h).
  • debug_agent::UnwindStack: Stack unwinding wrapper around //src/lib/unwinder (unwind.h).
  • debug_agent::AutomationHandler: Executor for automated memory and register readout instructions attached to breakpoint hits (automation_handler.h).
  • posix: Allocation-free POSIX/Linux system call helpers (HANDLE_EINTR, IGNORE_EINTR, linux::DirReaderLinux, posix::ShuffleFileDescriptors).

Invariants

Callers and implementations must preserve these invariants:

  • Initialize a debug::PlatformMessageLoop (debug::MessageLoopFuchsia on Fuchsia) on the current thread before constructing DebugAgent. The debug::StreamBuffer passed to DebugAgent::Connect or RemoteAPIAdapter must outlive the adapter.
  • DebugAgent::SendNotification requires ipc_version_ > 0 (negotiated via the IPC Hello handshake) before serializing notifications to a stream.
  • Call Init() and check for an OK debug::Status before using any DebuggedJob or DebuggedProcess instance.
  • A DebuggedThread runs only when neither client_suspend_handle_ nor any internal SuspendHandle token exists.
  • DebuggedProcess serializes breakpoint step-overs through step_over_queue_ so only one ProcessBreakpoint steps over at a time. DebuggedProcess ignores duplicate step-over requests for the same thread and breakpoint.
  • SoftwareBreakpoint::StepOverCleanup must run only after the next queued breakpoint's ExecuteStepOver acquires its suspend tokens. It uses a per-thread multimap (suspend_tokens_) to prevent premature thread resumption between consecutive step-overs.
  • Processes claimed from LimboProvider lack ZX_RIGHT_DESTROY. When killing a from_limbo process fails with ZX_ERR_ACCESS_DENIED, DebugAgent detaches, records its KOID in killed_limbo_procs_, and calls LimboProvider::ReleaseProcess once it re-enters limbo.
  • ProcessBreakpoint::OnHit does not delete one-shot breakpoints internally. Callers must inspect BreakpointStats::should_delete and delete the breakpoint afterward to avoid self-deletion during hit handling.
  • SystemInterface is non-movable because ComponentManager holds a raw back-pointer to it.
  • Recursive filter matching creates new kComponentMonikerPrefix filters only for moniker patterns not already present in DebugAgent::filters_.
  • DebuggedJob and AttachConfig distinguish the exclusive "job" exception channel (crash exceptions) from the non-exclusive "job debugger" channel (ZX_EXCP_PROCESS_STARTING). Process attachment uses the process debugger exception channel instead.
  • Job attachments with kMinimal or kNone priority do not claim the debugger exception channel and do not receive upfront ZX_EXCP_PROCESS_STARTING or ZX_EXCP_THREAD_STARTING notifications. Exception handlers in DebuggedJob and DebuggedProcess must lazily create DebuggedProcess and call PopulateCurrentThreads upon receiving an exception.

Side Effects

debug_agent produces these target and IPC side effects:

  • Reads and writes debuggee process virtual memory (including instruction patching in SoftwareBreakpoint) and thread general/debug registers (HardwareBreakpoint, Watchpoint, single-stepping, and unwinding).
  • Binds to Zircon job and process exception channels, suspends and resumes threads via SuspendHandle tokens, and resolves or forwards kernel exceptions via ExceptionHandle.
  • Exchanges messages with zxdb clients over debug_ipc streams (BufferedStream / RemoteAPIAdapter) and serves the fuchsia.debugger.DebugAgent FIDL protocol via DebugAgentServer.
  • Calls Fuchsia services to start binaries, components, and tests (BinaryLauncher, ComponentManager), watch component lifecycle events, and claim or release crashed processes in ProcessLimbo.
  • Deleting the last DebugAgentObserver without an active debug_ipc client quits the message loop and exits debug_agent.
  • Captures debuggee stdout/stderr streams to emit NotifyIO messages to the client, and generates process minidumps on request.

Verification

Run these commands to build and test debug_agent:

  • Build: fx build //src/developer/debug/debug_agent
  • Test: fx test debug_agent_unit_tests.cm debug_agent_launcher_unit_tests debug_agent_integration_tests