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