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