xref: /llvm-project/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.h (revision 6eec8d6c6f2c179ecea70087bf5f5dff3052dd4b)
1 //===-- ScriptInterpreterPython.h -------------------------------*- C++ -*-===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SCRIPTINTERPRETERPYTHON_H
11 #define LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SCRIPTINTERPRETERPYTHON_H
12 
13 #ifdef LLDB_DISABLE_PYTHON
14 
15 // Python is disabled in this build
16 
17 #else
18 
19 // C Includes
20 // C++ Includes
21 #include <memory>
22 #include <string>
23 #include <vector>
24 
25 // Other libraries and framework includes
26 // Project includes
27 #include "lldb/lldb-private.h"
28 #include "PythonDataObjects.h"
29 #include "lldb/Core/IOHandler.h"
30 #include "lldb/Interpreter/ScriptInterpreter.h"
31 #include "lldb/Host/Terminal.h"
32 
33 class IOHandlerPythonInterpreter;
34 
35 namespace lldb_private {
36 
37 class ScriptInterpreterPython :
38     public ScriptInterpreter,
39     public IOHandlerDelegateMultiline
40 {
41 public:
42 #if PY_MAJOR_VERSION >= 3
43     typedef PyObject*(*SWIGInitCallback) (void);
44 #else
45     typedef void(*SWIGInitCallback) (void);
46 #endif
47 
48     typedef bool (*SWIGBreakpointCallbackFunction) (const char *python_function_name,
49                                                     const char *session_dictionary_name,
50                                                     const lldb::StackFrameSP& frame_sp,
51                                                     const lldb::BreakpointLocationSP &bp_loc_sp);
52 
53     typedef bool (*SWIGWatchpointCallbackFunction) (const char *python_function_name,
54                                                     const char *session_dictionary_name,
55                                                     const lldb::StackFrameSP& frame_sp,
56                                                     const lldb::WatchpointSP &wp_sp);
57 
58     typedef bool (*SWIGPythonTypeScriptCallbackFunction) (const char *python_function_name,
59                                                           void *session_dictionary,
60                                                           const lldb::ValueObjectSP& valobj_sp,
61                                                           void** pyfunct_wrapper,
62                                                           const lldb::TypeSummaryOptionsSP& options,
63                                                           std::string& retval);
64 
65     typedef void* (*SWIGPythonCreateSyntheticProvider) (const char *python_class_name,
66                                                         const char *session_dictionary_name,
67                                                         const lldb::ValueObjectSP& valobj_sp);
68 
69     typedef void* (*SWIGPythonCreateCommandObject) (const char *python_class_name,
70                                                     const char *session_dictionary_name,
71                                                     const lldb::DebuggerSP debugger_sp);
72 
73     typedef void* (*SWIGPythonCreateScriptedThreadPlan) (const char *python_class_name,
74                                                         const char *session_dictionary_name,
75                                                         const lldb::ThreadPlanSP& thread_plan_sp);
76 
77     typedef bool (*SWIGPythonCallThreadPlan) (void *implementor, const char *method_name, Event *event_sp, bool &got_error);
78 
79     typedef void* (*SWIGPythonCreateOSPlugin) (const char *python_class_name,
80                                                const char *session_dictionary_name,
81                                                const lldb::ProcessSP& process_sp);
82 
83     typedef size_t          (*SWIGPythonCalculateNumChildren)                   (void *implementor, uint32_t max);
84 
85     typedef void*           (*SWIGPythonGetChildAtIndex)                        (void *implementor, uint32_t idx);
86 
87     typedef int             (*SWIGPythonGetIndexOfChildWithName)                (void *implementor, const char* child_name);
88 
89     typedef void*           (*SWIGPythonCastPyObjectToSBValue)                  (void* data);
90 
91     typedef lldb::ValueObjectSP  (*SWIGPythonGetValueObjectSPFromSBValue)       (void* data);
92 
93     typedef bool            (*SWIGPythonUpdateSynthProviderInstance)            (void* data);
94 
95     typedef bool            (*SWIGPythonMightHaveChildrenSynthProviderInstance) (void* data);
96 
97     typedef void*           (*SWIGPythonGetValueSynthProviderInstance)          (void *implementor);
98 
99     typedef bool            (*SWIGPythonCallCommand)            (const char *python_function_name,
100                                                                  const char *session_dictionary_name,
101                                                                  lldb::DebuggerSP& debugger,
102                                                                  const char* args,
103                                                                  lldb_private::CommandReturnObject& cmd_retobj,
104                                                                  lldb::ExecutionContextRefSP exe_ctx_ref_sp);
105 
106     typedef bool            (*SWIGPythonCallCommandObject)        (void *implementor,
107                                                                    lldb::DebuggerSP& debugger,
108                                                                    const char* args,
109                                                                    lldb_private::CommandReturnObject& cmd_retobj,
110                                                                    lldb::ExecutionContextRefSP exe_ctx_ref_sp);
111 
112     typedef bool            (*SWIGPythonCallModuleInit)         (const char *python_module_name,
113                                                                  const char *session_dictionary_name,
114                                                                  lldb::DebuggerSP& debugger);
115 
116     typedef bool            (*SWIGPythonScriptKeyword_Process)  (const char* python_function_name,
117                                                                  const char* session_dictionary_name,
118                                                                  lldb::ProcessSP& process,
119                                                                  std::string& output);
120 
121     typedef bool            (*SWIGPythonScriptKeyword_Thread)   (const char* python_function_name,
122                                                                  const char* session_dictionary_name,
123                                                                  lldb::ThreadSP& thread,
124                                                                  std::string& output);
125 
126     typedef bool            (*SWIGPythonScriptKeyword_Target)   (const char* python_function_name,
127                                                                  const char* session_dictionary_name,
128                                                                  lldb::TargetSP& target,
129                                                                  std::string& output);
130 
131     typedef bool            (*SWIGPythonScriptKeyword_Frame)    (const char* python_function_name,
132                                                                  const char* session_dictionary_name,
133                                                                  lldb::StackFrameSP& frame,
134                                                                  std::string& output);
135 
136     typedef bool            (*SWIGPythonScriptKeyword_Value)    (const char* python_function_name,
137                                                                  const char* session_dictionary_name,
138                                                                  lldb::ValueObjectSP& value,
139                                                                  std::string& output);
140 
141     typedef void*           (*SWIGPython_GetDynamicSetting)     (void* module,
142                                                                  const char* setting,
143                                                                  const lldb::TargetSP& target_sp);
144 
145     friend class ::IOHandlerPythonInterpreter;
146 
147     ScriptInterpreterPython (CommandInterpreter &interpreter);
148 
149     ~ScriptInterpreterPython() override;
150 
151     bool
152     Interrupt() override;
153 
154     bool
155     ExecuteOneLine (const char *command,
156                     CommandReturnObject *result,
157                     const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
158 
159     void
160     ExecuteInterpreterLoop () override;
161 
162     bool
163     ExecuteOneLineWithReturn (const char *in_string,
164                               ScriptInterpreter::ScriptReturnType return_type,
165                               void *ret_value,
166                               const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
167 
168     lldb_private::Error
169     ExecuteMultipleLines (const char *in_string,
170                           const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
171 
172     Error
173     ExportFunctionDefinitionToInterpreter (StringList &function_def) override;
174 
175     bool
176     GenerateTypeScriptFunction(StringList &input, std::string& output, const void* name_token = nullptr) override;
177 
178     bool
179     GenerateTypeSynthClass(StringList &input, std::string& output, const void* name_token = nullptr) override;
180 
181     bool
182     GenerateTypeSynthClass(const char* oneliner, std::string& output, const void* name_token = nullptr) override;
183 
184     // use this if the function code is just a one-liner script
185     bool
186     GenerateTypeScriptFunction(const char* oneliner, std::string& output, const void* name_token = nullptr) override;
187 
188     bool
189     GenerateScriptAliasFunction (StringList &input, std::string& output) override;
190 
191     StructuredData::ObjectSP CreateSyntheticScriptedProvider(const char *class_name, lldb::ValueObjectSP valobj) override;
192 
193     StructuredData::GenericSP CreateScriptCommandObject (const char *class_name) override;
194 
195     StructuredData::ObjectSP CreateScriptedThreadPlan(const char *class_name, lldb::ThreadPlanSP thread_plan) override;
196 
197     bool ScriptedThreadPlanExplainsStop(StructuredData::ObjectSP implementor_sp, Event *event, bool &script_error) override;
198 
199     bool ScriptedThreadPlanShouldStop(StructuredData::ObjectSP implementor_sp, Event *event, bool &script_error) override;
200 
201     lldb::StateType ScriptedThreadPlanGetRunState(StructuredData::ObjectSP implementor_sp, bool &script_error) override;
202 
203     StructuredData::GenericSP OSPlugin_CreatePluginObject(const char *class_name, lldb::ProcessSP process_sp) override;
204 
205     StructuredData::DictionarySP OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
206 
207     StructuredData::ArraySP OSPlugin_ThreadsInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
208 
209     StructuredData::StringSP OSPlugin_RegisterContextData(StructuredData::ObjectSP os_plugin_object_sp, lldb::tid_t thread_id) override;
210 
211     StructuredData::DictionarySP OSPlugin_CreateThread(StructuredData::ObjectSP os_plugin_object_sp, lldb::tid_t tid,
212                                                        lldb::addr_t context) override;
213 
214     StructuredData::ObjectSP LoadPluginModule(const FileSpec &file_spec, lldb_private::Error &error) override;
215 
216     StructuredData::DictionarySP GetDynamicSettings(StructuredData::ObjectSP plugin_module_sp, Target *target, const char *setting_name,
217                                                     lldb_private::Error &error) override;
218 
219     size_t CalculateNumChildren(const StructuredData::ObjectSP &implementor, uint32_t max) override;
220 
221     lldb::ValueObjectSP GetChildAtIndex(const StructuredData::ObjectSP &implementor, uint32_t idx) override;
222 
223     int GetIndexOfChildWithName(const StructuredData::ObjectSP &implementor, const char *child_name) override;
224 
225     bool UpdateSynthProviderInstance(const StructuredData::ObjectSP &implementor) override;
226 
227     bool MightHaveChildrenSynthProviderInstance(const StructuredData::ObjectSP &implementor) override;
228 
229     lldb::ValueObjectSP GetSyntheticValue(const StructuredData::ObjectSP &implementor) override;
230 
231     ConstString GetSyntheticTypeName (const StructuredData::ObjectSP &implementor) override;
232 
233     bool
234     RunScriptBasedCommand(const char* impl_function,
235                           const char* args,
236                           ScriptedCommandSynchronicity synchronicity,
237                           lldb_private::CommandReturnObject& cmd_retobj,
238                           Error& error,
239                           const lldb_private::ExecutionContext& exe_ctx) override;
240 
241     bool
242     RunScriptBasedCommand (StructuredData::GenericSP impl_obj_sp,
243                            const char* args,
244                            ScriptedCommandSynchronicity synchronicity,
245                            lldb_private::CommandReturnObject& cmd_retobj,
246                            Error& error,
247                            const lldb_private::ExecutionContext& exe_ctx) override;
248 
249     Error
250     GenerateFunction(const char *signature, const StringList &input) override;
251 
252     Error
253     GenerateBreakpointCommandCallbackData (StringList &input, std::string& output) override;
254 
255     bool
256     GenerateWatchpointCommandCallbackData (StringList &input, std::string& output) override;
257 
258 //    static size_t
259 //    GenerateBreakpointOptionsCommandCallback (void *baton,
260 //                                              InputReader &reader,
261 //                                              lldb::InputReaderAction notification,
262 //                                              const char *bytes,
263 //                                              size_t bytes_len);
264 //
265 //    static size_t
266 //    GenerateWatchpointOptionsCommandCallback (void *baton,
267 //                                              InputReader &reader,
268 //                                              lldb::InputReaderAction notification,
269 //                                              const char *bytes,
270 //                                              size_t bytes_len);
271 
272     static bool
273     BreakpointCallbackFunction (void *baton,
274                                 StoppointCallbackContext *context,
275                                 lldb::user_id_t break_id,
276                                 lldb::user_id_t break_loc_id);
277 
278     static bool
279     WatchpointCallbackFunction (void *baton,
280                                 StoppointCallbackContext *context,
281                                 lldb::user_id_t watch_id);
282 
283     bool GetScriptedSummary(const char *function_name, lldb::ValueObjectSP valobj, StructuredData::ObjectSP &callee_wrapper_sp,
284                             const TypeSummaryOptions &options, std::string &retval) override;
285 
286     void
287     Clear () override;
288 
289     bool
290     GetDocumentationForItem (const char* item, std::string& dest) override;
291 
292     bool
293     GetShortHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp, std::string& dest) override;
294 
295     uint32_t
296     GetFlagsForCommandObject (StructuredData::GenericSP cmd_obj_sp) override;
297 
298     bool
299     GetLongHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp, std::string& dest) override;
300 
301     bool
302     CheckObjectExists (const char* name) override
303     {
304         if (!name || !name[0])
305             return false;
306         std::string temp;
307         return GetDocumentationForItem (name,temp);
308     }
309 
310     bool
311     RunScriptFormatKeyword (const char* impl_function,
312                             Process* process,
313                             std::string& output,
314                             Error& error) override;
315 
316     bool
317     RunScriptFormatKeyword (const char* impl_function,
318                             Thread* thread,
319                             std::string& output,
320                             Error& error) override;
321 
322     bool
323     RunScriptFormatKeyword (const char* impl_function,
324                             Target* target,
325                             std::string& output,
326                             Error& error) override;
327 
328     bool
329     RunScriptFormatKeyword (const char* impl_function,
330                             StackFrame* frame,
331                             std::string& output,
332                             Error& error) override;
333 
334     bool
335     RunScriptFormatKeyword (const char* impl_function,
336                             ValueObject* value,
337                             std::string& output,
338                             Error& error) override;
339 
340     bool LoadScriptingModule(const char *filename, bool can_reload, bool init_session, lldb_private::Error &error,
341                              StructuredData::ObjectSP *module_sp = nullptr) override;
342 
343     bool
344     IsReservedWord (const char* word) override;
345 
346     std::unique_ptr<ScriptInterpreterLocker>
347     AcquireInterpreterLock () override;
348 
349     void
350     CollectDataForBreakpointCommandCallback (std::vector<BreakpointOptions *> &bp_options_vec,
351                                              CommandReturnObject &result) override;
352 
353     void
354     CollectDataForWatchpointCommandCallback (WatchpointOptions *wp_options,
355                                              CommandReturnObject &result) override;
356 
357     /// Set the callback body text into the callback for the breakpoint.
358     Error
359     SetBreakpointCommandCallback (BreakpointOptions *bp_options,
360                                   const char *callback_body) override;
361 
362     void
363     SetBreakpointCommandCallbackFunction (BreakpointOptions *bp_options,
364                                           const char *function_name) override;
365 
366     /// Set a one-liner as the callback for the watchpoint.
367     void
368     SetWatchpointCommandCallback (WatchpointOptions *wp_options,
369                                   const char *oneliner) override;
370 
371     StringList
372     ReadCommandInputFromUser (FILE *in_file);
373 
374     void ResetOutputFileHandle(FILE *new_fh) override;
375 
376     static void
377     InitializePrivate ();
378 
379     static void
380     InitializeInterpreter (SWIGInitCallback python_swig_init_callback,
381                            SWIGBreakpointCallbackFunction swig_breakpoint_callback,
382                            SWIGWatchpointCallbackFunction swig_watchpoint_callback,
383                            SWIGPythonTypeScriptCallbackFunction swig_typescript_callback,
384                            SWIGPythonCreateSyntheticProvider swig_synthetic_script,
385                            SWIGPythonCreateCommandObject swig_create_cmd,
386                            SWIGPythonCalculateNumChildren swig_calc_children,
387                            SWIGPythonGetChildAtIndex swig_get_child_index,
388                            SWIGPythonGetIndexOfChildWithName swig_get_index_child,
389                            SWIGPythonCastPyObjectToSBValue swig_cast_to_sbvalue ,
390                            SWIGPythonGetValueObjectSPFromSBValue swig_get_valobj_sp_from_sbvalue,
391                            SWIGPythonUpdateSynthProviderInstance swig_update_provider,
392                            SWIGPythonMightHaveChildrenSynthProviderInstance swig_mighthavechildren_provider,
393                            SWIGPythonGetValueSynthProviderInstance swig_getvalue_provider,
394                            SWIGPythonCallCommand swig_call_command,
395                            SWIGPythonCallCommandObject swig_call_command_object,
396                            SWIGPythonCallModuleInit swig_call_module_init,
397                            SWIGPythonCreateOSPlugin swig_create_os_plugin,
398                            SWIGPythonScriptKeyword_Process swig_run_script_keyword_process,
399                            SWIGPythonScriptKeyword_Thread swig_run_script_keyword_thread,
400                            SWIGPythonScriptKeyword_Target swig_run_script_keyword_target,
401                            SWIGPythonScriptKeyword_Frame swig_run_script_keyword_frame,
402                            SWIGPythonScriptKeyword_Value swig_run_script_keyword_value,
403                            SWIGPython_GetDynamicSetting swig_plugin_get,
404                            SWIGPythonCreateScriptedThreadPlan swig_thread_plan_script,
405                            SWIGPythonCallThreadPlan swig_call_thread_plan);
406 
407     const char *
408     GetDictionaryName ()
409     {
410         return m_dictionary_name.c_str();
411     }
412 
413     PyThreadState *
414     GetThreadState()
415     {
416         return m_command_thread_state;
417     }
418 
419     void
420     SetThreadState (PyThreadState *s)
421     {
422         if (s)
423             m_command_thread_state = s;
424     }
425 
426     //----------------------------------------------------------------------
427     // IOHandlerDelegate
428     //----------------------------------------------------------------------
429     void
430     IOHandlerActivated (IOHandler &io_handler) override;
431 
432     void
433     IOHandlerInputComplete (IOHandler &io_handler, std::string &data) override;
434 
435     //------------------------------------------------------------------
436     // Static Functions
437     //------------------------------------------------------------------
438     static void
439     Initialize();
440 
441     static void
442     Terminate();
443 
444     static lldb::ScriptInterpreterSP
445     CreateInstance(CommandInterpreter &interpreter);
446 
447     static lldb_private::ConstString
448     GetPluginNameStatic();
449 
450     static const char *
451     GetPluginDescriptionStatic();
452 
453     //------------------------------------------------------------------
454     // PluginInterface protocol
455     //------------------------------------------------------------------
456     lldb_private::ConstString
457     GetPluginName() override;
458 
459     uint32_t
460     GetPluginVersion() override;
461 
462     class Locker : public ScriptInterpreterLocker
463     {
464     public:
465         enum OnEntry
466         {
467             AcquireLock         = 0x0001,
468             InitSession         = 0x0002,
469             InitGlobals         = 0x0004,
470             NoSTDIN             = 0x0008
471         };
472 
473         enum OnLeave
474         {
475             FreeLock            = 0x0001,
476             FreeAcquiredLock    = 0x0002,    // do not free the lock if we already held it when calling constructor
477             TearDownSession     = 0x0004
478         };
479 
480         Locker(ScriptInterpreterPython *py_interpreter = nullptr,
481                uint16_t on_entry = AcquireLock | InitSession,
482                uint16_t on_leave = FreeLock | TearDownSession,
483                FILE *in = nullptr,
484                FILE *out = nullptr,
485                FILE *err = nullptr);
486 
487         ~Locker () override;
488 
489     private:
490         bool
491         DoAcquireLock ();
492 
493         bool
494         DoInitSession (uint16_t on_entry_flags, FILE *in, FILE *out, FILE *err);
495 
496         bool
497         DoFreeLock ();
498 
499         bool
500         DoTearDownSession ();
501 
502         static void
503         ReleasePythonLock ();
504 
505     	bool                     m_teardown_session;
506     	ScriptInterpreterPython *m_python_interpreter;
507 //    	FILE*                    m_tmp_fh;
508         PyGILState_STATE         m_GILState;
509     };
510 
511 protected:
512     class SynchronicityHandler
513     {
514     private:
515         lldb::DebuggerSP             m_debugger_sp;
516         ScriptedCommandSynchronicity m_synch_wanted;
517         bool                         m_old_asynch;
518 
519     public:
520         SynchronicityHandler(lldb::DebuggerSP,
521                              ScriptedCommandSynchronicity);
522 
523         ~SynchronicityHandler();
524     };
525 
526     enum class AddLocation
527     {
528         Beginning,
529         End
530     };
531 
532     static void AddToSysPath(AddLocation location, std::string path);
533 
534     bool
535     EnterSession(uint16_t on_entry_flags,
536                  FILE *in,
537                  FILE *out,
538                  FILE *err);
539 
540     void
541     LeaveSession();
542 
543     void
544     SaveTerminalState(int fd);
545 
546     void
547     RestoreTerminalState();
548 
549     uint32_t
550     IsExecutingPython () const
551     {
552         return m_lock_count > 0;
553     }
554 
555     uint32_t
556     IncrementLockCount()
557     {
558         return ++m_lock_count;
559     }
560 
561     uint32_t
562     DecrementLockCount()
563     {
564         if (m_lock_count > 0)
565             --m_lock_count;
566         return m_lock_count;
567     }
568 
569     enum ActiveIOHandler {
570         eIOHandlerNone,
571         eIOHandlerBreakpoint,
572         eIOHandlerWatchpoint
573     };
574 
575     PythonObject &GetMainModule();
576 
577     PythonDictionary &
578     GetSessionDictionary ();
579 
580     PythonDictionary &
581     GetSysModuleDictionary ();
582 
583     bool
584     GetEmbeddedInterpreterModuleObjects ();
585 
586     bool
587     SetStdHandle(File &file, const char *py_name, PythonFile &save_file, const char *mode);
588 
589     PythonFile m_saved_stdin;
590     PythonFile m_saved_stdout;
591     PythonFile m_saved_stderr;
592     PythonObject m_main_module;
593     PythonObject m_lldb_module;
594     PythonDictionary m_session_dict;
595     PythonDictionary m_sys_module_dict;
596     PythonObject m_run_one_line_function;
597     PythonObject m_run_one_line_str_global;
598     std::string m_dictionary_name;
599     TerminalState m_terminal_state;
600     ActiveIOHandler m_active_io_handler;
601     bool m_session_is_active;
602     bool m_pty_slave_is_open;
603     bool m_valid_session;
604     uint32_t m_lock_count;
605     PyThreadState *m_command_thread_state;
606 };
607 
608 } // namespace lldb_private
609 
610 #endif // LLDB_DISABLE_PYTHON
611 
612 #endif // LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_SCRIPTINTERPRETERPYTHON_H
613