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