xref: /llvm-project/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.h (revision 05495c5d4571b1756369e00a1ca7003d63e204da) 
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_SCRIPTINTERPRETERPYTHON_H
10 #define LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SCRIPTINTERPRETERPYTHON_H
11 
12 #ifdef LLDB_DISABLE_PYTHON
13 
14 // Python is disabled in this build
15 
16 #else
17 
18 #include <memory>
19 #include <string>
20 #include <vector>
21 
22 #include "PythonDataObjects.h"
23 #include "lldb/Breakpoint/BreakpointOptions.h"
24 #include "lldb/Core/IOHandler.h"
25 #include "lldb/Host/Terminal.h"
26 #include "lldb/Interpreter/ScriptInterpreter.h"
27 #include "lldb/lldb-private.h"
28 
29 class IOHandlerPythonInterpreter;
30 
31 namespace lldb_private {
32 
33 class ScriptInterpreterPython : public ScriptInterpreter,
34                                 public IOHandlerDelegateMultiline {
35 public:
36   class CommandDataPython : public BreakpointOptions::CommandData {
37   public:
38     CommandDataPython() : BreakpointOptions::CommandData() {
39       interpreter = lldb::eScriptLanguagePython;
40     }
41   };
42 
43   friend class ::IOHandlerPythonInterpreter;
44 
45   ScriptInterpreterPython(CommandInterpreter &interpreter);
46 
47   ~ScriptInterpreterPython() override;
48 
49   bool Interrupt() override;
50 
51   bool ExecuteOneLine(
52       llvm::StringRef command, CommandReturnObject *result,
53       const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
54 
55   void ExecuteInterpreterLoop() override;
56 
57   bool ExecuteOneLineWithReturn(
58       llvm::StringRef in_string,
59       ScriptInterpreter::ScriptReturnType return_type, void *ret_value,
60       const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
61 
62   lldb_private::Status ExecuteMultipleLines(
63       const char *in_string,
64       const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
65 
66   Status
67   ExportFunctionDefinitionToInterpreter(StringList &function_def) override;
68 
69   bool GenerateTypeScriptFunction(StringList &input, std::string &output,
70                                   const void *name_token = nullptr) override;
71 
72   bool GenerateTypeSynthClass(StringList &input, std::string &output,
73                               const void *name_token = nullptr) override;
74 
75   bool GenerateTypeSynthClass(const char *oneliner, std::string &output,
76                               const void *name_token = nullptr) override;
77 
78   // use this if the function code is just a one-liner script
79   bool GenerateTypeScriptFunction(const char *oneliner, std::string &output,
80                                   const void *name_token = nullptr) override;
81 
82   bool GenerateScriptAliasFunction(StringList &input,
83                                    std::string &output) override;
84 
85   StructuredData::ObjectSP
86   CreateSyntheticScriptedProvider(const char *class_name,
87                                   lldb::ValueObjectSP valobj) override;
88 
89   StructuredData::GenericSP
90   CreateScriptCommandObject(const char *class_name) override;
91 
92   StructuredData::ObjectSP
93   CreateScriptedThreadPlan(const char *class_name,
94                            lldb::ThreadPlanSP thread_plan) override;
95 
96   bool ScriptedThreadPlanExplainsStop(StructuredData::ObjectSP implementor_sp,
97                                       Event *event,
98                                       bool &script_error) override;
99 
100   bool ScriptedThreadPlanShouldStop(StructuredData::ObjectSP implementor_sp,
101                                     Event *event, bool &script_error) override;
102 
103   bool ScriptedThreadPlanIsStale(StructuredData::ObjectSP implementor_sp,
104                                  bool &script_error) override;
105 
106   lldb::StateType
107   ScriptedThreadPlanGetRunState(StructuredData::ObjectSP implementor_sp,
108                                 bool &script_error) override;
109 
110   StructuredData::GenericSP
111   CreateScriptedBreakpointResolver(const char *class_name,
112                                    StructuredDataImpl *args_data,
113                                    lldb::BreakpointSP &bkpt_sp) override;
114   bool
115   ScriptedBreakpointResolverSearchCallback(StructuredData::GenericSP
116                                                implementor_sp,
117                                            SymbolContext *sym_ctx) override;
118 
119   lldb::SearchDepth
120   ScriptedBreakpointResolverSearchDepth(StructuredData::GenericSP
121                                             implementor_sp) override;
122 
123   StructuredData::GenericSP
124   CreateFrameRecognizer(const char *class_name) override;
125 
126   lldb::ValueObjectListSP
127   GetRecognizedArguments(const StructuredData::ObjectSP &implementor,
128                          lldb::StackFrameSP frame_sp) override;
129 
130   StructuredData::GenericSP
131   OSPlugin_CreatePluginObject(const char *class_name,
132                               lldb::ProcessSP process_sp) override;
133 
134   StructuredData::DictionarySP
135   OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
136 
137   StructuredData::ArraySP
138   OSPlugin_ThreadsInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
139 
140   StructuredData::StringSP
141   OSPlugin_RegisterContextData(StructuredData::ObjectSP os_plugin_object_sp,
142                                lldb::tid_t thread_id) override;
143 
144   StructuredData::DictionarySP
145   OSPlugin_CreateThread(StructuredData::ObjectSP os_plugin_object_sp,
146                         lldb::tid_t tid, lldb::addr_t context) override;
147 
148   StructuredData::ObjectSP
149   LoadPluginModule(const FileSpec &file_spec,
150                    lldb_private::Status &error) override;
151 
152   StructuredData::DictionarySP
153   GetDynamicSettings(StructuredData::ObjectSP plugin_module_sp, Target *target,
154                      const char *setting_name,
155                      lldb_private::Status &error) override;
156 
157   size_t CalculateNumChildren(const StructuredData::ObjectSP &implementor,
158                               uint32_t max) override;
159 
160   lldb::ValueObjectSP
161   GetChildAtIndex(const StructuredData::ObjectSP &implementor,
162                   uint32_t idx) override;
163 
164   int GetIndexOfChildWithName(const StructuredData::ObjectSP &implementor,
165                               const char *child_name) override;
166 
167   bool UpdateSynthProviderInstance(
168       const StructuredData::ObjectSP &implementor) override;
169 
170   bool MightHaveChildrenSynthProviderInstance(
171       const StructuredData::ObjectSP &implementor) override;
172 
173   lldb::ValueObjectSP
174   GetSyntheticValue(const StructuredData::ObjectSP &implementor) override;
175 
176   ConstString
177   GetSyntheticTypeName(const StructuredData::ObjectSP &implementor) override;
178 
179   bool
180   RunScriptBasedCommand(const char *impl_function, llvm::StringRef args,
181                         ScriptedCommandSynchronicity synchronicity,
182                         lldb_private::CommandReturnObject &cmd_retobj,
183                         Status &error,
184                         const lldb_private::ExecutionContext &exe_ctx) override;
185 
186   bool RunScriptBasedCommand(
187       StructuredData::GenericSP impl_obj_sp, llvm::StringRef args,
188       ScriptedCommandSynchronicity synchronicity,
189       lldb_private::CommandReturnObject &cmd_retobj, Status &error,
190       const lldb_private::ExecutionContext &exe_ctx) override;
191 
192   Status GenerateFunction(const char *signature,
193                           const StringList &input) override;
194 
195   Status GenerateBreakpointCommandCallbackData(StringList &input,
196                                                std::string &output) override;
197 
198   bool GenerateWatchpointCommandCallbackData(StringList &input,
199                                              std::string &output) override;
200 
201   static bool BreakpointCallbackFunction(void *baton,
202                                          StoppointCallbackContext *context,
203                                          lldb::user_id_t break_id,
204                                          lldb::user_id_t break_loc_id);
205 
206   static bool WatchpointCallbackFunction(void *baton,
207                                          StoppointCallbackContext *context,
208                                          lldb::user_id_t watch_id);
209 
210   bool GetScriptedSummary(const char *function_name, lldb::ValueObjectSP valobj,
211                           StructuredData::ObjectSP &callee_wrapper_sp,
212                           const TypeSummaryOptions &options,
213                           std::string &retval) override;
214 
215   void Clear() override;
216 
217   bool GetDocumentationForItem(const char *item, std::string &dest) override;
218 
219   bool GetShortHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
220                                     std::string &dest) override;
221 
222   uint32_t
223   GetFlagsForCommandObject(StructuredData::GenericSP cmd_obj_sp) override;
224 
225   bool GetLongHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
226                                    std::string &dest) override;
227 
228   bool CheckObjectExists(const char *name) override {
229     if (!name || !name[0])
230       return false;
231     std::string temp;
232     return GetDocumentationForItem(name, temp);
233   }
234 
235   bool RunScriptFormatKeyword(const char *impl_function, Process *process,
236                               std::string &output, Status &error) override;
237 
238   bool RunScriptFormatKeyword(const char *impl_function, Thread *thread,
239                               std::string &output, Status &error) override;
240 
241   bool RunScriptFormatKeyword(const char *impl_function, Target *target,
242                               std::string &output, Status &error) override;
243 
244   bool RunScriptFormatKeyword(const char *impl_function, StackFrame *frame,
245                               std::string &output, Status &error) override;
246 
247   bool RunScriptFormatKeyword(const char *impl_function, ValueObject *value,
248                               std::string &output, Status &error) override;
249 
250   bool
251   LoadScriptingModule(const char *filename, bool can_reload, bool init_session,
252                       lldb_private::Status &error,
253                       StructuredData::ObjectSP *module_sp = nullptr) override;
254 
255   bool IsReservedWord(const char *word) override;
256 
257   std::unique_ptr<ScriptInterpreterLocker> AcquireInterpreterLock() override;
258 
259   void CollectDataForBreakpointCommandCallback(
260       std::vector<BreakpointOptions *> &bp_options_vec,
261       CommandReturnObject &result) override;
262 
263   void
264   CollectDataForWatchpointCommandCallback(WatchpointOptions *wp_options,
265                                           CommandReturnObject &result) override;
266 
267   /// Set the callback body text into the callback for the breakpoint.
268   Status SetBreakpointCommandCallback(BreakpointOptions *bp_options,
269                                       const char *callback_body) override;
270 
271   void SetBreakpointCommandCallbackFunction(BreakpointOptions *bp_options,
272                                             const char *function_name) override;
273 
274   /// This one is for deserialization:
275   Status SetBreakpointCommandCallback(
276       BreakpointOptions *bp_options,
277       std::unique_ptr<BreakpointOptions::CommandData> &data_up) override;
278 
279   /// Set a one-liner as the callback for the watchpoint.
280   void SetWatchpointCommandCallback(WatchpointOptions *wp_options,
281                                     const char *oneliner) override;
282 
283   StringList ReadCommandInputFromUser(FILE *in_file);
284 
285   void ResetOutputFileHandle(FILE *new_fh) override;
286 
287   const char *GetDictionaryName() { return m_dictionary_name.c_str(); }
288 
289   PyThreadState *GetThreadState() { return m_command_thread_state; }
290 
291   void SetThreadState(PyThreadState *s) {
292     if (s)
293       m_command_thread_state = s;
294   }
295 
296   //----------------------------------------------------------------------
297   // IOHandlerDelegate
298   //----------------------------------------------------------------------
299   void IOHandlerActivated(IOHandler &io_handler, bool interactive) override;
300 
301   void IOHandlerInputComplete(IOHandler &io_handler,
302                               std::string &data) override;
303 
304   //------------------------------------------------------------------
305   // Static Functions
306   //------------------------------------------------------------------
307   static void Initialize();
308 
309   static void Terminate();
310 
311   static lldb::ScriptInterpreterSP
312   CreateInstance(CommandInterpreter &interpreter);
313 
314   static lldb_private::ConstString GetPluginNameStatic();
315 
316   static const char *GetPluginDescriptionStatic();
317 
318   static FileSpec GetPythonDir();
319 
320   //------------------------------------------------------------------
321   // PluginInterface protocol
322   //------------------------------------------------------------------
323   lldb_private::ConstString GetPluginName() override;
324 
325   uint32_t GetPluginVersion() override;
326 
327   class Locker : public ScriptInterpreterLocker {
328   public:
329     enum OnEntry {
330       AcquireLock = 0x0001,
331       InitSession = 0x0002,
332       InitGlobals = 0x0004,
333       NoSTDIN = 0x0008
334     };
335 
336     enum OnLeave {
337       FreeLock = 0x0001,
338       FreeAcquiredLock = 0x0002, // do not free the lock if we already held it
339                                  // when calling constructor
340       TearDownSession = 0x0004
341     };
342 
343     Locker(ScriptInterpreterPython *py_interpreter = nullptr,
344            uint16_t on_entry = AcquireLock | InitSession,
345            uint16_t on_leave = FreeLock | TearDownSession, FILE *in = nullptr,
346            FILE *out = nullptr, FILE *err = nullptr);
347 
348     ~Locker() override;
349 
350   private:
351     bool DoAcquireLock();
352 
353     bool DoInitSession(uint16_t on_entry_flags, FILE *in, FILE *out, FILE *err);
354 
355     bool DoFreeLock();
356 
357     bool DoTearDownSession();
358 
359     static void ReleasePythonLock();
360 
361     bool m_teardown_session;
362     ScriptInterpreterPython *m_python_interpreter;
363     //    	FILE*                    m_tmp_fh;
364     PyGILState_STATE m_GILState;
365   };
366 
367 protected:
368   static void InitializePrivate();
369 
370   class SynchronicityHandler {
371   private:
372     lldb::DebuggerSP m_debugger_sp;
373     ScriptedCommandSynchronicity m_synch_wanted;
374     bool m_old_asynch;
375 
376   public:
377     SynchronicityHandler(lldb::DebuggerSP, ScriptedCommandSynchronicity);
378 
379     ~SynchronicityHandler();
380   };
381 
382   enum class AddLocation { Beginning, End };
383 
384   static void AddToSysPath(AddLocation location, std::string path);
385 
386   static void ComputePythonDirForApple(llvm::SmallVectorImpl<char> &path);
387   static void ComputePythonDirForPosix(llvm::SmallVectorImpl<char> &path);
388   static void ComputePythonDirForWindows(llvm::SmallVectorImpl<char> &path);
389 
390   bool EnterSession(uint16_t on_entry_flags, FILE *in, FILE *out, FILE *err);
391 
392   void LeaveSession();
393 
394   void SaveTerminalState(int fd);
395 
396   void RestoreTerminalState();
397 
398   uint32_t IsExecutingPython() const { return m_lock_count > 0; }
399 
400   uint32_t IncrementLockCount() { return ++m_lock_count; }
401 
402   uint32_t DecrementLockCount() {
403     if (m_lock_count > 0)
404       --m_lock_count;
405     return m_lock_count;
406   }
407 
408   enum ActiveIOHandler {
409     eIOHandlerNone,
410     eIOHandlerBreakpoint,
411     eIOHandlerWatchpoint
412   };
413 
414   PythonObject &GetMainModule();
415 
416   PythonDictionary &GetSessionDictionary();
417 
418   PythonDictionary &GetSysModuleDictionary();
419 
420   bool GetEmbeddedInterpreterModuleObjects();
421 
422   bool SetStdHandle(File &file, const char *py_name, PythonFile &save_file,
423                     const char *mode);
424 
425   PythonFile m_saved_stdin;
426   PythonFile m_saved_stdout;
427   PythonFile m_saved_stderr;
428   PythonObject m_main_module;
429   PythonObject m_lldb_module;
430   PythonDictionary m_session_dict;
431   PythonDictionary m_sys_module_dict;
432   PythonObject m_run_one_line_function;
433   PythonObject m_run_one_line_str_global;
434   std::string m_dictionary_name;
435   TerminalState m_terminal_state;
436   ActiveIOHandler m_active_io_handler;
437   bool m_session_is_active;
438   bool m_pty_slave_is_open;
439   bool m_valid_session;
440   uint32_t m_lock_count;
441   PyThreadState *m_command_thread_state;
442 };
443 
444 } // namespace lldb_private
445 
446 #endif // LLDB_DISABLE_PYTHON
447 
448 #endif // LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SCRIPTINTERPRETERPYTHON_H
449