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