lldb/Target/LanguageRuntime.h

0001 //===-- LanguageRuntime.h ---------------------------------------------------*-
0002 // C++ -*-===//
0003 //
0004 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0005 // See https://llvm.org/LICENSE.txt for license information.
0006 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0007 //
0008 //===----------------------------------------------------------------------===//
0009
0010 #ifndef LLDB_TARGET_LANGUAGERUNTIME_H
0011 #define LLDB_TARGET_LANGUAGERUNTIME_H
0012
0013 #include "lldb/Breakpoint/BreakpointResolver.h"
0014 #include "lldb/Breakpoint/BreakpointResolverName.h"
0015 #include "lldb/Core/PluginInterface.h"
0016 #include "lldb/Core/Value.h"
0017 #include "lldb/Expression/LLVMUserExpression.h"
0018 #include "lldb/Symbol/DeclVendor.h"
0019 #include "lldb/Target/ExecutionContextScope.h"
0020 #include "lldb/Target/Runtime.h"
0021 #include "lldb/ValueObject/ValueObject.h"
0022 #include "lldb/lldb-private.h"
0023 #include "lldb/lldb-public.h"
0024 #include <optional>
0025
0026 namespace lldb_private {
0027
0028 class ExceptionSearchFilter : public SearchFilter {
0029 public:
0030   ExceptionSearchFilter(const lldb::TargetSP &target_sp,
0031                         lldb::LanguageType language,
0032                         bool update_module_list = true);
0033
0034   ~ExceptionSearchFilter() override = default;
0035
0036   bool ModulePasses(const lldb::ModuleSP &module_sp) override;
0037
0038   bool ModulePasses(const FileSpec &spec) override;
0039
0040   void Search(Searcher &searcher) override;
0041
0042   void GetDescription(Stream *s) override;
0043
0044   static SearchFilter *
0045   CreateFromStructuredData(Target &target,
0046                            const StructuredData::Dictionary &data_dict,
0047                            Status &error);
0048
0049   StructuredData::ObjectSP SerializeToStructuredData() override;
0050
0051 protected:
0052   lldb::LanguageType m_language;
0053   LanguageRuntime *m_language_runtime;
0054   lldb::SearchFilterSP m_filter_sp;
0055
0056   lldb::SearchFilterSP DoCreateCopy() override;
0057
0058   void UpdateModuleListIfNeeded();
0059 };
0060
0061 class LanguageRuntime : public Runtime, public PluginInterface {
0062 public:
0063   static LanguageRuntime *FindPlugin(Process *process,
0064                                      lldb::LanguageType language);
0065
0066   static void InitializeCommands(CommandObject *parent);
0067
0068   virtual lldb::LanguageType GetLanguageType() const = 0;
0069
0070   /// Return the preferred language runtime instance, which in most cases will
0071   /// be the current instance.
0072   virtual LanguageRuntime *GetPreferredLanguageRuntime(ValueObject &in_value) {
0073     return nullptr;
0074   }
0075
0076   virtual llvm::Error GetObjectDescription(Stream &str,
0077                                            ValueObject &object) = 0;
0078
0079   virtual llvm::Error
0080   GetObjectDescription(Stream &str, Value &value,
0081                        ExecutionContextScope *exe_scope) = 0;
0082
0083   struct VTableInfo {
0084     Address addr; /// Address of the vtable's virtual function table
0085     Symbol *symbol; /// The vtable symbol from the symbol table
0086   };
0087   /// Get the vtable information for a given value.
0088   ///
0089   /// \param[in] in_value
0090   ///     The value object to try and extract the VTableInfo from.
0091   ///
0092   /// \param[in] check_type
0093   ///     If true, the compiler type of \a in_value will be checked to see if
0094   ///     it is an instance to, or pointer or reference to a class or struct
0095   ///     that has a vtable. If the type doesn't meet the requirements, an
0096   ///     error will be returned explaining why the type isn't suitable.
0097   ///
0098   /// \return
0099   ///     An error if anything goes wrong while trying to extract the vtable
0100   ///     or if \a check_type is true and the type doesn't have a vtable.
0101   virtual llvm::Expected<VTableInfo> GetVTableInfo(ValueObject &in_value,
0102                                                    bool check_type) {
0103     return llvm::createStringError(
0104         std::errc::invalid_argument,
0105         "language doesn't support getting vtable information");
0106   }
0107
0108   // this call should return true if it could set the name and/or the type
0109   virtual bool GetDynamicTypeAndAddress(ValueObject &in_value,
0110                                         lldb::DynamicValueType use_dynamic,
0111                                         TypeAndOrName &class_type_or_name,
0112                                         Address &address,
0113                                         Value::ValueType &value_type) = 0;
0114
0115   // This call should return a CompilerType given a generic type name and an
0116   // ExecutionContextScope in which one can actually fetch any specialization
0117   // information required.
0118   virtual CompilerType GetConcreteType(ExecutionContextScope *exe_scope,
0119                                        ConstString abstract_type_name) {
0120     return CompilerType();
0121   }
0122
0123   // This should be a fast test to determine whether it is likely that this
0124   // value would have a dynamic type.
0125   virtual bool CouldHaveDynamicValue(ValueObject &in_value) = 0;
0126
0127   // The contract for GetDynamicTypeAndAddress() is to return a "bare-bones"
0128   // dynamic type For instance, given a Base* pointer,
0129   // GetDynamicTypeAndAddress() will return the type of Derived, not Derived*.
0130   // The job of this API is to correct this misalignment between the static
0131   // type and the discovered dynamic type
0132   virtual TypeAndOrName FixUpDynamicType(const TypeAndOrName &type_and_or_name,
0133                                          ValueObject &static_value) = 0;
0134
0135   virtual void SetExceptionBreakpoints() {}
0136
0137   virtual void ClearExceptionBreakpoints() {}
0138
0139   virtual bool ExceptionBreakpointsAreSet() { return false; }
0140
0141   virtual bool ExceptionBreakpointsExplainStop(lldb::StopInfoSP stop_reason) {
0142     return false;
0143   }
0144
0145   static lldb::BreakpointSP
0146   CreateExceptionBreakpoint(Target &target, lldb::LanguageType language,
0147                             bool catch_bp, bool throw_bp,
0148                             bool is_internal = false);
0149
0150   static lldb::BreakpointPreconditionSP
0151   GetExceptionPrecondition(lldb::LanguageType language, bool throw_bp);
0152
0153   virtual lldb::ValueObjectSP GetExceptionObjectForThread(
0154       lldb::ThreadSP thread_sp) {
0155     return lldb::ValueObjectSP();
0156   }
0157
0158   virtual lldb::ThreadSP GetBacktraceThreadFromException(
0159       lldb::ValueObjectSP thread_sp) {
0160     return lldb::ThreadSP();
0161   }
0162
0163   virtual DeclVendor *GetDeclVendor() { return nullptr; }
0164
0165   virtual lldb::BreakpointResolverSP
0166   CreateExceptionResolver(const lldb::BreakpointSP &bkpt,
0167                           bool catch_bp, bool throw_bp) = 0;
0168
0169   virtual lldb::SearchFilterSP CreateExceptionSearchFilter() {
0170     return m_process->GetTarget().GetSearchFilterForModule(nullptr);
0171   }
0172
0173   virtual std::optional<uint64_t>
0174   GetTypeBitSize(const CompilerType &compiler_type) {
0175     return {};
0176   }
0177
0178   virtual void SymbolsDidLoad(const ModuleList &module_list) {}
0179
0180   virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread,
0181                                                           bool stop_others) = 0;
0182
0183   /// Identify whether a name is a runtime value that should not be hidden by
0184   /// from the user interface.
0185   virtual bool IsAllowedRuntimeValue(ConstString name) { return false; }
0186
0187   virtual std::optional<CompilerType> GetRuntimeType(CompilerType base_type) {
0188     return std::nullopt;
0189   }
0190
0191   void ModulesDidLoad(const ModuleList &module_list) override {}
0192
0193   // Called by ClangExpressionParser::PrepareForExecution to query for any
0194   // custom LLVM IR passes that need to be run before an expression is
0195   // assembled and run.
0196   virtual bool GetIRPasses(LLVMUserExpression::IRPasses &custom_passes) {
0197     return false;
0198   }
0199
0200   // Given the name of a runtime symbol (e.g. in Objective-C, an ivar offset
0201   // symbol), try to determine from the runtime what the value of that symbol
0202   // would be. Useful when the underlying binary is stripped.
0203   virtual lldb::addr_t LookupRuntimeSymbol(ConstString name) {
0204     return LLDB_INVALID_ADDRESS;
0205   }
0206
0207   virtual bool isA(const void *ClassID) const { return ClassID == &ID; }
0208   static char ID;
0209
0210   /// A language runtime may be able to provide a special UnwindPlan for
0211   /// the frame represented by the register contents \a regctx when that
0212   /// frame is not following the normal ABI conventions.
0213   /// Instead of using the normal UnwindPlan for the function, we will use
0214   /// this special UnwindPlan for this one backtrace.
0215   /// One example of this would be a language that has asynchronous functions,
0216   /// functions that may not be currently-executing, while waiting on other
0217   /// asynchronous calls they made, but are part of a logical backtrace that
0218   /// we want to show the developer because that's how they think of the
0219   /// program flow.
0220   ///
0221   /// \param[in] thread
0222   ///     The thread that the unwind is happening on.
0223   ///
0224   /// \param[in] regctx
0225   ///     The RegisterContext for the frame we need to create an UnwindPlan.
0226   ///     We don't yet have a StackFrame when we're selecting the UnwindPlan.
0227   ///
0228   /// \param[out] behaves_like_zeroth_frame
0229   ///     With normal ABI calls, all stack frames except the zeroth frame need
0230   ///     to have the return-pc value backed up by 1 for symbolication purposes.
0231   ///     For these LanguageRuntime unwind plans, they may not follow normal ABI
0232   ///     calling conventions and the return pc may need to be symbolicated
0233   ///     as-is.
0234   ///
0235   /// \return
0236   ///     Returns an UnwindPlan to find the caller frame if it should be used,
0237   ///     instead of the UnwindPlan that would normally be used for this
0238   ///     function.
0239   static lldb::UnwindPlanSP
0240   GetRuntimeUnwindPlan(lldb_private::Thread &thread,
0241                        lldb_private::RegisterContext *regctx,
0242                        bool &behaves_like_zeroth_frame);
0243
0244   /// Language runtime plugins can use this API to report
0245   /// language-specific runtime information about this compile unit,
0246   /// such as additional language version details or feature flags.
0247   virtual StructuredData::ObjectSP GetLanguageSpecificData(SymbolContext sc);
0248
0249 protected:
0250   // The static GetRuntimeUnwindPlan method above is only implemented in the
0251   // base class; subclasses may override this protected member if they can
0252   // provide one of these UnwindPlans.
0253   virtual lldb::UnwindPlanSP
0254   GetRuntimeUnwindPlan(lldb::ProcessSP process_sp,
0255                        lldb_private::RegisterContext *regctx,
0256                        bool &behaves_like_zeroth_frame) {
0257     return lldb::UnwindPlanSP();
0258   }
0259
0260   LanguageRuntime(Process *process);
0261 };
0262
0263 } // namespace lldb_private
0264
0265 #endif // LLDB_TARGET_LANGUAGERUNTIME_H