1 //===-- Debugger.h ----------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef LLDB_CORE_DEBUGGER_H
10 #define LLDB_CORE_DEBUGGER_H
17 #include "lldb/Core/FormatEntity.h"
18 #include "lldb/Core/IOHandler.h"
19 #include "lldb/Core/SourceManager.h"
20 #include "lldb/Core/StreamFile.h"
21 #include "lldb/Core/UserSettingsController.h"
22 #include "lldb/Host/HostThread.h"
23 #include "lldb/Host/Terminal.h"
24 #include "lldb/Target/ExecutionContext.h"
25 #include "lldb/Target/Platform.h"
26 #include "lldb/Target/TargetList.h"
27 #include "lldb/Utility/Broadcaster.h"
28 #include "lldb/Utility/ConstString.h"
29 #include "lldb/Utility/FileSpec.h"
30 #include "lldb/Utility/Status.h"
31 #include "lldb/Utility/UserID.h"
32 #include "lldb/lldb-defines.h"
33 #include "lldb/lldb-enumerations.h"
34 #include "lldb/lldb-forward.h"
35 #include "lldb/lldb-private-enumerations.h"
36 #include "lldb/lldb-private-types.h"
37 #include "lldb/lldb-types.h"
39 #include "llvm/ADT/ArrayRef.h"
40 #include "llvm/ADT/StringMap.h"
41 #include "llvm/ADT/StringRef.h"
42 #include "llvm/Support/DynamicLibrary.h"
43 #include "llvm/Support/Threading.h"
53 namespace lldb_private {
55 class CommandInterpreter;
65 /// \class Debugger Debugger.h "lldb/Core/Debugger.h"
66 /// A class to manage flag bits.
68 /// Provides a global root objects for the debugger core.
70 class Debugger : public std::enable_shared_from_this<Debugger>,
73 friend class SourceManager; // For GetSourceFileCache.
78 static lldb::DebuggerSP
79 CreateInstance(lldb::LogOutputCallback log_callback = nullptr,
80 void *baton = nullptr);
82 static lldb::TargetSP FindTargetWithProcessID(lldb::pid_t pid);
84 static lldb::TargetSP FindTargetWithProcess(Process *process);
86 static void Initialize(LoadPluginCallbackType load_plugin_callback);
88 static void Terminate();
90 static void SettingsInitialize();
92 static void SettingsTerminate();
94 static void Destroy(lldb::DebuggerSP &debugger_sp);
96 static lldb::DebuggerSP FindDebuggerWithID(lldb::user_id_t id);
98 static lldb::DebuggerSP
99 FindDebuggerWithInstanceName(ConstString instance_name);
101 static size_t GetNumDebuggers();
103 static lldb::DebuggerSP GetDebuggerAtIndex(size_t index);
105 static bool FormatDisassemblerAddress(const FormatEntity::Entry *format,
106 const SymbolContext *sc,
107 const SymbolContext *prev_sc,
108 const ExecutionContext *exe_ctx,
109 const Address *addr, Stream &s);
113 bool GetAsyncExecution();
115 void SetAsyncExecution(bool async);
117 lldb::FileSP GetInputFileSP() { return m_input_file_sp; }
119 lldb::StreamFileSP GetOutputStreamSP() { return m_output_stream_sp; }
121 lldb::StreamFileSP GetErrorStreamSP() { return m_error_stream_sp; }
123 File &GetInputFile() { return *m_input_file_sp; }
125 File &GetOutputFile() { return m_output_stream_sp->GetFile(); }
127 File &GetErrorFile() { return m_error_stream_sp->GetFile(); }
129 StreamFile &GetOutputStream() { return *m_output_stream_sp; }
131 StreamFile &GetErrorStream() { return *m_error_stream_sp; }
133 repro::DataRecorder *GetInputRecorder();
135 void SetInputFile(lldb::FileSP file, repro::DataRecorder *recorder = nullptr);
137 void SetOutputFile(lldb::FileSP file);
139 void SetErrorFile(lldb::FileSP file);
141 void SaveInputTerminalState();
143 void RestoreInputTerminalState();
145 lldb::StreamSP GetAsyncOutputStream();
147 lldb::StreamSP GetAsyncErrorStream();
149 CommandInterpreter &GetCommandInterpreter() {
150 assert(m_command_interpreter_up.get());
151 return *m_command_interpreter_up;
155 GetScriptInterpreter(bool can_create = true,
156 llvm::Optional<lldb::ScriptLanguage> language = {});
158 lldb::ListenerSP GetListener() { return m_listener_sp; }
160 // This returns the Debugger's scratch source manager. It won't be able to
161 // look up files in debug information, but it can look up files by absolute
162 // path and display them to you. To get the target's source manager, call
163 // GetSourceManager on the target instead.
164 SourceManager &GetSourceManager();
166 lldb::TargetSP GetSelectedTarget() {
167 return m_target_list.GetSelectedTarget();
170 ExecutionContext GetSelectedExecutionContext();
171 /// Get accessor for the target list.
173 /// The target list is part of the global debugger object. This the single
174 /// debugger shared instance to control where targets get created and to
175 /// allow for tracking and searching for targets based on certain criteria.
178 /// A global shared target list.
179 TargetList &GetTargetList() { return m_target_list; }
181 PlatformList &GetPlatformList() { return m_platform_list; }
183 void DispatchInputInterrupt();
185 void DispatchInputEndOfFile();
187 // If any of the streams are not set, set them to the in/out/err stream of
188 // the top most input reader to ensure they at least have something
189 void AdoptTopIOHandlerFilesIfInvalid(lldb::FileSP &in,
190 lldb::StreamFileSP &out,
191 lldb::StreamFileSP &err);
193 /// Run the given IO handler and return immediately.
194 void RunIOHandlerAsync(const lldb::IOHandlerSP &reader_sp,
195 bool cancel_top_handler = true);
197 /// Run the given IO handler and block until it's complete.
198 void RunIOHandlerSync(const lldb::IOHandlerSP &reader_sp);
200 /// Remove the given IO handler if it's currently active.
201 bool RemoveIOHandler(const lldb::IOHandlerSP &reader_sp);
203 bool IsTopIOHandler(const lldb::IOHandlerSP &reader_sp);
205 bool CheckTopIOHandlerTypes(IOHandler::Type top_type,
206 IOHandler::Type second_top_type);
208 void PrintAsync(const char *s, size_t len, bool is_stdout);
210 ConstString GetTopIOHandlerControlSequence(char ch);
212 const char *GetIOHandlerCommandPrefix();
214 const char *GetIOHandlerHelpPrologue();
216 void ClearIOHandlers();
218 bool GetCloseInputOnEOF() const;
220 void SetCloseInputOnEOF(bool b);
222 bool EnableLog(llvm::StringRef channel,
223 llvm::ArrayRef<const char *> categories,
224 llvm::StringRef log_file, uint32_t log_options,
225 llvm::raw_ostream &error_stream);
227 void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
229 // Properties Functions
230 enum StopDisassemblyType {
231 eStopDisassemblyTypeNever = 0,
232 eStopDisassemblyTypeNoDebugInfo,
233 eStopDisassemblyTypeNoSource,
234 eStopDisassemblyTypeAlways
237 Status SetPropertyValue(const ExecutionContext *exe_ctx,
238 VarSetOperationType op, llvm::StringRef property_path,
239 llvm::StringRef value) override;
241 bool GetAutoConfirm() const;
243 const FormatEntity::Entry *GetDisassemblyFormat() const;
245 const FormatEntity::Entry *GetFrameFormat() const;
247 const FormatEntity::Entry *GetFrameFormatUnique() const;
249 const FormatEntity::Entry *GetThreadFormat() const;
251 const FormatEntity::Entry *GetThreadStopFormat() const;
253 lldb::ScriptLanguage GetScriptLanguage() const;
255 bool SetScriptLanguage(lldb::ScriptLanguage script_lang);
257 uint32_t GetTerminalWidth() const;
259 bool SetTerminalWidth(uint32_t term_width);
261 llvm::StringRef GetPrompt() const;
263 void SetPrompt(llvm::StringRef p);
264 void SetPrompt(const char *) = delete;
266 llvm::StringRef GetReproducerPath() const;
268 bool GetUseExternalEditor() const;
270 bool SetUseExternalEditor(bool use_external_editor_p);
272 bool GetUseColor() const;
274 bool SetUseColor(bool use_color);
276 bool GetUseSourceCache() const;
278 bool SetUseSourceCache(bool use_source_cache);
280 bool GetHighlightSource() const;
282 lldb::StopShowColumn GetStopShowColumn() const;
284 llvm::StringRef GetStopShowColumnAnsiPrefix() const;
286 llvm::StringRef GetStopShowColumnAnsiSuffix() const;
288 uint32_t GetStopSourceLineCount(bool before) const;
290 StopDisassemblyType GetStopDisassemblyDisplay() const;
292 uint32_t GetDisassemblyLineCount() const;
294 llvm::StringRef GetStopShowLineMarkerAnsiPrefix() const;
296 llvm::StringRef GetStopShowLineMarkerAnsiSuffix() const;
298 bool GetAutoOneLineSummaries() const;
300 bool GetAutoIndent() const;
302 bool SetAutoIndent(bool b);
304 bool GetPrintDecls() const;
306 bool SetPrintDecls(bool b);
308 uint32_t GetTabSize() const;
310 bool SetTabSize(uint32_t tab_size);
312 bool GetEscapeNonPrintables() const;
314 bool GetNotifyVoid() const;
316 ConstString GetInstanceName() { return m_instance_name; }
318 bool LoadPlugin(const FileSpec &spec, Status &error);
320 void RunIOHandlers();
322 bool IsForwardingEvents();
324 void EnableForwardEvents(const lldb::ListenerSP &listener_sp);
326 void CancelForwardEvents(const lldb::ListenerSP &listener_sp);
328 bool IsHandlingEvents() const { return m_event_handler_thread.IsJoinable(); }
330 Status RunREPL(lldb::LanguageType language, const char *repl_options);
332 // This is for use in the command interpreter, when you either want the
333 // selected target, or if no target is present you want to prime the dummy
334 // target with entities that will be copied over to new targets.
335 Target *GetSelectedOrDummyTarget(bool prefer_dummy = false);
336 Target *GetDummyTarget() { return m_dummy_target_sp.get(); }
338 lldb::BroadcasterManagerSP GetBroadcasterManager() {
339 return m_broadcaster_manager_sp;
343 friend class CommandInterpreter;
346 bool StartEventHandlerThread();
348 void StopEventHandlerThread();
350 static lldb::thread_result_t EventHandlerThread(lldb::thread_arg_t arg);
352 void PushIOHandler(const lldb::IOHandlerSP &reader_sp,
353 bool cancel_top_handler = true);
355 bool PopIOHandler(const lldb::IOHandlerSP &reader_sp);
357 bool HasIOHandlerThread();
359 bool StartIOHandlerThread();
361 void StopIOHandlerThread();
363 void JoinIOHandlerThread();
365 static lldb::thread_result_t IOHandlerThread(lldb::thread_arg_t arg);
367 void DefaultEventHandler();
369 void HandleBreakpointEvent(const lldb::EventSP &event_sp);
371 void HandleProcessEvent(const lldb::EventSP &event_sp);
373 void HandleThreadEvent(const lldb::EventSP &event_sp);
375 // Ensures two threads don't attempt to flush process output in parallel.
376 std::mutex m_output_flush_mutex;
377 void FlushProcessOutput(Process &process, bool flush_stdout,
380 SourceManager::SourceFileCache &GetSourceFileCache() {
381 return m_source_file_cache;
384 void InstanceInitialize();
386 // these should never be NULL
387 lldb::FileSP m_input_file_sp;
388 lldb::StreamFileSP m_output_stream_sp;
389 lldb::StreamFileSP m_error_stream_sp;
391 /// Used for shadowing the input file when capturing a reproducer.
392 repro::DataRecorder *m_input_recorder;
394 lldb::BroadcasterManagerSP m_broadcaster_manager_sp; // The debugger acts as a
395 // broadcaster manager of
397 // It needs to get constructed before the target_list or any other member
398 // that might want to broadcast through the debugger.
400 TerminalState m_terminal_state;
401 TargetList m_target_list;
403 PlatformList m_platform_list;
404 lldb::ListenerSP m_listener_sp;
405 std::unique_ptr<SourceManager> m_source_manager_up; // This is a scratch
406 // source manager that we
407 // return if we have no
409 SourceManager::SourceFileCache m_source_file_cache; // All the source managers
410 // for targets created in
411 // this debugger used this
413 // source file cache.
414 std::unique_ptr<CommandInterpreter> m_command_interpreter_up;
416 std::recursive_mutex m_script_interpreter_mutex;
417 std::array<lldb::ScriptInterpreterSP, lldb::eScriptLanguageUnknown>
418 m_script_interpreters;
420 IOHandlerStack m_io_handler_stack;
421 std::recursive_mutex m_io_handler_synchronous_mutex;
423 llvm::StringMap<std::weak_ptr<llvm::raw_ostream>> m_log_streams;
424 std::shared_ptr<llvm::raw_ostream> m_log_callback_stream_sp;
425 ConstString m_instance_name;
426 static LoadPluginCallbackType g_load_plugin_callback;
427 typedef std::vector<llvm::sys::DynamicLibrary> LoadedPluginsList;
428 LoadedPluginsList m_loaded_plugins;
429 HostThread m_event_handler_thread;
430 HostThread m_io_handler_thread;
431 Broadcaster m_sync_broadcaster;
432 lldb::ListenerSP m_forward_listener_sp;
433 llvm::once_flag m_clear_once;
434 lldb::TargetSP m_dummy_target_sp;
436 // Events for m_sync_broadcaster
438 eBroadcastBitEventThreadIsListening = (1 << 0),
442 // Use Debugger::CreateInstance() to get a shared pointer to a new debugger
444 Debugger(lldb::LogOutputCallback m_log_callback, void *baton);
446 Debugger(const Debugger &) = delete;
447 const Debugger &operator=(const Debugger &) = delete;
450 } // namespace lldb_private
452 #endif // LLDB_CORE_DEBUGGER_H