lldb/Interpreter/ScriptInterpreter.h

0001 //===-- ScriptInterpreter.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_INTERPRETER_SCRIPTINTERPRETER_H
0010 #define LLDB_INTERPRETER_SCRIPTINTERPRETER_H
0011
0012 #include "lldb/API/SBAttachInfo.h"
0013 #include "lldb/API/SBBreakpoint.h"
0014 #include "lldb/API/SBData.h"
0015 #include "lldb/API/SBError.h"
0016 #include "lldb/API/SBEvent.h"
0017 #include "lldb/API/SBExecutionContext.h"
0018 #include "lldb/API/SBLaunchInfo.h"
0019 #include "lldb/API/SBMemoryRegionInfo.h"
0020 #include "lldb/API/SBStream.h"
0021 #include "lldb/Breakpoint/BreakpointOptions.h"
0022 #include "lldb/Core/PluginInterface.h"
0023 #include "lldb/Core/SearchFilter.h"
0024 #include "lldb/Core/ThreadedCommunication.h"
0025 #include "lldb/Host/PseudoTerminal.h"
0026 #include "lldb/Host/StreamFile.h"
0027 #include "lldb/Interpreter/Interfaces/OperatingSystemInterface.h"
0028 #include "lldb/Interpreter/Interfaces/ScriptedPlatformInterface.h"
0029 #include "lldb/Interpreter/Interfaces/ScriptedProcessInterface.h"
0030 #include "lldb/Interpreter/Interfaces/ScriptedThreadInterface.h"
0031 #include "lldb/Interpreter/ScriptObject.h"
0032 #include "lldb/Utility/Broadcaster.h"
0033 #include "lldb/Utility/Status.h"
0034 #include "lldb/Utility/StructuredData.h"
0035 #include "lldb/lldb-private.h"
0036 #include <optional>
0037
0038 namespace lldb_private {
0039
0040 class ScriptInterpreterLocker {
0041 public:
0042   ScriptInterpreterLocker() = default;
0043
0044   virtual ~ScriptInterpreterLocker() = default;
0045
0046 private:
0047   ScriptInterpreterLocker(const ScriptInterpreterLocker &) = delete;
0048   const ScriptInterpreterLocker &
0049   operator=(const ScriptInterpreterLocker &) = delete;
0050 };
0051
0052 class ExecuteScriptOptions {
0053 public:
0054   ExecuteScriptOptions() = default;
0055
0056   bool GetEnableIO() const { return m_enable_io; }
0057
0058   bool GetSetLLDBGlobals() const { return m_set_lldb_globals; }
0059
0060   // If this is true then any exceptions raised by the script will be
0061   // cleared with PyErr_Clear().   If false then they will be left for
0062   // the caller to clean up
0063   bool GetMaskoutErrors() const { return m_maskout_errors; }
0064
0065   ExecuteScriptOptions &SetEnableIO(bool enable) {
0066     m_enable_io = enable;
0067     return *this;
0068   }
0069
0070   ExecuteScriptOptions &SetSetLLDBGlobals(bool set) {
0071     m_set_lldb_globals = set;
0072     return *this;
0073   }
0074
0075   ExecuteScriptOptions &SetMaskoutErrors(bool maskout) {
0076     m_maskout_errors = maskout;
0077     return *this;
0078   }
0079
0080 private:
0081   bool m_enable_io = true;
0082   bool m_set_lldb_globals = true;
0083   bool m_maskout_errors = true;
0084 };
0085
0086 class LoadScriptOptions {
0087 public:
0088   LoadScriptOptions() = default;
0089
0090   bool GetInitSession() const { return m_init_session; }
0091   bool GetSilent() const { return m_silent; }
0092
0093   LoadScriptOptions &SetInitSession(bool b) {
0094     m_init_session = b;
0095     return *this;
0096   }
0097
0098   LoadScriptOptions &SetSilent(bool b) {
0099     m_silent = b;
0100     return *this;
0101   }
0102
0103 private:
0104   bool m_init_session = false;
0105   bool m_silent = false;
0106 };
0107
0108 class ScriptInterpreterIORedirect {
0109 public:
0110   /// Create an IO redirect. If IO is enabled, this will redirects the output
0111   /// to the command return object if set or to the debugger otherwise. If IO
0112   /// is disabled, it will redirect all IO to /dev/null.
0113   static llvm::Expected<std::unique_ptr<ScriptInterpreterIORedirect>>
0114   Create(bool enable_io, Debugger &debugger, CommandReturnObject *result);
0115
0116   ~ScriptInterpreterIORedirect();
0117
0118   lldb::FileSP GetInputFile() const { return m_input_file_sp; }
0119   lldb::FileSP GetOutputFile() const { return m_output_file_sp->GetFileSP(); }
0120   lldb::FileSP GetErrorFile() const { return m_error_file_sp->GetFileSP(); }
0121
0122   /// Flush our output and error file handles.
0123   void Flush();
0124
0125 private:
0126   ScriptInterpreterIORedirect(std::unique_ptr<File> input,
0127                               std::unique_ptr<File> output);
0128   ScriptInterpreterIORedirect(Debugger &debugger, CommandReturnObject *result);
0129
0130   lldb::FileSP m_input_file_sp;
0131   lldb::StreamFileSP m_output_file_sp;
0132   lldb::StreamFileSP m_error_file_sp;
0133   ThreadedCommunication m_communication;
0134   bool m_disconnect;
0135 };
0136
0137 class ScriptInterpreter : public PluginInterface {
0138 public:
0139   enum ScriptReturnType {
0140     eScriptReturnTypeCharPtr,
0141     eScriptReturnTypeBool,
0142     eScriptReturnTypeShortInt,
0143     eScriptReturnTypeShortIntUnsigned,
0144     eScriptReturnTypeInt,
0145     eScriptReturnTypeIntUnsigned,
0146     eScriptReturnTypeLongInt,
0147     eScriptReturnTypeLongIntUnsigned,
0148     eScriptReturnTypeLongLong,
0149     eScriptReturnTypeLongLongUnsigned,
0150     eScriptReturnTypeFloat,
0151     eScriptReturnTypeDouble,
0152     eScriptReturnTypeChar,
0153     eScriptReturnTypeCharStrOrNone,
0154     eScriptReturnTypeOpaqueObject
0155   };
0156
0157   ScriptInterpreter(Debugger &debugger, lldb::ScriptLanguage script_lang);
0158
0159   virtual StructuredData::DictionarySP GetInterpreterInfo();
0160
0161   ~ScriptInterpreter() override = default;
0162
0163   virtual bool Interrupt() { return false; }
0164
0165   virtual bool ExecuteOneLine(
0166       llvm::StringRef command, CommandReturnObject *result,
0167       const ExecuteScriptOptions &options = ExecuteScriptOptions()) = 0;
0168
0169   virtual void ExecuteInterpreterLoop() = 0;
0170
0171   virtual bool ExecuteOneLineWithReturn(
0172       llvm::StringRef in_string, ScriptReturnType return_type, void *ret_value,
0173       const ExecuteScriptOptions &options = ExecuteScriptOptions()) {
0174     return true;
0175   }
0176
0177   virtual Status ExecuteMultipleLines(
0178       const char *in_string,
0179       const ExecuteScriptOptions &options = ExecuteScriptOptions()) {
0180     return Status::FromErrorString("not implemented");
0181   }
0182
0183   virtual Status
0184   ExportFunctionDefinitionToInterpreter(StringList &function_def) {
0185     return Status::FromErrorString("not implemented");
0186   }
0187
0188   virtual Status GenerateBreakpointCommandCallbackData(StringList &input,
0189                                                        std::string &output,
0190                                                        bool has_extra_args,
0191                                                        bool is_callback) {
0192     return Status::FromErrorString("not implemented");
0193   }
0194
0195   virtual bool GenerateWatchpointCommandCallbackData(StringList &input,
0196                                                      std::string &output,
0197                                                      bool is_callback) {
0198     return false;
0199   }
0200
0201   virtual bool GenerateTypeScriptFunction(const char *oneliner,
0202                                           std::string &output,
0203                                           const void *name_token = nullptr) {
0204     return false;
0205   }
0206
0207   virtual bool GenerateTypeScriptFunction(StringList &input,
0208                                           std::string &output,
0209                                           const void *name_token = nullptr) {
0210     return false;
0211   }
0212
0213   virtual bool GenerateScriptAliasFunction(StringList &input,
0214                                            std::string &output) {
0215     return false;
0216   }
0217
0218   virtual bool GenerateTypeSynthClass(StringList &input, std::string &output,
0219                                       const void *name_token = nullptr) {
0220     return false;
0221   }
0222
0223   virtual bool GenerateTypeSynthClass(const char *oneliner, std::string &output,
0224                                       const void *name_token = nullptr) {
0225     return false;
0226   }
0227
0228   virtual StructuredData::ObjectSP
0229   CreateSyntheticScriptedProvider(const char *class_name,
0230                                   lldb::ValueObjectSP valobj) {
0231     return StructuredData::ObjectSP();
0232   }
0233
0234   virtual StructuredData::GenericSP
0235   CreateScriptCommandObject(const char *class_name) {
0236     return StructuredData::GenericSP();
0237   }
0238
0239   virtual StructuredData::GenericSP
0240   CreateFrameRecognizer(const char *class_name) {
0241     return StructuredData::GenericSP();
0242   }
0243
0244   virtual lldb::ValueObjectListSP GetRecognizedArguments(
0245       const StructuredData::ObjectSP &implementor,
0246       lldb::StackFrameSP frame_sp) {
0247     return lldb::ValueObjectListSP();
0248   }
0249
0250   virtual bool ShouldHide(const StructuredData::ObjectSP &implementor,
0251                           lldb::StackFrameSP frame_sp) {
0252     return false;
0253   }
0254
0255   virtual StructuredData::GenericSP
0256   CreateScriptedBreakpointResolver(const char *class_name,
0257                                    const StructuredDataImpl &args_data,
0258                                    lldb::BreakpointSP &bkpt_sp) {
0259     return StructuredData::GenericSP();
0260   }
0261
0262   virtual bool
0263   ScriptedBreakpointResolverSearchCallback(StructuredData::GenericSP implementor_sp,
0264                                            SymbolContext *sym_ctx)
0265   {
0266     return false;
0267   }
0268
0269   virtual lldb::SearchDepth
0270   ScriptedBreakpointResolverSearchDepth(StructuredData::GenericSP implementor_sp)
0271   {
0272     return lldb::eSearchDepthModule;
0273   }
0274
0275   virtual StructuredData::ObjectSP
0276   LoadPluginModule(const FileSpec &file_spec, lldb_private::Status &error) {
0277     return StructuredData::ObjectSP();
0278   }
0279
0280   virtual StructuredData::DictionarySP
0281   GetDynamicSettings(StructuredData::ObjectSP plugin_module_sp, Target *target,
0282                      const char *setting_name, lldb_private::Status &error) {
0283     return StructuredData::DictionarySP();
0284   }
0285
0286   virtual Status GenerateFunction(const char *signature,
0287                                   const StringList &input,
0288                                   bool is_callback) {
0289     return Status::FromErrorString("not implemented");
0290   }
0291
0292   virtual void CollectDataForBreakpointCommandCallback(
0293       std::vector<std::reference_wrapper<BreakpointOptions>> &options,
0294       CommandReturnObject &result);
0295
0296   virtual void
0297   CollectDataForWatchpointCommandCallback(WatchpointOptions *wp_options,
0298                                           CommandReturnObject &result);
0299
0300   /// Set the specified text as the callback for the breakpoint.
0301   Status SetBreakpointCommandCallback(
0302       std::vector<std::reference_wrapper<BreakpointOptions>> &bp_options_vec,
0303       const char *callback_text);
0304
0305   virtual Status SetBreakpointCommandCallback(BreakpointOptions &bp_options,
0306                                               const char *callback_text,
0307                                               bool is_callback) {
0308     return Status::FromErrorString("not implemented");
0309   }
0310
0311   /// This one is for deserialization:
0312   virtual Status SetBreakpointCommandCallback(
0313       BreakpointOptions &bp_options,
0314       std::unique_ptr<BreakpointOptions::CommandData> &data_up) {
0315     return Status::FromErrorString("not implemented");
0316   }
0317
0318   Status SetBreakpointCommandCallbackFunction(
0319       std::vector<std::reference_wrapper<BreakpointOptions>> &bp_options_vec,
0320       const char *function_name, StructuredData::ObjectSP extra_args_sp);
0321
0322   /// Set a script function as the callback for the breakpoint.
0323   virtual Status
0324   SetBreakpointCommandCallbackFunction(BreakpointOptions &bp_options,
0325                                        const char *function_name,
0326                                        StructuredData::ObjectSP extra_args_sp) {
0327     return Status::FromErrorString("not implemented");
0328   }
0329
0330   /// Set a one-liner as the callback for the watchpoint.
0331   virtual void SetWatchpointCommandCallback(WatchpointOptions *wp_options,
0332                                             const char *user_input,
0333                                             bool is_callback) {}
0334
0335   virtual bool GetScriptedSummary(const char *function_name,
0336                                   lldb::ValueObjectSP valobj,
0337                                   StructuredData::ObjectSP &callee_wrapper_sp,
0338                                   const TypeSummaryOptions &options,
0339                                   std::string &retval) {
0340     return false;
0341   }
0342
0343   // Calls the specified formatter matching Python function and returns its
0344   // result (true if it's a match, false if we should keep looking for a
0345   // matching formatter).
0346   virtual bool FormatterCallbackFunction(const char *function_name,
0347                                          lldb::TypeImplSP type_impl_sp) {
0348     return true;
0349   }
0350
0351   virtual void Clear() {
0352     // Clean up any ref counts to SBObjects that might be in global variables
0353   }
0354
0355   virtual size_t
0356   CalculateNumChildren(const StructuredData::ObjectSP &implementor,
0357                        uint32_t max) {
0358     return 0;
0359   }
0360
0361   virtual lldb::ValueObjectSP
0362   GetChildAtIndex(const StructuredData::ObjectSP &implementor, uint32_t idx) {
0363     return lldb::ValueObjectSP();
0364   }
0365
0366   virtual int
0367   GetIndexOfChildWithName(const StructuredData::ObjectSP &implementor,
0368                           const char *child_name) {
0369     return UINT32_MAX;
0370   }
0371
0372   virtual bool
0373   UpdateSynthProviderInstance(const StructuredData::ObjectSP &implementor) {
0374     return false;
0375   }
0376
0377   virtual bool MightHaveChildrenSynthProviderInstance(
0378       const StructuredData::ObjectSP &implementor) {
0379     return true;
0380   }
0381
0382   virtual lldb::ValueObjectSP
0383   GetSyntheticValue(const StructuredData::ObjectSP &implementor) {
0384     return nullptr;
0385   }
0386
0387   virtual ConstString
0388   GetSyntheticTypeName(const StructuredData::ObjectSP &implementor) {
0389     return ConstString();
0390   }
0391
0392   virtual bool
0393   RunScriptBasedCommand(const char *impl_function, llvm::StringRef args,
0394                         ScriptedCommandSynchronicity synchronicity,
0395                         lldb_private::CommandReturnObject &cmd_retobj,
0396                         Status &error,
0397                         const lldb_private::ExecutionContext &exe_ctx) {
0398     return false;
0399   }
0400
0401   virtual bool RunScriptBasedCommand(
0402       StructuredData::GenericSP impl_obj_sp, llvm::StringRef args,
0403       ScriptedCommandSynchronicity synchronicity,
0404       lldb_private::CommandReturnObject &cmd_retobj, Status &error,
0405       const lldb_private::ExecutionContext &exe_ctx) {
0406     return false;
0407   }
0408
0409   virtual bool RunScriptBasedParsedCommand(
0410       StructuredData::GenericSP impl_obj_sp, Args& args,
0411       ScriptedCommandSynchronicity synchronicity,
0412       lldb_private::CommandReturnObject &cmd_retobj, Status &error,
0413       const lldb_private::ExecutionContext &exe_ctx) {
0414     return false;
0415   }
0416
0417   virtual std::optional<std::string>
0418   GetRepeatCommandForScriptedCommand(StructuredData::GenericSP impl_obj_sp,
0419                                      Args &args) {
0420     return std::nullopt;
0421   }
0422
0423   virtual StructuredData::DictionarySP
0424   HandleArgumentCompletionForScriptedCommand(
0425       StructuredData::GenericSP impl_obj_sp, std::vector<llvm::StringRef> &args,
0426       size_t args_pos, size_t char_in_arg) {
0427     return {};
0428   }
0429
0430   virtual StructuredData::DictionarySP
0431   HandleOptionArgumentCompletionForScriptedCommand(
0432       StructuredData::GenericSP impl_obj_sp, llvm::StringRef &long_name,
0433       size_t char_in_arg) {
0434     return {};
0435   }
0436
0437   virtual bool RunScriptFormatKeyword(const char *impl_function,
0438                                       Process *process, std::string &output,
0439                                       Status &error) {
0440     error = Status::FromErrorString("unimplemented");
0441     return false;
0442   }
0443
0444   virtual bool RunScriptFormatKeyword(const char *impl_function, Thread *thread,
0445                                       std::string &output, Status &error) {
0446     error = Status::FromErrorString("unimplemented");
0447     return false;
0448   }
0449
0450   virtual bool RunScriptFormatKeyword(const char *impl_function, Target *target,
0451                                       std::string &output, Status &error) {
0452     error = Status::FromErrorString("unimplemented");
0453     return false;
0454   }
0455
0456   virtual bool RunScriptFormatKeyword(const char *impl_function,
0457                                       StackFrame *frame, std::string &output,
0458                                       Status &error) {
0459     error = Status::FromErrorString("unimplemented");
0460     return false;
0461   }
0462
0463   virtual bool RunScriptFormatKeyword(const char *impl_function,
0464                                       ValueObject *value, std::string &output,
0465                                       Status &error) {
0466     error = Status::FromErrorString("unimplemented");
0467     return false;
0468   }
0469
0470   virtual bool GetDocumentationForItem(const char *item, std::string &dest) {
0471     dest.clear();
0472     return false;
0473   }
0474
0475   virtual bool
0476   GetShortHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
0477                                std::string &dest) {
0478     dest.clear();
0479     return false;
0480   }
0481
0482   virtual StructuredData::ObjectSP
0483   GetOptionsForCommandObject(StructuredData::GenericSP cmd_obj_sp) {
0484     return {};
0485   }
0486
0487   virtual StructuredData::ObjectSP
0488   GetArgumentsForCommandObject(StructuredData::GenericSP cmd_obj_sp) {
0489     return {};
0490   }
0491
0492   virtual bool SetOptionValueForCommandObject(
0493       StructuredData::GenericSP cmd_obj_sp, ExecutionContext *exe_ctx,
0494       llvm::StringRef long_option, llvm::StringRef value) {
0495     return false;
0496   }
0497
0498   virtual void OptionParsingStartedForCommandObject(
0499       StructuredData::GenericSP cmd_obj_sp) {
0500     return;
0501   }
0502
0503   virtual uint32_t
0504   GetFlagsForCommandObject(StructuredData::GenericSP cmd_obj_sp) {
0505     return 0;
0506   }
0507
0508   virtual bool GetLongHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
0509                                            std::string &dest) {
0510     dest.clear();
0511     return false;
0512   }
0513
0514   virtual bool CheckObjectExists(const char *name) { return false; }
0515
0516   virtual bool
0517   LoadScriptingModule(const char *filename, const LoadScriptOptions &options,
0518                       lldb_private::Status &error,
0519                       StructuredData::ObjectSP *module_sp = nullptr,
0520                       FileSpec extra_search_dir = {});
0521
0522   virtual bool IsReservedWord(const char *word) { return false; }
0523
0524   virtual std::unique_ptr<ScriptInterpreterLocker> AcquireInterpreterLock();
0525
0526   const char *GetScriptInterpreterPtyName();
0527
0528   virtual llvm::Expected<unsigned>
0529   GetMaxPositionalArgumentsForCallable(const llvm::StringRef &callable_name) {
0530     return llvm::createStringError(
0531     llvm::inconvertibleErrorCode(), "Unimplemented function");
0532   }
0533
0534   static std::string LanguageToString(lldb::ScriptLanguage language);
0535
0536   static lldb::ScriptLanguage StringToLanguage(const llvm::StringRef &string);
0537
0538   lldb::ScriptLanguage GetLanguage() { return m_script_lang; }
0539
0540   virtual lldb::ScriptedProcessInterfaceUP CreateScriptedProcessInterface() {
0541     return {};
0542   }
0543
0544   virtual lldb::ScriptedThreadInterfaceSP CreateScriptedThreadInterface() {
0545     return {};
0546   }
0547
0548   virtual lldb::ScriptedThreadPlanInterfaceSP
0549   CreateScriptedThreadPlanInterface() {
0550     return {};
0551   }
0552
0553   virtual lldb::OperatingSystemInterfaceSP CreateOperatingSystemInterface() {
0554     return {};
0555   }
0556
0557   virtual lldb::ScriptedPlatformInterfaceUP GetScriptedPlatformInterface() {
0558     return {};
0559   }
0560
0561   virtual lldb::ScriptedStopHookInterfaceSP CreateScriptedStopHookInterface() {
0562     return {};
0563   }
0564
0565   virtual StructuredData::ObjectSP
0566   CreateStructuredDataFromScriptObject(ScriptObject obj) {
0567     return {};
0568   }
0569
0570   lldb::DataExtractorSP
0571   GetDataExtractorFromSBData(const lldb::SBData &data) const;
0572
0573   Status GetStatusFromSBError(const lldb::SBError &error) const;
0574
0575   Event *GetOpaqueTypeFromSBEvent(const lldb::SBEvent &event) const;
0576
0577   lldb::StreamSP GetOpaqueTypeFromSBStream(const lldb::SBStream &stream) const;
0578
0579   lldb::BreakpointSP
0580   GetOpaqueTypeFromSBBreakpoint(const lldb::SBBreakpoint &breakpoint) const;
0581
0582   lldb::ProcessAttachInfoSP
0583   GetOpaqueTypeFromSBAttachInfo(const lldb::SBAttachInfo &attach_info) const;
0584
0585   lldb::ProcessLaunchInfoSP
0586   GetOpaqueTypeFromSBLaunchInfo(const lldb::SBLaunchInfo &launch_info) const;
0587
0588   std::optional<MemoryRegionInfo> GetOpaqueTypeFromSBMemoryRegionInfo(
0589       const lldb::SBMemoryRegionInfo &mem_region) const;
0590
0591   lldb::ExecutionContextRefSP GetOpaqueTypeFromSBExecutionContext(
0592       const lldb::SBExecutionContext &exe_ctx) const;
0593
0594 protected:
0595   Debugger &m_debugger;
0596   lldb::ScriptLanguage m_script_lang;
0597 };
0598
0599 } // namespace lldb_private
0600
0601 #endif // LLDB_INTERPRETER_SCRIPTINTERPRETER_H