contrib/llvm/tools/lldb/include/lldb/Interpreter/ScriptInterpreter.h

   1 //===-- ScriptInterpreter.h -------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef liblldb_ScriptInterpreter_h_
  10 #define liblldb_ScriptInterpreter_h_
  11
  12 #include "lldb/lldb-private.h"
  13
  14 #include "lldb/Breakpoint/BreakpointOptions.h"
  15 #include "lldb/Core/PluginInterface.h"
  16 #include "lldb/Core/SearchFilter.h"
  17 #include "lldb/Utility/Broadcaster.h"
  18 #include "lldb/Utility/Status.h"
  19 #include "lldb/Utility/StructuredData.h"
  20
  21 #include "lldb/Host/PseudoTerminal.h"
  22
  23 namespace lldb_private {
  24
  25 class ScriptInterpreterLocker {
  26 public:
  27   ScriptInterpreterLocker() = default;
  28
  29   virtual ~ScriptInterpreterLocker() = default;
  30
  31 private:
  32   DISALLOW_COPY_AND_ASSIGN(ScriptInterpreterLocker);
  33 };
  34
  35 class ScriptInterpreter : public PluginInterface {
  36 public:
  37   enum ScriptReturnType {
  38     eScriptReturnTypeCharPtr,
  39     eScriptReturnTypeBool,
  40     eScriptReturnTypeShortInt,
  41     eScriptReturnTypeShortIntUnsigned,
  42     eScriptReturnTypeInt,
  43     eScriptReturnTypeIntUnsigned,
  44     eScriptReturnTypeLongInt,
  45     eScriptReturnTypeLongIntUnsigned,
  46     eScriptReturnTypeLongLong,
  47     eScriptReturnTypeLongLongUnsigned,
  48     eScriptReturnTypeFloat,
  49     eScriptReturnTypeDouble,
  50     eScriptReturnTypeChar,
  51     eScriptReturnTypeCharStrOrNone,
  52     eScriptReturnTypeOpaqueObject
  53   };
  54
  55   ScriptInterpreter(Debugger &debugger, lldb::ScriptLanguage script_lang);
  56
  57   ~ScriptInterpreter() override;
  58
  59   struct ExecuteScriptOptions {
  60   public:
  61     ExecuteScriptOptions()
  62         : m_enable_io(true), m_set_lldb_globals(true), m_maskout_errors(true) {}
  63
  64     bool GetEnableIO() const { return m_enable_io; }
  65
  66     bool GetSetLLDBGlobals() const { return m_set_lldb_globals; }
  67
  68     bool GetMaskoutErrors() const { return m_maskout_errors; }
  69
  70     ExecuteScriptOptions &SetEnableIO(bool enable) {
  71       m_enable_io = enable;
  72       return *this;
  73     }
  74
  75     ExecuteScriptOptions &SetSetLLDBGlobals(bool set) {
  76       m_set_lldb_globals = set;
  77       return *this;
  78     }
  79
  80     ExecuteScriptOptions &SetMaskoutErrors(bool maskout) {
  81       m_maskout_errors = maskout;
  82       return *this;
  83     }
  84
  85   private:
  86     bool m_enable_io;
  87     bool m_set_lldb_globals;
  88     bool m_maskout_errors;
  89   };
  90
  91   virtual bool Interrupt() { return false; }
  92
  93   virtual bool ExecuteOneLine(
  94       llvm::StringRef command, CommandReturnObject *result,
  95       const ExecuteScriptOptions &options = ExecuteScriptOptions()) = 0;
  96
  97   virtual void ExecuteInterpreterLoop() = 0;
  98
  99   virtual bool ExecuteOneLineWithReturn(
 100       llvm::StringRef in_string, ScriptReturnType return_type, void *ret_value,
 101       const ExecuteScriptOptions &options = ExecuteScriptOptions()) {
 102     return true;
 103   }
 104
 105   virtual Status ExecuteMultipleLines(
 106       const char *in_string,
 107       const ExecuteScriptOptions &options = ExecuteScriptOptions()) {
 108     Status error;
 109     error.SetErrorString("not implemented");
 110     return error;
 111   }
 112
 113   virtual Status
 114   ExportFunctionDefinitionToInterpreter(StringList &function_def) {
 115     Status error;
 116     error.SetErrorString("not implemented");
 117     return error;
 118   }
 119
 120   virtual Status GenerateBreakpointCommandCallbackData(StringList &input,
 121                                                        std::string &output) {
 122     Status error;
 123     error.SetErrorString("not implemented");
 124     return error;
 125   }
 126
 127   virtual bool GenerateWatchpointCommandCallbackData(StringList &input,
 128                                                      std::string &output) {
 129     return false;
 130   }
 131
 132   virtual bool GenerateTypeScriptFunction(const char *oneliner,
 133                                           std::string &output,
 134                                           const void *name_token = nullptr) {
 135     return false;
 136   }
 137
 138   virtual bool GenerateTypeScriptFunction(StringList &input,
 139                                           std::string &output,
 140                                           const void *name_token = nullptr) {
 141     return false;
 142   }
 143
 144   virtual bool GenerateScriptAliasFunction(StringList &input,
 145                                            std::string &output) {
 146     return false;
 147   }
 148
 149   virtual bool GenerateTypeSynthClass(StringList &input, std::string &output,
 150                                       const void *name_token = nullptr) {
 151     return false;
 152   }
 153
 154   virtual bool GenerateTypeSynthClass(const char *oneliner, std::string &output,
 155                                       const void *name_token = nullptr) {
 156     return false;
 157   }
 158
 159   virtual StructuredData::ObjectSP
 160   CreateSyntheticScriptedProvider(const char *class_name,
 161                                   lldb::ValueObjectSP valobj) {
 162     return StructuredData::ObjectSP();
 163   }
 164
 165   virtual StructuredData::GenericSP
 166   CreateScriptCommandObject(const char *class_name) {
 167     return StructuredData::GenericSP();
 168   }
 169
 170   virtual StructuredData::GenericSP
 171   CreateFrameRecognizer(const char *class_name) {
 172     return StructuredData::GenericSP();
 173   }
 174
 175   virtual lldb::ValueObjectListSP GetRecognizedArguments(
 176       const StructuredData::ObjectSP &implementor,
 177       lldb::StackFrameSP frame_sp) {
 178     return lldb::ValueObjectListSP();
 179   }
 180
 181   virtual StructuredData::GenericSP
 182   OSPlugin_CreatePluginObject(const char *class_name,
 183                               lldb::ProcessSP process_sp) {
 184     return StructuredData::GenericSP();
 185   }
 186
 187   virtual StructuredData::DictionarySP
 188   OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp) {
 189     return StructuredData::DictionarySP();
 190   }
 191
 192   virtual StructuredData::ArraySP
 193   OSPlugin_ThreadsInfo(StructuredData::ObjectSP os_plugin_object_sp) {
 194     return StructuredData::ArraySP();
 195   }
 196
 197   virtual StructuredData::StringSP
 198   OSPlugin_RegisterContextData(StructuredData::ObjectSP os_plugin_object_sp,
 199                                lldb::tid_t thread_id) {
 200     return StructuredData::StringSP();
 201   }
 202
 203   virtual StructuredData::DictionarySP
 204   OSPlugin_CreateThread(StructuredData::ObjectSP os_plugin_object_sp,
 205                         lldb::tid_t tid, lldb::addr_t context) {
 206     return StructuredData::DictionarySP();
 207   }
 208
 209   virtual StructuredData::ObjectSP
 210   CreateScriptedThreadPlan(const char *class_name,
 211                            lldb::ThreadPlanSP thread_plan_sp) {
 212     return StructuredData::ObjectSP();
 213   }
 214
 215   virtual bool
 216   ScriptedThreadPlanExplainsStop(StructuredData::ObjectSP implementor_sp,
 217                                  Event *event, bool &script_error) {
 218     script_error = true;
 219     return true;
 220   }
 221
 222   virtual bool
 223   ScriptedThreadPlanShouldStop(StructuredData::ObjectSP implementor_sp,
 224                                Event *event, bool &script_error) {
 225     script_error = true;
 226     return true;
 227   }
 228
 229   virtual bool
 230   ScriptedThreadPlanIsStale(StructuredData::ObjectSP implementor_sp,
 231                             bool &script_error) {
 232     script_error = true;
 233     return true;
 234   }
 235
 236   virtual lldb::StateType
 237   ScriptedThreadPlanGetRunState(StructuredData::ObjectSP implementor_sp,
 238                                 bool &script_error) {
 239     script_error = true;
 240     return lldb::eStateStepping;
 241   }
 242
 243   virtual StructuredData::GenericSP
 244   CreateScriptedBreakpointResolver(const char *class_name,
 245                                    StructuredDataImpl *args_data,
 246                                    lldb::BreakpointSP &bkpt_sp) {
 247     return StructuredData::GenericSP();
 248   }
 249
 250   virtual bool
 251   ScriptedBreakpointResolverSearchCallback(StructuredData::GenericSP implementor_sp,
 252                                            SymbolContext *sym_ctx)
 253   {
 254     return false;
 255   }
 256
 257   virtual lldb::SearchDepth
 258   ScriptedBreakpointResolverSearchDepth(StructuredData::GenericSP implementor_sp)
 259   {
 260     return lldb::eSearchDepthModule;
 261   }
 262
 263   virtual StructuredData::ObjectSP
 264   LoadPluginModule(const FileSpec &file_spec, lldb_private::Status &error) {
 265     return StructuredData::ObjectSP();
 266   }
 267
 268   virtual StructuredData::DictionarySP
 269   GetDynamicSettings(StructuredData::ObjectSP plugin_module_sp, Target *target,
 270                      const char *setting_name, lldb_private::Status &error) {
 271     return StructuredData::DictionarySP();
 272   }
 273
 274   virtual Status GenerateFunction(const char *signature,
 275                                   const StringList &input) {
 276     Status error;
 277     error.SetErrorString("unimplemented");
 278     return error;
 279   }
 280
 281   virtual void CollectDataForBreakpointCommandCallback(
 282       std::vector<BreakpointOptions *> &options, CommandReturnObject &result);
 283
 284   virtual void
 285   CollectDataForWatchpointCommandCallback(WatchpointOptions *wp_options,
 286                                           CommandReturnObject &result);
 287
 288   /// Set the specified text as the callback for the breakpoint.
 289   Status
 290   SetBreakpointCommandCallback(std::vector<BreakpointOptions *> &bp_options_vec,
 291                                const char *callback_text);
 292
 293   virtual Status SetBreakpointCommandCallback(BreakpointOptions *bp_options,
 294                                               const char *callback_text) {
 295     Status error;
 296     error.SetErrorString("unimplemented");
 297     return error;
 298   }
 299
 300   /// This one is for deserialization:
 301   virtual Status SetBreakpointCommandCallback(
 302       BreakpointOptions *bp_options,
 303       std::unique_ptr<BreakpointOptions::CommandData> &data_up) {
 304     Status error;
 305     error.SetErrorString("unimplemented");
 306     return error;
 307   }
 308
 309   void SetBreakpointCommandCallbackFunction(
 310       std::vector<BreakpointOptions *> &bp_options_vec,
 311       const char *function_name);
 312
 313   /// Set a one-liner as the callback for the breakpoint.
 314   virtual void
 315   SetBreakpointCommandCallbackFunction(BreakpointOptions *bp_options,
 316                                        const char *function_name) {}
 317
 318   /// Set a one-liner as the callback for the watchpoint.
 319   virtual void SetWatchpointCommandCallback(WatchpointOptions *wp_options,
 320                                             const char *oneliner) {}
 321
 322   virtual bool GetScriptedSummary(const char *function_name,
 323                                   lldb::ValueObjectSP valobj,
 324                                   StructuredData::ObjectSP &callee_wrapper_sp,
 325                                   const TypeSummaryOptions &options,
 326                                   std::string &retval) {
 327     return false;
 328   }
 329
 330   virtual void Clear() {
 331     // Clean up any ref counts to SBObjects that might be in global variables
 332   }
 333
 334   virtual size_t
 335   CalculateNumChildren(const StructuredData::ObjectSP &implementor,
 336                        uint32_t max) {
 337     return 0;
 338   }
 339
 340   virtual lldb::ValueObjectSP
 341   GetChildAtIndex(const StructuredData::ObjectSP &implementor, uint32_t idx) {
 342     return lldb::ValueObjectSP();
 343   }
 344
 345   virtual int
 346   GetIndexOfChildWithName(const StructuredData::ObjectSP &implementor,
 347                           const char *child_name) {
 348     return UINT32_MAX;
 349   }
 350
 351   virtual bool
 352   UpdateSynthProviderInstance(const StructuredData::ObjectSP &implementor) {
 353     return false;
 354   }
 355
 356   virtual bool MightHaveChildrenSynthProviderInstance(
 357       const StructuredData::ObjectSP &implementor) {
 358     return true;
 359   }
 360
 361   virtual lldb::ValueObjectSP
 362   GetSyntheticValue(const StructuredData::ObjectSP &implementor) {
 363     return nullptr;
 364   }
 365
 366   virtual ConstString
 367   GetSyntheticTypeName(const StructuredData::ObjectSP &implementor) {
 368     return ConstString();
 369   }
 370
 371   virtual bool
 372   RunScriptBasedCommand(const char *impl_function, llvm::StringRef args,
 373                         ScriptedCommandSynchronicity synchronicity,
 374                         lldb_private::CommandReturnObject &cmd_retobj,
 375                         Status &error,
 376                         const lldb_private::ExecutionContext &exe_ctx) {
 377     return false;
 378   }
 379
 380   virtual bool RunScriptBasedCommand(
 381       StructuredData::GenericSP impl_obj_sp, llvm::StringRef args,
 382       ScriptedCommandSynchronicity synchronicity,
 383       lldb_private::CommandReturnObject &cmd_retobj, Status &error,
 384       const lldb_private::ExecutionContext &exe_ctx) {
 385     return false;
 386   }
 387
 388   virtual bool RunScriptFormatKeyword(const char *impl_function,
 389                                       Process *process, std::string &output,
 390                                       Status &error) {
 391     error.SetErrorString("unimplemented");
 392     return false;
 393   }
 394
 395   virtual bool RunScriptFormatKeyword(const char *impl_function, Thread *thread,
 396                                       std::string &output, Status &error) {
 397     error.SetErrorString("unimplemented");
 398     return false;
 399   }
 400
 401   virtual bool RunScriptFormatKeyword(const char *impl_function, Target *target,
 402                                       std::string &output, Status &error) {
 403     error.SetErrorString("unimplemented");
 404     return false;
 405   }
 406
 407   virtual bool RunScriptFormatKeyword(const char *impl_function,
 408                                       StackFrame *frame, std::string &output,
 409                                       Status &error) {
 410     error.SetErrorString("unimplemented");
 411     return false;
 412   }
 413
 414   virtual bool RunScriptFormatKeyword(const char *impl_function,
 415                                       ValueObject *value, std::string &output,
 416                                       Status &error) {
 417     error.SetErrorString("unimplemented");
 418     return false;
 419   }
 420
 421   virtual bool GetDocumentationForItem(const char *item, std::string &dest) {
 422     dest.clear();
 423     return false;
 424   }
 425
 426   virtual bool
 427   GetShortHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
 428                                std::string &dest) {
 429     dest.clear();
 430     return false;
 431   }
 432
 433   virtual uint32_t
 434   GetFlagsForCommandObject(StructuredData::GenericSP cmd_obj_sp) {
 435     return 0;
 436   }
 437
 438   virtual bool GetLongHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
 439                                            std::string &dest) {
 440     dest.clear();
 441     return false;
 442   }
 443
 444   virtual bool CheckObjectExists(const char *name) { return false; }
 445
 446   virtual bool
 447   LoadScriptingModule(const char *filename, bool can_reload, bool init_session,
 448                       lldb_private::Status &error,
 449                       StructuredData::ObjectSP *module_sp = nullptr) {
 450     error.SetErrorString("loading unimplemented");
 451     return false;
 452   }
 453
 454   virtual bool IsReservedWord(const char *word) { return false; }
 455
 456   virtual std::unique_ptr<ScriptInterpreterLocker> AcquireInterpreterLock();
 457
 458   const char *GetScriptInterpreterPtyName();
 459
 460   int GetMasterFileDescriptor();
 461
 462   static std::string LanguageToString(lldb::ScriptLanguage language);
 463
 464   static lldb::ScriptLanguage StringToLanguage(const llvm::StringRef &string);
 465
 466   virtual void ResetOutputFileHandle(FILE *new_fh) {} // By default, do nothing.
 467
 468   lldb::ScriptLanguage GetLanguage() { return m_script_lang; }
 469
 470 protected:
 471   Debugger &m_debugger;
 472   lldb::ScriptLanguage m_script_lang;
 473 };
 474
 475 } // namespace lldb_private
 476
 477 #endif // liblldb_ScriptInterpreter_h_