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 /// 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 plug-in and
28 /// can have any value as long as the value is unique within the Module that
29 /// owns this compile units.
31 /// Each compile unit has a list of functions, global and static variables,
32 /// support file list (include files and inlined source files), and a line
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 to
45 /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
46 /// 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 to
85 /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
86 /// 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 parse the
131 /// 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 index.
168 /// Typically called when iterating though all functions in a compile unit
169 /// after all functions have been parsed. This provides raw access to the
170 /// function shared pointer list and will not cause the SymbolFile plug-in
171 /// to parse any unparsed functions.
174 /// An index into the function list.
177 /// A shared pointer to a function that might contain a NULL
178 /// Function class pointer.
179 //------------------------------------------------------------------
180 lldb::FunctionSP GetFunctionAtIndex(size_t idx);
182 //------------------------------------------------------------------
183 /// Dump the compile unit contents to the stream \a s.
186 /// The stream to which to dump the object description.
188 /// @param[in] show_context
189 /// If \b true, variables will dump their symbol context
191 //------------------------------------------------------------------
192 void Dump(Stream *s, bool show_context) const;
194 //------------------------------------------------------------------
195 /// Find the line entry by line and optional inlined file spec.
197 /// Finds the first line entry that has an index greater than \a start_idx
198 /// that matches \a line. If \a file_spec_ptr is NULL, then the search
199 /// matches line entries whose file matches the file for the compile unit.
200 /// If \a file_spec_ptr is not NULL, line entries must match the specified
201 /// file spec (for inlined line table entries).
203 /// Multiple calls to this function can find all entries that match a given
204 /// file and line by starting with \a start_idx equal to zero, and calling
205 /// this function back with the return value + 1.
207 /// @param[in] start_idx
208 /// The zero based index at which to start looking for matches.
211 /// The line number to search for.
213 /// @param[in] file_spec_ptr
214 /// If non-NULL search for entries that match this file spec,
215 /// else if NULL, search for line entries that match the compile
219 /// If \btrue match only if there is a line table entry for this line
221 /// If \bfalse, find the line table entry equal to or after this line
224 /// @param[out] line_entry
225 /// If non-NULL, a copy of the line entry that was found.
228 /// The zero based index of a matching line entry, or UINT32_MAX
229 /// if no matching line entry is found.
230 //------------------------------------------------------------------
231 uint32_t FindLineEntry(uint32_t start_idx, uint32_t line,
232 const FileSpec *file_spec_ptr, bool exact,
233 LineEntry *line_entry);
235 //------------------------------------------------------------------
236 /// Get the line table for the compile unit.
238 /// Called by clients and the SymbolFile plug-in. The SymbolFile plug-ins
239 /// use this function to determine if the line table has be parsed yet.
240 /// Clients use this function to get the line table from a compile unit.
243 /// The line table object pointer, or NULL if this line table
244 /// hasn't been parsed yet.
245 //------------------------------------------------------------------
246 LineTable *GetLineTable();
248 DebugMacros *GetDebugMacros();
250 //------------------------------------------------------------------
251 /// Get the compile unit's support file list.
253 /// The support file list is used by the line table, and any objects that
254 /// have valid Declaration objects.
257 /// A support file list object.
258 //------------------------------------------------------------------
259 FileSpecList &GetSupportFiles();
261 //------------------------------------------------------------------
262 /// Get the compile unit's imported module list.
264 /// This reports all the imports that the compile unit made, including the
268 /// A list of imported module names.
269 //------------------------------------------------------------------
270 const std::vector<ConstString> &GetImportedModules();
272 //------------------------------------------------------------------
273 /// Get the SymbolFile plug-in user data.
275 /// SymbolFile plug-ins can store user data to internal state or objects to
276 /// quickly allow them to parse more information for a given object.
279 /// The user data stored with the CompileUnit when it was
281 //------------------------------------------------------------------
282 void *GetUserData() const;
284 //------------------------------------------------------------------
285 /// Get the variable list for a compile unit.
287 /// Called by clients to get the variable list for a compile unit. The
288 /// variable list will contain all global and static variables that were
289 /// defined at the compile unit level.
291 /// @param[in] can_create
292 /// If \b true, the variable list will be parsed on demand. If
293 /// \b false, the current variable list will be returned even
294 /// if it contains a NULL VariableList object (typically
295 /// called by dumping routines that want to display only what
296 /// has currently been parsed).
299 /// A shared pointer to a variable list, that can contain NULL
300 /// VariableList pointer if there are no global or static
302 //------------------------------------------------------------------
303 lldb::VariableListSP GetVariableList(bool can_create);
305 //------------------------------------------------------------------
306 /// Finds a function by user ID.
308 /// Typically used by SymbolFile plug-ins when partially parsing the debug
309 /// information to see if the function has been parsed yet.
312 /// The user ID of the function to find. This value is supplied
313 /// by the SymbolFile plug-in and should be a value that
314 /// allows the plug-in to easily locate and parse additional
315 /// information in the function.
318 /// A shared pointer to the function object that might contain
319 /// a NULL Function pointer.
320 //------------------------------------------------------------------
321 lldb::FunctionSP FindFunctionByUID(lldb::user_id_t uid);
323 //------------------------------------------------------------------
324 /// Set the line table for the compile unit.
326 /// Called by the SymbolFile plug-in when if first parses the line table and
327 /// hands ownership of the line table to this object. The compile unit owns
328 /// the line table object and will delete the object when it is deleted.
330 /// @param[in] line_table
331 /// A line table object pointer that this object now owns.
332 //------------------------------------------------------------------
333 void SetLineTable(LineTable *line_table);
335 void SetDebugMacros(const DebugMacrosSP &debug_macros);
337 //------------------------------------------------------------------
338 /// Set accessor for the variable list.
340 /// Called by the SymbolFile plug-ins after they have parsed the variable
341 /// lists and are ready to hand ownership of the list over to this object.
343 /// @param[in] variable_list_sp
344 /// A shared pointer to a VariableList.
345 //------------------------------------------------------------------
346 void SetVariableList(lldb::VariableListSP &variable_list_sp);
348 //------------------------------------------------------------------
349 /// Resolve symbol contexts by file and line.
351 /// Given a file in \a file_spec, and a line number, find all instances and
352 /// append them to the supplied symbol context list \a sc_list.
354 /// @param[in] file_spec
355 /// A file specification. If \a file_spec contains no directory
356 /// information, only the basename will be used when matching
357 /// contexts. If the directory in \a file_spec is valid, a
358 /// complete file specification match will be performed.
361 /// The line number to match against the compile unit's line
364 /// @param[in] check_inlines
365 /// If \b true this function will also match any inline
366 /// file and line matches. If \b false, the compile unit's
367 /// file specification must match \a file_spec for any matches
371 /// If true, only resolve the context if \a line exists in the line table.
372 /// If false, resolve the context to the closest line greater than \a line
373 /// in the line table.
375 /// @param[in] resolve_scope
376 /// For each matching line entry, this bitfield indicates what
377 /// values within each SymbolContext that gets added to \a
378 /// sc_list will be resolved. See the SymbolContext::Scope
379 /// enumeration for a list of all available bits that can be
380 /// resolved. Only SymbolContext entries that can be resolved
381 /// using a LineEntry base address will be able to be resolved.
383 /// @param[out] sc_list
384 /// A SymbolContext list class that will get any matching
385 /// entries appended to.
388 /// The number of new matches that were added to \a sc_list.
390 /// @see enum SymbolContext::Scope
391 //------------------------------------------------------------------
392 uint32_t ResolveSymbolContext(const FileSpec &file_spec, uint32_t line,
393 bool check_inlines, bool exact,
394 uint32_t resolve_scope,
395 SymbolContextList &sc_list);
397 //------------------------------------------------------------------
398 /// Get whether compiler optimizations were enabled for this compile unit
400 /// "optimized" means that the debug experience may be difficult for the
401 /// user to understand. Variables may not be available when the developer
402 /// would expect them, stepping through the source lines in the function may
403 /// appear strange, etc.
406 /// Returns 'true' if this compile unit was compiled with
407 /// optimization. 'false' indicates that either the optimization
408 /// is unknown, or this compile unit was built without optimization.
409 //------------------------------------------------------------------
410 bool GetIsOptimized();
413 void *m_user_data; ///< User data for the SymbolFile parser to store
416 m_language; ///< The programming language enumeration value.
417 Flags m_flags; ///< Compile unit flags that help with partial parsing.
418 std::vector<lldb::FunctionSP> m_functions; ///< The sparsely populated list of
419 ///shared pointers to functions
420 ///< that gets populated as functions get partially parsed.
421 std::vector<ConstString> m_imported_modules; ///< All modules, including the
422 ///current module, imported by
425 FileSpecList m_support_files; ///< Files associated with this compile unit's
426 ///line table and declarations.
427 std::unique_ptr<LineTable>
428 m_line_table_ap; ///< Line table that will get parsed on demand.
430 m_debug_macros_sp; ///< Debug macros that will get parsed on demand.
431 lldb::VariableListSP m_variables; ///< Global and static variable list that
432 ///will get parsed on demand.
433 lldb_private::LazyBool m_is_optimized; /// eLazyBoolYes if this compile unit
434 /// was compiled with optimization.
438 flagsParsedAllFunctions =
439 (1u << 0), ///< Have we already parsed all our functions
440 flagsParsedVariables =
441 (1u << 1), ///< Have we already parsed globals and statics?
442 flagsParsedSupportFiles = (1u << 2), ///< Have we already parsed the support
443 ///files for this compile unit?
444 flagsParsedLineTable =
445 (1u << 3), ///< Have we parsed the line table already?
446 flagsParsedLanguage = (1u << 4), ///< Have we parsed the language already?
447 flagsParsedImportedModules =
448 (1u << 5), ///< Have we parsed the imported modules already?
449 flagsParsedDebugMacros =
450 (1u << 6) ///< Have we parsed the debug macros already?
453 DISALLOW_COPY_AND_ASSIGN(CompileUnit);
456 } // namespace lldb_private
458 #endif // liblldb_CompUnit_h_