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
17namespace lldb_private {
18class CommandPluginInterfaceImplementation;
19namespace python {
20class SWIGBridge;
21}
22} // namespace lldb_private
23
24namespace lldb {
25
26#ifndef SWIG
27class LLDB_API SBInputReader {
28public:
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
43class LLDB_API SBDebugger {
44public:
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
477protected:
478  friend class lldb_private::CommandPluginInterfaceImplementation;
479  friend class lldb_private::python::SWIGBridge;
480
481  SBDebugger(const lldb::DebuggerSP &debugger_sp);
482
483private:
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