1 //===-- SymbolFile.h --------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_SYMBOL_SYMBOLFILE_H 10 #define LLDB_SYMBOL_SYMBOLFILE_H 11 12 #include "lldb/Core/PluginInterface.h" 13 #include "lldb/Core/SourceLocationSpec.h" 14 #include "lldb/Symbol/CompilerDecl.h" 15 #include "lldb/Symbol/CompilerDeclContext.h" 16 #include "lldb/Symbol/CompilerType.h" 17 #include "lldb/Symbol/Function.h" 18 #include "lldb/Symbol/SourceModule.h" 19 #include "lldb/Symbol/Type.h" 20 #include "lldb/Symbol/TypeList.h" 21 #include "lldb/Symbol/TypeSystem.h" 22 #include "lldb/Target/Statistics.h" 23 #include "lldb/Utility/XcodeSDK.h" 24 #include "lldb/lldb-private.h" 25 #include "llvm/ADT/DenseSet.h" 26 #include "llvm/Support/Errc.h" 27 28 #include <mutex> 29 30 #if defined(LLDB_CONFIGURATION_DEBUG) 31 #define ASSERT_MODULE_LOCK(expr) (expr->AssertModuleLock()) 32 #else 33 #define ASSERT_MODULE_LOCK(expr) ((void)0) 34 #endif 35 36 namespace lldb_private { 37 38 class SymbolFile : public PluginInterface { 39 /// LLVM RTTI support. 40 static char ID; 41 42 public: 43 /// LLVM RTTI support. 44 /// \{ 45 virtual bool isA(const void *ClassID) const { return ClassID == &ID; } 46 static bool classof(const SymbolFile *obj) { return obj->isA(&ID); } 47 /// \} 48 49 // Symbol file ability bits. 50 // 51 // Each symbol file can claim to support one or more symbol file abilities. 52 // These get returned from SymbolFile::GetAbilities(). These help us to 53 // determine which plug-in will be best to load the debug information found 54 // in files. 55 enum Abilities { 56 CompileUnits = (1u << 0), 57 LineTables = (1u << 1), 58 Functions = (1u << 2), 59 Blocks = (1u << 3), 60 GlobalVariables = (1u << 4), 61 LocalVariables = (1u << 5), 62 VariableTypes = (1u << 6), 63 kAllAbilities = ((1u << 7) - 1u) 64 }; 65 66 static SymbolFile *FindPlugin(lldb::ObjectFileSP objfile_sp); 67 68 // Constructors and Destructors 69 SymbolFile(lldb::ObjectFileSP objfile_sp) 70 : m_objfile_sp(std::move(objfile_sp)), m_abilities(0), 71 m_calculated_abilities(false) {} 72 73 ~SymbolFile() override = default; 74 75 /// Get a mask of what this symbol file supports for the object file 76 /// that it was constructed with. 77 /// 78 /// Each symbol file gets to respond with a mask of abilities that 79 /// it supports for each object file. This happens when we are 80 /// trying to figure out which symbol file plug-in will get used 81 /// for a given object file. The plug-in that responds with the 82 /// best mix of "SymbolFile::Abilities" bits set, will get chosen to 83 /// be the symbol file parser. This allows each plug-in to check for 84 /// sections that contain data a symbol file plug-in would need. For 85 /// example the DWARF plug-in requires DWARF sections in a file that 86 /// contain debug information. If the DWARF plug-in doesn't find 87 /// these sections, it won't respond with many ability bits set, and 88 /// we will probably fall back to the symbol table SymbolFile plug-in 89 /// which uses any information in the symbol table. Also, plug-ins 90 /// might check for some specific symbols in a symbol table in the 91 /// case where the symbol table contains debug information (STABS 92 /// and COFF). Not a lot of work should happen in these functions 93 /// as the plug-in might not get selected due to another plug-in 94 /// having more abilities. Any initialization work should be saved 95 /// for "void SymbolFile::InitializeObject()" which will get called 96 /// on the SymbolFile object with the best set of abilities. 97 /// 98 /// \return 99 /// A uint32_t mask containing bits from the SymbolFile::Abilities 100 /// enumeration. Any bits that are set represent an ability that 101 /// this symbol plug-in can parse from the object file. 102 uint32_t GetAbilities() { 103 if (!m_calculated_abilities) { 104 m_abilities = CalculateAbilities(); 105 m_calculated_abilities = true; 106 } 107 108 return m_abilities; 109 } 110 111 virtual uint32_t CalculateAbilities() = 0; 112 113 /// Symbols file subclasses should override this to return the Module that 114 /// owns the TypeSystem that this symbol file modifies type information in. 115 virtual std::recursive_mutex &GetModuleMutex() const; 116 117 /// Initialize the SymbolFile object. 118 /// 119 /// The SymbolFile object with the best set of abilities (detected 120 /// in "uint32_t SymbolFile::GetAbilities()) will have this function 121 /// called if it is chosen to parse an object file. More complete 122 /// initialization can happen in this function which will get called 123 /// prior to any other functions in the SymbolFile protocol. 124 virtual void InitializeObject() {} 125 126 // Compile Unit function calls 127 // Approach 1 - iterator 128 uint32_t GetNumCompileUnits(); 129 lldb::CompUnitSP GetCompileUnitAtIndex(uint32_t idx); 130 131 Symtab *GetSymtab(); 132 133 virtual lldb::LanguageType ParseLanguage(CompileUnit &comp_unit) = 0; 134 /// Return the Xcode SDK comp_unit was compiled against. 135 virtual XcodeSDK ParseXcodeSDK(CompileUnit &comp_unit) { return {}; } 136 virtual size_t ParseFunctions(CompileUnit &comp_unit) = 0; 137 virtual bool ParseLineTable(CompileUnit &comp_unit) = 0; 138 virtual bool ParseDebugMacros(CompileUnit &comp_unit) = 0; 139 140 /// Apply a lambda to each external lldb::Module referenced by this 141 /// \p comp_unit. Recursively also descends into the referenced external 142 /// modules of any encountered compilation unit. 143 /// 144 /// This function can be used to traverse Clang -gmodules debug 145 /// information, which is stored in DWARF files separate from the 146 /// object files. 147 /// 148 /// \param comp_unit 149 /// When this SymbolFile consists of multiple auxilliary 150 /// SymbolFiles, for example, a Darwin debug map that references 151 /// multiple .o files, comp_unit helps choose the auxilliary 152 /// file. In most other cases comp_unit's symbol file is 153 /// identical with *this. 154 /// 155 /// \param[in] lambda 156 /// The lambda that should be applied to every function. The lambda can 157 /// return true if the iteration should be aborted earlier. 158 /// 159 /// \param visited_symbol_files 160 /// A set of SymbolFiles that were already visited to avoid 161 /// visiting one file more than once. 162 /// 163 /// \return 164 /// If the lambda early-exited, this function returns true to 165 /// propagate the early exit. 166 virtual bool ForEachExternalModule( 167 lldb_private::CompileUnit &comp_unit, 168 llvm::DenseSet<lldb_private::SymbolFile *> &visited_symbol_files, 169 llvm::function_ref<bool(Module &)> lambda) { 170 return false; 171 } 172 virtual bool ParseSupportFiles(CompileUnit &comp_unit, 173 FileSpecList &support_files) = 0; 174 virtual size_t ParseTypes(CompileUnit &comp_unit) = 0; 175 virtual bool ParseIsOptimized(CompileUnit &comp_unit) { return false; } 176 177 virtual bool 178 ParseImportedModules(const SymbolContext &sc, 179 std::vector<SourceModule> &imported_modules) = 0; 180 virtual size_t ParseBlocksRecursive(Function &func) = 0; 181 virtual size_t ParseVariablesForContext(const SymbolContext &sc) = 0; 182 virtual Type *ResolveTypeUID(lldb::user_id_t type_uid) = 0; 183 184 185 /// The characteristics of an array type. 186 struct ArrayInfo { 187 int64_t first_index = 0; 188 llvm::SmallVector<uint64_t, 1> element_orders; 189 uint32_t byte_stride = 0; 190 uint32_t bit_stride = 0; 191 }; 192 /// If \c type_uid points to an array type, return its characteristics. 193 /// To support variable-length array types, this function takes an 194 /// optional \p ExecutionContext. If \c exe_ctx is non-null, the 195 /// dynamic characteristics for that context are returned. 196 virtual llvm::Optional<ArrayInfo> 197 GetDynamicArrayInfoForUID(lldb::user_id_t type_uid, 198 const lldb_private::ExecutionContext *exe_ctx) = 0; 199 200 virtual bool CompleteType(CompilerType &compiler_type) = 0; 201 virtual void ParseDeclsForContext(CompilerDeclContext decl_ctx) {} 202 virtual CompilerDecl GetDeclForUID(lldb::user_id_t uid) { 203 return CompilerDecl(); 204 } 205 virtual CompilerDeclContext GetDeclContextForUID(lldb::user_id_t uid) { 206 return CompilerDeclContext(); 207 } 208 virtual CompilerDeclContext GetDeclContextContainingUID(lldb::user_id_t uid) { 209 return CompilerDeclContext(); 210 } 211 virtual uint32_t ResolveSymbolContext(const Address &so_addr, 212 lldb::SymbolContextItem resolve_scope, 213 SymbolContext &sc) = 0; 214 virtual uint32_t 215 ResolveSymbolContext(const SourceLocationSpec &src_location_spec, 216 lldb::SymbolContextItem resolve_scope, 217 SymbolContextList &sc_list); 218 219 virtual void DumpClangAST(Stream &s) {} 220 virtual void FindGlobalVariables(ConstString name, 221 const CompilerDeclContext &parent_decl_ctx, 222 uint32_t max_matches, 223 VariableList &variables); 224 virtual void FindGlobalVariables(const RegularExpression ®ex, 225 uint32_t max_matches, 226 VariableList &variables); 227 virtual void FindFunctions(ConstString name, 228 const CompilerDeclContext &parent_decl_ctx, 229 lldb::FunctionNameType name_type_mask, 230 bool include_inlines, SymbolContextList &sc_list); 231 virtual void FindFunctions(const RegularExpression ®ex, 232 bool include_inlines, SymbolContextList &sc_list); 233 virtual void 234 FindTypes(ConstString name, const CompilerDeclContext &parent_decl_ctx, 235 uint32_t max_matches, 236 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files, 237 TypeMap &types); 238 239 /// Find types specified by a CompilerContextPattern. 240 /// \param languages 241 /// Only return results in these languages. 242 /// \param searched_symbol_files 243 /// Prevents one file from being visited multiple times. 244 virtual void 245 FindTypes(llvm::ArrayRef<CompilerContext> pattern, LanguageSet languages, 246 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files, 247 TypeMap &types); 248 249 virtual void 250 GetMangledNamesForFunction(const std::string &scope_qualified_name, 251 std::vector<ConstString> &mangled_names); 252 253 virtual void GetTypes(lldb_private::SymbolContextScope *sc_scope, 254 lldb::TypeClass type_mask, 255 lldb_private::TypeList &type_list) = 0; 256 257 virtual void PreloadSymbols(); 258 259 virtual llvm::Expected<lldb_private::TypeSystem &> 260 GetTypeSystemForLanguage(lldb::LanguageType language); 261 262 virtual CompilerDeclContext 263 FindNamespace(ConstString name, const CompilerDeclContext &parent_decl_ctx) { 264 return CompilerDeclContext(); 265 } 266 267 ObjectFile *GetObjectFile() { return m_objfile_sp.get(); } 268 const ObjectFile *GetObjectFile() const { return m_objfile_sp.get(); } 269 ObjectFile *GetMainObjectFile(); 270 271 virtual std::vector<std::unique_ptr<CallEdge>> 272 ParseCallEdgesInFunction(UserID func_id) { 273 return {}; 274 } 275 276 virtual void AddSymbols(Symtab &symtab) {} 277 278 /// Notify the SymbolFile that the file addresses in the Sections 279 /// for this module have been changed. 280 virtual void SectionFileAddressesChanged(); 281 282 struct RegisterInfoResolver { 283 virtual ~RegisterInfoResolver(); // anchor 284 285 virtual const RegisterInfo *ResolveName(llvm::StringRef name) const = 0; 286 virtual const RegisterInfo *ResolveNumber(lldb::RegisterKind kind, 287 uint32_t number) const = 0; 288 }; 289 virtual lldb::UnwindPlanSP 290 GetUnwindPlan(const Address &address, const RegisterInfoResolver &resolver) { 291 return nullptr; 292 } 293 294 /// Return the number of stack bytes taken up by the parameters to this 295 /// function. 296 virtual llvm::Expected<lldb::addr_t> GetParameterStackSize(Symbol &symbol) { 297 return llvm::createStringError(make_error_code(llvm::errc::not_supported), 298 "Operation not supported."); 299 } 300 301 virtual void Dump(Stream &s); 302 303 /// Metrics gathering functions 304 305 /// Return the size in bytes of all debug information in the symbol file. 306 /// 307 /// If the debug information is contained in sections of an ObjectFile, then 308 /// this call should add the size of all sections that contain debug 309 /// information. Symbols the symbol tables are not considered debug 310 /// information for this call to make it easy and quick for this number to be 311 /// calculated. If the symbol file is all debug information, the size of the 312 /// entire file should be returned. The default implementation of this 313 /// function will iterate over all sections in a module and add up their 314 /// debug info only section byte sizes. 315 virtual uint64_t GetDebugInfoSize(); 316 317 /// Return the time taken to parse the debug information. 318 /// 319 /// \returns 0.0 if no information has been parsed or if there is 320 /// no computational cost to parsing the debug information. 321 virtual StatsDuration GetDebugInfoParseTime() { 322 return StatsDuration(0.0); 323 } 324 325 /// Return the time it took to index the debug information in the object 326 /// file. 327 /// 328 /// \returns 0.0 if the file doesn't need to be indexed or if it 329 /// hasn't been indexed yet, or a valid duration if it has. 330 virtual StatsDuration GetDebugInfoIndexTime() { 331 return StatsDuration(0.0); 332 } 333 334 335 protected: 336 void AssertModuleLock(); 337 virtual uint32_t CalculateNumCompileUnits() = 0; 338 virtual lldb::CompUnitSP ParseCompileUnitAtIndex(uint32_t idx) = 0; 339 virtual TypeList &GetTypeList() { return m_type_list; } 340 341 void SetCompileUnitAtIndex(uint32_t idx, const lldb::CompUnitSP &cu_sp); 342 343 lldb::ObjectFileSP m_objfile_sp; // Keep a reference to the object file in 344 // case it isn't the same as the module 345 // object file (debug symbols in a separate 346 // file) 347 llvm::Optional<std::vector<lldb::CompUnitSP>> m_compile_units; 348 TypeList m_type_list; 349 Symtab *m_symtab = nullptr; 350 uint32_t m_abilities; 351 bool m_calculated_abilities; 352 353 private: 354 SymbolFile(const SymbolFile &) = delete; 355 const SymbolFile &operator=(const SymbolFile &) = delete; 356 }; 357 358 } // namespace lldb_private 359 360 #endif // LLDB_SYMBOL_SYMBOLFILE_H 361