1 //===-- CompileUnit.h -------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_CompUnit_h_
11 #define liblldb_CompUnit_h_
13 #include "lldb/Core/FileSpecList.h"
14 #include "lldb/Core/ModuleChild.h"
15 #include "lldb/Symbol/DebugMacros.h"
16 #include "lldb/Symbol/Function.h"
17 #include "lldb/Utility/Stream.h"
18 #include "lldb/Utility/UserID.h"
19 #include "lldb/lldb-enumerations.h"
21 namespace lldb_private {
22 //----------------------------------------------------------------------
23 /// @class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
24 /// @brief A class that describes a compilation unit.
26 /// A representation of a compilation unit, or compiled source file.
27 /// The UserID of the compile unit is specified by the SymbolFile
28 /// plug-in and can have any value as long as the value is unique
29 /// within the Module that owns this compile units.
31 /// Each compile unit has a list of functions, global and static
32 /// variables, support file list (include files and inlined source
33 /// files), and a line table.
34 //----------------------------------------------------------------------
35 class CompileUnit : public std::enable_shared_from_this<CompileUnit>,
39 public SymbolContextScope {
41 //------------------------------------------------------------------
42 /// Construct with a module, path, UID and language.
44 /// Initialize the compile unit given the owning \a module, a path
45 /// to convert into a FileSpec, the SymbolFile plug-in supplied
46 /// \a uid, and the source language type.
49 /// The parent module that owns this compile unit. This value
50 /// must be a valid pointer value.
52 /// @param[in] user_data
53 /// User data where the SymbolFile parser can store data.
55 /// @param[in] pathname
56 /// The path to the source file for this compile unit.
59 /// The user ID of the compile unit. This value is supplied by
60 /// the SymbolFile plug-in and should be a value that allows
61 /// the SymbolFile plug-in to easily locate and parse additional
62 /// information for the compile unit.
64 /// @param[in] language
65 /// A language enumeration type that describes the main language
66 /// of this compile unit.
68 /// @param[in] is_optimized
69 /// A value that can initialized with eLazyBoolYes, eLazyBoolNo
70 /// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
71 /// an extra call into SymbolVendor will be made to calculate if
72 /// the compile unit is optimized will be made when
73 /// CompileUnit::GetIsOptimized() is called.
75 /// @see lldb::LanguageType
76 //------------------------------------------------------------------
77 CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
78 const char *pathname, lldb::user_id_t uid,
79 lldb::LanguageType language, lldb_private::LazyBool is_optimized);
81 //------------------------------------------------------------------
82 /// Construct with a module, file spec, UID and language.
84 /// Initialize the compile unit given the owning \a module, a path
85 /// to convert into a FileSpec, the SymbolFile plug-in supplied
86 /// \a uid, and the source language type.
89 /// The parent module that owns this compile unit. This value
90 /// must be a valid pointer value.
92 /// @param[in] user_data
93 /// User data where the SymbolFile parser can store data.
95 /// @param[in] file_spec
96 /// The file specification for the source file of this compile
100 /// The user ID of the compile unit. This value is supplied by
101 /// the SymbolFile plug-in and should be a value that allows
102 /// the plug-in to easily locate and parse
103 /// additional information for the compile unit.
105 /// @param[in] language
106 /// A language enumeration type that describes the main language
107 /// of this compile unit.
109 /// @param[in] is_optimized
110 /// A value that can initialized with eLazyBoolYes, eLazyBoolNo
111 /// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
112 /// an extra call into SymbolVendor will be made to calculate if
113 /// the compile unit is optimized will be made when
114 /// CompileUnit::GetIsOptimized() is called.
116 /// @see lldb::LanguageType
117 //------------------------------------------------------------------
118 CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
119 const FileSpec &file_spec, lldb::user_id_t uid,
120 lldb::LanguageType language, lldb_private::LazyBool is_optimized);
122 //------------------------------------------------------------------
124 //------------------------------------------------------------------
125 ~CompileUnit() override;
127 //------------------------------------------------------------------
128 /// Add a function to this compile unit.
130 /// Typically called by the SymbolFile plug-ins as they partially
131 /// parse the debug information.
133 /// @param[in] function_sp
134 /// A shared pointer to the Function object.
135 //------------------------------------------------------------------
136 void AddFunction(lldb::FunctionSP &function_sp);
138 //------------------------------------------------------------------
139 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
141 /// @see SymbolContextScope
142 //------------------------------------------------------------------
143 void CalculateSymbolContext(SymbolContext *sc) override;
145 lldb::ModuleSP CalculateSymbolContextModule() override;
147 CompileUnit *CalculateSymbolContextCompileUnit() override;
149 //------------------------------------------------------------------
150 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
152 /// @see SymbolContextScope
153 //------------------------------------------------------------------
154 void DumpSymbolContext(Stream *s) override;
156 lldb::LanguageType GetLanguage();
158 void SetLanguage(lldb::LanguageType language) {
159 m_flags.Set(flagsParsedLanguage);
160 m_language = language;
163 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
165 //------------------------------------------------------------------
166 /// Get a shared pointer to a function in this compile unit by
169 /// Typically called when iterating though all functions in a
170 /// compile unit after all functions have been parsed. This provides
171 /// raw access to the function shared pointer list and will not
172 /// cause the SymbolFile plug-in to parse any unparsed functions.
175 /// An index into the function list.
178 /// A shared pointer to a function that might contain a NULL
179 /// Function class pointer.
180 //------------------------------------------------------------------
181 lldb::FunctionSP GetFunctionAtIndex(size_t idx);
183 //------------------------------------------------------------------
184 /// Dump the compile unit contents to the stream \a s.
187 /// The stream to which to dump the object description.
189 /// @param[in] show_context
190 /// If \b true, variables will dump their symbol context
192 //------------------------------------------------------------------
193 void Dump(Stream *s, bool show_context) const;
195 //------------------------------------------------------------------
196 /// Find the line entry by line and optional inlined file spec.
198 /// Finds the first line entry that has an index greater than
199 /// \a start_idx that matches \a line. If \a file_spec_ptr
200 /// is NULL, then the search matches line entries whose file matches
201 /// the file for the compile unit. If \a file_spec_ptr is
202 /// not NULL, line entries must match the specified file spec (for
203 /// inlined line table entries).
205 /// Multiple calls to this function can find all entries that match
206 /// a given file and line by starting with \a start_idx equal to zero,
207 /// and calling this function back with the return value + 1.
209 /// @param[in] start_idx
210 /// The zero based index at which to start looking for matches.
213 /// The line number to search for.
215 /// @param[in] file_spec_ptr
216 /// If non-NULL search for entries that match this file spec,
217 /// else if NULL, search for line entries that match the compile
221 /// If \btrue match only if there is a line table entry for this line
223 /// If \bfalse, find the line table entry equal to or after this line
226 /// @param[out] line_entry
227 /// If non-NULL, a copy of the line entry that was found.
230 /// The zero based index of a matching line entry, or UINT32_MAX
231 /// if no matching line entry is found.
232 //------------------------------------------------------------------
233 uint32_t FindLineEntry(uint32_t start_idx, uint32_t line,
234 const FileSpec *file_spec_ptr, bool exact,
235 LineEntry *line_entry);
237 //------------------------------------------------------------------
238 /// Get the line table for the compile unit.
240 /// Called by clients and the SymbolFile plug-in. The SymbolFile
241 /// plug-ins use this function to determine if the line table has
242 /// be parsed yet. Clients use this function to get the line table
243 /// from a compile unit.
246 /// The line table object pointer, or NULL if this line table
247 /// hasn't been parsed yet.
248 //------------------------------------------------------------------
249 LineTable *GetLineTable();
251 DebugMacros *GetDebugMacros();
253 //------------------------------------------------------------------
254 /// Get the compile unit's support file list.
256 /// The support file list is used by the line table, and any objects
257 /// that have valid Declaration objects.
260 /// A support file list object.
261 //------------------------------------------------------------------
262 FileSpecList &GetSupportFiles();
264 //------------------------------------------------------------------
265 /// Get the compile unit's imported module list.
267 /// This reports all the imports that the compile unit made,
268 /// including the current module.
271 /// A list of imported module names.
272 //------------------------------------------------------------------
273 const std::vector<ConstString> &GetImportedModules();
275 //------------------------------------------------------------------
276 /// Get the SymbolFile plug-in user data.
278 /// SymbolFile plug-ins can store user data to internal state or
279 /// objects to quickly allow them to parse more information for a
283 /// The user data stored with the CompileUnit when it was
285 //------------------------------------------------------------------
286 void *GetUserData() const;
288 //------------------------------------------------------------------
289 /// Get the variable list for a compile unit.
291 /// Called by clients to get the variable list for a compile unit.
292 /// The variable list will contain all global and static variables
293 /// that were defined at the compile unit level.
295 /// @param[in] can_create
296 /// If \b true, the variable list will be parsed on demand. If
297 /// \b false, the current variable list will be returned even
298 /// if it contains a NULL VariableList object (typically
299 /// called by dumping routines that want to display only what
300 /// has currently been parsed).
303 /// A shared pointer to a variable list, that can contain NULL
304 /// VariableList pointer if there are no global or static
306 //------------------------------------------------------------------
307 lldb::VariableListSP GetVariableList(bool can_create);
309 //------------------------------------------------------------------
310 /// Finds a function by user ID.
312 /// Typically used by SymbolFile plug-ins when partially parsing
313 /// the debug information to see if the function has been parsed
317 /// The user ID of the function to find. This value is supplied
318 /// by the SymbolFile plug-in and should be a value that
319 /// allows the plug-in to easily locate and parse additional
320 /// information in the function.
323 /// A shared pointer to the function object that might contain
324 /// a NULL Function pointer.
325 //------------------------------------------------------------------
326 lldb::FunctionSP FindFunctionByUID(lldb::user_id_t uid);
328 //------------------------------------------------------------------
329 /// Set the line table for the compile unit.
331 /// Called by the SymbolFile plug-in when if first parses the line
332 /// table and hands ownership of the line table to this object. The
333 /// compile unit owns the line table object and will delete the
334 /// object when it is deleted.
336 /// @param[in] line_table
337 /// A line table object pointer that this object now owns.
338 //------------------------------------------------------------------
339 void SetLineTable(LineTable *line_table);
341 void SetDebugMacros(const DebugMacrosSP &debug_macros);
343 //------------------------------------------------------------------
344 /// Set accessor for the variable list.
346 /// Called by the SymbolFile plug-ins after they have parsed the
347 /// variable lists and are ready to hand ownership of the list over
350 /// @param[in] variable_list_sp
351 /// A shared pointer to a VariableList.
352 //------------------------------------------------------------------
353 void SetVariableList(lldb::VariableListSP &variable_list_sp);
355 //------------------------------------------------------------------
356 /// Resolve symbol contexts by file and line.
358 /// Given a file in \a file_spec, and a line number, find all
359 /// instances and append them to the supplied symbol context list
362 /// @param[in] file_spec
363 /// A file specification. If \a file_spec contains no directory
364 /// information, only the basename will be used when matching
365 /// contexts. If the directory in \a file_spec is valid, a
366 /// complete file specification match will be performed.
369 /// The line number to match against the compile unit's line
372 /// @param[in] check_inlines
373 /// If \b true this function will also match any inline
374 /// file and line matches. If \b false, the compile unit's
375 /// file specification must match \a file_spec for any matches
379 /// If true, only resolve the context if \a line exists in the line table.
380 /// If false, resolve the context to the closest line greater than \a line
381 /// in the line table.
383 /// @param[in] resolve_scope
384 /// For each matching line entry, this bitfield indicates what
385 /// values within each SymbolContext that gets added to \a
386 /// sc_list will be resolved. See the SymbolContext::Scope
387 /// enumeration for a list of all available bits that can be
388 /// resolved. Only SymbolContext entries that can be resolved
389 /// using a LineEntry base address will be able to be resolved.
391 /// @param[out] sc_list
392 /// A SymbolContext list class that will get any matching
393 /// entries appended to.
396 /// The number of new matches that were added to \a sc_list.
398 /// @see enum SymbolContext::Scope
399 //------------------------------------------------------------------
400 uint32_t ResolveSymbolContext(const FileSpec &file_spec, uint32_t line,
401 bool check_inlines, bool exact,
402 uint32_t resolve_scope,
403 SymbolContextList &sc_list);
405 //------------------------------------------------------------------
406 /// Get whether compiler optimizations were enabled for this compile unit
408 /// "optimized" means that the debug experience may be difficult
409 /// for the user to understand. Variables may not be available when
410 /// the developer would expect them, stepping through the source lines
411 /// in the function may appear strange, etc.
414 /// Returns 'true' if this compile unit was compiled with
415 /// optimization. 'false' indicates that either the optimization
416 /// is unknown, or this compile unit was built without optimization.
417 //------------------------------------------------------------------
418 bool GetIsOptimized();
421 void *m_user_data; ///< User data for the SymbolFile parser to store
424 m_language; ///< The programming language enumeration value.
425 Flags m_flags; ///< Compile unit flags that help with partial parsing.
426 std::vector<lldb::FunctionSP> m_functions; ///< The sparsely populated list of
427 ///shared pointers to functions
428 ///< that gets populated as functions get partially parsed.
429 std::vector<ConstString> m_imported_modules; ///< All modules, including the
430 ///current module, imported by
433 FileSpecList m_support_files; ///< Files associated with this compile unit's
434 ///line table and declarations.
435 std::unique_ptr<LineTable>
436 m_line_table_ap; ///< Line table that will get parsed on demand.
438 m_debug_macros_sp; ///< Debug macros that will get parsed on demand.
439 lldb::VariableListSP m_variables; ///< Global and static variable list that
440 ///will get parsed on demand.
441 lldb_private::LazyBool m_is_optimized; /// eLazyBoolYes if this compile unit
442 /// was compiled with optimization.
446 flagsParsedAllFunctions =
447 (1u << 0), ///< Have we already parsed all our functions
448 flagsParsedVariables =
449 (1u << 1), ///< Have we already parsed globals and statics?
450 flagsParsedSupportFiles = (1u << 2), ///< Have we already parsed the support
451 ///files for this compile unit?
452 flagsParsedLineTable =
453 (1u << 3), ///< Have we parsed the line table already?
454 flagsParsedLanguage = (1u << 4), ///< Have we parsed the language already?
455 flagsParsedImportedModules =
456 (1u << 5), ///< Have we parsed the imported modules already?
457 flagsParsedDebugMacros =
458 (1u << 6) ///< Have we parsed the debug macros already?
461 DISALLOW_COPY_AND_ASSIGN(CompileUnit);
464 } // namespace lldb_private
466 #endif // liblldb_CompUnit_h_