lldb/include/lldb/Target/LanguageRuntime.h

   1 //===-- LanguageRuntime.h ---------------------------------------------------*-
   2 // C++ -*-===//
   3 //
   4 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   5 // See https://llvm.org/LICENSE.txt for license information.
   6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_TARGET_LANGUAGERUNTIME_H
  11 #define LLDB_TARGET_LANGUAGERUNTIME_H
  12
  13 #include "lldb/Breakpoint/BreakpointResolver.h"
  14 #include "lldb/Breakpoint/BreakpointResolverName.h"
  15 #include "lldb/Core/PluginInterface.h"
  16 #include "lldb/Core/Value.h"
  17 #include "lldb/Expression/LLVMUserExpression.h"
  18 #include "lldb/Symbol/DeclVendor.h"
  19 #include "lldb/Target/ExecutionContextScope.h"
  20 #include "lldb/Target/Runtime.h"
  21 #include "lldb/ValueObject/ValueObject.h"
  22 #include "lldb/lldb-private.h"
  23 #include "lldb/lldb-public.h"
  24 #include <optional>
  25
  26 namespace lldb_private {
  27
  28 class ExceptionSearchFilter : public SearchFilter {
  29 public:
  30   ExceptionSearchFilter(const lldb::TargetSP &target_sp,
  31                         lldb::LanguageType language,
  32                         bool update_module_list = true);
  33
  34   ~ExceptionSearchFilter() override = default;
  35
  36   bool ModulePasses(const lldb::ModuleSP &module_sp) override;
  37
  38   bool ModulePasses(const FileSpec &spec) override;
  39
  40   void Search(Searcher &searcher) override;
  41
  42   void GetDescription(Stream *s) override;
  43
  44   static SearchFilter *
  45   CreateFromStructuredData(Target &target,
  46                            const StructuredData::Dictionary &data_dict,
  47                            Status &error);
  48
  49   StructuredData::ObjectSP SerializeToStructuredData() override;
  50
  51 protected:
  52   lldb::LanguageType m_language;
  53   LanguageRuntime *m_language_runtime;
  54   lldb::SearchFilterSP m_filter_sp;
  55
  56   lldb::SearchFilterSP DoCreateCopy() override;
  57
  58   void UpdateModuleListIfNeeded();
  59 };
  60
  61 class LanguageRuntime : public Runtime, public PluginInterface {
  62 public:
  63   static LanguageRuntime *FindPlugin(Process *process,
  64                                      lldb::LanguageType language);
  65
  66   static void InitializeCommands(CommandObject *parent);
  67
  68   virtual lldb::LanguageType GetLanguageType() const = 0;
  69
  70   /// Return the preferred language runtime instance, which in most cases will
  71   /// be the current instance.
  72   virtual LanguageRuntime *GetPreferredLanguageRuntime(ValueObject &in_value) {
  73     return nullptr;
  74   }
  75
  76   virtual llvm::Error GetObjectDescription(Stream &str,
  77                                            ValueObject &object) = 0;
  78
  79   virtual llvm::Error
  80   GetObjectDescription(Stream &str, Value &value,
  81                        ExecutionContextScope *exe_scope) = 0;
  82
  83   struct VTableInfo {
  84     Address addr; /// Address of the vtable's virtual function table
  85     Symbol *symbol; /// The vtable symbol from the symbol table
  86   };
  87   /// Get the vtable information for a given value.
  88   ///
  89   /// \param[in] in_value
  90   ///     The value object to try and extract the VTableInfo from.
  91   ///
  92   /// \param[in] check_type
  93   ///     If true, the compiler type of \a in_value will be checked to see if
  94   ///     it is an instance to, or pointer or reference to a class or struct
  95   ///     that has a vtable. If the type doesn't meet the requirements, an
  96   ///     error will be returned explaining why the type isn't suitable.
  97   ///
  98   /// \return
  99   ///     An error if anything goes wrong while trying to extract the vtable
 100   ///     or if \a check_type is true and the type doesn't have a vtable.
 101   virtual llvm::Expected<VTableInfo> GetVTableInfo(ValueObject &in_value,
 102                                                    bool check_type) {
 103     return llvm::createStringError(
 104         std::errc::invalid_argument,
 105         "language doesn't support getting vtable information");
 106   }
 107
 108   // this call should return true if it could set the name and/or the type
 109   virtual bool GetDynamicTypeAndAddress(ValueObject &in_value,
 110                                         lldb::DynamicValueType use_dynamic,
 111                                         TypeAndOrName &class_type_or_name,
 112                                         Address &address,
 113                                         Value::ValueType &value_type) = 0;
 114
 115   // This call should return a CompilerType given a generic type name and an
 116   // ExecutionContextScope in which one can actually fetch any specialization
 117   // information required.
 118   virtual CompilerType GetConcreteType(ExecutionContextScope *exe_scope,
 119                                        ConstString abstract_type_name) {
 120     return CompilerType();
 121   }
 122
 123   // This should be a fast test to determine whether it is likely that this
 124   // value would have a dynamic type.
 125   virtual bool CouldHaveDynamicValue(ValueObject &in_value) = 0;
 126
 127   // The contract for GetDynamicTypeAndAddress() is to return a "bare-bones"
 128   // dynamic type For instance, given a Base* pointer,
 129   // GetDynamicTypeAndAddress() will return the type of Derived, not Derived*.
 130   // The job of this API is to correct this misalignment between the static
 131   // type and the discovered dynamic type
 132   virtual TypeAndOrName FixUpDynamicType(const TypeAndOrName &type_and_or_name,
 133                                          ValueObject &static_value) = 0;
 134
 135   virtual void SetExceptionBreakpoints() {}
 136
 137   virtual void ClearExceptionBreakpoints() {}
 138
 139   virtual bool ExceptionBreakpointsAreSet() { return false; }
 140
 141   virtual bool ExceptionBreakpointsExplainStop(lldb::StopInfoSP stop_reason) {
 142     return false;
 143   }
 144
 145   static lldb::BreakpointSP
 146   CreateExceptionBreakpoint(Target &target, lldb::LanguageType language,
 147                             bool catch_bp, bool throw_bp,
 148                             bool is_internal = false);
 149
 150   static lldb::BreakpointPreconditionSP
 151   GetExceptionPrecondition(lldb::LanguageType language, bool throw_bp);
 152
 153   virtual lldb::ValueObjectSP GetExceptionObjectForThread(
 154       lldb::ThreadSP thread_sp) {
 155     return lldb::ValueObjectSP();
 156   }
 157
 158   virtual lldb::ThreadSP GetBacktraceThreadFromException(
 159       lldb::ValueObjectSP thread_sp) {
 160     return lldb::ThreadSP();
 161   }
 162
 163   virtual DeclVendor *GetDeclVendor() { return nullptr; }
 164
 165   virtual lldb::BreakpointResolverSP
 166   CreateExceptionResolver(const lldb::BreakpointSP &bkpt,
 167                           bool catch_bp, bool throw_bp) = 0;
 168
 169   virtual lldb::SearchFilterSP CreateExceptionSearchFilter() {
 170     return m_process->GetTarget().GetSearchFilterForModule(nullptr);
 171   }
 172
 173   virtual std::optional<uint64_t>
 174   GetTypeBitSize(const CompilerType &compiler_type) {
 175     return {};
 176   }
 177
 178   virtual void SymbolsDidLoad(const ModuleList &module_list) {}
 179
 180   virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread,
 181                                                           bool stop_others) = 0;
 182
 183   /// Identify whether a name is a runtime value that should not be hidden by
 184   /// from the user interface.
 185   virtual bool IsAllowedRuntimeValue(ConstString name) { return false; }
 186
 187   virtual std::optional<CompilerType> GetRuntimeType(CompilerType base_type) {
 188     return std::nullopt;
 189   }
 190
 191   void ModulesDidLoad(const ModuleList &module_list) override {}
 192
 193   // Called by ClangExpressionParser::PrepareForExecution to query for any
 194   // custom LLVM IR passes that need to be run before an expression is
 195   // assembled and run.
 196   virtual bool GetIRPasses(LLVMUserExpression::IRPasses &custom_passes) {
 197     return false;
 198   }
 199
 200   // Given the name of a runtime symbol (e.g. in Objective-C, an ivar offset
 201   // symbol), try to determine from the runtime what the value of that symbol
 202   // would be. Useful when the underlying binary is stripped.
 203   virtual lldb::addr_t LookupRuntimeSymbol(ConstString name) {
 204     return LLDB_INVALID_ADDRESS;
 205   }
 206
 207   virtual bool isA(const void *ClassID) const { return ClassID == &ID; }
 208   static char ID;
 209
 210   /// A language runtime may be able to provide a special UnwindPlan for
 211   /// the frame represented by the register contents \a regctx when that
 212   /// frame is not following the normal ABI conventions.
 213   /// Instead of using the normal UnwindPlan for the function, we will use
 214   /// this special UnwindPlan for this one backtrace.
 215   /// One example of this would be a language that has asynchronous functions,
 216   /// functions that may not be currently-executing, while waiting on other
 217   /// asynchronous calls they made, but are part of a logical backtrace that
 218   /// we want to show the developer because that's how they think of the
 219   /// program flow.
 220   ///
 221   /// \param[in] thread
 222   ///     The thread that the unwind is happening on.
 223   ///
 224   /// \param[in] regctx
 225   ///     The RegisterContext for the frame we need to create an UnwindPlan.
 226   ///     We don't yet have a StackFrame when we're selecting the UnwindPlan.
 227   ///
 228   /// \param[out] behaves_like_zeroth_frame
 229   ///     With normal ABI calls, all stack frames except the zeroth frame need
 230   ///     to have the return-pc value backed up by 1 for symbolication purposes.
 231   ///     For these LanguageRuntime unwind plans, they may not follow normal ABI
 232   ///     calling conventions and the return pc may need to be symbolicated
 233   ///     as-is.
 234   ///
 235   /// \return
 236   ///     Returns an UnwindPlan to find the caller frame if it should be used,
 237   ///     instead of the UnwindPlan that would normally be used for this
 238   ///     function.
 239   static lldb::UnwindPlanSP
 240   GetRuntimeUnwindPlan(lldb_private::Thread &thread,
 241                        lldb_private::RegisterContext *regctx,
 242                        bool &behaves_like_zeroth_frame);
 243
 244   /// Language runtime plugins can use this API to report
 245   /// language-specific runtime information about this compile unit,
 246   /// such as additional language version details or feature flags.
 247   virtual StructuredData::ObjectSP GetLanguageInfo(SymbolContext sc);
 248
 249 protected:
 250   // The static GetRuntimeUnwindPlan method above is only implemented in the
 251   // base class; subclasses may override this protected member if they can
 252   // provide one of these UnwindPlans.
 253   virtual lldb::UnwindPlanSP
 254   GetRuntimeUnwindPlan(lldb::ProcessSP process_sp,
 255                        lldb_private::RegisterContext *regctx,
 256                        bool &behaves_like_zeroth_frame) {
 257     return lldb::UnwindPlanSP();
 258   }
 259
 260   LanguageRuntime(Process *process);
 261 };
 262
 263 } // namespace lldb_private
 264
 265 #endif // LLDB_TARGET_LANGUAGERUNTIME_H