LLDB  mainline
Function.h
Go to the documentation of this file.
1 //===-- Function.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 liblldb_Function_h_
10 #define liblldb_Function_h_
11 
12 #include "lldb/Core/AddressRange.h"
13 #include "lldb/Core/Mangled.h"
15 #include "lldb/Symbol/Block.h"
17 #include "lldb/Utility/UserID.h"
18 #include "llvm/ADT/ArrayRef.h"
19 
20 namespace lldb_private {
21 
22 /// \class FunctionInfo Function.h "lldb/Symbol/Function.h"
23 /// A class that contains generic function information.
24 ///
25 /// This provides generic function information that gets reused between inline
26 /// functions and function types.
27 class FunctionInfo {
28 public:
29  /// Construct with the function method name and optional declaration
30  /// information.
31  ///
32  /// \param[in] name
33  /// A C string name for the method name for this function. This
34  /// value should not be the mangled named, but the simple method
35  /// name.
36  ///
37  /// \param[in] decl_ptr
38  /// Optional declaration information that describes where the
39  /// function was declared. This can be NULL.
40  FunctionInfo(const char *name, const Declaration *decl_ptr);
41 
42  /// Construct with the function method name and optional declaration
43  /// information.
44  ///
45  /// \param[in] name
46  /// A name for the method name for this function. This value
47  /// should not be the mangled named, but the simple method name.
48  ///
49  /// \param[in] decl_ptr
50  /// Optional declaration information that describes where the
51  /// function was declared. This can be NULL.
52  FunctionInfo(ConstString name, const Declaration *decl_ptr);
53 
54  /// Destructor.
55  ///
56  /// The destructor is virtual since classes inherit from this class.
57  virtual ~FunctionInfo();
58 
59  /// Compare two function information objects.
60  ///
61  /// First compares the method names, and if equal, then compares the
62  /// declaration information.
63  ///
64  /// \param[in] lhs
65  /// The Left Hand Side const FunctionInfo object reference.
66  ///
67  /// \param[in] rhs
68  /// The Right Hand Side const FunctionInfo object reference.
69  ///
70  /// \return
71  /// \li -1 if lhs < rhs
72  /// \li 0 if lhs == rhs
73  /// \li 1 if lhs > rhs
74  static int Compare(const FunctionInfo &lhs, const FunctionInfo &rhs);
75 
76  /// Dump a description of this object to a Stream.
77  ///
78  /// Dump a description of the contents of this object to the supplied stream
79  /// \a s.
80  ///
81  /// \param[in] s
82  /// The stream to which to dump the object description.
83  void Dump(Stream *s, bool show_fullpaths) const;
84 
85  /// Get accessor for the declaration information.
86  ///
87  /// \return
88  /// A reference to the declaration object.
90 
91  /// Get const accessor for the declaration information.
92  ///
93  /// \return
94  /// A const reference to the declaration object.
95  const Declaration &GetDeclaration() const;
96 
97  /// Get accessor for the method name.
98  ///
99  /// \return
100  /// A const reference to the method name object.
101  ConstString GetName() const;
102 
103  /// Get the memory cost of this object.
104  ///
105  /// \return
106  /// The number of bytes that this object occupies in memory.
107  /// The returned value does not include the bytes for any
108  /// shared string values.
109  ///
110  /// \see ConstString::StaticMemorySize ()
111  virtual size_t MemorySize() const;
112 
113 protected:
114  // Member variables.
115  ConstString m_name; ///< Function method name (not a mangled name).
116  Declaration m_declaration; ///< Information describing where this function
117  ///information was defined.
118 };
119 
120 /// \class InlineFunctionInfo Function.h "lldb/Symbol/Function.h"
121 /// A class that describes information for an inlined function.
123 public:
124  /// Construct with the function method name, mangled name, and optional
125  /// declaration information.
126  ///
127  /// \param[in] name
128  /// A C string name for the method name for this function. This
129  /// value should not be the mangled named, but the simple method
130  /// name.
131  ///
132  /// \param[in] mangled
133  /// A C string name for the mangled name for this function. This
134  /// value can be NULL if there is no mangled information.
135  ///
136  /// \param[in] decl_ptr
137  /// Optional declaration information that describes where the
138  /// function was declared. This can be NULL.
139  ///
140  /// \param[in] call_decl_ptr
141  /// Optional calling location declaration information that
142  /// describes from where this inlined function was called.
143  InlineFunctionInfo(const char *name, const char *mangled,
144  const Declaration *decl_ptr,
145  const Declaration *call_decl_ptr);
146 
147  /// Construct with the function method name, mangled name, and optional
148  /// declaration information.
149  ///
150  /// \param[in] name
151  /// A name for the method name for this function. This value
152  /// should not be the mangled named, but the simple method name.
153  ///
154  /// \param[in] mangled
155  /// A name for the mangled name for this function. This value
156  /// can be empty if there is no mangled information.
157  ///
158  /// \param[in] decl_ptr
159  /// Optional declaration information that describes where the
160  /// function was declared. This can be NULL.
161  ///
162  /// \param[in] call_decl_ptr
163  /// Optional calling location declaration information that
164  /// describes from where this inlined function was called.
165  InlineFunctionInfo(ConstString name, const Mangled &mangled,
166  const Declaration *decl_ptr,
167  const Declaration *call_decl_ptr);
168 
169  /// Destructor.
170  ~InlineFunctionInfo() override;
171 
172  /// Compare two inlined function information objects.
173  ///
174  /// First compares the FunctionInfo objects, and if equal, compares the
175  /// mangled names.
176  ///
177  /// \param[in] lhs
178  /// The Left Hand Side const InlineFunctionInfo object
179  /// reference.
180  ///
181  /// \param[in] rhs
182  /// The Right Hand Side const InlineFunctionInfo object
183  /// reference.
184  ///
185  /// \return
186  /// \li -1 if lhs < rhs
187  /// \li 0 if lhs == rhs
188  /// \li 1 if lhs > rhs
189  int Compare(const InlineFunctionInfo &lhs, const InlineFunctionInfo &rhs);
190 
191  /// Dump a description of this object to a Stream.
192  ///
193  /// Dump a description of the contents of this object to the supplied stream
194  /// \a s.
195  ///
196  /// \param[in] s
197  /// The stream to which to dump the object description.
198  void Dump(Stream *s, bool show_fullpaths) const;
199 
200  void DumpStopContext(Stream *s, lldb::LanguageType language) const;
201 
202  ConstString GetName(lldb::LanguageType language) const;
203 
204  ConstString GetDisplayName(lldb::LanguageType language) const;
205 
206  /// Get accessor for the call site declaration information.
207  ///
208  /// \return
209  /// A reference to the declaration object.
210  Declaration &GetCallSite();
211 
212  /// Get const accessor for the call site declaration information.
213  ///
214  /// \return
215  /// A const reference to the declaration object.
216  const Declaration &GetCallSite() const;
217 
218  /// Get accessor for the mangled name object.
219  ///
220  /// \return
221  /// A reference to the mangled name object.
222  Mangled &GetMangled();
223 
224  /// Get const accessor for the mangled name object.
225  ///
226  /// \return
227  /// A const reference to the mangled name object.
228  const Mangled &GetMangled() const;
229 
230  /// Get the memory cost of this object.
231  ///
232  /// \return
233  /// The number of bytes that this object occupies in memory.
234  /// The returned value does not include the bytes for any
235  /// shared string values.
236  ///
237  /// \see ConstString::StaticMemorySize ()
238  size_t MemorySize() const override;
239 
240 private:
241  // Member variables.
242  Mangled m_mangled; ///< Mangled inlined function name (can be empty if there
243  ///is no mangled information).
244  Declaration m_call_decl;
245 };
246 
247 class Function;
248 
249 /// \class CallEdge Function.h "lldb/Symbol/Function.h"
250 ///
251 /// Represent a call made within a Function. This can be used to find a path
252 /// in the call graph between two functions.
253 class CallEdge {
254 public:
255  /// Construct a call edge using a symbol name to identify the calling
256  /// function, and a return PC within the calling function to identify a
257  /// specific call site.
258  ///
259  /// TODO: A symbol name may not be globally unique. To disambiguate ODR
260  /// conflicts, it's necessary to determine the \c Target a call edge is
261  /// associated with before resolving it.
262  CallEdge(const char *symbol_name, lldb::addr_t return_pc);
263 
264  CallEdge(CallEdge &&) = default;
265  CallEdge &operator=(CallEdge &&) = default;
266 
267  /// Get the callee's definition.
268  ///
269  /// Note that this might lazily invoke the DWARF parser.
270  Function *GetCallee(ModuleList &images);
271 
272  /// Get the load PC address of the instruction which executes after the call
273  /// returns. Returns LLDB_INVALID_ADDRESS iff this is a tail call. \p caller
274  /// is the Function containing this call, and \p target is the Target which
275  /// made the call.
276  lldb::addr_t GetReturnPCAddress(Function &caller, Target &target) const;
277 
278  /// Like \ref GetReturnPCAddress, but returns an unslid function-local PC
279  /// offset.
280  lldb::addr_t GetUnresolvedReturnPCAddress() const { return return_pc; }
281 
282 private:
283  void ParseSymbolFileAndResolve(ModuleList &images);
284 
285  /// Either the callee's mangled name or its definition, discriminated by
286  /// \ref resolved.
287  union {
288  const char *symbol_name;
290  } lazy_callee;
291 
292  /// An invalid address if this is a tail call. Otherwise, the function-local
293  /// PC offset. Adding this PC offset to the function's base load address
294  /// gives the return PC for the call.
295  lldb::addr_t return_pc;
296 
297  /// Whether or not an attempt was made to find the callee's definition.
298  bool resolved;
299 
300  DISALLOW_COPY_AND_ASSIGN(CallEdge);
301 };
302 
303 /// \class Function Function.h "lldb/Symbol/Function.h"
304 /// A class that describes a function.
305 ///
306 /// Functions belong to CompileUnit objects (Function::m_comp_unit), have
307 /// unique user IDs (Function::UserID), know how to reconstruct their symbol
308 /// context (Function::SymbolContextScope), have a specific function type
309 /// (Function::m_type_uid), have a simple method name (FunctionInfo::m_name),
310 /// be declared at a specific location (FunctionInfo::m_declaration), possibly
311 /// have mangled names (Function::m_mangled), an optional return type
312 /// (Function::m_type), and contains lexical blocks (Function::m_blocks).
313 ///
314 /// The function information is split into a few pieces:
315 /// \li The concrete instance information
316 /// \li The abstract information
317 ///
318 /// The abstract information is found in the function type (Type) that
319 /// describes a function information, return type and parameter types.
320 ///
321 /// The concrete information is the address range information and specific
322 /// locations for an instance of this function.
323 class Function : public UserID, public SymbolContextScope {
324 public:
325  /// Construct with a compile unit, function UID, function type UID, optional
326  /// mangled name, function type, and a section offset based address range.
327  ///
328  /// \param[in] comp_unit
329  /// The compile unit to which this function belongs.
330  ///
331  /// \param[in] func_uid
332  /// The UID for this function. This value is provided by the
333  /// SymbolFile plug-in and can be any value that allows
334  /// the plug-in to quickly find and parse more detailed
335  /// information when and if more information is needed.
336  ///
337  /// \param[in] func_type_uid
338  /// The type UID for the function Type to allow for lazy type
339  /// parsing from the debug information.
340  ///
341  /// \param[in] mangled
342  /// The optional mangled name for this function. If empty, there
343  /// is no mangled information.
344  ///
345  /// \param[in] func_type
346  /// The optional function type. If NULL, the function type will
347  /// be parsed on demand when accessed using the
348  /// Function::GetType() function by asking the SymbolFile
349  /// plug-in to get the type for \a func_type_uid.
350  ///
351  /// \param[in] range
352  /// The section offset based address for this function.
353  Function(CompileUnit *comp_unit, lldb::user_id_t func_uid,
354  lldb::user_id_t func_type_uid, const Mangled &mangled,
355  Type *func_type, const AddressRange &range);
356 
357  /// Destructor.
358  ~Function() override;
359 
360  /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
361  ///
362  /// \see SymbolContextScope
363  void CalculateSymbolContext(SymbolContext *sc) override;
364 
365  lldb::ModuleSP CalculateSymbolContextModule() override;
366 
367  CompileUnit *CalculateSymbolContextCompileUnit() override;
368 
369  Function *CalculateSymbolContextFunction() override;
370 
371  const AddressRange &GetAddressRange() { return m_range; }
372 
373  lldb::LanguageType GetLanguage() const;
374  /// Find the file and line number of the source location of the start of the
375  /// function. This will use the declaration if present and fall back on the
376  /// line table if that fails. So there may NOT be a line table entry for
377  /// this source file/line combo.
378  ///
379  /// \param[out] source_file
380  /// The source file.
381  ///
382  /// \param[out] line_no
383  /// The line number.
384  void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
385 
386  /// Find the file and line number of the source location of the end of the
387  /// function.
388  ///
389  ///
390  /// \param[out] source_file
391  /// The source file.
392  ///
393  /// \param[out] line_no
394  /// The line number.
395  void GetEndLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
396 
397  /// Get the outgoing call edges from this function, sorted by their return
398  /// PC addresses (in increasing order).
399  llvm::MutableArrayRef<CallEdge> GetCallEdges();
400 
401  /// Get the outgoing tail-calling edges from this function. If none exist,
402  /// return None.
403  llvm::MutableArrayRef<CallEdge> GetTailCallingEdges();
404 
405  /// Get accessor for the block list.
406  ///
407  /// \return
408  /// The block list object that describes all lexical blocks
409  /// in the function.
410  ///
411  /// \see BlockList
412  Block &GetBlock(bool can_create);
413 
414  /// Get accessor for the compile unit that owns this function.
415  ///
416  /// \return
417  /// A compile unit object pointer.
418  CompileUnit *GetCompileUnit();
419 
420  /// Get const accessor for the compile unit that owns this function.
421  ///
422  /// \return
423  /// A const compile unit object pointer.
424  const CompileUnit *GetCompileUnit() const;
425 
426  void GetDescription(Stream *s, lldb::DescriptionLevel level, Target *target);
427 
428  /// Get accessor for the frame base location.
429  ///
430  /// \return
431  /// A location expression that describes the function frame
432  /// base.
433  DWARFExpression &GetFrameBaseExpression() { return m_frame_base; }
434 
435  /// Get const accessor for the frame base location.
436  ///
437  /// \return
438  /// A const compile unit object pointer.
439  const DWARFExpression &GetFrameBaseExpression() const { return m_frame_base; }
440 
441  ConstString GetName() const;
442 
443  ConstString GetNameNoArguments() const;
444 
445  ConstString GetDisplayName() const;
446 
447  const Mangled &GetMangled() const { return m_mangled; }
448 
449  /// Get the DeclContext for this function, if available.
450  ///
451  /// \return
452  /// The DeclContext, or NULL if none exists.
453  CompilerDeclContext GetDeclContext();
454 
455  /// Get accessor for the type that describes the function return value type,
456  /// and parameter types.
457  ///
458  /// \return
459  /// A type object pointer.
460  Type *GetType();
461 
462  /// Get const accessor for the type that describes the function return value
463  /// type, and parameter types.
464  ///
465  /// \return
466  /// A const type object pointer.
467  const Type *GetType() const;
468 
469  CompilerType GetCompilerType();
470 
471  /// Get the size of the prologue instructions for this function. The
472  /// "prologue" instructions include any instructions given line number 0
473  /// immediately following the prologue end.
474  ///
475  /// \return
476  /// The size of the prologue.
477  uint32_t GetPrologueByteSize();
478 
479  /// Dump a description of this object to a Stream.
480  ///
481  /// Dump a description of the contents of this object to the supplied stream
482  /// \a s.
483  ///
484  /// \param[in] s
485  /// The stream to which to dump the object description.
486  ///
487  /// \param[in] show_context
488  /// If \b true, variables will dump their symbol context
489  /// information.
490  void Dump(Stream *s, bool show_context) const;
491 
492  /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
493  ///
494  /// \see SymbolContextScope
495  void DumpSymbolContext(Stream *s) override;
496 
497  /// Get the memory cost of this object.
498  ///
499  /// \return
500  /// The number of bytes that this object occupies in memory.
501  /// The returned value does not include the bytes for any
502  /// shared string values.
503  ///
504  /// \see ConstString::StaticMemorySize ()
505  size_t MemorySize() const;
506 
507  /// Get whether compiler optimizations were enabled for this function
508  ///
509  /// The debug information may provide information about whether this
510  /// function was compiled with optimization or not. In this case,
511  /// "optimized" means that the debug experience may be difficult for the
512  /// user to understand. Variables may not be available when the developer
513  /// would expect them, stepping through the source lines in the function may
514  /// appear strange, etc.
515  ///
516  /// \return
517  /// Returns 'true' if this function was compiled with
518  /// optimization. 'false' indicates that either the optimization
519  /// is unknown, or this function was built without optimization.
520  bool GetIsOptimized();
521 
522  /// Get whether this function represents a 'top-level' function
523  ///
524  /// The concept of a top-level function is language-specific, mostly meant
525  /// to represent the notion of scripting-style code that has global
526  /// visibility of the variables/symbols/functions/... defined within the
527  /// containing file/module
528  ///
529  /// If stopped in a top-level function, LLDB will expose global variables
530  /// as-if locals in the 'frame variable' command
531  ///
532  /// \return
533  /// Returns 'true' if this function is a top-level function,
534  /// 'false' otherwise.
535  bool IsTopLevelFunction();
536 
537  lldb::DisassemblerSP GetInstructions(const ExecutionContext &exe_ctx,
538  const char *flavor,
539  bool prefer_file_cache);
540 
541  bool GetDisassembly(const ExecutionContext &exe_ctx, const char *flavor,
542  bool prefer_file_cache, Stream &strm);
543 
544 protected:
545  enum {
546  flagsCalculatedPrologueSize =
547  (1 << 0) ///< Have we already tried to calculate the prologue size?
548  };
549 
550  // Member variables.
551  CompileUnit *m_comp_unit; ///< The compile unit that owns this function.
553  m_type_uid; ///< The user ID of for the prototype Type for this function.
554  Type *m_type; ///< The function prototype type for this function that include
555  ///the function info (FunctionInfo), return type and parameters.
556  Mangled m_mangled; ///< The mangled function name if any, if empty, there is
557  ///no mangled information.
558  Block m_block; ///< All lexical blocks contained in this function.
559  AddressRange m_range; ///< The function address range that covers the widest
560  ///range needed to contain all blocks
561  DWARFExpression m_frame_base; ///< The frame base expression for variables
562  ///that are relative to the frame pointer.
564  uint32_t
565  m_prologue_byte_size; ///< Compute the prologue size once and cache it
566 
567  bool m_call_edges_resolved = false; ///< Whether call site info has been
568  /// parsed.
569  std::vector<CallEdge> m_call_edges; ///< Outgoing call edges.
570 private:
571  DISALLOW_COPY_AND_ASSIGN(Function);
572 };
573 
574 } // namespace lldb_private
575 
576 #endif // liblldb_Function_h_
lldb::user_id_t m_type_uid
The user ID of for the prototype Type for this function.
Definition: Function.h:553
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
void Dump(Stream *s, bool show_fullpaths) const
Dump a description of this object to a Stream.
Definition: Function.cpp:37
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
"lldb/Expression/DWARFExpression.h" Encapsulates a DWARF location expression and interprets it...
AddressRange m_range
The function address range that covers the widest range needed to contain all blocks.
Definition: Function.h:559
A mix in class that contains a generic user ID.
Definition: UserID.h:33
A file utility class.
Definition: FileSpec.h:55
const DWARFExpression & GetFrameBaseExpression() const
Get const accessor for the frame base location.
Definition: Function.h:439
A class that describes a function.
Definition: Function.h:323
Mangled m_mangled
The mangled function name if any, if empty, there is no mangled information.
Definition: Function.h:556
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
ConstString m_name
Function method name (not a mangled name).
Definition: Function.h:115
A class that describes a single lexical block.
Definition: Block.h:41
lldb::addr_t GetUnresolvedReturnPCAddress() const
Like GetReturnPCAddress, but returns an unslid function-local PC offset.
Definition: Function.h:280
A class that describes a compilation unit.
Definition: CompileUnit.h:35
static int Compare(const FunctionInfo &lhs, const FunctionInfo &rhs)
Compare two function information objects.
Definition: Function.cpp:43
uint64_t user_id_t
Definition: lldb-types.h:84
LanguageType
Programming language type.
FunctionInfo(const char *name, const Declaration *decl_ptr)
Construct with the function method name and optional declaration information.
Definition: Function.cpp:29
A collection class for Module objects.
Definition: ModuleList.h:91
const char * symbol_name
Definition: Function.h:288
Represent a call made within a Function.
Definition: Function.h:253
virtual size_t MemorySize() const
Get the memory cost of this object.
Definition: Function.cpp:59
DWARFExpression m_frame_base
The frame base expression for variables that are relative to the frame pointer.
Definition: Function.h:561
CompileUnit * m_comp_unit
The compile unit that owns this function.
Definition: Function.h:551
const Mangled & GetMangled() const
Definition: Function.h:447
uint32_t m_prologue_byte_size
Compute the prologue size once and cache it.
Definition: Function.h:565
A class that contains generic function information.
Definition: Function.h:27
Declaration m_declaration
Information describing where this function information was defined.
Definition: Function.h:116
std::vector< CallEdge > m_call_edges
Outgoing call edges.
Definition: Function.h:569
Type * m_type
The function prototype type for this function that include the function info (FunctionInfo), return type and parameters.
Definition: Function.h:554
A class to manage flags.
Definition: Flags.h:22
A class that describes information for an inlined function.
Definition: Function.h:122
uint64_t addr_t
Definition: lldb-types.h:83
A uniqued constant string class.
Definition: ConstString.h:38
Declaration & GetDeclaration()
Get accessor for the declaration information.
Definition: Function.cpp:51
DWARFExpression & GetFrameBaseExpression()
Get accessor for the frame base location.
Definition: Function.h:433
virtual ~FunctionInfo()
Destructor.
Definition: Function.cpp:35
const AddressRange & GetAddressRange()
Definition: Function.h:371
A class that describes the declaration location of a lldb object.
Definition: Declaration.h:24
A section + offset based address range class.
Definition: AddressRange.h:32
"lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is part of a symbol context and c...
ConstString GetName() const
Get accessor for the method name.
Definition: Function.cpp:57
Block m_block
All lexical blocks contained in this function.
Definition: Function.h:558