LLDB  mainline
CompileUnit.h
Go to the documentation of this file.
1 //===-- CompileUnit.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_CompUnit_h_
10 #define liblldb_CompUnit_h_
11 
12 #include "lldb/Core/FileSpecList.h"
13 #include "lldb/Core/ModuleChild.h"
15 #include "lldb/Symbol/Function.h"
17 #include "lldb/Utility/Stream.h"
18 #include "lldb/Utility/UserID.h"
19 #include "lldb/lldb-enumerations.h"
20 
21 #include "llvm/ADT/DenseMap.h"
22 
23 namespace lldb_private {
24 /// \class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
25 /// A class that describes a compilation unit.
26 ///
27 /// A representation of a compilation unit, or compiled source file.
28 /// The UserID of the compile unit is specified by the SymbolFile plug-in and
29 /// can have any value as long as the value is unique within the Module that
30 /// owns this compile units.
31 ///
32 /// Each compile unit has a list of functions, global and static variables,
33 /// support file list (include files and inlined source files), and a line
34 /// table.
35 class CompileUnit : public std::enable_shared_from_this<CompileUnit>,
36  public ModuleChild,
37  public FileSpec,
38  public UserID,
39  public SymbolContextScope {
40 public:
41  /// Construct with a module, path, UID and language.
42  ///
43  /// Initialize the compile unit given the owning \a module, a path to
44  /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
45  /// source language type.
46  ///
47  /// \param[in] module
48  /// The parent module that owns this compile unit. This value
49  /// must be a valid pointer value.
50  ///
51  /// \param[in] user_data
52  /// User data where the SymbolFile parser can store data.
53  ///
54  /// \param[in] pathname
55  /// The path to the source file for this compile unit.
56  ///
57  /// \param[in] uid
58  /// The user ID of the compile unit. This value is supplied by
59  /// the SymbolFile plug-in and should be a value that allows
60  /// the SymbolFile plug-in to easily locate and parse additional
61  /// information for the compile unit.
62  ///
63  /// \param[in] language
64  /// A language enumeration type that describes the main language
65  /// of this compile unit.
66  ///
67  /// \param[in] is_optimized
68  /// A value that can initialized with eLazyBoolYes, eLazyBoolNo
69  /// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
70  /// an extra call into SymbolVendor will be made to calculate if
71  /// the compile unit is optimized will be made when
72  /// CompileUnit::GetIsOptimized() is called.
73  ///
74  /// \see lldb::LanguageType
75  CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
76  const char *pathname, lldb::user_id_t uid,
77  lldb::LanguageType language, lldb_private::LazyBool is_optimized);
78 
79  /// Construct with a module, file spec, UID and language.
80  ///
81  /// Initialize the compile unit given the owning \a module, a path to
82  /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
83  /// source language type.
84  ///
85  /// \param[in] module
86  /// The parent module that owns this compile unit. This value
87  /// must be a valid pointer value.
88  ///
89  /// \param[in] user_data
90  /// User data where the SymbolFile parser can store data.
91  ///
92  /// \param[in] file_spec
93  /// The file specification for the source file of this compile
94  /// unit.
95  ///
96  /// \param[in] uid
97  /// The user ID of the compile unit. This value is supplied by
98  /// the SymbolFile plug-in and should be a value that allows
99  /// the plug-in to easily locate and parse
100  /// additional information for the compile unit.
101  ///
102  /// \param[in] language
103  /// A language enumeration type that describes the main language
104  /// of this compile unit.
105  ///
106  /// \param[in] is_optimized
107  /// A value that can initialized with eLazyBoolYes, eLazyBoolNo
108  /// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
109  /// an extra call into SymbolVendor will be made to calculate if
110  /// the compile unit is optimized will be made when
111  /// CompileUnit::GetIsOptimized() is called.
112  ///
113  /// \see lldb::LanguageType
114  CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
115  const FileSpec &file_spec, lldb::user_id_t uid,
116  lldb::LanguageType language, lldb_private::LazyBool is_optimized);
117 
118  /// Destructor
119  ~CompileUnit() override;
120 
121  /// Add a function to this compile unit.
122  ///
123  /// Typically called by the SymbolFile plug-ins as they partially parse the
124  /// debug information.
125  ///
126  /// \param[in] function_sp
127  /// A shared pointer to the Function object.
128  void AddFunction(lldb::FunctionSP &function_sp);
129 
130  /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
131  ///
132  /// \see SymbolContextScope
133  void CalculateSymbolContext(SymbolContext *sc) override;
134 
135  lldb::ModuleSP CalculateSymbolContextModule() override;
136 
138 
139  /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
140  ///
141  /// \see SymbolContextScope
142  void DumpSymbolContext(Stream *s) override;
143 
145 
147  m_flags.Set(flagsParsedLanguage);
148  m_language = language;
149  }
150 
151  void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
152 
153  /// Apply a lambda to each function in this compile unit.
154  ///
155  /// This provides raw access to the function shared pointer list and will not
156  /// cause the SymbolFile plug-in to parse any unparsed functions.
157  ///
158  /// \note Prefer using FindFunctionByUID over this if possible.
159  ///
160  /// \param[in] lambda
161  /// The lambda that should be applied to every function. The lambda can
162  /// return true if the iteration should be aborted earlier.
163  void ForeachFunction(
164  llvm::function_ref<bool(const lldb::FunctionSP &)> lambda) const;
165 
166  /// Dump the compile unit contents to the stream \a s.
167  ///
168  /// \param[in] s
169  /// The stream to which to dump the object description.
170  ///
171  /// \param[in] show_context
172  /// If \b true, variables will dump their symbol context
173  /// information.
174  void Dump(Stream *s, bool show_context) const;
175 
176  /// Find the line entry by line and optional inlined file spec.
177  ///
178  /// Finds the first line entry that has an index greater than \a start_idx
179  /// that matches \a line. If \a file_spec_ptr is NULL, then the search
180  /// matches line entries whose file matches the file for the compile unit.
181  /// If \a file_spec_ptr is not NULL, line entries must match the specified
182  /// file spec (for inlined line table entries).
183  ///
184  /// Multiple calls to this function can find all entries that match a given
185  /// file and line by starting with \a start_idx equal to zero, and calling
186  /// this function back with the return value + 1.
187  ///
188  /// \param[in] start_idx
189  /// The zero based index at which to start looking for matches.
190  ///
191  /// \param[in] line
192  /// The line number to search for.
193  ///
194  /// \param[in] file_spec_ptr
195  /// If non-NULL search for entries that match this file spec,
196  /// else if NULL, search for line entries that match the compile
197  /// unit file.
198  ///
199  /// \param[in] exact
200  /// If \btrue match only if there is a line table entry for this line
201  /// number.
202  /// If \bfalse, find the line table entry equal to or after this line
203  /// number.
204  ///
205  /// \param[out] line_entry
206  /// If non-NULL, a copy of the line entry that was found.
207  ///
208  /// \return
209  /// The zero based index of a matching line entry, or UINT32_MAX
210  /// if no matching line entry is found.
211  uint32_t FindLineEntry(uint32_t start_idx, uint32_t line,
212  const FileSpec *file_spec_ptr, bool exact,
213  LineEntry *line_entry);
214 
215  /// Get the line table for the compile unit.
216  ///
217  /// Called by clients and the SymbolFile plug-in. The SymbolFile plug-ins
218  /// use this function to determine if the line table has be parsed yet.
219  /// Clients use this function to get the line table from a compile unit.
220  ///
221  /// \return
222  /// The line table object pointer, or NULL if this line table
223  /// hasn't been parsed yet.
225 
227 
228  /// Get the compile unit's support file list.
229  ///
230  /// The support file list is used by the line table, and any objects that
231  /// have valid Declaration objects.
232  ///
233  /// \return
234  /// A support file list object.
235  FileSpecList &GetSupportFiles();
236 
237  /// Get the compile unit's imported module list.
238  ///
239  /// This reports all the imports that the compile unit made, including the
240  /// current module.
241  ///
242  /// \return
243  /// A list of imported modules.
244  const std::vector<SourceModule> &GetImportedModules();
245 
246  /// Get the SymbolFile plug-in user data.
247  ///
248  /// SymbolFile plug-ins can store user data to internal state or objects to
249  /// quickly allow them to parse more information for a given object.
250  ///
251  /// \return
252  /// The user data stored with the CompileUnit when it was
253  /// constructed.
254  void *GetUserData() const;
255 
256  /// Get the variable list for a compile unit.
257  ///
258  /// Called by clients to get the variable list for a compile unit. The
259  /// variable list will contain all global and static variables that were
260  /// defined at the compile unit level.
261  ///
262  /// \param[in] can_create
263  /// If \b true, the variable list will be parsed on demand. If
264  /// \b false, the current variable list will be returned even
265  /// if it contains a NULL VariableList object (typically
266  /// called by dumping routines that want to display only what
267  /// has currently been parsed).
268  ///
269  /// \return
270  /// A shared pointer to a variable list, that can contain NULL
271  /// VariableList pointer if there are no global or static
272  /// variables.
273  lldb::VariableListSP GetVariableList(bool can_create);
274 
275  /// Finds a function by user ID.
276  ///
277  /// Typically used by SymbolFile plug-ins when partially parsing the debug
278  /// information to see if the function has been parsed yet.
279  ///
280  /// \param[in] uid
281  /// The user ID of the function to find. This value is supplied
282  /// by the SymbolFile plug-in and should be a value that
283  /// allows the plug-in to easily locate and parse additional
284  /// information in the function.
285  ///
286  /// \return
287  /// A shared pointer to the function object that might contain
288  /// a NULL Function pointer.
289  lldb::FunctionSP FindFunctionByUID(lldb::user_id_t uid);
290 
291  /// Set the line table for the compile unit.
292  ///
293  /// Called by the SymbolFile plug-in when if first parses the line table and
294  /// hands ownership of the line table to this object. The compile unit owns
295  /// the line table object and will delete the object when it is deleted.
296  ///
297  /// \param[in] line_table
298  /// A line table object pointer that this object now owns.
299  void SetLineTable(LineTable *line_table);
300 
301  void SetDebugMacros(const DebugMacrosSP &debug_macros);
302 
303  /// Set accessor for the variable list.
304  ///
305  /// Called by the SymbolFile plug-ins after they have parsed the variable
306  /// lists and are ready to hand ownership of the list over to this object.
307  ///
308  /// \param[in] variable_list_sp
309  /// A shared pointer to a VariableList.
310  void SetVariableList(lldb::VariableListSP &variable_list_sp);
311 
312  /// Resolve symbol contexts by file and line.
313  ///
314  /// Given a file in \a file_spec, and a line number, find all instances and
315  /// append them to the supplied symbol context list \a sc_list.
316  ///
317  /// \param[in] file_spec
318  /// A file specification. If \a file_spec contains no directory
319  /// information, only the basename will be used when matching
320  /// contexts. If the directory in \a file_spec is valid, a
321  /// complete file specification match will be performed.
322  ///
323  /// \param[in] line
324  /// The line number to match against the compile unit's line
325  /// tables.
326  ///
327  /// \param[in] check_inlines
328  /// If \b true this function will also match any inline
329  /// file and line matches. If \b false, the compile unit's
330  /// file specification must match \a file_spec for any matches
331  /// to be returned.
332  ///
333  /// \param[in] exact
334  /// If true, only resolve the context if \a line exists in the line table.
335  /// If false, resolve the context to the closest line greater than \a line
336  /// in the line table.
337  ///
338  /// \param[in] resolve_scope
339  /// For each matching line entry, this bitfield indicates what
340  /// values within each SymbolContext that gets added to \a
341  /// sc_list will be resolved. See the SymbolContext::Scope
342  /// enumeration for a list of all available bits that can be
343  /// resolved. Only SymbolContext entries that can be resolved
344  /// using a LineEntry base address will be able to be resolved.
345  ///
346  /// \param[out] sc_list
347  /// A SymbolContext list class that will get any matching
348  /// entries appended to.
349  ///
350  /// \return
351  /// The number of new matches that were added to \a sc_list.
352  ///
353  /// \see enum SymbolContext::Scope
354  uint32_t ResolveSymbolContext(const FileSpec &file_spec, uint32_t line,
355  bool check_inlines, bool exact,
356  lldb::SymbolContextItem resolve_scope,
357  SymbolContextList &sc_list);
358 
359  /// Get whether compiler optimizations were enabled for this compile unit
360  ///
361  /// "optimized" means that the debug experience may be difficult for the
362  /// user to understand. Variables may not be available when the developer
363  /// would expect them, stepping through the source lines in the function may
364  /// appear strange, etc.
365  ///
366  /// \return
367  /// Returns 'true' if this compile unit was compiled with
368  /// optimization. 'false' indicates that either the optimization
369  /// is unknown, or this compile unit was built without optimization.
370  bool GetIsOptimized();
371 
372  /// Returns the number of functions in this compile unit
373  size_t GetNumFunctions() const { return m_functions_by_uid.size(); }
374 
375 protected:
376  /// User data for the SymbolFile parser to store information into.
377  void *m_user_data;
378  /// The programming language enumeration value.
380  /// Compile unit flags that help with partial parsing.
382  /// Maps UIDs to functions.
383  llvm::DenseMap<lldb::user_id_t, lldb::FunctionSP> m_functions_by_uid;
384  /// All modules, including the current module, imported by this
385  /// compile unit.
386  std::vector<SourceModule> m_imported_modules;
387  /// Files associated with this compile unit's line table and
388  /// declarations.
389  FileSpecList m_support_files;
390  /// Line table that will get parsed on demand.
391  std::unique_ptr<LineTable> m_line_table_up;
392  /// Debug macros that will get parsed on demand.
394  /// Global and static variable list that will get parsed on demand.
395  lldb::VariableListSP m_variables;
396  /// eLazyBoolYes if this compile unit was compiled with
397  /// optimization.
399 
400 private:
401  enum {
402  flagsParsedAllFunctions =
403  (1u << 0), ///< Have we already parsed all our functions
404  flagsParsedVariables =
405  (1u << 1), ///< Have we already parsed globals and statics?
406  flagsParsedSupportFiles = (1u << 2), ///< Have we already parsed the support
407  ///files for this compile unit?
408  flagsParsedLineTable =
409  (1u << 3), ///< Have we parsed the line table already?
410  flagsParsedLanguage = (1u << 4), ///< Have we parsed the language already?
411  flagsParsedImportedModules =
412  (1u << 5), ///< Have we parsed the imported modules already?
413  flagsParsedDebugMacros =
414  (1u << 6) ///< Have we parsed the debug macros already?
415  };
416 
417  DISALLOW_COPY_AND_ASSIGN(CompileUnit);
418 };
419 
420 } // namespace lldb_private
421 
422 #endif // liblldb_CompUnit_h_
lldb::LanguageType m_language
The programming language enumeration value.
Definition: CompileUnit.h:379
uint32_t FindLineEntry(uint32_t start_idx, uint32_t line, const FileSpec *file_spec_ptr, bool exact, LineEntry *line_entry)
Find the line entry by line and optional inlined file spec.
void CalculateSymbolContext(SymbolContext *sc) override
Reconstruct the object&#39;s symbol context into sc.
Definition: CompileUnit.cpp:47
A line table entry class.
Definition: LineEntry.h:20
CompileUnit(const lldb::ModuleSP &module_sp, void *user_data, const char *pathname, lldb::user_id_t uid, lldb::LanguageType language, lldb_private::LazyBool is_optimized)
Construct with a module, path, UID and language.
Definition: CompileUnit.cpp:19
void GetDescription(Stream *s, lldb::DescriptionLevel level) const
Definition: CompileUnit.cpp:61
std::unique_ptr< LineTable > m_line_table_up
Line table that will get parsed on demand.
Definition: CompileUnit.h:391
void DumpSymbolContext(Stream *s) override
Dump the object&#39;s symbol context to the stream s.
Definition: CompileUnit.cpp:56
DebugMacros * GetDebugMacros()
Defines a list of symbol context objects.
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
std::vector< SourceModule > m_imported_modules
All modules, including the current module, imported by this compile unit.
Definition: CompileUnit.h:386
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
lldb::VariableListSP m_variables
Global and static variable list that will get parsed on demand.
Definition: CompileUnit.h:395
A mix in class that contains a generic user ID.
Definition: UserID.h:33
A file utility class.
Definition: FileSpec.h:55
lldb::LanguageType GetLanguage()
~CompileUnit() override
Destructor.
Definition: CompileUnit.cpp:45
lldb::ModuleSP CalculateSymbolContextModule() override
Definition: CompileUnit.cpp:52
lldb::FunctionSP FindFunctionByUID(lldb::user_id_t uid)
Finds a function by user ID.
const std::vector< SourceModule > & GetImportedModules()
Get the compile unit&#39;s imported module list.
void SetDebugMacros(const DebugMacrosSP &debug_macros)
A class that describes a compilation unit.
Definition: CompileUnit.h:35
void SetLineTable(LineTable *line_table)
Set the line table for the compile unit.
Flags m_flags
Compile unit flags that help with partial parsing.
Definition: CompileUnit.h:381
DebugMacrosSP m_debug_macros_sp
Debug macros that will get parsed on demand.
Definition: CompileUnit.h:393
uint64_t user_id_t
Definition: lldb-types.h:84
LanguageType
Programming language type.
void * m_user_data
User data for the SymbolFile parser to store information into.
Definition: CompileUnit.h:377
A line table class.
Definition: LineTable.h:37
bool GetIsOptimized()
Get whether compiler optimizations were enabled for this compile unit.
FileSpecList & GetSupportFiles()
Get the compile unit&#39;s support file list.
std::shared_ptr< DebugMacros > DebugMacrosSP
Definition: DebugMacros.h:21
lldb::VariableListSP GetVariableList(bool can_create)
Get the variable list for a compile unit.
lldb_private::LazyBool m_is_optimized
eLazyBoolYes if this compile unit was compiled with optimization.
Definition: CompileUnit.h:398
ValueType Set(ValueType mask)
Set one or more flags by logical OR&#39;ing mask with the current flags.
Definition: Flags.h:84
LineTable * GetLineTable()
Get the line table for the compile unit.
llvm::DenseMap< lldb::user_id_t, lldb::FunctionSP > m_functions_by_uid
Maps UIDs to functions.
Definition: CompileUnit.h:383
void Dump(Stream *s, bool show_context) const
Dump the compile unit contents to the stream s.
Definition: CompileUnit.cpp:88
void * GetUserData() const
Get the SymbolFile plug-in user data.
A class to manage flags.
Definition: Flags.h:22
void SetLanguage(lldb::LanguageType language)
Definition: CompileUnit.h:146
size_t GetNumFunctions() const
Returns the number of functions in this compile unit.
Definition: CompileUnit.h:373
void SetVariableList(lldb::VariableListSP &variable_list_sp)
Set accessor for the variable list.
uint32_t ResolveSymbolContext(const FileSpec &file_spec, uint32_t line, bool check_inlines, bool exact, lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list)
Resolve symbol contexts by file and line.
A mix in class that contains a pointer back to the module that owns the object which inherits from it...
Definition: ModuleChild.h:19
void ForeachFunction(llvm::function_ref< bool(const lldb::FunctionSP &)> lambda) const
Apply a lambda to each function in this compile unit.
Definition: CompileUnit.cpp:68
void AddFunction(lldb::FunctionSP &function_sp)
Add a function to this compile unit.
CompileUnit * CalculateSymbolContextCompileUnit() override
Definition: CompileUnit.cpp:54
FileSpecList m_support_files
Files associated with this compile unit&#39;s line table and declarations.
Definition: CompileUnit.h:389
"lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is part of a symbol context and c...