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