tree: 9d5abd12a97005b7f8cda20da4f6d5272355bd79 [search]
  1. test_data/
  2. address_range_map.h
  3. address_range_map_builder.cc
  4. address_range_map_builder.h
  5. address_range_map_builder_unittest.cc
  6. address_range_map_unittest.cc
  7. arch.cc
  8. arch.h
  9. array_type.cc
  10. array_type.h
  11. base_type.cc
  12. base_type.h
  13. BUILD.bazel
  14. BUILD.gn
  15. build_id_index.cc
  16. build_id_index.h
  17. build_id_index_unittest.cc
  18. call_site.h
  19. call_site_parameter.h
  20. code_block.cc
  21. code_block.h
  22. code_block_unittest.cc
  23. collection.cc
  24. collection.h
  25. collection_unittest.cc
  26. compile_unit.cc
  27. compile_unit.h
  28. const_value.cc
  29. const_value.h
  30. const_value_unittest.cc
  31. data_member.cc
  32. data_member.h
  33. debug_symbol_file_type.h
  34. dwarf_abstract_child_iterator.h
  35. dwarf_abstract_child_iterator_unittest.cc
  36. dwarf_binary.h
  37. dwarf_binary_impl.cc
  38. dwarf_binary_impl.h
  39. dwarf_debug_names.cc
  40. dwarf_debug_names.h
  41. dwarf_debug_names_unittest.cc
  42. dwarf_die_decoder.cc
  43. dwarf_die_decoder.h
  44. dwarf_die_ref.h
  45. dwarf_die_ref_unittest.cc
  46. dwarf_die_scanner.cc
  47. dwarf_die_scanner.h
  48. dwarf_expr.cc
  49. dwarf_expr.h
  50. dwarf_expr_eval.cc
  51. dwarf_expr_eval.h
  52. dwarf_expr_eval_unittest.cc
  53. dwarf_lang.cc
  54. dwarf_lang.h
  55. dwarf_location.cc
  56. dwarf_location.h
  57. dwarf_location_unittest.cc
  58. dwarf_stack_entry.cc
  59. dwarf_stack_entry.h
  60. dwarf_symbol_factory.cc
  61. dwarf_symbol_factory.h
  62. dwarf_symbol_factory_unittest.cc
  63. dwarf_tag.cc
  64. dwarf_tag.h
  65. dwarf_tag_unittest.cc
  66. dwarf_test_util.cc
  67. dwarf_test_util.h
  68. dwarf_unit.h
  69. dwarf_unit_impl.cc
  70. dwarf_unit_impl.h
  71. dwo_info.cc
  72. dwo_info.h
  73. elf_symbol.cc
  74. elf_symbol.h
  75. elf_symbol_record.cc
  76. elf_symbol_record.h
  77. elf_symbol_record_unittest.cc
  78. elf_symbol_unittest.cc
  79. enumeration.cc
  80. enumeration.h
  81. file_line.cc
  82. file_line.h
  83. find_line.cc
  84. find_line.h
  85. find_line_unittest.cc
  86. function.cc
  87. function.h
  88. function_call_info.h
  89. function_type.cc
  90. function_type.h
  91. function_type_unittest.cc
  92. identifier.cc
  93. identifier.h
  94. identifier_base.cc
  95. identifier_base.h
  96. identifier_unittest.cc
  97. index.cc
  98. index.h
  99. index_largetest.cc
  100. index_node.cc
  101. index_node.h
  102. index_node_unittest.cc
  103. index_test_support.cc
  104. index_test_support.h
  105. index_unittest.cc
  106. inheritance_path.cc
  107. inheritance_path.h
  108. inherited_from.cc
  109. inherited_from.h
  110. input_location.cc
  111. input_location.h
  112. lazy_symbol.cc
  113. lazy_symbol.h
  114. line_details.cc
  115. line_details.h
  116. line_table.cc
  117. line_table.h
  118. line_table_impl.cc
  119. line_table_impl.h
  120. line_table_unittest.cc
  121. loaded_module_symbols.cc
  122. loaded_module_symbols.h
  123. loaded_module_symbols_unittest.cc
  124. location.cc
  125. location.h
  126. member_ptr.cc
  127. member_ptr.h
  128. member_ptr_unittest.cc
  129. mock_line_table.cc
  130. mock_line_table.h
  131. mock_module_symbols.cc
  132. mock_module_symbols.h
  133. mock_source_file_provider.cc
  134. mock_source_file_provider.h
  135. mock_symbol_data_provider.cc
  136. mock_symbol_data_provider.h
  137. mock_symbol_data_provider_unittest.cc
  138. mock_symbol_factory.h
  139. modified_type.cc
  140. modified_type.h
  141. modified_type_unittest.cc
  142. module_indexer.cc
  143. module_indexer.h
  144. module_symbol_status.h
  145. module_symbols.cc
  146. module_symbols.h
  147. module_symbols_impl.cc
  148. module_symbols_impl.h
  149. module_symbols_impl_largetest.cc
  150. module_symbols_impl_unittest.cc
  151. namespace.cc
  152. namespace.h
  153. process_symbols.cc
  154. process_symbols.h
  155. process_symbols_test_setup.cc
  156. process_symbols_test_setup.h
  157. process_symbols_unittest.cc
  158. README.md
  159. resolve_options.h
  160. skeleton_unit.h
  161. source_file_provider.h
  162. source_util.cc
  163. source_util.h
  164. source_util_unittest.cc
  165. symbol.cc
  166. symbol.h
  167. symbol_context.cc
  168. symbol_context.h
  169. symbol_data_provider.cc
  170. symbol_data_provider.h
  171. symbol_data_provider_unittest.cc
  172. symbol_factory.cc
  173. symbol_factory.h
  174. symbol_test_parent_setter.h
  175. symbol_unittest.cc
  176. symbol_utils.cc
  177. symbol_utils.h
  178. symbol_utils_unittest.cc
  179. system_symbols.cc
  180. system_symbols.h
  181. target_symbols.cc
  182. target_symbols.h
  183. target_symbols_unittest.cc
  184. template_parameter.cc
  185. template_parameter.h
  186. test_symbol_module.cc
  187. test_symbol_module.h
  188. type.cc
  189. type.h
  190. type_test_support.cc
  191. type_test_support.h
  192. unit_index.h
  193. unit_symbol_factory.h
  194. value.cc
  195. value.h
  196. variable.cc
  197. variable.h
  198. variable_location.cc
  199. variable_location.h
  200. variable_location_unittest.cc
  201. variable_test_support.cc
  202. variable_test_support.h
  203. variant.cc
  204. variant.h
  205. variant_part.cc
  206. variant_part.h
  207. visit_scopes.cc
  208. visit_scopes.h
  209. visit_scopes_unittest.cc
src/developer/debug/zxdb/symbols/README.md

Symbol Library (zxdb/symbols)

Overview

//src/developer/debug/zxdb/symbols is the DWARF and ELF symbol indexing and lookup subsystem (Layer 2) for zxdb. It decodes DWARF Debug Information Entries (DIEs), line tables, and ELF symbols into a reference-counted object graph, and evaluates DWARF location expressions (DwarfExprEval).

Interface

Public headers expose these symbol classes, factories, and evaluators:

  • zxdb::Symbol (symbol.h): Reference-counted base class (fxl::RefCountedThreadSafe<Symbol>) for DWARF DIE symbols with manual RTTI (As<T>()). Exposes GetLazySymbol, GetDieRef, parent, GetAssignedName, GetFullName, GetIdentifier, GetCompileUnit, GetDwarfUnit, GetModuleSymbols, GetSymbolContext, and GetLanguage.
  • zxdb::Type (type.h, collection.h): Base type symbol (StripCV, StripCVT, is_declaration, byte_size). Subclasses include BaseType, ModifiedType, Collection (struct, class, union, and Rust enum or tuple), ArrayType, FunctionType, Enumeration, MemberPtr, VariantPart, and Variant.
  • zxdb::Value, zxdb::Variable, zxdb::DataMember: Named data symbols with type, is_external, artificial, const_value, and VariableLocation metadata (value.h, variable.h, data_member.h).
  • zxdb::CodeBlock, zxdb::Function, zxdb::CompileUnit: Lexical scopes, functions, inlined routines, and compilation units (code_block.h, function.h, compile_unit.h). Exposes address range queries (code_ranges, GetAbsoluteCodeRanges, ContainsAddress) and scope traversal (GetMostSpecificChild, GetContainingFunction, GetInlineChain, GetAmbiguousInlineChain).
  • zxdb::LazySymbolBase, zxdb::LazySymbol, zxdb::UncachedLazySymbol, zxdb::SymbolFactory, zxdb::DwarfSymbolFactory: Lazy DIE reference wrappers and factories that decode DwarfDieRef entries into Symbol objects on demand (lazy_symbol.h, symbol_factory.h, dwarf_symbol_factory.h).
  • zxdb::SystemSymbols, zxdb::TargetSymbols, zxdb::ProcessSymbols, zxdb::ModuleSymbols, zxdb::ModuleSymbolsImpl, zxdb::LoadedModuleSymbols: Symbol containers from global BuildIDIndex caches down to loaded modules with SymbolContext address translation (system_symbols.h, target_symbols.h, process_symbols.h, module_symbols.h, loaded_module_symbols.h).
  • zxdb::DwarfExpr, zxdb::DwarfExprEval, zxdb::SymbolDataProvider: Asynchronous stack-based DWARF expression evaluator and target memory/register provider interface (dwarf_expr.h, dwarf_expr_eval.h, symbol_data_provider.h).
  • Binary readers, symbol indices, line tables, and scope visitors: zxdb::DwarfBinary, zxdb::DwarfUnit, zxdb::DwarfDieDecoder, zxdb::DwarfDieScanner, zxdb::ElfSymbol, zxdb::Index, and zxdb::IndexNode. Also exposes zxdb::Identifier, zxdb::Location, zxdb::InputLocation, zxdb::LineTable, zxdb::LineDetails, zxdb::VariableLocation, zxdb::VisitScopes, and symbol name helpers in symbol_utils.h (zxdb::GetSymbolScopePrefix, zxdb::NameHasTemplate, zxdb::StripTemplate, zxdb::AddTemplateParameterToName).

Invariants

Callers and implementations must preserve these invariants:

  • Symbol objects use fxl::RefCountedThreadSafe<Symbol> and do not globally cache or deduplicate instances by DIE offset. Never compare Symbol* pointers to test semantic symbol equality.
  • Downward edges in the symbol graph (parent to child) must use cached LazySymbol instances. Upward edges (such as Symbol::parent() and Function::containing_block()) must use UncachedLazySymbol to prevent reference-counting cycles and memory leaks.
  • SymbolFactory::CreateSymbol(), LazySymbol::Get(), and UncachedLazySymbol::Get() never return nullptr. On failure or unloaded modules, they return an empty Symbol with DwarfTag::kNone. UncachedLazySymbol::Get() constructs a new fxl::RefPtr<Symbol> on each call. Store the fxl::RefPtr<Symbol> in a local variable before you call Symbol::As<Derived>(). When you walk Symbol::parent() chains, verify is_valid() or tag() != DwarfTag::kNone.
  • Symbol, CodeBlock, and ModuleSymbols store module-relative addresses. Pass a SymbolContext bound to a loaded module's base address to convert to or from absolute process addresses.
  • TargetSymbols::ResolveInputLocation rejects address-based locations (InputLocation::Type::kAddress) because address resolution requires a running process via ProcessSymbols.
  • Use Symbol::As<Derived>() instead of C++ dynamic_cast because the build disables compiler RTTI.
  • DWARF unit offsets and type signatures of 0 are valid DWARF values (DwarfDieRef, UnitSymbolFactory, DwarfSymbolFactory). Never use 0 as an invalid sentinel. Use std::optional<uint64_t> and guard accessors with DCHECK(is_valid()).
  • DwarfSymbolFactory handles DwarfTag::kTypeUnit alongside DwarfTag::kCompileUnit so child DIEs can reach llvm::DWARFUnit via CompileUnit. DwarfBinaryImpl queries both normal compilation units (getNormalUnitsVector()) and split-DWARF DWO units (getDWOUnitsVector()).
  • When resolving a DWARF type signature whose target DwarfDieRef is invalid (!sig_ref.is_valid()), return an empty fxl::RefPtr<Symbol>() instead of crashing with FX_CHECK.
  • In FindDebugNamesEntries(), compile unit and DIE unit offsets are validated with has_value() because section and unit offset 0 is a valid DWARF offset. Never use 0 as an invalid sentinel.
  • Local type units in .debug_names use .debug_info offsets. Foreign type unit entries return std::nullopt until zxdb supports split DWARF (https://fxbug.dev/583730372).
  • Index fallback: when .debug_names is absent or empty, or when force_slow_index is set, ModuleSymbolsImpl falls back to the full-DIE Index.

Side Effects

Using zxdb/symbols produces these disk, cache, and IPC side effects:

  • Calling Get() on a LazySymbol or UncachedLazySymbol decodes DWARF DIE records from the binary or .dwo file via SymbolFactory and caches LazySymbol::symbol_.
  • Calling Symbol::GetFullName(), Symbol::GetIdentifier(), or Collection::GetSpecialType() lazily computes and caches the formatted name, Identifier, or SpecialType on the Symbol.
  • SystemSymbols::GetModule() loads ELF and DWARF files from disk via BuildIDIndex and builds the symbol Index, or calls RequestDownloadFunction when local symbols are missing.
  • ProcessSymbols::SetModules() and RetryLoadBuildID() load and unload module symbols, update TargetSymbols, and invoke ProcessSymbols::Notifications callbacks.
  • DwarfExprEval::Eval() and SymbolDataProvider methods issue asynchronous register and memory reads and writes against the target process.

Verification

Run these commands to build and test zxdb/symbols:

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