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

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

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

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