1 //===-- CompileUnit.h -------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_CompUnit_h_
10 #define liblldb_CompUnit_h_
12 #include "lldb/Core/FileSpecList.h"
13 #include "lldb/Core/ModuleChild.h"
14 #include "lldb/Symbol/DebugMacros.h"
15 #include "lldb/Symbol/Function.h"
16 #include "lldb/Symbol/SourceModule.h"
17 #include "lldb/Utility/Stream.h"
18 #include "lldb/Utility/UserID.h"
19 #include "lldb/lldb-enumerations.h"
21 #include "llvm/ADT/DenseMap.h"
23 namespace lldb_private {
24 /// \class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
25 /// A class that describes a compilation unit.
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.
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
35 class CompileUnit : public std::enable_shared_from_this<CompileUnit>,
39 public SymbolContextScope {
41 /// Construct with a module, path, UID and language.
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.
48 /// The parent module that owns this compile unit. This value
49 /// must be a valid pointer value.
51 /// \param[in] user_data
52 /// User data where the SymbolFile parser can store data.
54 /// \param[in] pathname
55 /// The path to the source file for this compile unit.
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.
63 /// \param[in] language
64 /// A language enumeration type that describes the main language
65 /// of this compile unit.
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.
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);
79 /// Construct with a module, file spec, UID and language.
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.
86 /// The parent module that owns this compile unit. This value
87 /// must be a valid pointer value.
89 /// \param[in] user_data
90 /// User data where the SymbolFile parser can store data.
92 /// \param[in] file_spec
93 /// The file specification for the source file of this compile
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.
102 /// \param[in] language
103 /// A language enumeration type that describes the main language
104 /// of this compile unit.
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.
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);
119 ~CompileUnit() override;
121 /// Add a function to this compile unit.
123 /// Typically called by the SymbolFile plug-ins as they partially parse the
124 /// debug information.
126 /// \param[in] function_sp
127 /// A shared pointer to the Function object.
128 void AddFunction(lldb::FunctionSP &function_sp);
130 /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
132 /// \see SymbolContextScope
133 void CalculateSymbolContext(SymbolContext *sc) override;
135 lldb::ModuleSP CalculateSymbolContextModule() override;
137 CompileUnit *CalculateSymbolContextCompileUnit() override;
139 /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
141 /// \see SymbolContextScope
142 void DumpSymbolContext(Stream *s) override;
144 lldb::LanguageType GetLanguage();
146 void SetLanguage(lldb::LanguageType language) {
147 m_flags.Set(flagsParsedLanguage);
148 m_language = language;
151 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
153 /// Apply a lambda to each function in this compile unit.
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.
158 /// \note Prefer using FindFunctionByUID over this if possible.
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;
166 /// Dump the compile unit contents to the stream \a s.
169 /// The stream to which to dump the object description.
171 /// \param[in] show_context
172 /// If \b true, variables will dump their symbol context
174 void Dump(Stream *s, bool show_context) const;
176 /// Find the line entry by line and optional inlined file spec.
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).
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.
188 /// \param[in] start_idx
189 /// The zero based index at which to start looking for matches.
192 /// The line number to search for.
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
200 /// If \btrue match only if there is a line table entry for this line
202 /// If \bfalse, find the line table entry equal to or after this line
205 /// \param[out] line_entry
206 /// If non-NULL, a copy of the line entry that was found.
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);
215 /// Get the line table for the compile unit.
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.
222 /// The line table object pointer, or NULL if this line table
223 /// hasn't been parsed yet.
224 LineTable *GetLineTable();
226 DebugMacros *GetDebugMacros();
228 /// Get the compile unit's support file list.
230 /// The support file list is used by the line table, and any objects that
231 /// have valid Declaration objects.
234 /// A support file list object.
235 const FileSpecList &GetSupportFiles();
237 /// Get the compile unit's imported module list.
239 /// This reports all the imports that the compile unit made, including the
243 /// A list of imported modules.
244 const std::vector<SourceModule> &GetImportedModules();
246 /// Get the SymbolFile plug-in user data.
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.
252 /// The user data stored with the CompileUnit when it was
254 void *GetUserData() const;
256 /// Get the variable list for a compile unit.
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.
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).
270 /// A shared pointer to a variable list, that can contain NULL
271 /// VariableList pointer if there are no global or static
273 lldb::VariableListSP GetVariableList(bool can_create);
275 /// Finds a function by user ID.
277 /// Typically used by SymbolFile plug-ins when partially parsing the debug
278 /// information to see if the function has been parsed yet.
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.
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);
291 /// Set the line table for the compile unit.
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.
297 /// \param[in] line_table
298 /// A line table object pointer that this object now owns.
299 void SetLineTable(LineTable *line_table);
301 void SetDebugMacros(const DebugMacrosSP &debug_macros);
303 /// Set accessor for the variable list.
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.
308 /// \param[in] variable_list_sp
309 /// A shared pointer to a VariableList.
310 void SetVariableList(lldb::VariableListSP &variable_list_sp);
312 /// Resolve symbol contexts by file and line.
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.
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.
324 /// The line number to match against the compile unit's line
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
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.
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.
346 /// \param[out] sc_list
347 /// A SymbolContext list class that will get any matching
348 /// entries appended to.
351 /// The number of new matches that were added to \a sc_list.
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);
359 /// Get whether compiler optimizations were enabled for this compile unit
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.
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();
372 /// Returns the number of functions in this compile unit
373 size_t GetNumFunctions() const { return m_functions_by_uid.size(); }
376 /// User data for the SymbolFile parser to store information into.
378 /// The programming language enumeration value.
379 lldb::LanguageType m_language;
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
386 std::vector<SourceModule> m_imported_modules;
387 /// Files associated with this compile unit's line table and
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.
393 DebugMacrosSP m_debug_macros_sp;
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
398 lldb_private::LazyBool m_is_optimized;
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?
417 DISALLOW_COPY_AND_ASSIGN(CompileUnit);
420 } // namespace lldb_private
422 #endif // liblldb_CompUnit_h_