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: |
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 | |