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