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

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