1 //===-- Function.h ----------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_Function_h_
10 #define liblldb_Function_h_
12 #include "lldb/Core/AddressRange.h"
13 #include "lldb/Core/Mangled.h"
14 #include "lldb/Expression/DWARFExpression.h"
15 #include "lldb/Symbol/Block.h"
16 #include "lldb/Symbol/Declaration.h"
17 #include "lldb/Utility/UserID.h"
18 #include "llvm/ADT/ArrayRef.h"
20 namespace lldb_private {
22 /// \class FunctionInfo Function.h "lldb/Symbol/Function.h"
23 /// A class that contains generic function information.
25 /// This provides generic function information that gets reused between inline
26 /// functions and function types.
29 /// Construct with the function method name and optional declaration
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
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);
42 /// Construct with the function method name and optional declaration
46 /// A name for the method name for this function. This value
47 /// should not be the mangled named, but the simple method name.
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);
56 /// The destructor is virtual since classes inherit from this class.
57 virtual ~FunctionInfo();
59 /// Compare two function information objects.
61 /// First compares the method names, and if equal, then compares the
62 /// declaration information.
65 /// The Left Hand Side const FunctionInfo object reference.
68 /// The Right Hand Side const FunctionInfo object reference.
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);
76 /// Dump a description of this object to a Stream.
78 /// Dump a description of the contents of this object to the supplied stream
82 /// The stream to which to dump the object description.
83 void Dump(Stream *s, bool show_fullpaths) const;
85 /// Get accessor for the declaration information.
88 /// A reference to the declaration object.
89 Declaration &GetDeclaration();
91 /// Get const accessor for the declaration information.
94 /// A const reference to the declaration object.
95 const Declaration &GetDeclaration() const;
97 /// Get accessor for the method name.
100 /// A const reference to the method name object.
101 ConstString GetName() const;
103 /// Get the memory cost of this object.
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.
110 /// \see ConstString::StaticMemorySize ()
111 virtual size_t MemorySize() const;
115 ConstString m_name; ///< Function method name (not a mangled name).
116 Declaration m_declaration; ///< Information describing where this function
117 ///information was defined.
120 /// \class InlineFunctionInfo Function.h "lldb/Symbol/Function.h"
121 /// A class that describes information for an inlined function.
122 class InlineFunctionInfo : public FunctionInfo {
124 /// Construct with the function method name, mangled name, and optional
125 /// declaration information.
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
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.
136 /// \param[in] decl_ptr
137 /// Optional declaration information that describes where the
138 /// function was declared. This can be NULL.
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);
147 /// Construct with the function method name, mangled name, and optional
148 /// declaration information.
151 /// A name for the method name for this function. This value
152 /// should not be the mangled named, but the simple method name.
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.
158 /// \param[in] decl_ptr
159 /// Optional declaration information that describes where the
160 /// function was declared. This can be NULL.
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);
170 ~InlineFunctionInfo() override;
172 /// Compare two inlined function information objects.
174 /// First compares the FunctionInfo objects, and if equal, compares the
178 /// The Left Hand Side const InlineFunctionInfo object
182 /// The Right Hand Side const InlineFunctionInfo object
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);
191 /// Dump a description of this object to a Stream.
193 /// Dump a description of the contents of this object to the supplied stream
197 /// The stream to which to dump the object description.
198 void Dump(Stream *s, bool show_fullpaths) const;
200 void DumpStopContext(Stream *s, lldb::LanguageType language) const;
202 ConstString GetName(lldb::LanguageType language) const;
204 ConstString GetDisplayName(lldb::LanguageType language) const;
206 /// Get accessor for the call site declaration information.
209 /// A reference to the declaration object.
210 Declaration &GetCallSite();
212 /// Get const accessor for the call site declaration information.
215 /// A const reference to the declaration object.
216 const Declaration &GetCallSite() const;
218 /// Get accessor for the mangled name object.
221 /// A reference to the mangled name object.
222 Mangled &GetMangled();
224 /// Get const accessor for the mangled name object.
227 /// A const reference to the mangled name object.
228 const Mangled &GetMangled() const;
230 /// Get the memory cost of this object.
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.
237 /// \see ConstString::StaticMemorySize ()
238 size_t MemorySize() const override;
242 Mangled m_mangled; ///< Mangled inlined function name (can be empty if there
243 ///is no mangled information).
244 Declaration m_call_decl;
249 /// \class CallEdge Function.h "lldb/Symbol/Function.h"
251 /// Represent a call made within a Function. This can be used to find a path
252 /// in the call graph between two functions.
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.
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);
264 CallEdge(CallEdge &&) = default;
265 CallEdge &operator=(CallEdge &&) = default;
267 /// Get the callee's definition.
269 /// Note that this might lazily invoke the DWARF parser.
270 Function *GetCallee(ModuleList &images);
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
276 lldb::addr_t GetReturnPCAddress(Function &caller, Target &target) const;
278 /// Like \ref GetReturnPCAddress, but returns an unslid function-local PC
280 lldb::addr_t GetUnresolvedReturnPCAddress() const { return return_pc; }
283 void ParseSymbolFileAndResolve(ModuleList &images);
285 /// Either the callee's mangled name or its definition, discriminated by
288 const char *symbol_name;
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;
297 /// Whether or not an attempt was made to find the callee's definition.
300 DISALLOW_COPY_AND_ASSIGN(CallEdge);
303 /// \class Function Function.h "lldb/Symbol/Function.h"
304 /// A class that describes a function.
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).
314 /// The function information is split into a few pieces:
315 /// \li The concrete instance information
316 /// \li The abstract information
318 /// The abstract information is found in the function type (Type) that
319 /// describes a function information, return type and parameter types.
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 {
325 /// Construct with a compile unit, function UID, function type UID, optional
326 /// mangled name, function type, and a section offset based address range.
328 /// \param[in] comp_unit
329 /// The compile unit to which this function belongs.
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.
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.
341 /// \param[in] mangled
342 /// The optional mangled name for this function. If empty, there
343 /// is no mangled information.
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.
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);
358 ~Function() override;
360 /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
362 /// \see SymbolContextScope
363 void CalculateSymbolContext(SymbolContext *sc) override;
365 lldb::ModuleSP CalculateSymbolContextModule() override;
367 CompileUnit *CalculateSymbolContextCompileUnit() override;
369 Function *CalculateSymbolContextFunction() override;
371 const AddressRange &GetAddressRange() { return m_range; }
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.
379 /// \param[out] source_file
382 /// \param[out] line_no
384 void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
386 /// Find the file and line number of the source location of the end of the
390 /// \param[out] source_file
393 /// \param[out] line_no
395 void GetEndLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
397 /// Get the outgoing call edges from this function, sorted by their return
398 /// PC addresses (in increasing order).
399 llvm::MutableArrayRef<CallEdge> GetCallEdges();
401 /// Get the outgoing tail-calling edges from this function. If none exist,
403 llvm::MutableArrayRef<CallEdge> GetTailCallingEdges();
405 /// Get accessor for the block list.
408 /// The block list object that describes all lexical blocks
412 Block &GetBlock(bool can_create);
414 /// Get accessor for the compile unit that owns this function.
417 /// A compile unit object pointer.
418 CompileUnit *GetCompileUnit();
420 /// Get const accessor for the compile unit that owns this function.
423 /// A const compile unit object pointer.
424 const CompileUnit *GetCompileUnit() const;
426 void GetDescription(Stream *s, lldb::DescriptionLevel level, Target *target);
428 /// Get accessor for the frame base location.
431 /// A location expression that describes the function frame
433 DWARFExpression &GetFrameBaseExpression() { return m_frame_base; }
435 /// Get const accessor for the frame base location.
438 /// A const compile unit object pointer.
439 const DWARFExpression &GetFrameBaseExpression() const { return m_frame_base; }
441 ConstString GetName() const;
443 ConstString GetNameNoArguments() const;
445 ConstString GetDisplayName() const;
447 const Mangled &GetMangled() const { return m_mangled; }
449 /// Get the DeclContext for this function, if available.
452 /// The DeclContext, or NULL if none exists.
453 CompilerDeclContext GetDeclContext();
455 /// Get accessor for the type that describes the function return value type,
456 /// and parameter types.
459 /// A type object pointer.
462 /// Get const accessor for the type that describes the function return value
463 /// type, and parameter types.
466 /// A const type object pointer.
467 const Type *GetType() const;
469 CompilerType GetCompilerType();
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.
476 /// The size of the prologue.
477 uint32_t GetPrologueByteSize();
479 /// Dump a description of this object to a Stream.
481 /// Dump a description of the contents of this object to the supplied stream
485 /// The stream to which to dump the object description.
487 /// \param[in] show_context
488 /// If \b true, variables will dump their symbol context
490 void Dump(Stream *s, bool show_context) const;
492 /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
494 /// \see SymbolContextScope
495 void DumpSymbolContext(Stream *s) override;
497 /// Get the memory cost of this object.
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.
504 /// \see ConstString::StaticMemorySize ()
505 size_t MemorySize() const;
507 /// Get whether compiler optimizations were enabled for this function
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.
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();
522 /// Get whether this function represents a 'top-level' function
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
529 /// If stopped in a top-level function, LLDB will expose global variables
530 /// as-if locals in the 'frame variable' command
533 /// Returns 'true' if this function is a top-level function,
534 /// 'false' otherwise.
535 bool IsTopLevelFunction();
537 lldb::DisassemblerSP GetInstructions(const ExecutionContext &exe_ctx,
539 bool prefer_file_cache);
541 bool GetDisassembly(const ExecutionContext &exe_ctx, const char *flavor,
542 bool prefer_file_cache, Stream &strm);
546 flagsCalculatedPrologueSize =
547 (1 << 0) ///< Have we already tried to calculate the prologue size?
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.
565 m_prologue_byte_size; ///< Compute the prologue size once and cache it
567 bool m_call_edges_resolved = false; ///< Whether call site info has been
569 std::vector<CallEdge> m_call_edges; ///< Outgoing call edges.
571 DISALLOW_COPY_AND_ASSIGN(Function);
574 } // namespace lldb_private
576 #endif // liblldb_Function_h_