Coverage Report

Created: 2022-01-22 13:19

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Symbol/CompileUnit.h
Line
Count
Source (jump to first uncovered line)
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
26
namespace 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.
38
class CompileUnit : public std::enable_shared_from_this<CompileUnit>,
39
                    public ModuleChild,
40
                    public UserID,
41
                    public SymbolContextScope {
42
public:
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
0
  void SetLanguage(lldb::LanguageType language) {
146
0
    m_flags.Set(flagsParsedLanguage);
147
0
    m_language = language;
148
0
  }
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 \btrue match only if there is a line table entry for this line
212
  ///     number.
213
  ///     If \bfalse, 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
16.5k
  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
0
  size_t GetNumFunctions() const { return m_functions_by_uid.size(); }
399
400
protected:
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
427
private:
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