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/Core/Mangled.h"
15 #include "lldb/Core/UserID.h"
16 #include "lldb/Expression/DWARFExpression.h"
17 #include "lldb/Symbol/Block.h"
18 #include "lldb/Symbol/Declaration.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 //----------------------------------------------------------------------
31 //------------------------------------------------------------------
32 /// Construct with the function method name and optional declaration
36 /// A C string name for the method name for this function. This
37 /// value should not be the mangled named, but the simple method
40 /// @param[in] decl_ptr
41 /// Optional declaration information that describes where the
42 /// function was declared. This can be NULL.
43 //------------------------------------------------------------------
44 FunctionInfo(const char *name, const Declaration *decl_ptr);
46 //------------------------------------------------------------------
47 /// Construct with the function method name and optional declaration
51 /// A name for the method name for this function. This value
52 /// should not be the mangled named, but the simple method name.
54 /// @param[in] decl_ptr
55 /// Optional declaration information that describes where the
56 /// function was declared. This can be NULL.
57 //------------------------------------------------------------------
58 FunctionInfo(const ConstString &name, const Declaration *decl_ptr);
60 //------------------------------------------------------------------
63 /// The destructor is virtual since classes inherit from this class.
64 //------------------------------------------------------------------
65 virtual ~FunctionInfo();
67 //------------------------------------------------------------------
68 /// Compare two function information objects.
70 /// First compares the method names, and if equal, then compares
71 /// the declaration information.
74 /// The Left Hand Side const FunctionInfo object reference.
77 /// The Right Hand Side const FunctionInfo object reference.
80 /// @li -1 if lhs < rhs
81 /// @li 0 if lhs == rhs
82 /// @li 1 if lhs > rhs
83 //------------------------------------------------------------------
84 static int Compare(const FunctionInfo &lhs, const FunctionInfo &rhs);
86 //------------------------------------------------------------------
87 /// Dump a description of this object to a Stream.
89 /// Dump a description of the contents of this object to the
90 /// supplied stream \a s.
93 /// The stream to which to dump the object description.
94 //------------------------------------------------------------------
95 void Dump(Stream *s, bool show_fullpaths) const;
97 //------------------------------------------------------------------
98 /// Get accessor for the declaration information.
101 /// A reference to the declaration object.
102 //------------------------------------------------------------------
103 Declaration &GetDeclaration();
105 //------------------------------------------------------------------
106 /// Get const accessor for the declaration information.
109 /// A const reference to the declaration object.
110 //------------------------------------------------------------------
111 const Declaration &GetDeclaration() const;
113 //------------------------------------------------------------------
114 /// Get accessor for the method name.
117 /// A const reference to the method name object.
118 //------------------------------------------------------------------
119 ConstString GetName() const;
121 //------------------------------------------------------------------
122 /// Get the memory cost of this object.
125 /// The number of bytes that this object occupies in memory.
126 /// The returned value does not include the bytes for any
127 /// shared string values.
129 /// @see ConstString::StaticMemorySize ()
130 //------------------------------------------------------------------
131 virtual size_t MemorySize() const;
134 //------------------------------------------------------------------
136 //------------------------------------------------------------------
137 ConstString m_name; ///< Function method name (not a mangled name).
138 Declaration m_declaration; ///< Information describing where this function
139 ///information was defined.
142 //----------------------------------------------------------------------
143 /// @class InlineFunctionInfo Function.h "lldb/Symbol/Function.h"
144 /// @brief A class that describes information for an inlined function.
145 //----------------------------------------------------------------------
146 class InlineFunctionInfo : public FunctionInfo {
148 //------------------------------------------------------------------
149 /// Construct with the function method name, mangled name, and
150 /// optional declaration information.
153 /// A C string name for the method name for this function. This
154 /// value should not be the mangled named, but the simple method
157 /// @param[in] mangled
158 /// A C string name for the mangled name for this function. This
159 /// value can be NULL if there is no mangled information.
161 /// @param[in] decl_ptr
162 /// Optional declaration information that describes where the
163 /// function was declared. This can be NULL.
165 /// @param[in] call_decl_ptr
166 /// Optional calling location declaration information that
167 /// describes from where this inlined function was called.
168 //------------------------------------------------------------------
169 InlineFunctionInfo(const char *name, const char *mangled,
170 const Declaration *decl_ptr,
171 const Declaration *call_decl_ptr);
173 //------------------------------------------------------------------
174 /// Construct with the function method name, mangled name, and
175 /// optional declaration information.
178 /// A name for the method name for this function. This value
179 /// should not be the mangled named, but the simple method name.
181 /// @param[in] mangled
182 /// A name for the mangled name for this function. This value
183 /// can be empty if there is no mangled information.
185 /// @param[in] decl_ptr
186 /// Optional declaration information that describes where the
187 /// function was declared. This can be NULL.
189 /// @param[in] call_decl_ptr
190 /// Optional calling location declaration information that
191 /// describes from where this inlined function was called.
192 //------------------------------------------------------------------
193 InlineFunctionInfo(const ConstString &name, const Mangled &mangled,
194 const Declaration *decl_ptr,
195 const Declaration *call_decl_ptr);
197 //------------------------------------------------------------------
199 //------------------------------------------------------------------
200 ~InlineFunctionInfo() override;
202 //------------------------------------------------------------------
203 /// Compare two inlined function information objects.
205 /// First compares the FunctionInfo objects, and if equal,
206 /// compares the mangled names.
209 /// The Left Hand Side const InlineFunctionInfo object
213 /// The Right Hand Side const InlineFunctionInfo object
217 /// @li -1 if lhs < rhs
218 /// @li 0 if lhs == rhs
219 /// @li 1 if lhs > rhs
220 //------------------------------------------------------------------
221 int Compare(const InlineFunctionInfo &lhs, const InlineFunctionInfo &rhs);
223 //------------------------------------------------------------------
224 /// Dump a description of this object to a Stream.
226 /// Dump a description of the contents of this object to the
227 /// supplied stream \a s.
230 /// The stream to which to dump the object description.
231 //------------------------------------------------------------------
232 void Dump(Stream *s, bool show_fullpaths) const;
234 void DumpStopContext(Stream *s, lldb::LanguageType language) const;
236 ConstString GetName(lldb::LanguageType language) const;
238 ConstString GetDisplayName(lldb::LanguageType language) const;
240 //------------------------------------------------------------------
241 /// Get accessor for the call site declaration information.
244 /// A reference to the declaration object.
245 //------------------------------------------------------------------
246 Declaration &GetCallSite();
248 //------------------------------------------------------------------
249 /// Get const accessor for the call site declaration information.
252 /// A const reference to the declaration object.
253 //------------------------------------------------------------------
254 const Declaration &GetCallSite() const;
256 //------------------------------------------------------------------
257 /// Get accessor for the mangled name object.
260 /// A reference to the mangled name object.
261 //------------------------------------------------------------------
262 Mangled &GetMangled();
264 //------------------------------------------------------------------
265 /// Get const accessor for the mangled name object.
268 /// A const reference to the mangled name object.
269 //------------------------------------------------------------------
270 const Mangled &GetMangled() const;
272 //------------------------------------------------------------------
273 /// Get the memory cost of this object.
276 /// The number of bytes that this object occupies in memory.
277 /// The returned value does not include the bytes for any
278 /// shared string values.
280 /// @see ConstString::StaticMemorySize ()
281 //------------------------------------------------------------------
282 size_t MemorySize() const override;
285 //------------------------------------------------------------------
287 //------------------------------------------------------------------
288 Mangled m_mangled; ///< Mangled inlined function name (can be empty if there
289 ///is no mangled information).
290 Declaration m_call_decl;
293 //----------------------------------------------------------------------
294 /// @class Function Function.h "lldb/Symbol/Function.h"
295 /// @brief A class that describes a function.
297 /// Functions belong to CompileUnit objects (Function::m_comp_unit),
298 /// have unique user IDs (Function::UserID), know how to reconstruct
299 /// their symbol context (Function::SymbolContextScope), have a
300 /// specific function type (Function::m_type_uid), have a simple
301 /// method name (FunctionInfo::m_name), be declared at a specific
302 /// location (FunctionInfo::m_declaration), possibly have mangled
303 /// names (Function::m_mangled), an optional return type
304 /// (Function::m_type), and contains lexical blocks
305 /// (Function::m_blocks).
307 /// The function information is split into a few pieces:
308 /// @li The concrete instance information
309 /// @li The abstract information
311 /// The abstract information is found in the function type (Type) that
312 /// describes a function information, return type and parameter types.
314 /// The concrete information is the address range information and
315 /// specific locations for an instance of this function.
316 //----------------------------------------------------------------------
317 class Function : public UserID, public SymbolContextScope {
319 //------------------------------------------------------------------
320 /// Construct with a compile unit, function UID, function type UID,
321 /// optional mangled name, function type, and a section offset
322 /// based address range.
324 /// @param[in] comp_unit
325 /// The compile unit to which this function belongs.
327 /// @param[in] func_uid
328 /// The UID for this function. This value is provided by the
329 /// SymbolFile plug-in and can be any value that allows
330 /// the plug-in to quickly find and parse more detailed
331 /// information when and if more information is needed.
333 /// @param[in] func_type_uid
334 /// The type UID for the function Type to allow for lazy type
335 /// parsing from the debug information.
337 /// @param[in] mangled
338 /// The optional mangled name for this function. If empty, there
339 /// is no mangled information.
341 /// @param[in] func_type
342 /// The optional function type. If NULL, the function type will
343 /// be parsed on demand when accessed using the
344 /// Function::GetType() function by asking the SymbolFile
345 /// plug-in to get the type for \a func_type_uid.
348 /// The section offset based address for this function.
349 //------------------------------------------------------------------
350 Function(CompileUnit *comp_unit, lldb::user_id_t func_uid,
351 lldb::user_id_t func_type_uid, const Mangled &mangled,
352 Type *func_type, const AddressRange &range);
354 //------------------------------------------------------------------
355 /// Construct with a compile unit, function UID, function type UID,
356 /// optional mangled name, function type, and a section offset
357 /// based address range.
359 /// @param[in] comp_unit
360 /// The compile unit to which this function belongs.
362 /// @param[in] func_uid
363 /// The UID for this function. This value is provided by the
364 /// SymbolFile plug-in and can be any value that allows
365 /// the plug-in to quickly find and parse more detailed
366 /// information when and if more information is needed.
368 /// @param[in] func_type_uid
369 /// The type UID for the function Type to allow for lazy type
370 /// parsing from the debug information.
372 /// @param[in] mangled
373 /// The optional mangled name for this function. If empty, there
374 /// is no mangled information.
376 /// @param[in] func_type
377 /// The optional function type. If NULL, the function type will
378 /// be parsed on demand when accessed using the
379 /// Function::GetType() function by asking the SymbolFile
380 /// plug-in to get the type for \a func_type_uid.
383 /// The section offset based address for this function.
384 //------------------------------------------------------------------
385 Function(CompileUnit *comp_unit, lldb::user_id_t func_uid,
386 lldb::user_id_t func_type_uid, const char *mangled, Type *func_type,
387 const AddressRange &range);
389 //------------------------------------------------------------------
391 //------------------------------------------------------------------
392 ~Function() override;
394 //------------------------------------------------------------------
395 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
397 /// @see SymbolContextScope
398 //------------------------------------------------------------------
399 void CalculateSymbolContext(SymbolContext *sc) override;
401 lldb::ModuleSP CalculateSymbolContextModule() override;
403 CompileUnit *CalculateSymbolContextCompileUnit() override;
405 Function *CalculateSymbolContextFunction() override;
407 const AddressRange &GetAddressRange() { return m_range; }
409 lldb::LanguageType GetLanguage() const;
410 //------------------------------------------------------------------
411 /// Find the file and line number of the source location of the start
412 /// of the function. This will use the declaration if present and fall
413 /// back on the line table if that fails. So there may NOT be a line
414 /// table entry for this source file/line combo.
416 /// @param[out] source_file
419 /// @param[out] line_no
421 //------------------------------------------------------------------
422 void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
424 //------------------------------------------------------------------
425 /// Find the file and line number of the source location of the end
429 /// @param[out] source_file
432 /// @param[out] line_no
434 //------------------------------------------------------------------
435 void GetEndLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
437 //------------------------------------------------------------------
438 /// Get accessor for the block list.
441 /// The block list object that describes all lexical blocks
445 //------------------------------------------------------------------
446 Block &GetBlock(bool can_create);
448 //------------------------------------------------------------------
449 /// Get accessor for the compile unit that owns this function.
452 /// A compile unit object pointer.
453 //------------------------------------------------------------------
454 CompileUnit *GetCompileUnit();
456 //------------------------------------------------------------------
457 /// Get const accessor for the compile unit that owns this function.
460 /// A const compile unit object pointer.
461 //------------------------------------------------------------------
462 const CompileUnit *GetCompileUnit() const;
464 void GetDescription(Stream *s, lldb::DescriptionLevel level, Target *target);
466 //------------------------------------------------------------------
467 /// Get accessor for the frame base location.
470 /// A location expression that describes the function frame
472 //------------------------------------------------------------------
473 DWARFExpression &GetFrameBaseExpression() { return m_frame_base; }
475 //------------------------------------------------------------------
476 /// Get const accessor for the frame base location.
479 /// A const compile unit object pointer.
480 //------------------------------------------------------------------
481 const DWARFExpression &GetFrameBaseExpression() const { return m_frame_base; }
483 ConstString GetName() const;
485 ConstString GetNameNoArguments() const;
487 ConstString GetDisplayName() const;
489 const Mangled &GetMangled() const { return m_mangled; }
491 //------------------------------------------------------------------
492 /// Get the DeclContext for this function, if available.
495 /// The DeclContext, or NULL if none exists.
496 //------------------------------------------------------------------
497 CompilerDeclContext GetDeclContext();
499 //------------------------------------------------------------------
500 /// Get accessor for the type that describes the function
501 /// return value type, and parameter types.
504 /// A type object pointer.
505 //------------------------------------------------------------------
508 //------------------------------------------------------------------
509 /// Get const accessor for the type that describes the function
510 /// return value type, and parameter types.
513 /// A const type object pointer.
514 //------------------------------------------------------------------
515 const Type *GetType() const;
517 CompilerType GetCompilerType();
519 //------------------------------------------------------------------
520 /// Get the size of the prologue instructions for this function. The
522 /// instructions include any instructions given line number 0 immediately
524 /// the prologue end.
527 /// The size of the prologue.
528 //------------------------------------------------------------------
529 uint32_t GetPrologueByteSize();
531 //------------------------------------------------------------------
532 /// Dump a description of this object to a Stream.
534 /// Dump a description of the contents of this object to the
535 /// supplied stream \a s.
538 /// The stream to which to dump the object description.
540 /// @param[in] show_context
541 /// If \b true, variables will dump their symbol context
543 //------------------------------------------------------------------
544 void Dump(Stream *s, bool show_context) const;
546 //------------------------------------------------------------------
547 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
549 /// @see SymbolContextScope
550 //------------------------------------------------------------------
551 void DumpSymbolContext(Stream *s) override;
553 //------------------------------------------------------------------
554 /// Get the memory cost of this object.
557 /// The number of bytes that this object occupies in memory.
558 /// The returned value does not include the bytes for any
559 /// shared string values.
561 /// @see ConstString::StaticMemorySize ()
562 //------------------------------------------------------------------
563 size_t MemorySize() const;
565 //------------------------------------------------------------------
566 /// Get whether compiler optimizations were enabled for this function
568 /// The debug information may provide information about whether this
569 /// function was compiled with optimization or not. In this case,
570 /// "optimized" means that the debug experience may be difficult
571 /// for the user to understand. Variables may not be available when
572 /// the developer would expect them, stepping through the source lines
573 /// in the function may appear strange, etc.
576 /// Returns 'true' if this function was compiled with
577 /// optimization. 'false' indicates that either the optimization
578 /// is unknown, or this function was built without optimization.
579 //------------------------------------------------------------------
580 bool GetIsOptimized();
582 //------------------------------------------------------------------
583 /// Get whether this function represents a 'top-level' function
585 /// The concept of a top-level function is language-specific, mostly
586 /// meant to represent the notion of scripting-style code that has
587 /// global visibility of the variables/symbols/functions/...
588 /// defined within the containing file/module
590 /// If stopped in a top-level function, LLDB will expose global variables
591 /// as-if locals in the 'frame variable' command
594 /// Returns 'true' if this function is a top-level function,
595 /// 'false' otherwise.
596 //------------------------------------------------------------------
597 bool IsTopLevelFunction();
599 lldb::DisassemblerSP GetInstructions(const ExecutionContext &exe_ctx,
601 bool prefer_file_cache);
603 bool GetDisassembly(const ExecutionContext &exe_ctx, const char *flavor,
604 bool prefer_file_cache, Stream &strm);
608 flagsCalculatedPrologueSize =
609 (1 << 0) ///< Have we already tried to calculate the prologue size?
612 //------------------------------------------------------------------
614 //------------------------------------------------------------------
615 CompileUnit *m_comp_unit; ///< The compile unit that owns this function.
617 m_type_uid; ///< The user ID of for the prototype Type for this function.
618 Type *m_type; ///< The function prototype type for this function that include
619 ///the function info (FunctionInfo), return type and parameters.
620 Mangled m_mangled; ///< The mangled function name if any, if empty, there is
621 ///no mangled information.
622 Block m_block; ///< All lexical blocks contained in this function.
623 AddressRange m_range; ///< The function address range that covers the widest
624 ///range needed to contain all blocks
625 DWARFExpression m_frame_base; ///< The frame base expression for variables
626 ///that are relative to the frame pointer.
629 m_prologue_byte_size; ///< Compute the prologue size once and cache it
631 DISALLOW_COPY_AND_ASSIGN(Function);
634 } // namespace lldb_private
636 #endif // liblldb_Function_h_