1 //===-- SBDebugger.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_API_SBDEBUGGER_H
10 #define LLDB_API_SBDEBUGGER_H
11 
12 #include <cstdio>
13 
14 #include "lldb/API/SBDefines.h"
15 #include "lldb/API/SBPlatform.h"
16 
17 namespace lldb_private {
18 class CommandPluginInterfaceImplementation;
19 namespace python {
20 class SWIGBridge;
21 }
22 } // namespace lldb_private
23 
24 namespace lldb {
25 
26 #ifndef SWIG
27 class LLDB_API SBInputReader {
28 public:
29   SBInputReader() = default;
30   ~SBInputReader() = default;
31 
32   SBError Initialize(lldb::SBDebugger &sb_debugger,
33                      unsigned long (*callback)(void *, lldb::SBInputReader *,
34                                                lldb::InputReaderAction,
35                                                char const *, unsigned long),
36                      void *a, lldb::InputReaderGranularity b, char const *c,
37                      char const *d, bool e);
38   void SetIsDone(bool);
39   bool IsActive() const;
40 };
41 #endif
42 
43 class LLDB_API SBDebugger {
44 public:
FLAGS_ANONYMOUS_ENUM()45   FLAGS_ANONYMOUS_ENUM(){
46       eBroadcastBitProgress = (1 << 0),
47       eBroadcastBitWarning = (1 << 1),
48       eBroadcastBitError = (1 << 2),
49       eBroadcastBitProgressCategory = (1 << 3),
50   };
51 
52   SBDebugger();
53 
54   SBDebugger(const lldb::SBDebugger &rhs);
55 
56   ~SBDebugger();
57 
58   static const char *GetBroadcasterClass();
59 
60   lldb::SBBroadcaster GetBroadcaster();
61 
62   /// Get progress data from a SBEvent whose type is eBroadcastBitProgress.
63   ///
64   /// \param [in] event
65   ///   The event to extract the progress information from.
66   ///
67   /// \param [out] progress_id
68   ///   The unique integer identifier for the progress to report.
69   ///
70   /// \param [out] completed
71   ///   The amount of work completed. If \a completed is zero, then this event
72   ///   is a progress started event. If \a completed is equal to \a total, then
73   ///   this event is a progress end event. Otherwise completed indicates the
74   ///   current progress update.
75   ///
76   /// \param [out] total
77   ///   The total amount of work units that need to be completed. If this value
78   ///   is UINT64_MAX, then an indeterminate progress indicator should be
79   ///   displayed.
80   ///
81   /// \param [out] is_debugger_specific
82   ///   Set to true if this progress is specific to this debugger only. Many
83   ///   progress events are not specific to a debugger instance, like any
84   ///   progress events for loading information in modules since LLDB has a
85   ///   global module cache that all debuggers use.
86   ///
87   /// \return The message for the progress. If the returned value is NULL, then
88   ///   \a event was not a eBroadcastBitProgress event.
89 #ifdef SWIG
90   static const char *GetProgressFromEvent(const lldb::SBEvent &event,
91                                           uint64_t &OUTPUT,
92                                           uint64_t &OUTPUT, uint64_t &OUTPUT,
93                                           bool &OUTPUT);
94 #else
95   static const char *GetProgressFromEvent(const lldb::SBEvent &event,
96                                           uint64_t &progress_id,
97                                           uint64_t &completed, uint64_t &total,
98                                           bool &is_debugger_specific);
99 #endif
100 
101   static lldb::SBStructuredData
102   GetProgressDataFromEvent(const lldb::SBEvent &event);
103 
104   static lldb::SBStructuredData
105   GetDiagnosticFromEvent(const lldb::SBEvent &event);
106 
107   lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs);
108 
109   static void Initialize();
110 
111   static lldb::SBError InitializeWithErrorHandling();
112 
113   static void PrintStackTraceOnError();
114 
115   static void PrintDiagnosticsOnError();
116 
117   static void Terminate();
118 
119   LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)")
120   static lldb::SBDebugger Create();
121 
122   static lldb::SBDebugger Create(bool source_init_files);
123 
124   static lldb::SBDebugger Create(bool source_init_files,
125                                  lldb::LogOutputCallback log_callback,
126                                  void *baton);
127 
128   static void Destroy(lldb::SBDebugger &debugger);
129 
130   static void MemoryPressureDetected();
131 
132   explicit operator bool() const;
133 
134   bool IsValid() const;
135 
136   void Clear();
137 
138   /// Getting a specific setting value into SBStructuredData format.
139   /// Client can specify empty string or null to get all settings.
140   ///
141   /// Example usages:
142   /// lldb::SBStructuredData settings = debugger.GetSetting();
143   /// lldb::SBStructuredData settings = debugger.GetSetting(nullptr);
144   /// lldb::SBStructuredData settings = debugger.GetSetting("");
145   /// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0");
146   /// lldb::SBStructuredData settings = debugger.GetSetting("target");
147   ///
148   /// \param[out] setting
149   ///   Property setting path to retrieve values. e.g "target.source-map"
150   ///
151   lldb::SBStructuredData GetSetting(const char *setting = nullptr);
152 
153   void SetAsync(bool b);
154 
155   bool GetAsync();
156 
157   void SkipLLDBInitFiles(bool b);
158 
159   void SkipAppInitFiles(bool b);
160 
161 #ifndef SWIG
162   void SetInputFileHandle(FILE *f, bool transfer_ownership);
163 
164   void SetOutputFileHandle(FILE *f, bool transfer_ownership);
165 
166   void SetErrorFileHandle(FILE *f, bool transfer_ownership);
167 #endif
168 
169 #ifndef SWIG
170   FILE *GetInputFileHandle();
171 
172   FILE *GetOutputFileHandle();
173 
174   FILE *GetErrorFileHandle();
175 #endif
176 
177   SBError SetInputString(const char *data);
178 
179   SBError SetInputFile(SBFile file);
180 
181   SBError SetOutputFile(SBFile file);
182 
183   SBError SetErrorFile(SBFile file);
184 
185   SBError SetInputFile(FileSP file);
186 
187   SBError SetOutputFile(FileSP file);
188 
189   SBError SetErrorFile(FileSP file);
190 
191   SBFile GetInputFile();
192 
193   SBFile GetOutputFile();
194 
195   SBFile GetErrorFile();
196 
197   void SaveInputTerminalState();
198 
199   void RestoreInputTerminalState();
200 
201   lldb::SBCommandInterpreter GetCommandInterpreter();
202 
203   void HandleCommand(const char *command);
204 
205   void RequestInterrupt();
206   void CancelInterruptRequest();
207   bool InterruptRequested();
208 
209   lldb::SBListener GetListener();
210 
211 #ifndef SWIG
212   LLDB_DEPRECATED_FIXME(
213       "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, "
214       "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, "
215       "FileSP, FileSP)",
216       "HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, SBFile)")
217   void HandleProcessEvent(const lldb::SBProcess &process,
218                           const lldb::SBEvent &event, FILE *out, FILE *err);
219 #endif
220 
221   void HandleProcessEvent(const lldb::SBProcess &process,
222                           const lldb::SBEvent &event, SBFile out, SBFile err);
223 
224 #ifdef SWIG
225   void HandleProcessEvent(const lldb::SBProcess &process,
226                           const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED);
227 #else
228   void HandleProcessEvent(const lldb::SBProcess &process,
229                           const lldb::SBEvent &event, FileSP out, FileSP err);
230 #endif
231 
232   lldb::SBTarget CreateTarget(const char *filename, const char *target_triple,
233                               const char *platform_name,
234                               bool add_dependent_modules, lldb::SBError &error);
235 
236   lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename,
237                                                      const char *target_triple);
238 
239   lldb::SBTarget CreateTargetWithFileAndArch(const char *filename,
240                                              const char *archname);
241 
242   lldb::SBTarget CreateTarget(const char *filename);
243 
244   lldb::SBTarget GetDummyTarget();
245 
246   // Return true if target is deleted from the target list of the debugger.
247   bool DeleteTarget(lldb::SBTarget &target);
248 
249   lldb::SBTarget GetTargetAtIndex(uint32_t idx);
250 
251   uint32_t GetIndexOfTarget(lldb::SBTarget target);
252 
253   lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid);
254 
255   lldb::SBTarget FindTargetWithFileAndArch(const char *filename,
256                                            const char *arch);
257 
258   uint32_t GetNumTargets();
259 
260   lldb::SBTarget GetSelectedTarget();
261 
262   void SetSelectedTarget(SBTarget &target);
263 
264   lldb::SBPlatform GetSelectedPlatform();
265 
266   void SetSelectedPlatform(lldb::SBPlatform &platform);
267 
268   /// Get the number of currently active platforms.
269   uint32_t GetNumPlatforms();
270 
271   /// Get one of the currently active platforms.
272   lldb::SBPlatform GetPlatformAtIndex(uint32_t idx);
273 
274   /// Get the number of available platforms.
275   ///
276   /// The return value should match the number of entries output by the
277   /// "platform list" command.
278   uint32_t GetNumAvailablePlatforms();
279 
280   /// Get the name and description of one of the available platforms.
281   ///
282   /// \param[in] idx
283   ///     Zero-based index of the platform for which info should be retrieved,
284   ///     must be less than the value returned by GetNumAvailablePlatforms().
285   lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx);
286 
287   lldb::SBSourceManager GetSourceManager();
288 
289   // REMOVE: just for a quick fix, need to expose platforms through
290   // SBPlatform from this class.
291   lldb::SBError SetCurrentPlatform(const char *platform_name);
292 
293   bool SetCurrentPlatformSDKRoot(const char *sysroot);
294 
295   // FIXME: Once we get the set show stuff in place, the driver won't need
296   // an interface to the Set/Get UseExternalEditor.
297   bool SetUseExternalEditor(bool input);
298 
299   bool GetUseExternalEditor();
300 
301   bool SetUseColor(bool use_color);
302 
303   bool GetUseColor() const;
304 
305   bool SetUseSourceCache(bool use_source_cache);
306 
307   bool GetUseSourceCache() const;
308 
309   static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len);
310 
311   static bool SetDefaultArchitecture(const char *arch_name);
312 
313   lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name);
314 
315   SBStructuredData GetScriptInterpreterInfo(ScriptLanguage);
316 
317   static const char *GetVersionString();
318 
319   static const char *StateAsCString(lldb::StateType state);
320 
321   static SBStructuredData GetBuildConfiguration();
322 
323   static bool StateIsRunningState(lldb::StateType state);
324 
325   static bool StateIsStoppedState(lldb::StateType state);
326 
327   bool EnableLog(const char *channel, const char **categories);
328 
329   void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
330 
331   void SetDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback,
332                           void *baton);
333 
334 #ifndef SWIG
335   LLDB_DEPRECATED_FIXME("Use DispatchInput(const void *, size_t)",
336                         "DispatchInput(const void *, size_t)")
337   void DispatchInput(void *baton, const void *data, size_t data_len);
338 #endif
339 
340   void DispatchInput(const void *data, size_t data_len);
341 
342   void DispatchInputInterrupt();
343 
344   void DispatchInputEndOfFile();
345 
346 #ifndef SWIG
347   void PushInputReader(lldb::SBInputReader &reader);
348 #endif
349 
350   const char *GetInstanceName();
351 
352   static SBDebugger FindDebuggerWithID(int id);
353 
354   static lldb::SBError SetInternalVariable(const char *var_name,
355                                            const char *value,
356                                            const char *debugger_instance_name);
357 
358   static lldb::SBStringList
359   GetInternalVariableValue(const char *var_name,
360                            const char *debugger_instance_name);
361 
362   bool GetDescription(lldb::SBStream &description);
363 
364   uint32_t GetTerminalWidth() const;
365 
366   void SetTerminalWidth(uint32_t term_width);
367 
368   lldb::user_id_t GetID();
369 
370   const char *GetPrompt() const;
371 
372   void SetPrompt(const char *prompt);
373 
374   const char *GetReproducerPath() const;
375 
376   lldb::ScriptLanguage GetScriptLanguage() const;
377 
378   void SetScriptLanguage(lldb::ScriptLanguage script_lang);
379 
380   lldb::LanguageType GetREPLLanguage() const;
381 
382   void SetREPLLanguage(lldb::LanguageType repl_lang);
383 
384   LLDB_DEPRECATED("SBDebugger::GetCloseInputOnEOF() is deprecated.")
385   bool GetCloseInputOnEOF() const;
386 
387   LLDB_DEPRECATED("SBDebugger::SetCloseInputOnEOF() is deprecated.")
388   void SetCloseInputOnEOF(bool b);
389 
390   SBTypeCategory GetCategory(const char *category_name);
391 
392   SBTypeCategory GetCategory(lldb::LanguageType lang_type);
393 
394   SBTypeCategory CreateCategory(const char *category_name);
395 
396   bool DeleteCategory(const char *category_name);
397 
398   uint32_t GetNumCategories();
399 
400   SBTypeCategory GetCategoryAtIndex(uint32_t);
401 
402   SBTypeCategory GetDefaultCategory();
403 
404   SBTypeFormat GetFormatForType(SBTypeNameSpecifier);
405 
406   SBTypeSummary GetSummaryForType(SBTypeNameSpecifier);
407 
408   SBTypeFilter GetFilterForType(SBTypeNameSpecifier);
409 
410   SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier);
411 
412 #ifndef SWIG
413   /// Run the command interpreter.
414   ///
415   /// \param[in] auto_handle_events
416   ///     If true, automatically handle resulting events. This takes precedence
417   ///     and overrides the corresponding option in
418   ///     SBCommandInterpreterRunOptions.
419   ///
420   /// \param[in] spawn_thread
421   ///     If true, start a new thread for IO handling. This takes precedence
422   ///     and overrides the corresponding option in
423   ///     SBCommandInterpreterRunOptions.
424   void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread);
425 #endif
426 
427   /// Run the command interpreter.
428   ///
429   /// \param[in] auto_handle_events
430   ///     If true, automatically handle resulting events. This takes precedence
431   ///     and overrides the corresponding option in
432   ///     SBCommandInterpreterRunOptions.
433   ///
434   /// \param[in] spawn_thread
435   ///     If true, start a new thread for IO handling. This takes precedence
436   ///     and overrides the corresponding option in
437   ///     SBCommandInterpreterRunOptions.
438   ///
439   /// \param[in] options
440   ///     Parameter collection of type SBCommandInterpreterRunOptions.
441   ///
442   /// \param[out] num_errors
443   ///     The number of errors.
444   ///
445   /// \param[out] quit_requested
446   ///     Whether a quit was requested.
447   ///
448   /// \param[out] stopped_for_crash
449   ///     Whether the interpreter stopped for a crash.
450 #ifdef SWIG
451   %apply int& INOUT { int& num_errors };
452   %apply bool& INOUT { bool& quit_requested };
453   %apply bool& INOUT { bool& stopped_for_crash };
454 #endif
455   void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread,
456                              SBCommandInterpreterRunOptions &options,
457                              int &num_errors, bool &quit_requested,
458                              bool &stopped_for_crash);
459 
460 #ifndef SWIG
461   SBCommandInterpreterRunResult
462   RunCommandInterpreter(const SBCommandInterpreterRunOptions &options);
463 #endif
464 
465   SBError RunREPL(lldb::LanguageType language, const char *repl_options);
466 
467   /// Load a trace from a trace description file and create Targets,
468   /// Processes and Threads based on the contents of such file.
469   ///
470   /// \param[out] error
471   ///   An error if the trace could not be created.
472   ///
473   /// \param[in] trace_description_file
474   ///   The file containing the necessary information to load the trace.
475   SBTrace LoadTraceFromFile(SBError &error,
476                             const SBFileSpec &trace_description_file);
477 
478 protected:
479   friend class lldb_private::CommandPluginInterfaceImplementation;
480   friend class lldb_private::python::SWIGBridge;
481 
482   SBDebugger(const lldb::DebuggerSP &debugger_sp);
483 
484 private:
485   friend class SBCommandInterpreter;
486   friend class SBInputReader;
487   friend class SBListener;
488   friend class SBProcess;
489   friend class SBSourceManager;
490   friend class SBStructuredData;
491   friend class SBPlatform;
492   friend class SBTarget;
493   friend class SBTrace;
494 
495   lldb::SBTarget FindTargetWithLLDBProcess(const lldb::ProcessSP &processSP);
496 
497   void reset(const lldb::DebuggerSP &debugger_sp);
498 
499   lldb_private::Debugger *get() const;
500 
501   lldb_private::Debugger &ref() const;
502 
503   const lldb::DebuggerSP &get_sp() const;
504 
505   lldb::DebuggerSP m_opaque_sp;
506 
507 }; // class SBDebugger
508 
509 } // namespace lldb
510 
511 #endif // LLDB_API_SBDEBUGGER_H
512