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