LLDB  mainline
Debugger.h
Go to the documentation of this file.
1 //===-- Debugger.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 liblldb_Debugger_h_
10 #define liblldb_Debugger_h_
11 
12 #include <stdint.h>
13 
14 #include <memory>
15 #include <vector>
16 
17 #include "lldb/Core/FormatEntity.h"
18 #include "lldb/Core/IOHandler.h"
21 #include "lldb/Host/HostThread.h"
22 #include "lldb/Host/Terminal.h"
24 #include "lldb/Target/Platform.h"
25 #include "lldb/Target/TargetList.h"
28 #include "lldb/Utility/FileSpec.h"
29 #include "lldb/Utility/Status.h"
30 #include "lldb/Utility/UserID.h"
31 #include "lldb/lldb-defines.h"
32 #include "lldb/lldb-enumerations.h"
33 #include "lldb/lldb-forward.h"
36 #include "lldb/lldb-types.h"
37 
38 #include "llvm/ADT/ArrayRef.h"
39 #include "llvm/ADT/StringMap.h"
40 #include "llvm/ADT/StringRef.h"
41 #include "llvm/Support/DynamicLibrary.h"
42 #include "llvm/Support/Threading.h"
43 
44 #include <assert.h>
45 #include <stddef.h>
46 #include <stdio.h>
47 
48 namespace lldb_private {
49 class Address;
50 }
51 namespace lldb_private {
52 class CommandInterpreter;
53 }
54 namespace lldb_private {
55 class Process;
56 }
57 namespace lldb_private {
58 class Stream;
59 }
60 namespace lldb_private {
61 class SymbolContext;
62 }
63 namespace lldb_private {
64 class Target;
65 }
66 namespace lldb_private {
67 namespace repro {
68 class DataRecorder;
69 }
70 } // namespace lldb_private
71 namespace llvm {
72 class raw_ostream;
73 }
74 
75 namespace lldb_private {
76 
77 /// \class Debugger Debugger.h "lldb/Core/Debugger.h"
78 /// A class to manage flag bits.
79 ///
80 /// Provides a global root objects for the debugger core.
81 
82 class Debugger : public std::enable_shared_from_this<Debugger>,
83  public UserID,
84  public Properties {
85  friend class SourceManager; // For GetSourceFileCache.
86 
87 public:
88  ~Debugger() override;
89 
90  static lldb::DebuggerSP
91  CreateInstance(lldb::LogOutputCallback log_callback = nullptr,
92  void *baton = nullptr);
93 
94  static lldb::TargetSP FindTargetWithProcessID(lldb::pid_t pid);
95 
96  static lldb::TargetSP FindTargetWithProcess(Process *process);
97 
98  static void Initialize(LoadPluginCallbackType load_plugin_callback);
99 
100  static void Terminate();
101 
102  static void SettingsInitialize();
103 
104  static void SettingsTerminate();
105 
106  static void Destroy(lldb::DebuggerSP &debugger_sp);
107 
108  static lldb::DebuggerSP FindDebuggerWithID(lldb::user_id_t id);
109 
110  static lldb::DebuggerSP
111  FindDebuggerWithInstanceName(ConstString instance_name);
112 
113  static size_t GetNumDebuggers();
114 
115  static lldb::DebuggerSP GetDebuggerAtIndex(size_t index);
116 
117  static bool FormatDisassemblerAddress(const FormatEntity::Entry *format,
118  const SymbolContext *sc,
119  const SymbolContext *prev_sc,
120  const ExecutionContext *exe_ctx,
121  const Address *addr, Stream &s);
122 
123  void Clear();
124 
125  bool GetAsyncExecution();
126 
127  void SetAsyncExecution(bool async);
128 
129  lldb::StreamFileSP GetInputFile() { return m_input_file_sp; }
130 
131  lldb::StreamFileSP GetOutputFile() { return m_output_file_sp; }
132 
133  lldb::StreamFileSP GetErrorFile() { return m_error_file_sp; }
134 
135  repro::DataRecorder *GetInputRecorder();
136 
137  void SetInputFileHandle(FILE *fh, bool tranfer_ownership,
138  repro::DataRecorder *recorder = nullptr);
139 
140  void SetOutputFileHandle(FILE *fh, bool tranfer_ownership);
141 
142  void SetErrorFileHandle(FILE *fh, bool tranfer_ownership);
143 
144  void SaveInputTerminalState();
145 
146  void RestoreInputTerminalState();
147 
148  lldb::StreamSP GetAsyncOutputStream();
149 
150  lldb::StreamSP GetAsyncErrorStream();
151 
153  assert(m_command_interpreter_up.get());
154  return *m_command_interpreter_up;
155  }
156 
157  ScriptInterpreter *GetScriptInterpreter(bool can_create = true);
158 
159  lldb::ListenerSP GetListener() { return m_listener_sp; }
160 
161  // This returns the Debugger's scratch source manager. It won't be able to
162  // look up files in debug information, but it can look up files by absolute
163  // path and display them to you. To get the target's source manager, call
164  // GetSourceManager on the target instead.
165  SourceManager &GetSourceManager();
166 
167  lldb::TargetSP GetSelectedTarget() {
168  return m_target_list.GetSelectedTarget();
169  }
170 
171  ExecutionContext GetSelectedExecutionContext();
172  /// Get accessor for the target list.
173  ///
174  /// The target list is part of the global debugger object. This the single
175  /// debugger shared instance to control where targets get created and to
176  /// allow for tracking and searching for targets based on certain criteria.
177  ///
178  /// \return
179  /// A global shared target list.
180  TargetList &GetTargetList() { return m_target_list; }
181 
182  PlatformList &GetPlatformList() { return m_platform_list; }
183 
184  void DispatchInputInterrupt();
185 
186  void DispatchInputEndOfFile();
187 
188  // If any of the streams are not set, set them to the in/out/err stream of
189  // the top most input reader to ensure they at least have something
190  void AdoptTopIOHandlerFilesIfInvalid(lldb::StreamFileSP &in,
191  lldb::StreamFileSP &out,
192  lldb::StreamFileSP &err);
193 
194  void PushIOHandler(const lldb::IOHandlerSP &reader_sp,
195  bool cancel_top_handler = true);
196 
197  bool PopIOHandler(const lldb::IOHandlerSP &reader_sp);
198 
199  // Synchronously run an input reader until it is done
200  void RunIOHandler(const lldb::IOHandlerSP &reader_sp);
201 
202  bool IsTopIOHandler(const lldb::IOHandlerSP &reader_sp);
203 
204  bool CheckTopIOHandlerTypes(IOHandler::Type top_type,
205  IOHandler::Type second_top_type);
206 
207  void PrintAsync(const char *s, size_t len, bool is_stdout);
208 
209  ConstString GetTopIOHandlerControlSequence(char ch);
210 
211  const char *GetIOHandlerCommandPrefix();
212 
213  const char *GetIOHandlerHelpPrologue();
214 
215  void ClearIOHandlers();
216 
217  bool GetCloseInputOnEOF() const;
218 
219  void SetCloseInputOnEOF(bool b);
220 
221  bool EnableLog(llvm::StringRef channel,
222  llvm::ArrayRef<const char *> categories,
223  llvm::StringRef log_file, uint32_t log_options,
224  llvm::raw_ostream &error_stream);
225 
226  void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
227 
228  // Properties Functions
230  eStopDisassemblyTypeNever = 0,
233  eStopDisassemblyTypeAlways
234  };
235 
236  Status SetPropertyValue(const ExecutionContext *exe_ctx,
237  VarSetOperationType op, llvm::StringRef property_path,
238  llvm::StringRef value) override;
239 
240  bool GetAutoConfirm() const;
241 
242  const FormatEntity::Entry *GetDisassemblyFormat() const;
243 
244  const FormatEntity::Entry *GetFrameFormat() const;
245 
246  const FormatEntity::Entry *GetFrameFormatUnique() const;
247 
248  const FormatEntity::Entry *GetThreadFormat() const;
249 
250  const FormatEntity::Entry *GetThreadStopFormat() const;
251 
252  lldb::ScriptLanguage GetScriptLanguage() const;
253 
254  bool SetScriptLanguage(lldb::ScriptLanguage script_lang);
255 
256  uint32_t GetTerminalWidth() const;
257 
258  bool SetTerminalWidth(uint32_t term_width);
259 
260  llvm::StringRef GetPrompt() const;
261 
262  void SetPrompt(llvm::StringRef p);
263  void SetPrompt(const char *) = delete;
264 
265  llvm::StringRef GetReproducerPath() const;
266 
267  bool GetUseExternalEditor() const;
268 
269  bool SetUseExternalEditor(bool use_external_editor_p);
270 
271  bool GetUseColor() const;
272 
273  bool SetUseColor(bool use_color);
274 
275  bool GetHighlightSource() const;
276 
277  lldb::StopShowColumn GetStopShowColumn() const;
278 
279  llvm::StringRef GetStopShowColumnAnsiPrefix() const;
280 
281  llvm::StringRef GetStopShowColumnAnsiSuffix() const;
282 
283  uint32_t GetStopSourceLineCount(bool before) const;
284 
285  StopDisassemblyType GetStopDisassemblyDisplay() const;
286 
287  uint32_t GetDisassemblyLineCount() const;
288 
289  bool GetAutoOneLineSummaries() const;
290 
291  bool GetAutoIndent() const;
292 
293  bool SetAutoIndent(bool b);
294 
295  bool GetPrintDecls() const;
296 
297  bool SetPrintDecls(bool b);
298 
299  uint32_t GetTabSize() const;
300 
301  bool SetTabSize(uint32_t tab_size);
302 
303  bool GetEscapeNonPrintables() const;
304 
305  bool GetNotifyVoid() const;
306 
307  ConstString GetInstanceName() { return m_instance_name; }
308 
309  bool LoadPlugin(const FileSpec &spec, Status &error);
310 
311  void ExecuteIOHandlers();
312 
313  bool IsForwardingEvents();
314 
315  void EnableForwardEvents(const lldb::ListenerSP &listener_sp);
316 
317  void CancelForwardEvents(const lldb::ListenerSP &listener_sp);
318 
319  bool IsHandlingEvents() const { return m_event_handler_thread.IsJoinable(); }
320 
321  Status RunREPL(lldb::LanguageType language, const char *repl_options);
322 
323  // This is for use in the command interpreter, when you either want the
324  // selected target, or if no target is present you want to prime the dummy
325  // target with entities that will be copied over to new targets.
326  Target *GetSelectedOrDummyTarget(bool prefer_dummy = false);
327  Target *GetDummyTarget();
328 
329  lldb::BroadcasterManagerSP GetBroadcasterManager() {
330  return m_broadcaster_manager_sp;
331  }
332 
333 protected:
334  friend class CommandInterpreter;
335  friend class REPL;
336 
337  bool StartEventHandlerThread();
338 
339  void StopEventHandlerThread();
340 
341  static lldb::thread_result_t EventHandlerThread(lldb::thread_arg_t arg);
342 
343  bool HasIOHandlerThread();
344 
345  bool StartIOHandlerThread();
346 
347  void StopIOHandlerThread();
348 
349  void JoinIOHandlerThread();
350 
351  static lldb::thread_result_t IOHandlerThread(lldb::thread_arg_t arg);
352 
353  void DefaultEventHandler();
354 
355  void HandleBreakpointEvent(const lldb::EventSP &event_sp);
356 
357  void HandleProcessEvent(const lldb::EventSP &event_sp);
358 
359  void HandleThreadEvent(const lldb::EventSP &event_sp);
360 
361  size_t GetProcessSTDOUT(Process *process, Stream *stream);
362 
363  size_t GetProcessSTDERR(Process *process, Stream *stream);
364 
366  return m_source_file_cache;
367  }
368 
369  void InstanceInitialize();
370 
371  lldb::StreamFileSP m_input_file_sp;
372  lldb::StreamFileSP m_output_file_sp;
373  lldb::StreamFileSP m_error_file_sp;
374 
375  /// Used for shadowing the input file when capturing a reproducer.
377 
378  lldb::BroadcasterManagerSP m_broadcaster_manager_sp; // The debugger acts as a
379  // broadcaster manager of
380  // last resort.
381  // It needs to get constructed before the target_list or any other member
382  // that might want to broadcast through the debugger.
383 
384  TerminalState m_terminal_state;
386 
388  lldb::ListenerSP m_listener_sp;
389  std::unique_ptr<SourceManager> m_source_manager_up; // This is a scratch
390  // source manager that we
391  // return if we have no
392  // targets.
394  // for targets created in
395  // this debugger used this
396  // shared
397  // source file cache.
398  std::unique_ptr<CommandInterpreter> m_command_interpreter_up;
399 
400  lldb::ScriptInterpreterSP m_script_interpreter_sp;
401  std::recursive_mutex m_script_interpreter_mutex;
402 
404  llvm::StringMap<std::weak_ptr<llvm::raw_ostream>> m_log_streams;
405  std::shared_ptr<llvm::raw_ostream> m_log_callback_stream_sp;
407  static LoadPluginCallbackType g_load_plugin_callback;
408  typedef std::vector<llvm::sys::DynamicLibrary> LoadedPluginsList;
409  LoadedPluginsList m_loaded_plugins;
413  lldb::ListenerSP m_forward_listener_sp;
414  llvm::once_flag m_clear_once;
415 
416  // Events for m_sync_broadcaster
417  enum {
418  eBroadcastBitEventThreadIsListening = (1 << 0),
419  };
420 
421 private:
422  // Use Debugger::CreateInstance() to get a shared pointer to a new debugger
423  // object
424  Debugger(lldb::LogOutputCallback m_log_callback, void *baton);
425 
426  DISALLOW_COPY_AND_ASSIGN(Debugger);
427 };
428 
429 } // namespace lldb_private
430 
431 #endif // liblldb_Debugger_h_
A class to manage flag bits.
Definition: Debugger.h:82
void * thread_arg_t
Definition: lldb-types.h:61
lldb::StreamFileSP GetInputFile()
Definition: Debugger.h:129
ConstString m_instance_name
Definition: Debugger.h:406
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
Definition: Debugger.h:71
lldb::StreamFileSP GetErrorFile()
Definition: Debugger.h:133
CommandInterpreter & GetCommandInterpreter()
Definition: Debugger.h:152
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
lldb::ListenerSP m_forward_listener_sp
Definition: Debugger.h:413
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
lldb::StreamFileSP m_error_file_sp
Definition: Debugger.h:373
static llvm::sys::DynamicLibrary LoadPlugin(const lldb::DebuggerSP &debugger_sp, const FileSpec &spec, Status &error)
Definition: SBDebugger.cpp:99
A mix in class that contains a generic user ID.
Definition: UserID.h:33
A file utility class.
Definition: FileSpec.h:55
std::vector< llvm::sys::DynamicLibrary > LoadedPluginsList
Definition: Debugger.h:408
lldb::StreamFileSP GetOutputFile()
Definition: Debugger.h:131
An event broadcasting class.
Definition: Broadcaster.h:250
lldb::BroadcasterManagerSP m_broadcaster_manager_sp
Definition: Debugger.h:378
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
llvm::once_flag m_clear_once
Definition: Debugger.h:414
lldb::ListenerSP GetListener()
Definition: Debugger.h:159
PlatformList m_platform_list
Definition: Debugger.h:387
std::unique_ptr< SourceManager > m_source_manager_up
Definition: Debugger.h:389
HostThread m_event_handler_thread
Definition: Debugger.h:410
SourceManager::SourceFileCache & GetSourceFileCache()
Definition: Debugger.h:365
ConstString GetInstanceName()
Definition: Debugger.h:307
TerminalState m_terminal_state
Definition: Debugger.h:384
repro::DataRecorder * m_input_recorder
Used for shadowing the input file when capturing a reproducer.
Definition: Debugger.h:376
uint64_t user_id_t
Definition: lldb-types.h:84
LanguageType
Programming language type.
VarSetOperationType
Settable state variable types.
SourceManager::SourceFileCache m_source_file_cache
Definition: Debugger.h:393
HostThread m_io_handler_thread
Definition: Debugger.h:411
lldb::ScriptInterpreterSP m_script_interpreter_sp
Definition: Debugger.h:400
A plug-in interface definition class for debugging a process.
Definition: Process.h:353
TargetList & GetTargetList()
Get accessor for the target list.
Definition: Debugger.h:180
A section + offset based address class.
Definition: Address.h:80
std::shared_ptr< llvm::raw_ostream > m_log_callback_stream_sp
Definition: Debugger.h:405
void(* LogOutputCallback)(const char *, void *baton)
Definition: lldb-types.h:70
lldb::StreamFileSP m_output_file_sp
Definition: Debugger.h:372
bool IsHandlingEvents() const
Definition: Debugger.h:319
IOHandlerStack m_input_reader_stack
Definition: Debugger.h:403
std::unique_ptr< CommandInterpreter > m_command_interpreter_up
Definition: Debugger.h:398
lldb::ListenerSP m_listener_sp
Definition: Debugger.h:388
lldb::BroadcasterManagerSP GetBroadcasterManager()
Definition: Debugger.h:329
Broadcaster m_sync_broadcaster
Definition: Debugger.h:412
A uniqued constant string class.
Definition: ConstString.h:38
std::recursive_mutex m_script_interpreter_mutex
Definition: Debugger.h:401
uint64_t pid_t
Definition: lldb-types.h:85
static LoadPluginCallbackType g_load_plugin_callback
Definition: Debugger.h:407
lldb::TargetSP GetSelectedTarget()
Definition: Debugger.h:167
LoadedPluginsList m_loaded_plugins
Definition: Debugger.h:409
llvm::StringMap< std::weak_ptr< llvm::raw_ostream > > m_log_streams
Definition: Debugger.h:404
TargetList m_target_list
Definition: Debugger.h:385
PlatformList & GetPlatformList()
Definition: Debugger.h:182
An error handling class.
Definition: Status.h:44
lldb::StreamFileSP m_input_file_sp
Definition: Debugger.h:371
void * thread_result_t
Definition: lldb-types.h:62