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

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() = default;
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(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 : caller_address(caller_address),
310 caller_address_type(caller_address_type), is_tail_call(is_tail_call),
311 parameters(std::move(parameters)) {}
312
313 /// Helper that finds the load address of \p unresolved_pc, a file address
314 /// which refers to an instruction within \p caller.
315 static lldb::addr_t GetLoadAddress(lldb::addr_t unresolved_pc,
316 Function &caller, Target &target);
317
318 /// Like \ref GetReturnPCAddress, but returns an unresolved file address.
319 lldb::addr_t GetUnresolvedReturnPCAddress() const {
320 return caller_address_type == AddrType::AfterCall && !is_tail_call
321 ? caller_address
322 : LLDB_INVALID_ADDRESS;
323 }
324
325private:
326 lldb::addr_t caller_address;
327 AddrType caller_address_type;
328 bool is_tail_call;
329
330 CallSiteParameterArray parameters;
331};
332
333/// A direct call site. Used to represent call sites where the address of the
334/// callee is fixed (e.g. a function call in C in which the call target is not
335/// a function pointer).
336class DirectCallEdge : public CallEdge {
337public:
338 /// Construct a call edge using a symbol name to identify the callee, and a
339 /// return PC within the calling function to identify a specific call site.
340 DirectCallEdge(const char *symbol_name, AddrType caller_address_type,
341 lldb::addr_t caller_address, bool is_tail_call,
342 CallSiteParameterArray &&parameters)
343 : CallEdge(caller_address_type, caller_address, is_tail_call,
344 std::move(parameters)) {
345 lazy_callee.symbol_name = symbol_name;
346 }
347
348 Function *GetCallee(ModuleList &images, ExecutionContext &exe_ctx) override;
349
350private:
351 void ParseSymbolFileAndResolve(ModuleList &images);
352
353 // Used to describe a direct call.
354 //
355 // Either the callee's mangled name or its definition, discriminated by
356 // \ref resolved.
357 union {
358 const char *symbol_name;
359 Function *def;
360 } lazy_callee;
361
362 /// Whether or not an attempt was made to find the callee's definition.
363 bool resolved = false;
364};
365
366/// An indirect call site. Used to represent call sites where the address of
367/// the callee is not fixed, e.g. a call to a C++ virtual function (where the
368/// address is loaded out of a vtable), or a call to a function pointer in C.
369class IndirectCallEdge : public CallEdge {
370public:
371 /// Construct a call edge using a DWARFExpression to identify the callee, and
372 /// a return PC within the calling function to identify a specific call site.
373 IndirectCallEdge(DWARFExpressionList call_target, AddrType caller_address_type,
374 lldb::addr_t caller_address, bool is_tail_call,
375 CallSiteParameterArray &&parameters)
376 : CallEdge(caller_address_type, caller_address, is_tail_call,
377 std::move(parameters)),
378 call_target(std::move(call_target)) {}
379
380 Function *GetCallee(ModuleList &images, ExecutionContext &exe_ctx) override;
381
382private:
383 // Used to describe an indirect call.
384 //
385 // Specifies the location of the callee address in the calling frame.
386 DWARFExpressionList call_target;
387};
388
389/// \class Function Function.h "lldb/Symbol/Function.h"
390/// A class that describes a function.
391///
392/// Functions belong to CompileUnit objects (Function::m_comp_unit), have
393/// unique user IDs (Function::UserID), know how to reconstruct their symbol
394/// context (Function::SymbolContextScope), have a specific function type
395/// (Function::m_type_uid), have a simple method name (FunctionInfo::m_name),
396/// be declared at a specific location (FunctionInfo::m_declaration), possibly
397/// have mangled names (Function::m_mangled), an optional return type
398/// (Function::m_type), and contains lexical blocks (Function::m_blocks).
399///
400/// The function information is split into a few pieces:
401/// \li The concrete instance information
402/// \li The abstract information
403///
404/// The abstract information is found in the function type (Type) that
405/// describes a function information, return type and parameter types.
406///
407/// The concrete information is the address range information and specific
408/// locations for an instance of this function.
409class Function : public UserID, public SymbolContextScope {
410public:
411 /// Construct with a compile unit, function UID, function type UID, optional
412 /// mangled name, function type, and a section offset based address range.
413 ///
414 /// \param[in] comp_unit
415 /// The compile unit to which this function belongs.
416 ///
417 /// \param[in] func_uid
418 /// The UID for this function. This value is provided by the
419 /// SymbolFile plug-in and can be any value that allows
420 /// the plug-in to quickly find and parse more detailed
421 /// information when and if more information is needed.
422 ///
423 /// \param[in] func_type_uid
424 /// The type UID for the function Type to allow for lazy type
425 /// parsing from the debug information.
426 ///
427 /// \param[in] mangled
428 /// The optional mangled name for this function. If empty, there
429 /// is no mangled information.
430 ///
431 /// \param[in] func_type
432 /// The optional function type. If NULL, the function type will
433 /// be parsed on demand when accessed using the
434 /// Function::GetType() function by asking the SymbolFile
435 /// plug-in to get the type for \a func_type_uid.
436 ///
437 /// \param[in] range
438 /// The section offset based address for this function.
439 Function(CompileUnit *comp_unit, lldb::user_id_t func_uid,
440 lldb::user_id_t func_type_uid, const Mangled &mangled,
441 Type *func_type, const AddressRange &range);
442
443 /// Destructor.
444 ~Function() override;
445
446 /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
447 ///
448 /// \see SymbolContextScope
449 void CalculateSymbolContext(SymbolContext *sc) override;
450
451 lldb::ModuleSP CalculateSymbolContextModule() override;
452
453 CompileUnit *CalculateSymbolContextCompileUnit() override;
454
455 Function *CalculateSymbolContextFunction() override;
456
457 const AddressRange &GetAddressRange() { return m_range; }
458
459 lldb::LanguageType GetLanguage() const;
460 /// Find the file and line number of the source location of the start of the
461 /// function. This will use the declaration if present and fall back on the
462 /// line table if that fails. So there may NOT be a line table entry for
463 /// this source file/line combo.
464 ///
465 /// \param[out] source_file
466 /// The source file.
467 ///
468 /// \param[out] line_no
469 /// The line number.
470 void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
471
472 /// Find the file and line number of the source location of the end of the
473 /// function.
474 ///
475 ///
476 /// \param[out] source_file
477 /// The source file.
478 ///
479 /// \param[out] line_no
480 /// The line number.
481 void GetEndLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
482
483 /// Get the outgoing call edges from this function, sorted by their return
484 /// PC addresses (in increasing order).
485 llvm::ArrayRef<std::unique_ptr<CallEdge>> GetCallEdges();
486
487 /// Get the outgoing tail-calling edges from this function. If none exist,
488 /// return None.
489 llvm::ArrayRef<std::unique_ptr<CallEdge>> GetTailCallingEdges();
490
491 /// Get the outgoing call edge from this function which has the given return
492 /// address \p return_pc, or return nullptr. Note that this will not return a
493 /// tail-calling edge.
494 CallEdge *GetCallEdgeForReturnAddress(lldb::addr_t return_pc, Target &target);
495
496 /// Get accessor for the block list.
497 ///
498 /// \return
499 /// The block list object that describes all lexical blocks
500 /// in the function.
501 ///
502 /// \see BlockList
503 Block &GetBlock(bool can_create);
504
505 /// Get accessor for the compile unit that owns this function.
506 ///
507 /// \return
508 /// A compile unit object pointer.
509 CompileUnit *GetCompileUnit();
510
511 /// Get const accessor for the compile unit that owns this function.
512 ///
513 /// \return
514 /// A const compile unit object pointer.
515 const CompileUnit *GetCompileUnit() const;
516
517 void GetDescription(Stream *s, lldb::DescriptionLevel level, Target *target);
518
519 /// Get accessor for the frame base location.
520 ///
521 /// \return
522 /// A location expression that describes the function frame
523 /// base.
524 DWARFExpressionList &GetFrameBaseExpression() { return m_frame_base; }
525
526 /// Get const accessor for the frame base location.
527 ///
528 /// \return
529 /// A const compile unit object pointer.
530 const DWARFExpressionList &GetFrameBaseExpression() const { return m_frame_base; }
531
532 ConstString GetName() const;
533
534 ConstString GetNameNoArguments() const;
535
536 ConstString GetDisplayName() const;
537
538 const Mangled &GetMangled() const { return m_mangled; }
539
540 /// Get the DeclContext for this function, if available.
541 ///
542 /// \return
543 /// The DeclContext, or NULL if none exists.
544 CompilerDeclContext GetDeclContext();
545
546 /// Get accessor for the type that describes the function return value type,
547 /// and parameter types.
548 ///
549 /// \return
550 /// A type object pointer.
551 Type *GetType();
552
553 /// Get const accessor for the type that describes the function return value
554 /// type, and parameter types.
555 ///
556 /// \return
557 /// A const type object pointer.
558 const Type *GetType() const;
559
560 CompilerType GetCompilerType();
561
562 /// Get the size of the prologue instructions for this function. The
563 /// "prologue" instructions include any instructions given line number 0
564 /// immediately following the prologue end.
565 ///
566 /// \return
567 /// The size of the prologue.
568 uint32_t GetPrologueByteSize();
569
570 /// Dump a description of this object to a Stream.
571 ///
572 /// Dump a description of the contents of this object to the supplied stream
573 /// \a s.
574 ///
575 /// \param[in] s
576 /// The stream to which to dump the object description.
577 ///
578 /// \param[in] show_context
579 /// If \b true, variables will dump their symbol context
580 /// information.
581 void Dump(Stream *s, bool show_context) const;
582
583 /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
584 ///
585 /// \see SymbolContextScope
586 void DumpSymbolContext(Stream *s) override;
587
588 /// Get the memory cost of this object.
589 ///
590 /// \return
591 /// The number of bytes that this object occupies in memory.
592 /// The returned value does not include the bytes for any
593 /// shared string values.
594 size_t MemorySize() const;
595
596 /// Get whether compiler optimizations were enabled for this function
597 ///
598 /// The debug information may provide information about whether this
599 /// function was compiled with optimization or not. In this case,
600 /// "optimized" means that the debug experience may be difficult for the
601 /// user to understand. Variables may not be available when the developer
602 /// would expect them, stepping through the source lines in the function may
603 /// appear strange, etc.
604 ///
605 /// \return
606 /// Returns 'true' if this function was compiled with
607 /// optimization. 'false' indicates that either the optimization
608 /// is unknown, or this function was built without optimization.
609 bool GetIsOptimized();
610
611 /// Get whether this function represents a 'top-level' function
612 ///
613 /// The concept of a top-level function is language-specific, mostly meant
614 /// to represent the notion of scripting-style code that has global
615 /// visibility of the variables/symbols/functions/... defined within the
616 /// containing file/module
617 ///
618 /// If stopped in a top-level function, LLDB will expose global variables
619 /// as-if locals in the 'frame variable' command
620 ///
621 /// \return
622 /// Returns 'true' if this function is a top-level function,
623 /// 'false' otherwise.
624 bool IsTopLevelFunction();
625
626 lldb::DisassemblerSP GetInstructions(const ExecutionContext &exe_ctx,
627 const char *flavor,
628 bool force_live_memory = false);
629
630 bool GetDisassembly(const ExecutionContext &exe_ctx, const char *flavor,
631 Stream &strm, bool force_live_memory = false);
632
633protected:
634 enum {
635 /// Whether we already tried to calculate the prologue size.
636 flagsCalculatedPrologueSize = (1 << 0)
637 };
638
639 /// The compile unit that owns this function.
640 CompileUnit *m_comp_unit;
641
642 /// The user ID of for the prototype Type for this function.
643 lldb::user_id_t m_type_uid;
644
645 /// The function prototype type for this function that includes the function
646 /// info (FunctionInfo), return type and parameters.
647 Type *m_type;
648
649 /// The mangled function name if any. If empty, there is no mangled
650 /// information.
651 Mangled m_mangled;
652
653 /// All lexical blocks contained in this function.
654 Block m_block;
655
656 /// The function address range that covers the widest range needed to contain
657 /// all blocks
658 AddressRange m_range;
659
660 /// The frame base expression for variables that are relative to the frame
661 /// pointer.
662 DWARFExpressionList m_frame_base;
663
664 Flags m_flags;
665
666 /// Compute the prologue size once and cache it.
667 uint32_t m_prologue_byte_size;
668
669 /// Exclusive lock that controls read/write access to m_call_edges and
670 /// m_call_edges_resolved.
671 std::mutex m_call_edges_lock;
672
673 /// Whether call site info has been parsed.
674 bool m_call_edges_resolved = false;
675
676 /// Outgoing call edges.
677 std::vector<std::unique_ptr<CallEdge>> m_call_edges;
678
679private:
680 Function(const Function &) = delete;
681 const Function &operator=(const Function &) = delete;
682};
683
684} // namespace lldb_private
685
686#endif // LLDB_SYMBOL_FUNCTION_H
687

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

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