contrib/llvm-project/lldb/include/lldb/Core/Debugger.h

   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_