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