Google GitGoogle Git
Sign in
fuchsia/fuchsia/HEAD/./src/developer/debug/zxdb/console
tree: 53a4f3c4326678d398f9ec520529b96be5974496 [search]
  1. commands/
  2. analyze_memory.cc
  3. analyze_memory.h
  4. analyze_memory_unittest.cc
  5. BUILD.gn
  6. command.cc
  7. command.h
  8. command_context.cc
  9. command_context.h
  10. command_context_unittest.cc
  11. command_group.h
  12. command_line_options.cc
  13. command_line_options.h
  14. command_parser.cc
  15. command_parser.h
  16. command_parser_unittest.cc
  17. command_sequence.cc
  18. command_sequence.h
  19. command_sequence_unittest.cc
  20. command_utils.cc
  21. command_utils.h
  22. command_utils_unittest.cc
  23. console.cc
  24. console.h
  25. console_context.cc
  26. console_context.h
  27. console_context_unittest.cc
  28. console_impl.cc
  29. console_impl.h
  30. console_impl_unittest.cc
  31. console_noninteractive.cc
  32. console_noninteractive.h
  33. console_test.cc
  34. console_test.h
  35. did_you_mean.cc
  36. did_you_mean.h
  37. fd_streamer.cc
  38. fd_streamer.h
  39. format_async_task.cc
  40. format_async_task.h
  41. format_async_task_unittest.cc
  42. format_context.cc
  43. format_context.h
  44. format_context_unittest.cc
  45. format_exception.cc
  46. format_exception.h
  47. format_exception_unittest.cc
  48. format_filter.cc
  49. format_filter.h
  50. format_filter_unittest.cc
  51. format_frame.cc
  52. format_frame.h
  53. format_frame_unittest.cc
  54. format_handle.cc
  55. format_handle.h
  56. format_handle_unittest.cc
  57. format_location.cc
  58. format_location.h
  59. format_location_unittest.cc
  60. format_memory.cc
  61. format_memory.h
  62. format_memory_unittest.cc
  63. format_register.cc
  64. format_register.h
  65. format_register_arm64.cc
  66. format_register_arm64.h
  67. format_register_unittest.cc
  68. format_register_x64.cc
  69. format_register_x64.h
  70. format_settings.cc
  71. format_settings.h
  72. format_settings_unittest.cc
  73. format_symbol.cc
  74. format_symbol.h
  75. format_symbol_unittest.cc
  76. format_table.cc
  77. format_table.h
  78. format_table_unittest.cc
  79. format_target.cc
  80. format_target.h
  81. format_target_unittest.cc
  82. format_thread.cc
  83. format_thread.h
  84. format_thread_unittest.cc
  85. input_location_parser.cc
  86. input_location_parser.h
  87. input_location_parser_unittest.cc
  88. mock_console.cc
  89. mock_console.h
  90. nouns.cc
  91. nouns.h
  92. nouns_unittest.cc
  93. print_command_utils.cc
  94. print_command_utils.h
  95. README.md
  96. script_runner.cc
  97. script_runner.h
  98. script_runner_unittest.cc
  99. string_formatters.cc
  100. string_formatters.h
  101. string_formatters_unittest.cc
  102. switch_record.h
  103. test_failure_stack_matcher.cc
  104. test_failure_stack_matcher.h
  105. test_failure_stack_matcher_unittest.cc
  106. verbs.cc
  107. verbs.h
  108. verbs_settings.cc
  109. verbs_settings.h
  110. verbs_settings_unittest.cc
src/developer/debug/zxdb/console/README.md

Zxdb Console (zxdb/console)

Overview

//src/developer/debug/zxdb/console implements the interactive and non-interactive command-line interface (Layer 5) for zxdb. It handles CLI flag parsing, noun/verb tokenization and dispatch, active object tracking via ConsoleContext, input location resolution, and terminal formatting for frames, registers, and tables.

Interface

Public headers and subdirectories expose these console components:

  • Console frontends and session context (console.h, console_impl.h, console_noninteractive.h, console_context.h): zxdb::Console, zxdb::Console::OutputObserver, zxdb::ConsoleImpl, zxdb::ConsoleNoninteractive, and zxdb::ConsoleContext (tracks active 1-based target/thread/breakpoint IDs and 0-based frame indices).
  • Command parsing, completion, and execution (command.h, command_parser.h, command_context.h, command_sequence.h, command_line_options.h): zxdb::Command, zxdb::CommandCallback, zxdb::DispatchCommand, zxdb::CommandContext, zxdb::ConsoleCommandContext, zxdb::OfflineCommandContext, and zxdb::NestedCommandContext. Also exposes zxdb::CommandToken, zxdb::TokenizeCommand, zxdb::ParseCommand, zxdb::FillCommandContextCallback, zxdb::GetCommandCompletions, zxdb::RunCommandSequence, zxdb::ReadCommandsFromFile, zxdb::CommandLineOptions, and zxdb::ParseCommandLine.
  • Noun, verb, and switch registries (nouns.h, verbs.h, switch_record.h): zxdb::Noun, zxdb::NounRecord, zxdb::GetNouns, zxdb::NounToString, zxdb::NounToRecord, zxdb::GetStringNounMap, zxdb::ExecuteNoun, zxdb::AppendNouns, and zxdb::GetNounSwitches. Also exposes zxdb::SourceAffinity, zxdb::Verb, zxdb::VerbRecord, zxdb::GetVerbs, zxdb::VerbToString, zxdb::GetVerbRecord, zxdb::GetStringVerbMap, zxdb::AppendSettingsVerbs, and zxdb::SwitchRecord.
  • Command validation and evaluation helpers (command_utils.h): zxdb::AssertRunningTarget, zxdb::AssertStoppedThreadWithFrameCommand, zxdb::AssertAllStoppedThreadsCommand, zxdb::CheckHexPrefix, zxdb::ReadUint64Arg, zxdb::ThreadStateToString, zxdb::ExecutionScopeToString, zxdb::ExecutionScopeForCommand, zxdb::ResolveBreakpointsForModification, zxdb::FormatBreakpoint, zxdb::FormatInputLocation, and zxdb::FormatInputLocations. Also exposes zxdb::GetEvalContextForCommand, zxdb::EvalCommandExpression, zxdb::EvalCommandAddressExpression, zxdb::RewriteCommandExpressionError, zxdb::FormatConsoleString, zxdb::GetNumberFormatForTarget, zxdb::GetRunnableTarget, zxdb::GetRunningProcesses, zxdb::VerifySystemHasRunningProcess, zxdb::ProcessCommandCallback, and zxdb::ScheduleAsyncPrintReturnValue.
  • Input location parsing and resolution (input_location_parser.h): zxdb::ParseGlobalInputLocation, zxdb::EvalGlobalInputLocation, zxdb::ParseLocalInputLocation, zxdb::EvalLocalInputLocation, zxdb::ResolveInputLocations, zxdb::ResolveUniqueInputLocation, and zxdb::CompleteInputLocation.
  • Stack, location, register, target, and table formatters (format_frame.h, format_location.h, format_register.h, format_table.h, format_target.h): zxdb::FormatFrameOptions, zxdb::FormatStackOptions, zxdb::FormatStack, zxdb::FormatFrame, zxdb::FormatAllThreadStacks, zxdb::FormatLocationOptions, zxdb::FormatLocation, zxdb::FormatFileName, and zxdb::FormatFileLine. Also exposes zxdb::FormatRegisterOptions, zxdb::FormatRegisters, zxdb::FormatGeneralRegisters, zxdb::FormatGeneralVectorRegisters, zxdb::DescribeRegister, zxdb::Align, zxdb::ColSpec, zxdb::FormatTable, zxdb::FormatTarget, zxdb::FormatTargetList, and zxdb::TargetStateToString.
  • commands: Individual console verb implementations (attach, break, step, run, print, backtrace, and memory/symbol inspection) exposing VerbRecord descriptors.

Invariants

Callers and implementations must preserve these invariants:

  • Console maintains a global singleton pointer accessible via Console::get().
  • Console::output_enabled_, Console::streaming_enabled_, and ConsoleImpl::input_enabled_ act as balanced reference counters. Each feature is active only when its counter is greater than 0.
  • Command::targets_ is never empty for valid commands, and Command::target() asserts !targets_.empty().
  • Single-object getters on Command (frame(), thread(), breakpoint(), filter(), sym_server()) return non-null only when the command has exactly one instance of that noun.
  • CommandContext is reference-counted and must stay alive across asynchronous command execution. Pending AsyncOutputBuffer instances hold a RefPtr<CommandContext>, and the completion callback runs when CommandContext destructs.
  • ConsoleContext assigns 1-based user IDs to targets, threads, breakpoints, filters, and symbol servers (0 means none or invalid). Frame IDs use 0-based indices into the thread's backtrace.
  • The active target in ConsoleContext always exists outside setup and teardown, whereas the active thread, breakpoint, filter, and symbol server may be null or 0.
  • GetNouns() and GetVerbs() return static maps that never change after initialization.

Side Effects

zxdb/console produces these terminal, file I/O, and session side effects:

  • ConsoleImpl watches stdin via debug::MessageLoop, writes formatted output to stdout, and reads and writes $HOME/.zxdb_history.
  • Console::Output and CommandContext::Output register completion callbacks and hold RefPtr references to pending AsyncOutputBuffer instances until they finish.
  • ConsoleContext observes Session, System, Target, Process, Thread, Breakpoint, Download, Component, and SettingStore. It updates active selections, evaluates display expressions on thread stop, and switches between Embedded and EmbeddedInteractive console modes.
  • RunCommandSequence reads script files from disk and dispatches commands on Console in order until completion or the first error.
  • ScheduleAsyncPrintReturnValue registers a PostStopTask on a stopped thread to evaluate and print function return values before normal stop handling.

Verification

Run these commands to build and test zxdb/console:

  • Build: fx build //src/developer/debug/zxdb/console
  • Test: fx test zxdb_tests