lldb/API/SBFrame.h

0001 //===-- SBFrame.h -----------------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLDB_API_SBFRAME_H
0010 #define LLDB_API_SBFRAME_H
0011
0012 #include "lldb/API/SBDefines.h"
0013 #include "lldb/API/SBValueList.h"
0014
0015 namespace lldb_private {
0016 namespace python {
0017 class SWIGBridge;
0018 }
0019 namespace lua {
0020 class SWIGBridge;
0021 }
0022 } // namespace lldb_private
0023
0024 namespace lldb {
0025
0026 class LLDB_API SBFrame {
0027 public:
0028   SBFrame();
0029
0030   SBFrame(const lldb::SBFrame &rhs);
0031
0032   const lldb::SBFrame &operator=(const lldb::SBFrame &rhs);
0033
0034   ~SBFrame();
0035
0036   bool IsEqual(const lldb::SBFrame &that) const;
0037
0038   explicit operator bool() const;
0039
0040   bool IsValid() const;
0041
0042   uint32_t GetFrameID() const;
0043
0044   lldb::addr_t GetCFA() const;
0045
0046   lldb::addr_t GetPC() const;
0047
0048   bool SetPC(lldb::addr_t new_pc);
0049
0050   lldb::addr_t GetSP() const;
0051
0052   lldb::addr_t GetFP() const;
0053
0054   lldb::SBAddress GetPCAddress() const;
0055
0056   lldb::SBSymbolContext GetSymbolContext(uint32_t resolve_scope) const;
0057
0058   lldb::SBModule GetModule() const;
0059
0060   lldb::SBCompileUnit GetCompileUnit() const;
0061
0062   lldb::SBFunction GetFunction() const;
0063
0064   lldb::SBSymbol GetSymbol() const;
0065
0066   /// Gets the deepest block that contains the frame PC.
0067   ///
0068   /// See also GetFrameBlock().
0069   lldb::SBBlock GetBlock() const;
0070
0071   /// Get the appropriate function name for this frame. Inlined functions in
0072   /// LLDB are represented by Blocks that have inlined function information, so
0073   /// just looking at the SBFunction or SBSymbol for a frame isn't enough.
0074   /// This function will return the appropriate function, symbol or inlined
0075   /// function name for the frame.
0076   ///
0077   /// This function returns:
0078   /// - the name of the inlined function (if there is one)
0079   /// - the name of the concrete function (if there is one)
0080   /// - the name of the symbol (if there is one)
0081   /// - NULL
0082   ///
0083   /// See also IsInlined().
0084   const char *GetFunctionName();
0085
0086   // Get an appropriate function name for this frame that is suitable for
0087   // display to a user
0088   const char *GetDisplayFunctionName();
0089
0090   const char *GetFunctionName() const;
0091
0092   // Return the frame function's language.  If there isn't a function, then
0093   // guess the language type from the mangled name.
0094   lldb::LanguageType GuessLanguage() const;
0095
0096   /// Return true if this frame represents an inlined function.
0097   ///
0098   /// See also GetFunctionName().
0099   bool IsInlined();
0100
0101   bool IsInlined() const;
0102
0103   bool IsArtificial();
0104
0105   bool IsArtificial() const;
0106
0107   /// Return whether a frame recognizer decided this frame should not
0108   /// be displayes in backtraces etc.
0109   bool IsHidden() const;
0110
0111   /// The version that doesn't supply a 'use_dynamic' value will use the
0112   /// target's default.
0113   lldb::SBValue EvaluateExpression(const char *expr);
0114
0115   lldb::SBValue EvaluateExpression(const char *expr,
0116                                    lldb::DynamicValueType use_dynamic);
0117
0118   lldb::SBValue EvaluateExpression(const char *expr,
0119                                    lldb::DynamicValueType use_dynamic,
0120                                    bool unwind_on_error);
0121
0122   lldb::SBValue EvaluateExpression(const char *expr,
0123                                    const SBExpressionOptions &options);
0124
0125   /// Language plugins can use this API to report language-specific
0126   /// runtime information about this compile unit, such as additional
0127   /// language version details or feature flags.
0128   SBStructuredData GetLanguageSpecificData() const;
0129
0130   /// Gets the lexical block that defines the stack frame. Another way to think
0131   /// of this is it will return the block that contains all of the variables
0132   /// for a stack frame. Inlined functions are represented as SBBlock objects
0133   /// that have inlined function information: the name of the inlined function,
0134   /// where it was called from. The block that is returned will be the first
0135   /// block at or above the block for the PC (SBFrame::GetBlock()) that defines
0136   /// the scope of the frame. When a function contains no inlined functions,
0137   /// this will be the top most lexical block that defines the function.
0138   /// When a function has inlined functions and the PC is currently
0139   /// in one of those inlined functions, this method will return the inlined
0140   /// block that defines this frame. If the PC isn't currently in an inlined
0141   /// function, the lexical block that defines the function is returned.
0142   lldb::SBBlock GetFrameBlock() const;
0143
0144   lldb::SBLineEntry GetLineEntry() const;
0145
0146   lldb::SBThread GetThread() const;
0147
0148   const char *Disassemble() const;
0149
0150   void Clear();
0151
0152   bool operator==(const lldb::SBFrame &rhs) const;
0153
0154   bool operator!=(const lldb::SBFrame &rhs) const;
0155
0156   /// The version that doesn't supply a 'use_dynamic' value will use the
0157   /// target's default.
0158   lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics,
0159                                  bool in_scope_only);
0160
0161   lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics,
0162                                  bool in_scope_only,
0163                                  lldb::DynamicValueType use_dynamic);
0164
0165   lldb::SBValueList GetVariables(const lldb::SBVariablesOptions &options);
0166
0167   lldb::SBValueList GetRegisters();
0168
0169   lldb::SBValue FindRegister(const char *name);
0170
0171   /// The version that doesn't supply a 'use_dynamic' value will use the
0172   /// target's default.
0173   lldb::SBValue FindVariable(const char *var_name);
0174
0175   lldb::SBValue FindVariable(const char *var_name,
0176                              lldb::DynamicValueType use_dynamic);
0177
0178   // Find a value for a variable expression path like "rect.origin.x" or
0179   // "pt_ptr->x", "*self", "*this->obj_ptr". The returned value is _not_ and
0180   // expression result and is not a constant object like
0181   // SBFrame::EvaluateExpression(...) returns, but a child object of the
0182   // variable value.
0183   lldb::SBValue GetValueForVariablePath(const char *var_expr_cstr,
0184                                         DynamicValueType use_dynamic);
0185
0186   /// The version that doesn't supply a 'use_dynamic' value will use the
0187   /// target's default.
0188   lldb::SBValue GetValueForVariablePath(const char *var_path);
0189
0190   /// Find variables, register sets, registers, or persistent variables using
0191   /// the frame as the scope.
0192   ///
0193   /// NB. This function does not look up ivars in the function object pointer.
0194   /// To do that use GetValueForVariablePath.
0195   ///
0196   /// The version that doesn't supply a 'use_dynamic' value will use the
0197   /// target's default.
0198   lldb::SBValue FindValue(const char *name, ValueType value_type);
0199
0200   lldb::SBValue FindValue(const char *name, ValueType value_type,
0201                           lldb::DynamicValueType use_dynamic);
0202
0203   bool GetDescription(lldb::SBStream &description);
0204
0205   /// Similar to \a GetDescription() but the format of the description can be
0206   /// configured via the \p format parameter. See
0207   /// https://lldb.llvm.org/use/formatting.html for more information on format
0208   /// strings.
0209   ///
0210   /// \param[in] format
0211   ///   The format to use for generating the description.
0212   ///
0213   /// \param[out] output
0214   ///   The stream where the description will be written to.
0215   ///
0216   /// \return
0217   ///   An error object with an error message in case of failures.
0218   SBError GetDescriptionWithFormat(const SBFormat &format, SBStream &output);
0219
0220 protected:
0221   friend class SBBlock;
0222   friend class SBExecutionContext;
0223   friend class SBInstruction;
0224   friend class SBThread;
0225   friend class SBValue;
0226
0227   friend class lldb_private::python::SWIGBridge;
0228   friend class lldb_private::lua::SWIGBridge;
0229
0230   SBFrame(const lldb::StackFrameSP &lldb_object_sp);
0231
0232   lldb::StackFrameSP GetFrameSP() const;
0233
0234   void SetFrameSP(const lldb::StackFrameSP &lldb_object_sp);
0235
0236   lldb::ExecutionContextRefSP m_opaque_sp;
0237 };
0238
0239 } // namespace lldb
0240
0241 #endif // LLDB_API_SBFRAME_H