1 //===-- Function.h ----------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Function_h_
11 #define liblldb_Function_h_
13 #include "lldb/Core/AddressRange.h"
14 #include "lldb/Symbol/Block.h"
15 #include "lldb/Symbol/Declaration.h"
16 #include "lldb/Expression/DWARFExpression.h"
17 #include "lldb/Core/Mangled.h"
18 #include "lldb/Core/UserID.h"
20 namespace lldb_private {
22 //----------------------------------------------------------------------
23 /// @class FunctionInfo Function.h "lldb/Symbol/Function.h"
24 /// @brief A class that contains generic function information.
26 /// This provides generic function information that gets reused between
27 /// inline functions and function types.
28 //----------------------------------------------------------------------
32 //------------------------------------------------------------------
33 /// Construct with the function method name and optional declaration
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
41 /// @param[in] decl_ptr
42 /// Optional declaration information that describes where the
43 /// function was declared. This can be NULL.
44 //------------------------------------------------------------------
45 FunctionInfo (const char *name, const Declaration *decl_ptr);
47 //------------------------------------------------------------------
48 /// Construct with the function method name and optional declaration
52 /// A name for the method name for this function. This value
53 /// should not be the mangled named, but the simple method name.
55 /// @param[in] decl_ptr
56 /// Optional declaration information that describes where the
57 /// function was declared. This can be NULL.
58 //------------------------------------------------------------------
59 FunctionInfo (const ConstString& name, const Declaration *decl_ptr);
61 //------------------------------------------------------------------
64 /// The destructor is virtual since classes inherit from this class.
65 //------------------------------------------------------------------
69 //------------------------------------------------------------------
70 /// Compare two function information objects.
72 /// First compares the method names, and if equal, then compares
73 /// the declaration information.
76 /// The Left Hand Side const FunctionInfo object reference.
79 /// The Right Hand Side const FunctionInfo object reference.
82 /// @li -1 if lhs < rhs
83 /// @li 0 if lhs == rhs
84 /// @li 1 if lhs > rhs
85 //------------------------------------------------------------------
87 Compare (const FunctionInfo& lhs, const FunctionInfo& rhs);
89 //------------------------------------------------------------------
90 /// Dump a description of this object to a Stream.
92 /// Dump a description of the contents of this object to the
93 /// supplied stream \a s.
96 /// The stream to which to dump the object description.
97 //------------------------------------------------------------------
99 Dump (Stream *s, bool show_fullpaths) const;
101 //------------------------------------------------------------------
102 /// Get accessor for the declaration information.
105 /// A reference to the declaration object.
106 //------------------------------------------------------------------
110 //------------------------------------------------------------------
111 /// Get const accessor for the declaration information.
114 /// A const reference to the declaration object.
115 //------------------------------------------------------------------
117 GetDeclaration () const;
119 //------------------------------------------------------------------
120 /// Get accessor for the method name.
123 /// A const reference to the method name object.
124 //------------------------------------------------------------------
128 //------------------------------------------------------------------
129 /// Get the memory cost of this object.
132 /// The number of bytes that this object occupies in memory.
133 /// The returned value does not include the bytes for any
134 /// shared string values.
136 /// @see ConstString::StaticMemorySize ()
137 //------------------------------------------------------------------
142 //------------------------------------------------------------------
144 //------------------------------------------------------------------
145 ConstString m_name; ///< Function method name (not a mangled name).
146 Declaration m_declaration; ///< Information describing where this function information was defined.
149 //----------------------------------------------------------------------
150 /// @class InlineFunctionInfo Function.h "lldb/Symbol/Function.h"
151 /// @brief A class that describes information for an inlined function.
152 //----------------------------------------------------------------------
153 class InlineFunctionInfo : public FunctionInfo
156 //------------------------------------------------------------------
157 /// Construct with the function method name, mangled name, and
158 /// optional declaration information.
161 /// A C string name for the method name for this function. This
162 /// value should not be the mangled named, but the simple method
165 /// @param[in] mangled
166 /// A C string name for the mangled name for this function. This
167 /// value can be NULL if there is no mangled information.
169 /// @param[in] decl_ptr
170 /// Optional declaration information that describes where the
171 /// function was declared. This can be NULL.
173 /// @param[in] call_decl_ptr
174 /// Optional calling location declaration information that
175 /// describes from where this inlined function was called.
176 //------------------------------------------------------------------
177 InlineFunctionInfo(const char *name, const char *mangled, const Declaration *decl_ptr, const Declaration *call_decl_ptr);
179 //------------------------------------------------------------------
180 /// Construct with the function method name, mangled name, and
181 /// optional declaration information.
184 /// A name for the method name for this function. This value
185 /// should not be the mangled named, but the simple method name.
187 /// @param[in] mangled
188 /// A name for the mangled name for this function. This value
189 /// can be empty if there is no mangled information.
191 /// @param[in] decl_ptr
192 /// Optional declaration information that describes where the
193 /// function was declared. This can be NULL.
195 /// @param[in] call_decl_ptr
196 /// Optional calling location declaration information that
197 /// describes from where this inlined function was called.
198 //------------------------------------------------------------------
199 InlineFunctionInfo(const ConstString& name, const Mangled &mangled, const Declaration *decl_ptr, const Declaration *call_decl_ptr);
201 //------------------------------------------------------------------
203 //------------------------------------------------------------------
204 ~InlineFunctionInfo() override;
206 //------------------------------------------------------------------
207 /// Compare two inlined function information objects.
209 /// First compares the FunctionInfo objects, and if equal,
210 /// compares the mangled names.
213 /// The Left Hand Side const InlineFunctionInfo object
217 /// The Right Hand Side const InlineFunctionInfo object
221 /// @li -1 if lhs < rhs
222 /// @li 0 if lhs == rhs
223 /// @li 1 if lhs > rhs
224 //------------------------------------------------------------------
226 Compare(const InlineFunctionInfo& lhs, const InlineFunctionInfo& rhs);
228 //------------------------------------------------------------------
229 /// Dump a description of this object to a Stream.
231 /// Dump a description of the contents of this object to the
232 /// supplied stream \a s.
235 /// The stream to which to dump the object description.
236 //------------------------------------------------------------------
238 Dump(Stream *s, bool show_fullpaths) const;
241 DumpStopContext (Stream *s, lldb::LanguageType language) const;
244 GetName (lldb::LanguageType language) const;
247 GetDisplayName (lldb::LanguageType language) const;
249 //------------------------------------------------------------------
250 /// Get accessor for the call site declaration information.
253 /// A reference to the declaration object.
254 //------------------------------------------------------------------
258 //------------------------------------------------------------------
259 /// Get const accessor for the call site declaration information.
262 /// A const reference to the declaration object.
263 //------------------------------------------------------------------
265 GetCallSite () const;
267 //------------------------------------------------------------------
268 /// Get accessor for the mangled name object.
271 /// A reference to the mangled name object.
272 //------------------------------------------------------------------
276 //------------------------------------------------------------------
277 /// Get const accessor for the mangled name object.
280 /// A const reference to the mangled name object.
281 //------------------------------------------------------------------
285 //------------------------------------------------------------------
286 /// Get the memory cost of this object.
289 /// The number of bytes that this object occupies in memory.
290 /// The returned value does not include the bytes for any
291 /// shared string values.
293 /// @see ConstString::StaticMemorySize ()
294 //------------------------------------------------------------------
296 MemorySize() const override;
299 //------------------------------------------------------------------
301 //------------------------------------------------------------------
302 Mangled m_mangled; ///< Mangled inlined function name (can be empty if there is no mangled information).
303 Declaration m_call_decl;
306 //----------------------------------------------------------------------
307 /// @class Function Function.h "lldb/Symbol/Function.h"
308 /// @brief A class that describes a function.
310 /// Functions belong to CompileUnit objects (Function::m_comp_unit),
311 /// have unique user IDs (Function::UserID), know how to reconstruct
312 /// their symbol context (Function::SymbolContextScope), have a
313 /// specific function type (Function::m_type_uid), have a simple
314 /// method name (FunctionInfo::m_name), be declared at a specific
315 /// location (FunctionInfo::m_declaration), possibly have mangled
316 /// names (Function::m_mangled), an optional return type
317 /// (Function::m_type), and contains lexical blocks
318 /// (Function::m_blocks).
320 /// The function information is split into a few pieces:
321 /// @li The concrete instance information
322 /// @li The abstract information
324 /// The abstract information is found in the function type (Type) that
325 /// describes a function information, return type and parameter types.
327 /// The concrete information is the address range information and
328 /// specific locations for an instance of this function.
329 //----------------------------------------------------------------------
332 public SymbolContextScope
335 //------------------------------------------------------------------
336 /// Construct with a compile unit, function UID, function type UID,
337 /// optional mangled name, function type, and a section offset
338 /// based address range.
340 /// @param[in] comp_unit
341 /// The compile unit to which this function belongs.
343 /// @param[in] func_uid
344 /// The UID for this function. This value is provided by the
345 /// SymbolFile plug-in and can be any value that allows
346 /// the plug-in to quickly find and parse more detailed
347 /// information when and if more information is needed.
349 /// @param[in] func_type_uid
350 /// The type UID for the function Type to allow for lazy type
351 /// parsing from the debug information.
353 /// @param[in] mangled
354 /// The optional mangled name for this function. If empty, there
355 /// is no mangled information.
357 /// @param[in] func_type
358 /// The optional function type. If NULL, the function type will
359 /// be parsed on demand when accessed using the
360 /// Function::GetType() function by asking the SymbolFile
361 /// plug-in to get the type for \a func_type_uid.
364 /// The section offset based address for this function.
365 //------------------------------------------------------------------
367 CompileUnit *comp_unit,
368 lldb::user_id_t func_uid,
369 lldb::user_id_t func_type_uid,
370 const Mangled &mangled,
372 const AddressRange& range);
374 //------------------------------------------------------------------
375 /// Construct with a compile unit, function UID, function type UID,
376 /// optional mangled name, function type, and a section offset
377 /// based address range.
379 /// @param[in] comp_unit
380 /// The compile unit to which this function belongs.
382 /// @param[in] func_uid
383 /// The UID for this function. This value is provided by the
384 /// SymbolFile plug-in and can be any value that allows
385 /// the plug-in to quickly find and parse more detailed
386 /// information when and if more information is needed.
388 /// @param[in] func_type_uid
389 /// The type UID for the function Type to allow for lazy type
390 /// parsing from the debug information.
392 /// @param[in] mangled
393 /// The optional mangled name for this function. If empty, there
394 /// is no mangled information.
396 /// @param[in] func_type
397 /// The optional function type. If NULL, the function type will
398 /// be parsed on demand when accessed using the
399 /// Function::GetType() function by asking the SymbolFile
400 /// plug-in to get the type for \a func_type_uid.
403 /// The section offset based address for this function.
404 //------------------------------------------------------------------
406 CompileUnit *comp_unit,
407 lldb::user_id_t func_uid,
408 lldb::user_id_t func_type_uid,
411 const AddressRange& range);
413 //------------------------------------------------------------------
415 //------------------------------------------------------------------
416 ~Function() override;
418 //------------------------------------------------------------------
419 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
421 /// @see SymbolContextScope
422 //------------------------------------------------------------------
424 CalculateSymbolContext(SymbolContext* sc) override;
427 CalculateSymbolContextModule() override;
430 CalculateSymbolContextCompileUnit() override;
433 CalculateSymbolContextFunction() override;
443 //------------------------------------------------------------------
444 /// Find the file and line number of the source location of the start
445 /// of the function. This will use the declaration if present and fall
446 /// back on the line table if that fails. So there may NOT be a line
447 /// table entry for this source file/line combo.
449 /// @param[out] source_file
452 /// @param[out] line_no
454 //------------------------------------------------------------------
456 GetStartLineSourceInfo (FileSpec &source_file, uint32_t &line_no);
458 //------------------------------------------------------------------
459 /// Find the file and line number of the source location of the end
463 /// @param[out] source_file
466 /// @param[out] line_no
468 //------------------------------------------------------------------
470 GetEndLineSourceInfo (FileSpec &source_file, uint32_t &line_no);
472 //------------------------------------------------------------------
473 /// Get accessor for the block list.
476 /// The block list object that describes all lexical blocks
480 //------------------------------------------------------------------
482 GetBlock (bool can_create);
484 //------------------------------------------------------------------
485 /// Get accessor for the compile unit that owns this function.
488 /// A compile unit object pointer.
489 //------------------------------------------------------------------
493 //------------------------------------------------------------------
494 /// Get const accessor for the compile unit that owns this function.
497 /// A const compile unit object pointer.
498 //------------------------------------------------------------------
500 GetCompileUnit() const;
503 GetDescription(Stream *s, lldb::DescriptionLevel level, Target *target);
505 //------------------------------------------------------------------
506 /// Get accessor for the frame base location.
509 /// A location expression that describes the function frame
511 //------------------------------------------------------------------
513 GetFrameBaseExpression()
518 //------------------------------------------------------------------
519 /// Get const accessor for the frame base location.
522 /// A const compile unit object pointer.
523 //------------------------------------------------------------------
524 const DWARFExpression &
525 GetFrameBaseExpression() const
534 GetNameNoArguments () const;
537 GetDisplayName () const;
545 //------------------------------------------------------------------
546 /// Get the DeclContext for this function, if available.
549 /// The DeclContext, or NULL if none exists.
550 //------------------------------------------------------------------
554 //------------------------------------------------------------------
555 /// Get accessor for the type that describes the function
556 /// return value type, and parameter types.
559 /// A type object pointer.
560 //------------------------------------------------------------------
564 //------------------------------------------------------------------
565 /// Get const accessor for the type that describes the function
566 /// return value type, and parameter types.
569 /// A const type object pointer.
570 //------------------------------------------------------------------
577 //------------------------------------------------------------------
578 /// Get the size of the prologue instructions for this function. The "prologue"
579 /// instructions include any instructions given line number 0 immediately following
580 /// the prologue end.
583 /// The size of the prologue.
584 //------------------------------------------------------------------
586 GetPrologueByteSize ();
588 //------------------------------------------------------------------
589 /// Dump a description of this object to a Stream.
591 /// Dump a description of the contents of this object to the
592 /// supplied stream \a s.
595 /// The stream to which to dump the object description.
597 /// @param[in] show_context
598 /// If \b true, variables will dump their symbol context
600 //------------------------------------------------------------------
602 Dump(Stream *s, bool show_context) const;
604 //------------------------------------------------------------------
605 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
607 /// @see SymbolContextScope
608 //------------------------------------------------------------------
610 DumpSymbolContext(Stream *s) override;
612 //------------------------------------------------------------------
613 /// Get the memory cost of this object.
616 /// The number of bytes that this object occupies in memory.
617 /// The returned value does not include the bytes for any
618 /// shared string values.
620 /// @see ConstString::StaticMemorySize ()
621 //------------------------------------------------------------------
625 //------------------------------------------------------------------
626 /// Get whether compiler optimizations were enabled for this function
628 /// The debug information may provide information about whether this
629 /// function was compiled with optimization or not. In this case,
630 /// "optimized" means that the debug experience may be difficult
631 /// for the user to understand. Variables may not be available when
632 /// the developer would expect them, stepping through the source lines
633 /// in the function may appear strange, etc.
636 /// Returns 'true' if this function was compiled with
637 /// optimization. 'false' indicates that either the optimization
638 /// is unknown, or this function was built without optimization.
639 //------------------------------------------------------------------
643 //------------------------------------------------------------------
644 /// Get whether this function represents a 'top-level' function
646 /// The concept of a top-level function is language-specific, mostly
647 /// meant to represent the notion of scripting-style code that has
648 /// global visibility of the variables/symbols/functions/...
649 /// defined within the containing file/module
651 /// If stopped in a top-level function, LLDB will expose global variables
652 /// as-if locals in the 'frame variable' command
655 /// Returns 'true' if this function is a top-level function,
656 /// 'false' otherwise.
657 //------------------------------------------------------------------
659 IsTopLevelFunction ();
662 GetInstructions (const ExecutionContext &exe_ctx,
664 bool prefer_file_cache);
667 GetDisassembly (const ExecutionContext &exe_ctx,
669 bool prefer_file_cache,
676 flagsCalculatedPrologueSize = (1 << 0) ///< Have we already tried to calculate the prologue size?
679 //------------------------------------------------------------------
681 //------------------------------------------------------------------
682 CompileUnit *m_comp_unit; ///< The compile unit that owns this function.
683 lldb::user_id_t m_type_uid; ///< The user ID of for the prototype Type for this function.
684 Type * m_type; ///< The function prototype type for this function that include the function info (FunctionInfo), return type and parameters.
685 Mangled m_mangled; ///< The mangled function name if any, if empty, there is no mangled information.
686 Block m_block; ///< All lexical blocks contained in this function.
687 AddressRange m_range; ///< The function address range that covers the widest range needed to contain all blocks
688 DWARFExpression m_frame_base; ///< The frame base expression for variables that are relative to the frame pointer.
690 uint32_t m_prologue_byte_size; ///< Compute the prologue size once and cache it
692 DISALLOW_COPY_AND_ASSIGN(Function);
695 } // namespace lldb_private
697 #endif // liblldb_Function_h_