Warning: This file is not a C or C++ file. It does not have highlighting.

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

Warning: This file is not a C or C++ file. It does not have highlighting.

source code of lldb/include/lldb/Symbol/SymbolFile.h