lldb/source/Plugins/ScriptInterpreter/Python/SWIGPythonBridge.h

   1 //===-- ScriptInterpreterPython.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 LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SWIGPYTHONBRIDGE_H
  10 #define LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SWIGPYTHONBRIDGE_H
  11
  12 #include <optional>
  13 #include <string>
  14
  15 #include "lldb/Host/Config.h"
  16
  17 #if LLDB_ENABLE_PYTHON
  18
  19 // LLDB Python header must be included first
  20 #include "lldb-python.h"
  21
  22 #include "Plugins/ScriptInterpreter/Python/PythonDataObjects.h"
  23 #include "lldb/lldb-forward.h"
  24 #include "lldb/lldb-types.h"
  25 #include "llvm/Support/Error.h"
  26
  27 namespace lldb {
  28 class SBEvent;
  29 class SBCommandReturnObject;
  30 class SBValue;
  31 class SBStream;
  32 class SBStructuredData;
  33 class SBFileSpec;
  34 class SBModuleSpec;
  35 class SBStringList;
  36 } // namespace lldb
  37
  38 namespace lldb_private {
  39 namespace python {
  40
  41 typedef struct swig_type_info swig_type_info;
  42
  43 python::PythonObject ToSWIGHelper(void *obj, swig_type_info *info);
  44
  45 /// A class that automatically clears an SB object when it goes out of scope.
  46 /// Use for cases where the SB object points to a temporary/unowned entity.
  47 template <typename T> class ScopedPythonObject : PythonObject {
  48 public:
  49   ScopedPythonObject(T *sb, swig_type_info *info)
  50       : PythonObject(ToSWIGHelper(sb, info)), m_sb(sb) {}
  51   ~ScopedPythonObject() {
  52     if (m_sb)
  53       *m_sb = T();
  54   }
  55   ScopedPythonObject(ScopedPythonObject &&rhs)
  56       : PythonObject(std::move(rhs)), m_sb(std::exchange(rhs.m_sb, nullptr)) {}
  57   ScopedPythonObject(const ScopedPythonObject &) = delete;
  58   ScopedPythonObject &operator=(const ScopedPythonObject &) = delete;
  59   ScopedPythonObject &operator=(ScopedPythonObject &&) = delete;
  60
  61   const PythonObject &obj() const { return *this; }
  62
  63 private:
  64   T *m_sb;
  65 };
  66
  67 // TODO: We may want to support other languages in the future w/ SWIG (we
  68 // already support Lua right now, for example). We could create a generic
  69 // SWIGBridge class and have this one specialize it, something like this:
  70 //
  71 // <typename T>
  72 // class SWIGBridge {
  73 //   static T ToSWIGWrapper(...);
  74 // };
  75 //
  76 // class SWIGPythonBridge : public SWIGBridge<PythonObject> {
  77 //   template<> static PythonObject ToSWIGWrapper(...);
  78 // };
  79 //
  80 // And we should be able to more easily support things like Lua
  81 class SWIGBridge {
  82 public:
  83   static PythonObject ToSWIGWrapper(std::unique_ptr<lldb::SBValue> value_sb);
  84   static PythonObject ToSWIGWrapper(lldb::ValueObjectSP value_sp);
  85   static PythonObject ToSWIGWrapper(lldb::TargetSP target_sp);
  86   static PythonObject ToSWIGWrapper(lldb::ProcessSP process_sp);
  87   static PythonObject ToSWIGWrapper(lldb::ThreadPlanSP thread_plan_sp);
  88   static PythonObject ToSWIGWrapper(lldb::BreakpointSP breakpoint_sp);
  89   static PythonObject ToSWIGWrapper(Status &&status);
  90   static PythonObject ToSWIGWrapper(const StructuredDataImpl &data_impl);
  91   static PythonObject ToSWIGWrapper(lldb::ThreadSP thread_sp);
  92   static PythonObject ToSWIGWrapper(lldb::StackFrameSP frame_sp);
  93   static PythonObject ToSWIGWrapper(lldb::DebuggerSP debugger_sp);
  94   static PythonObject ToSWIGWrapper(lldb::WatchpointSP watchpoint_sp);
  95   static PythonObject ToSWIGWrapper(lldb::BreakpointLocationSP bp_loc_sp);
  96   static PythonObject ToSWIGWrapper(lldb::TypeImplSP type_impl_sp);
  97   static PythonObject ToSWIGWrapper(lldb::ExecutionContextRefSP ctx_sp);
  98   static PythonObject ToSWIGWrapper(const TypeSummaryOptions &summary_options);
  99   static PythonObject ToSWIGWrapper(const SymbolContext &sym_ctx);
 100   static PythonObject ToSWIGWrapper(const Stream *stream);
 101   static PythonObject ToSWIGWrapper(std::shared_ptr<lldb::SBStream> stream_sb);
 102   static PythonObject ToSWIGWrapper(Event *event);
 103
 104   static PythonObject ToSWIGWrapper(lldb::ProcessAttachInfoSP attach_info_sp);
 105   static PythonObject ToSWIGWrapper(lldb::ProcessLaunchInfoSP launch_info_sp);
 106   static PythonObject ToSWIGWrapper(lldb::DataExtractorSP data_extractor_sp);
 107
 108   static PythonObject
 109   ToSWIGWrapper(std::unique_ptr<lldb::SBStructuredData> data_sb);
 110   static PythonObject
 111   ToSWIGWrapper(std::unique_ptr<lldb::SBFileSpec> file_spec_sb);
 112   static PythonObject
 113   ToSWIGWrapper(std::unique_ptr<lldb::SBModuleSpec> module_spec_sb);
 114
 115   static python::ScopedPythonObject<lldb::SBCommandReturnObject>
 116   ToSWIGWrapper(CommandReturnObject &cmd_retobj);
 117   // These prototypes are the Pythonic implementations of the required
 118   // callbacks. Although these are scripting-language specific, their definition
 119   // depends on the public API.
 120
 121   static llvm::Expected<bool> LLDBSwigPythonBreakpointCallbackFunction(
 122       const char *python_function_name, const char *session_dictionary_name,
 123       const lldb::StackFrameSP &sb_frame,
 124       const lldb::BreakpointLocationSP &sb_bp_loc,
 125       const lldb_private::StructuredDataImpl &args_impl);
 126
 127   static bool LLDBSwigPythonWatchpointCallbackFunction(
 128       const char *python_function_name, const char *session_dictionary_name,
 129       const lldb::StackFrameSP &sb_frame, const lldb::WatchpointSP &sb_wp);
 130
 131   static bool
 132   LLDBSwigPythonFormatterCallbackFunction(const char *python_function_name,
 133                                           const char *session_dictionary_name,
 134                                           lldb::TypeImplSP type_impl_sp);
 135
 136   static bool LLDBSwigPythonCallTypeScript(
 137       const char *python_function_name, const void *session_dictionary,
 138       const lldb::ValueObjectSP &valobj_sp, void **pyfunct_wrapper,
 139       const lldb::TypeSummaryOptionsSP &options_sp, std::string &retval);
 140
 141   static python::PythonObject
 142   LLDBSwigPythonCreateSyntheticProvider(const char *python_class_name,
 143                                         const char *session_dictionary_name,
 144                                         const lldb::ValueObjectSP &valobj_sp);
 145
 146   static python::PythonObject
 147   LLDBSwigPythonCreateCommandObject(const char *python_class_name,
 148                                     const char *session_dictionary_name,
 149                                     lldb::DebuggerSP debugger_sp);
 150
 151   static python::PythonObject LLDBSwigPythonCreateScriptedBreakpointResolver(
 152       const char *python_class_name, const char *session_dictionary_name,
 153       const StructuredDataImpl &args, const lldb::BreakpointSP &bkpt_sp);
 154
 155   static unsigned int
 156   LLDBSwigPythonCallBreakpointResolver(void *implementor,
 157                                        const char *method_name,
 158                                        lldb_private::SymbolContext *sym_ctx);
 159
 160   static size_t LLDBSwigPython_CalculateNumChildren(PyObject *implementor,
 161                                                     uint32_t max);
 162
 163   static PyObject *LLDBSwigPython_GetChildAtIndex(PyObject *implementor,
 164                                                   uint32_t idx);
 165
 166   static int LLDBSwigPython_GetIndexOfChildWithName(PyObject *implementor,
 167                                                     const char *child_name);
 168
 169   static lldb::ValueObjectSP
 170   LLDBSWIGPython_GetValueObjectSPFromSBValue(void *data);
 171
 172   static bool LLDBSwigPython_UpdateSynthProviderInstance(PyObject *implementor);
 173
 174   static bool
 175   LLDBSwigPython_MightHaveChildrenSynthProviderInstance(PyObject *implementor);
 176
 177   static PyObject *
 178   LLDBSwigPython_GetValueSynthProviderInstance(PyObject *implementor);
 179
 180   static bool
 181   LLDBSwigPythonCallCommand(const char *python_function_name,
 182                             const char *session_dictionary_name,
 183                             lldb::DebuggerSP debugger, const char *args,
 184                             lldb_private::CommandReturnObject &cmd_retobj,
 185                             lldb::ExecutionContextRefSP exe_ctx_ref_sp);
 186
 187   static bool
 188   LLDBSwigPythonCallCommandObject(PyObject *implementor,
 189                                   lldb::DebuggerSP debugger, const char *args,
 190                                   lldb_private::CommandReturnObject &cmd_retobj,
 191                                   lldb::ExecutionContextRefSP exe_ctx_ref_sp);
 192   static bool
 193   LLDBSwigPythonCallParsedCommandObject(PyObject *implementor,
 194                                   lldb::DebuggerSP debugger,
 195                                   StructuredDataImpl &args_impl,
 196                                   lldb_private::CommandReturnObject &cmd_retobj,
 197                                   lldb::ExecutionContextRefSP exe_ctx_ref_sp);
 198
 199   static std::optional<std::string>
 200   LLDBSwigPythonGetRepeatCommandForScriptedCommand(PyObject *implementor,
 201                                                    std::string &command);
 202
 203   static StructuredData::DictionarySP
 204   LLDBSwigPythonHandleArgumentCompletionForScriptedCommand(
 205       PyObject *implementor, std::vector<llvm::StringRef> &args_impl,
 206       size_t args_pos, size_t pos_in_arg);
 207
 208   static StructuredData::DictionarySP
 209   LLDBSwigPythonHandleOptionArgumentCompletionForScriptedCommand(
 210       PyObject *implementor, llvm::StringRef &long_option, size_t pos_in_arg);
 211
 212   static bool LLDBSwigPythonCallModuleInit(const char *python_module_name,
 213                                            const char *session_dictionary_name,
 214                                            lldb::DebuggerSP debugger);
 215
 216   static python::PythonObject
 217   LLDBSWIGPythonCreateOSPlugin(const char *python_class_name,
 218                                const char *session_dictionary_name,
 219                                const lldb::ProcessSP &process_sp);
 220
 221   static python::PythonObject
 222   LLDBSWIGPython_CreateFrameRecognizer(const char *python_class_name,
 223                                        const char *session_dictionary_name);
 224
 225   static PyObject *
 226   LLDBSwigPython_GetRecognizedArguments(PyObject *implementor,
 227                                         const lldb::StackFrameSP &frame_sp);
 228
 229   static bool LLDBSwigPython_ShouldHide(PyObject *implementor,
 230                                         const lldb::StackFrameSP &frame_sp);
 231
 232   static bool LLDBSWIGPythonRunScriptKeywordProcess(
 233       const char *python_function_name, const char *session_dictionary_name,
 234       const lldb::ProcessSP &process, std::string &output);
 235
 236   static std::optional<std::string>
 237   LLDBSWIGPythonRunScriptKeywordThread(const char *python_function_name,
 238                                        const char *session_dictionary_name,
 239                                        lldb::ThreadSP thread);
 240
 241   static bool LLDBSWIGPythonRunScriptKeywordTarget(
 242       const char *python_function_name, const char *session_dictionary_name,
 243       const lldb::TargetSP &target, std::string &output);
 244
 245   static std::optional<std::string>
 246   LLDBSWIGPythonRunScriptKeywordFrame(const char *python_function_name,
 247                                       const char *session_dictionary_name,
 248                                       lldb::StackFrameSP frame);
 249
 250   static bool LLDBSWIGPythonRunScriptKeywordValue(
 251       const char *python_function_name, const char *session_dictionary_name,
 252       const lldb::ValueObjectSP &value, std::string &output);
 253
 254   static void *
 255   LLDBSWIGPython_GetDynamicSetting(void *module, const char *setting,
 256                                    const lldb::TargetSP &target_sp);
 257 };
 258
 259 void *LLDBSWIGPython_CastPyObjectToSBData(PyObject *data);
 260 void *LLDBSWIGPython_CastPyObjectToSBBreakpoint(PyObject *data);
 261 void *LLDBSWIGPython_CastPyObjectToSBAttachInfo(PyObject *data);
 262 void *LLDBSWIGPython_CastPyObjectToSBLaunchInfo(PyObject *data);
 263 void *LLDBSWIGPython_CastPyObjectToSBError(PyObject *data);
 264 void *LLDBSWIGPython_CastPyObjectToSBEvent(PyObject *data);
 265 void *LLDBSWIGPython_CastPyObjectToSBStream(PyObject *data);
 266 void *LLDBSWIGPython_CastPyObjectToSBValue(PyObject *data);
 267 void *LLDBSWIGPython_CastPyObjectToSBMemoryRegionInfo(PyObject *data);
 268 void *LLDBSWIGPython_CastPyObjectToSBExecutionContext(PyObject *data);
 269 } // namespace python
 270
 271 } // namespace lldb_private
 272
 273 #endif // LLDB_ENABLE_PYTHON
 274 #endif // LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SWIGPYTHONBRIDGE_H