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 } // namespace lldb 34 35 namespace lldb_private { 36 namespace python { 37 38 typedef struct swig_type_info swig_type_info; 39 40 python::PythonObject ToSWIGHelper(void *obj, swig_type_info *info); 41 42 /// A class that automatically clears an SB object when it goes out of scope. 43 /// Use for cases where the SB object points to a temporary/unowned entity. 44 template <typename T> class ScopedPythonObject : PythonObject { 45 public: 46 ScopedPythonObject(T *sb, swig_type_info *info) 47 : PythonObject(ToSWIGHelper(sb, info)), m_sb(sb) {} 48 ~ScopedPythonObject() { 49 if (m_sb) 50 *m_sb = T(); 51 } 52 ScopedPythonObject(ScopedPythonObject &&rhs) 53 : PythonObject(std::move(rhs)), m_sb(std::exchange(rhs.m_sb, nullptr)) {} 54 ScopedPythonObject(const ScopedPythonObject &) = delete; 55 ScopedPythonObject &operator=(const ScopedPythonObject &) = delete; 56 ScopedPythonObject &operator=(ScopedPythonObject &&) = delete; 57 58 const PythonObject &obj() const { return *this; } 59 60 private: 61 T *m_sb; 62 }; 63 64 PythonObject ToSWIGWrapper(lldb::ValueObjectSP value_sp); 65 PythonObject ToSWIGWrapper(lldb::TargetSP target_sp); 66 PythonObject ToSWIGWrapper(lldb::ProcessSP process_sp); 67 PythonObject ToSWIGWrapper(lldb::ThreadPlanSP thread_plan_sp); 68 PythonObject ToSWIGWrapper(lldb::BreakpointSP breakpoint_sp); 69 PythonObject ToSWIGWrapper(const Status &status); 70 PythonObject ToSWIGWrapper(const StructuredDataImpl &data_impl); 71 PythonObject ToSWIGWrapper(lldb::ThreadSP thread_sp); 72 PythonObject ToSWIGWrapper(lldb::StackFrameSP frame_sp); 73 PythonObject ToSWIGWrapper(lldb::DebuggerSP debugger_sp); 74 PythonObject ToSWIGWrapper(lldb::WatchpointSP watchpoint_sp); 75 PythonObject ToSWIGWrapper(lldb::BreakpointLocationSP bp_loc_sp); 76 PythonObject ToSWIGWrapper(lldb::ExecutionContextRefSP ctx_sp); 77 PythonObject ToSWIGWrapper(const TypeSummaryOptions &summary_options); 78 PythonObject ToSWIGWrapper(const SymbolContext &sym_ctx); 79 80 PythonObject ToSWIGWrapper(lldb::ProcessAttachInfoSP attach_info_sp); 81 PythonObject ToSWIGWrapper(lldb::ProcessLaunchInfoSP launch_info_sp); 82 PythonObject ToSWIGWrapper(lldb::DataExtractorSP data_extractor_sp); 83 84 PythonObject ToSWIGWrapper(std::unique_ptr<lldb::SBValue> value_sb); 85 PythonObject ToSWIGWrapper(std::unique_ptr<lldb::SBStream> stream_sb); 86 PythonObject ToSWIGWrapper(std::unique_ptr<lldb::SBStructuredData> data_sb); 87 88 python::ScopedPythonObject<lldb::SBCommandReturnObject> 89 ToSWIGWrapper(CommandReturnObject &cmd_retobj); 90 python::ScopedPythonObject<lldb::SBEvent> ToSWIGWrapper(Event *event); 91 92 } // namespace python 93 94 void *LLDBSWIGPython_CastPyObjectToSBData(PyObject *data); 95 void *LLDBSWIGPython_CastPyObjectToSBBreakpoint(PyObject *data); 96 void *LLDBSWIGPython_CastPyObjectToSBAttachInfo(PyObject *data); 97 void *LLDBSWIGPython_CastPyObjectToSBLaunchInfo(PyObject *data); 98 void *LLDBSWIGPython_CastPyObjectToSBError(PyObject *data); 99 void *LLDBSWIGPython_CastPyObjectToSBValue(PyObject *data); 100 void *LLDBSWIGPython_CastPyObjectToSBMemoryRegionInfo(PyObject *data); 101 102 // These prototypes are the Pythonic implementations of the required callbacks. 103 // Although these are scripting-language specific, their definition depends on 104 // the public API. 105 106 python::PythonObject LLDBSwigPythonCreateScriptedObject( 107 const char *python_class_name, const char *session_dictionary_name, 108 lldb::ExecutionContextRefSP exe_ctx_sp, 109 const lldb_private::StructuredDataImpl &args_impl, 110 std::string &error_string); 111 112 llvm::Expected<bool> LLDBSwigPythonBreakpointCallbackFunction( 113 const char *python_function_name, const char *session_dictionary_name, 114 const lldb::StackFrameSP &sb_frame, 115 const lldb::BreakpointLocationSP &sb_bp_loc, 116 const lldb_private::StructuredDataImpl &args_impl); 117 118 bool LLDBSwigPythonWatchpointCallbackFunction( 119 const char *python_function_name, const char *session_dictionary_name, 120 const lldb::StackFrameSP &sb_frame, const lldb::WatchpointSP &sb_wp); 121 122 bool LLDBSwigPythonFormatterCallbackFunction( 123 const char *python_function_name, const char *session_dictionary_name, 124 lldb::TypeImplSP type_impl_sp); 125 126 bool LLDBSwigPythonCallTypeScript(const char *python_function_name, 127 const void *session_dictionary, 128 const lldb::ValueObjectSP &valobj_sp, 129 void **pyfunct_wrapper, 130 const lldb::TypeSummaryOptionsSP &options_sp, 131 std::string &retval); 132 133 python::PythonObject 134 LLDBSwigPythonCreateSyntheticProvider(const char *python_class_name, 135 const char *session_dictionary_name, 136 const lldb::ValueObjectSP &valobj_sp); 137 138 python::PythonObject 139 LLDBSwigPythonCreateCommandObject(const char *python_class_name, 140 const char *session_dictionary_name, 141 lldb::DebuggerSP debugger_sp); 142 143 python::PythonObject LLDBSwigPythonCreateScriptedThreadPlan( 144 const char *python_class_name, const char *session_dictionary_name, 145 const StructuredDataImpl &args_data, std::string &error_string, 146 const lldb::ThreadPlanSP &thread_plan_sp); 147 148 bool LLDBSWIGPythonCallThreadPlan(void *implementor, const char *method_name, 149 lldb_private::Event *event_sp, 150 bool &got_error); 151 152 python::PythonObject LLDBSwigPythonCreateScriptedBreakpointResolver( 153 const char *python_class_name, const char *session_dictionary_name, 154 const StructuredDataImpl &args, const lldb::BreakpointSP &bkpt_sp); 155 156 unsigned int 157 LLDBSwigPythonCallBreakpointResolver(void *implementor, const char *method_name, 158 lldb_private::SymbolContext *sym_ctx); 159 160 python::PythonObject LLDBSwigPythonCreateScriptedStopHook( 161 lldb::TargetSP target_sp, const char *python_class_name, 162 const char *session_dictionary_name, const StructuredDataImpl &args, 163 lldb_private::Status &error); 164 165 bool LLDBSwigPythonStopHookCallHandleStop(void *implementor, 166 lldb::ExecutionContextRefSP exc_ctx, 167 lldb::StreamSP stream); 168 169 size_t LLDBSwigPython_CalculateNumChildren(PyObject *implementor, uint32_t max); 170 171 PyObject *LLDBSwigPython_GetChildAtIndex(PyObject *implementor, uint32_t idx); 172 173 int LLDBSwigPython_GetIndexOfChildWithName(PyObject *implementor, 174 const char *child_name); 175 176 lldb::ValueObjectSP LLDBSWIGPython_GetValueObjectSPFromSBValue(void *data); 177 178 bool LLDBSwigPython_UpdateSynthProviderInstance(PyObject *implementor); 179 180 bool LLDBSwigPython_MightHaveChildrenSynthProviderInstance( 181 PyObject *implementor); 182 183 PyObject *LLDBSwigPython_GetValueSynthProviderInstance(PyObject *implementor); 184 185 bool LLDBSwigPythonCallCommand(const char *python_function_name, 186 const char *session_dictionary_name, 187 lldb::DebuggerSP debugger, const char *args, 188 lldb_private::CommandReturnObject &cmd_retobj, 189 lldb::ExecutionContextRefSP exe_ctx_ref_sp); 190 191 bool LLDBSwigPythonCallCommandObject( 192 PyObject *implementor, lldb::DebuggerSP debugger, const char *args, 193 lldb_private::CommandReturnObject &cmd_retobj, 194 lldb::ExecutionContextRefSP exe_ctx_ref_sp); 195 196 bool LLDBSwigPythonCallModuleInit(const char *python_module_name, 197 const char *session_dictionary_name, 198 lldb::DebuggerSP debugger); 199 200 python::PythonObject 201 LLDBSWIGPythonCreateOSPlugin(const char *python_class_name, 202 const char *session_dictionary_name, 203 const lldb::ProcessSP &process_sp); 204 205 python::PythonObject 206 LLDBSWIGPython_CreateFrameRecognizer(const char *python_class_name, 207 const char *session_dictionary_name); 208 209 PyObject * 210 LLDBSwigPython_GetRecognizedArguments(PyObject *implementor, 211 const lldb::StackFrameSP &frame_sp); 212 213 bool LLDBSWIGPythonRunScriptKeywordProcess(const char *python_function_name, 214 const char *session_dictionary_name, 215 const lldb::ProcessSP &process, 216 std::string &output); 217 218 std::optional<std::string> 219 LLDBSWIGPythonRunScriptKeywordThread(const char *python_function_name, 220 const char *session_dictionary_name, 221 lldb::ThreadSP thread); 222 223 bool LLDBSWIGPythonRunScriptKeywordTarget(const char *python_function_name, 224 const char *session_dictionary_name, 225 const lldb::TargetSP &target, 226 std::string &output); 227 228 std::optional<std::string> 229 LLDBSWIGPythonRunScriptKeywordFrame(const char *python_function_name, 230 const char *session_dictionary_name, 231 lldb::StackFrameSP frame); 232 233 bool LLDBSWIGPythonRunScriptKeywordValue(const char *python_function_name, 234 const char *session_dictionary_name, 235 const lldb::ValueObjectSP &value, 236 std::string &output); 237 238 void *LLDBSWIGPython_GetDynamicSetting(void *module, const char *setting, 239 const lldb::TargetSP &target_sp); 240 241 } // namespace lldb_private 242 243 #endif // LLDB_ENABLE_PYTHON 244 #endif // LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SWIGPYTHONBRIDGE_H 245