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