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