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 LLDB_CORE_DEBUGGER_H 10 #define LLDB_CORE_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/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" 38 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" 44 45 #include <assert.h> 46 #include <stddef.h> 47 #include <stdio.h> 48 49 namespace llvm { 50 class raw_ostream; 51 } 52 53 namespace lldb_private { 54 class Address; 55 class CommandInterpreter; 56 class Process; 57 class Stream; 58 class SymbolContext; 59 class Target; 60 61 namespace repro { 62 class DataRecorder; 63 } 64 65 /// \class Debugger Debugger.h "lldb/Core/Debugger.h" 66 /// A class to manage flag bits. 67 /// 68 /// Provides a global root objects for the debugger core. 69 70 class Debugger : public std::enable_shared_from_this<Debugger>, 71 public UserID, 72 public Properties { 73 friend class SourceManager; // For GetSourceFileCache. 74 75 public: 76 ~Debugger() override; 77 78 static lldb::DebuggerSP 79 CreateInstance(lldb::LogOutputCallback log_callback = nullptr, 80 void *baton = nullptr); 81 82 static lldb::TargetSP FindTargetWithProcessID(lldb::pid_t pid); 83 84 static lldb::TargetSP FindTargetWithProcess(Process *process); 85 86 static void Initialize(LoadPluginCallbackType load_plugin_callback); 87 88 static void Terminate(); 89 90 static void SettingsInitialize(); 91 92 static void SettingsTerminate(); 93 94 static void Destroy(lldb::DebuggerSP &debugger_sp); 95 96 static lldb::DebuggerSP FindDebuggerWithID(lldb::user_id_t id); 97 98 static lldb::DebuggerSP 99 FindDebuggerWithInstanceName(ConstString instance_name); 100 101 static size_t GetNumDebuggers(); 102 103 static lldb::DebuggerSP GetDebuggerAtIndex(size_t index); 104 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); 110 111 void Clear(); 112 113 bool GetAsyncExecution(); 114 115 void SetAsyncExecution(bool async); 116 GetInputFileSP()117 lldb::FileSP GetInputFileSP() { return m_input_file_sp; } 118 GetOutputStreamSP()119 lldb::StreamFileSP GetOutputStreamSP() { return m_output_stream_sp; } 120 GetErrorStreamSP()121 lldb::StreamFileSP GetErrorStreamSP() { return m_error_stream_sp; } 122 GetInputFile()123 File &GetInputFile() { return *m_input_file_sp; } 124 GetOutputFile()125 File &GetOutputFile() { return m_output_stream_sp->GetFile(); } 126 GetErrorFile()127 File &GetErrorFile() { return m_error_stream_sp->GetFile(); } 128 GetOutputStream()129 StreamFile &GetOutputStream() { return *m_output_stream_sp; } 130 GetErrorStream()131 StreamFile &GetErrorStream() { return *m_error_stream_sp; } 132 133 repro::DataRecorder *GetInputRecorder(); 134 135 void SetInputFile(lldb::FileSP file, repro::DataRecorder *recorder = nullptr); 136 137 void SetOutputFile(lldb::FileSP file); 138 139 void SetErrorFile(lldb::FileSP file); 140 141 void SaveInputTerminalState(); 142 143 void RestoreInputTerminalState(); 144 145 lldb::StreamSP GetAsyncOutputStream(); 146 147 lldb::StreamSP GetAsyncErrorStream(); 148 GetCommandInterpreter()149 CommandInterpreter &GetCommandInterpreter() { 150 assert(m_command_interpreter_up.get()); 151 return *m_command_interpreter_up; 152 } 153 154 ScriptInterpreter * 155 GetScriptInterpreter(bool can_create = true, 156 llvm::Optional<lldb::ScriptLanguage> language = {}); 157 GetListener()158 lldb::ListenerSP GetListener() { return m_listener_sp; } 159 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(); 165 GetSelectedTarget()166 lldb::TargetSP GetSelectedTarget() { 167 return m_target_list.GetSelectedTarget(); 168 } 169 170 ExecutionContext GetSelectedExecutionContext(); 171 /// Get accessor for the target list. 172 /// 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. 176 /// 177 /// \return 178 /// A global shared target list. GetTargetList()179 TargetList &GetTargetList() { return m_target_list; } 180 GetPlatformList()181 PlatformList &GetPlatformList() { return m_platform_list; } 182 183 void DispatchInputInterrupt(); 184 185 void DispatchInputEndOfFile(); 186 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); 192 193 /// Run the given IO handler and return immediately. 194 void RunIOHandlerAsync(const lldb::IOHandlerSP &reader_sp, 195 bool cancel_top_handler = true); 196 197 /// Run the given IO handler and block until it's complete. 198 void RunIOHandlerSync(const lldb::IOHandlerSP &reader_sp); 199 200 /// Remove the given IO handler if it's currently active. 201 bool RemoveIOHandler(const lldb::IOHandlerSP &reader_sp); 202 203 bool IsTopIOHandler(const lldb::IOHandlerSP &reader_sp); 204 205 bool CheckTopIOHandlerTypes(IOHandler::Type top_type, 206 IOHandler::Type second_top_type); 207 208 void PrintAsync(const char *s, size_t len, bool is_stdout); 209 210 ConstString GetTopIOHandlerControlSequence(char ch); 211 212 const char *GetIOHandlerCommandPrefix(); 213 214 const char *GetIOHandlerHelpPrologue(); 215 216 void ClearIOHandlers(); 217 218 bool GetCloseInputOnEOF() const; 219 220 void SetCloseInputOnEOF(bool b); 221 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); 226 227 void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton); 228 229 // Properties Functions 230 enum StopDisassemblyType { 231 eStopDisassemblyTypeNever = 0, 232 eStopDisassemblyTypeNoDebugInfo, 233 eStopDisassemblyTypeNoSource, 234 eStopDisassemblyTypeAlways 235 }; 236 237 Status SetPropertyValue(const ExecutionContext *exe_ctx, 238 VarSetOperationType op, llvm::StringRef property_path, 239 llvm::StringRef value) override; 240 241 bool GetAutoConfirm() const; 242 243 const FormatEntity::Entry *GetDisassemblyFormat() const; 244 245 const FormatEntity::Entry *GetFrameFormat() const; 246 247 const FormatEntity::Entry *GetFrameFormatUnique() const; 248 249 const FormatEntity::Entry *GetThreadFormat() const; 250 251 const FormatEntity::Entry *GetThreadStopFormat() const; 252 253 lldb::ScriptLanguage GetScriptLanguage() const; 254 255 bool SetScriptLanguage(lldb::ScriptLanguage script_lang); 256 257 uint32_t GetTerminalWidth() const; 258 259 bool SetTerminalWidth(uint32_t term_width); 260 261 llvm::StringRef GetPrompt() const; 262 263 void SetPrompt(llvm::StringRef p); 264 void SetPrompt(const char *) = delete; 265 266 llvm::StringRef GetReproducerPath() const; 267 268 bool GetUseExternalEditor() const; 269 270 bool SetUseExternalEditor(bool use_external_editor_p); 271 272 bool GetUseColor() const; 273 274 bool SetUseColor(bool use_color); 275 276 bool GetUseAutosuggestion() const; 277 278 bool GetUseSourceCache() const; 279 280 bool SetUseSourceCache(bool use_source_cache); 281 282 bool GetHighlightSource() const; 283 284 lldb::StopShowColumn GetStopShowColumn() const; 285 286 llvm::StringRef GetStopShowColumnAnsiPrefix() const; 287 288 llvm::StringRef GetStopShowColumnAnsiSuffix() const; 289 290 uint32_t GetStopSourceLineCount(bool before) const; 291 292 StopDisassemblyType GetStopDisassemblyDisplay() const; 293 294 uint32_t GetDisassemblyLineCount() const; 295 296 llvm::StringRef GetStopShowLineMarkerAnsiPrefix() const; 297 298 llvm::StringRef GetStopShowLineMarkerAnsiSuffix() const; 299 300 bool GetAutoOneLineSummaries() const; 301 302 bool GetAutoIndent() const; 303 304 bool SetAutoIndent(bool b); 305 306 bool GetPrintDecls() const; 307 308 bool SetPrintDecls(bool b); 309 310 uint32_t GetTabSize() const; 311 312 bool SetTabSize(uint32_t tab_size); 313 314 bool GetEscapeNonPrintables() const; 315 316 bool GetNotifyVoid() const; 317 GetInstanceName()318 ConstString GetInstanceName() { return m_instance_name; } 319 320 bool LoadPlugin(const FileSpec &spec, Status &error); 321 322 void RunIOHandlers(); 323 324 bool IsForwardingEvents(); 325 326 void EnableForwardEvents(const lldb::ListenerSP &listener_sp); 327 328 void CancelForwardEvents(const lldb::ListenerSP &listener_sp); 329 IsHandlingEvents()330 bool IsHandlingEvents() const { return m_event_handler_thread.IsJoinable(); } 331 332 Status RunREPL(lldb::LanguageType language, const char *repl_options); 333 334 // This is for use in the command interpreter, when you either want the 335 // selected target, or if no target is present you want to prime the dummy 336 // target with entities that will be copied over to new targets. 337 Target &GetSelectedOrDummyTarget(bool prefer_dummy = false); GetDummyTarget()338 Target &GetDummyTarget() { return *m_dummy_target_sp; } 339 GetBroadcasterManager()340 lldb::BroadcasterManagerSP GetBroadcasterManager() { 341 return m_broadcaster_manager_sp; 342 } 343 344 protected: 345 friend class CommandInterpreter; 346 friend class REPL; 347 348 bool StartEventHandlerThread(); 349 350 void StopEventHandlerThread(); 351 352 static lldb::thread_result_t EventHandlerThread(lldb::thread_arg_t arg); 353 354 void PushIOHandler(const lldb::IOHandlerSP &reader_sp, 355 bool cancel_top_handler = true); 356 357 bool PopIOHandler(const lldb::IOHandlerSP &reader_sp); 358 359 bool HasIOHandlerThread(); 360 361 bool StartIOHandlerThread(); 362 363 void StopIOHandlerThread(); 364 365 void JoinIOHandlerThread(); 366 367 static lldb::thread_result_t IOHandlerThread(lldb::thread_arg_t arg); 368 369 void DefaultEventHandler(); 370 371 void HandleBreakpointEvent(const lldb::EventSP &event_sp); 372 373 void HandleProcessEvent(const lldb::EventSP &event_sp); 374 375 void HandleThreadEvent(const lldb::EventSP &event_sp); 376 377 // Ensures two threads don't attempt to flush process output in parallel. 378 std::mutex m_output_flush_mutex; 379 void FlushProcessOutput(Process &process, bool flush_stdout, 380 bool flush_stderr); 381 GetSourceFileCache()382 SourceManager::SourceFileCache &GetSourceFileCache() { 383 return m_source_file_cache; 384 } 385 386 void InstanceInitialize(); 387 388 // these should never be NULL 389 lldb::FileSP m_input_file_sp; 390 lldb::StreamFileSP m_output_stream_sp; 391 lldb::StreamFileSP m_error_stream_sp; 392 393 /// Used for shadowing the input file when capturing a reproducer. 394 repro::DataRecorder *m_input_recorder; 395 396 lldb::BroadcasterManagerSP m_broadcaster_manager_sp; // The debugger acts as a 397 // broadcaster manager of 398 // last resort. 399 // It needs to get constructed before the target_list or any other member 400 // that might want to broadcast through the debugger. 401 402 TerminalState m_terminal_state; 403 TargetList m_target_list; 404 405 PlatformList m_platform_list; 406 lldb::ListenerSP m_listener_sp; 407 std::unique_ptr<SourceManager> m_source_manager_up; // This is a scratch 408 // source manager that we 409 // return if we have no 410 // targets. 411 SourceManager::SourceFileCache m_source_file_cache; // All the source managers 412 // for targets created in 413 // this debugger used this 414 // shared 415 // source file cache. 416 std::unique_ptr<CommandInterpreter> m_command_interpreter_up; 417 418 std::recursive_mutex m_script_interpreter_mutex; 419 std::array<lldb::ScriptInterpreterSP, lldb::eScriptLanguageUnknown> 420 m_script_interpreters; 421 422 IOHandlerStack m_io_handler_stack; 423 std::recursive_mutex m_io_handler_synchronous_mutex; 424 425 llvm::StringMap<std::weak_ptr<llvm::raw_ostream>> m_log_streams; 426 std::shared_ptr<llvm::raw_ostream> m_log_callback_stream_sp; 427 ConstString m_instance_name; 428 static LoadPluginCallbackType g_load_plugin_callback; 429 typedef std::vector<llvm::sys::DynamicLibrary> LoadedPluginsList; 430 LoadedPluginsList m_loaded_plugins; 431 HostThread m_event_handler_thread; 432 HostThread m_io_handler_thread; 433 Broadcaster m_sync_broadcaster; 434 lldb::ListenerSP m_forward_listener_sp; 435 llvm::once_flag m_clear_once; 436 lldb::TargetSP m_dummy_target_sp; 437 438 // Events for m_sync_broadcaster 439 enum { 440 eBroadcastBitEventThreadIsListening = (1 << 0), 441 }; 442 443 private: 444 // Use Debugger::CreateInstance() to get a shared pointer to a new debugger 445 // object 446 Debugger(lldb::LogOutputCallback m_log_callback, void *baton); 447 448 Debugger(const Debugger &) = delete; 449 const Debugger &operator=(const Debugger &) = delete; 450 }; 451 452 } // namespace lldb_private 453 454 #endif // LLDB_CORE_DEBUGGER_H 455