contrib/llvm-project/lldb/include/lldb/API/SBDebugger.h

   1 //===-- SBDebugger.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_API_SBDEBUGGER_H
  10 #define LLDB_API_SBDEBUGGER_H
  11
  12 #include <cstdio>
  13
  14 #include "lldb/API/SBDefines.h"
  15 #include "lldb/API/SBPlatform.h"
  16
  17 namespace lldb_private {
  18 class CommandPluginInterfaceImplementation;
  19 namespace python {
  20 class SWIGBridge;
  21 }
  22 } // namespace lldb_private
  23
  24 namespace lldb {
  25
  26 #ifndef SWIG
  27 class LLDB_API SBInputReader {
  28 public:
  29   SBInputReader() = default;
  30   ~SBInputReader() = default;
  31
  32   SBError Initialize(lldb::SBDebugger &sb_debugger,
  33                      unsigned long (*callback)(void *, lldb::SBInputReader *,
  34                                                lldb::InputReaderAction,
  35                                                char const *, unsigned long),
  36                      void *a, lldb::InputReaderGranularity b, char const *c,
  37                      char const *d, bool e);
  38   void SetIsDone(bool);
  39   bool IsActive() const;
  40 };
  41 #endif
  42
  43 class LLDB_API SBDebugger {
  44 public:
  45   FLAGS_ANONYMOUS_ENUM(){
  46       eBroadcastBitProgress = (1 << 0),
  47       eBroadcastBitWarning = (1 << 1),
  48       eBroadcastBitError = (1 << 2),
  49   };
  50
  51   SBDebugger();
  52
  53   SBDebugger(const lldb::SBDebugger &rhs);
  54
  55   ~SBDebugger();
  56
  57   static const char *GetBroadcasterClass();
  58
  59   lldb::SBBroadcaster GetBroadcaster();
  60
  61   /// Get progress data from a SBEvent whose type is eBroadcastBitProgress.
  62   ///
  63   /// \param [in] event
  64   ///   The event to extract the progress information from.
  65   ///
  66   /// \param [out] progress_id
  67   ///   The unique integer identifier for the progress to report.
  68   ///
  69   /// \param [out] completed
  70   ///   The amount of work completed. If \a completed is zero, then this event
  71   ///   is a progress started event. If \a completed is equal to \a total, then
  72   ///   this event is a progress end event. Otherwise completed indicates the
  73   ///   current progress update.
  74   ///
  75   /// \param [out] total
  76   ///   The total amount of work units that need to be completed. If this value
  77   ///   is UINT64_MAX, then an indeterminate progress indicator should be
  78   ///   displayed.
  79   ///
  80   /// \param [out] is_debugger_specific
  81   ///   Set to true if this progress is specific to this debugger only. Many
  82   ///   progress events are not specific to a debugger instance, like any
  83   ///   progress events for loading information in modules since LLDB has a
  84   ///   global module cache that all debuggers use.
  85   ///
  86   /// \return The message for the progress. If the returned value is NULL, then
  87   ///   \a event was not a eBroadcastBitProgress event.
  88 #ifdef SWIG
  89   static const char *GetProgressFromEvent(const lldb::SBEvent &event,
  90                                           uint64_t &OUTPUT,
  91                                           uint64_t &OUTPUT, uint64_t &OUTPUT,
  92                                           bool &OUTPUT);
  93 #else
  94   static const char *GetProgressFromEvent(const lldb::SBEvent &event,
  95                                           uint64_t &progress_id,
  96                                           uint64_t &completed, uint64_t &total,
  97                                           bool &is_debugger_specific);
  98 #endif
  99
 100   static lldb::SBStructuredData
 101   GetProgressDataFromEvent(const lldb::SBEvent &event);
 102
 103   static lldb::SBStructuredData
 104   GetDiagnosticFromEvent(const lldb::SBEvent &event);
 105
 106   lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs);
 107
 108   static void Initialize();
 109
 110   static lldb::SBError InitializeWithErrorHandling();
 111
 112   static void PrintStackTraceOnError();
 113
 114   static void PrintDiagnosticsOnError();
 115
 116   static void Terminate();
 117
 118   LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)")
 119   static lldb::SBDebugger Create();
 120
 121   static lldb::SBDebugger Create(bool source_init_files);
 122
 123   static lldb::SBDebugger Create(bool source_init_files,
 124                                  lldb::LogOutputCallback log_callback,
 125                                  void *baton);
 126
 127   static void Destroy(lldb::SBDebugger &debugger);
 128
 129   static void MemoryPressureDetected();
 130
 131   explicit operator bool() const;
 132
 133   bool IsValid() const;
 134
 135   void Clear();
 136
 137   /// Getting a specific setting value into SBStructuredData format.
 138   /// Client can specify empty string or null to get all settings.
 139   ///
 140   /// Example usages:
 141   /// lldb::SBStructuredData settings = debugger.GetSetting();
 142   /// lldb::SBStructuredData settings = debugger.GetSetting(nullptr);
 143   /// lldb::SBStructuredData settings = debugger.GetSetting("");
 144   /// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0");
 145   /// lldb::SBStructuredData settings = debugger.GetSetting("target");
 146   ///
 147   /// \param[out] setting
 148   ///   Property setting path to retrieve values. e.g "target.source-map"
 149   ///
 150   lldb::SBStructuredData GetSetting(const char *setting = nullptr);
 151
 152   void SetAsync(bool b);
 153
 154   bool GetAsync();
 155
 156   void SkipLLDBInitFiles(bool b);
 157
 158   void SkipAppInitFiles(bool b);
 159
 160 #ifndef SWIG
 161   void SetInputFileHandle(FILE *f, bool transfer_ownership);
 162
 163   void SetOutputFileHandle(FILE *f, bool transfer_ownership);
 164
 165   void SetErrorFileHandle(FILE *f, bool transfer_ownership);
 166 #endif
 167
 168 #ifndef SWIG
 169   FILE *GetInputFileHandle();
 170
 171   FILE *GetOutputFileHandle();
 172
 173   FILE *GetErrorFileHandle();
 174 #endif
 175
 176   SBError SetInputString(const char *data);
 177
 178   SBError SetInputFile(SBFile file);
 179
 180   SBError SetOutputFile(SBFile file);
 181
 182   SBError SetErrorFile(SBFile file);
 183
 184   SBError SetInputFile(FileSP file);
 185
 186   SBError SetOutputFile(FileSP file);
 187
 188   SBError SetErrorFile(FileSP file);
 189
 190   SBFile GetInputFile();
 191
 192   SBFile GetOutputFile();
 193
 194   SBFile GetErrorFile();
 195
 196   void SaveInputTerminalState();
 197
 198   void RestoreInputTerminalState();
 199
 200   lldb::SBCommandInterpreter GetCommandInterpreter();
 201
 202   void HandleCommand(const char *command);
 203
 204   void RequestInterrupt();
 205   void CancelInterruptRequest();
 206   bool InterruptRequested();
 207
 208   lldb::SBListener GetListener();
 209
 210 #ifndef SWIG
 211   LLDB_DEPRECATED_FIXME(
 212       "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, "
 213       "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, "
 214       "FileSP, FileSP)",
 215       "HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, SBFile)")
 216   void HandleProcessEvent(const lldb::SBProcess &process,
 217                           const lldb::SBEvent &event, FILE *out, FILE *err);
 218 #endif
 219
 220   void HandleProcessEvent(const lldb::SBProcess &process,
 221                           const lldb::SBEvent &event, SBFile out, SBFile err);
 222
 223 #ifdef SWIG
 224   void HandleProcessEvent(const lldb::SBProcess &process,
 225                           const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED);
 226 #else
 227   void HandleProcessEvent(const lldb::SBProcess &process,
 228                           const lldb::SBEvent &event, FileSP out, FileSP err);
 229 #endif
 230
 231   lldb::SBTarget CreateTarget(const char *filename, const char *target_triple,
 232                               const char *platform_name,
 233                               bool add_dependent_modules, lldb::SBError &error);
 234
 235   lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename,
 236                                                      const char *target_triple);
 237
 238   lldb::SBTarget CreateTargetWithFileAndArch(const char *filename,
 239                                              const char *archname);
 240
 241   lldb::SBTarget CreateTarget(const char *filename);
 242
 243   lldb::SBTarget GetDummyTarget();
 244
 245   // Return true if target is deleted from the target list of the debugger.
 246   bool DeleteTarget(lldb::SBTarget &target);
 247
 248   lldb::SBTarget GetTargetAtIndex(uint32_t idx);
 249
 250   uint32_t GetIndexOfTarget(lldb::SBTarget target);
 251
 252   lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid);
 253
 254   lldb::SBTarget FindTargetWithFileAndArch(const char *filename,
 255                                            const char *arch);
 256
 257   uint32_t GetNumTargets();
 258
 259   lldb::SBTarget GetSelectedTarget();
 260
 261   void SetSelectedTarget(SBTarget &target);
 262
 263   lldb::SBPlatform GetSelectedPlatform();
 264
 265   void SetSelectedPlatform(lldb::SBPlatform &platform);
 266
 267   /// Get the number of currently active platforms.
 268   uint32_t GetNumPlatforms();
 269
 270   /// Get one of the currently active platforms.
 271   lldb::SBPlatform GetPlatformAtIndex(uint32_t idx);
 272
 273   /// Get the number of available platforms.
 274   ///
 275   /// The return value should match the number of entries output by the
 276   /// "platform list" command.
 277   uint32_t GetNumAvailablePlatforms();
 278
 279   /// Get the name and description of one of the available platforms.
 280   ///
 281   /// \param[in] idx
 282   ///     Zero-based index of the platform for which info should be retrieved,
 283   ///     must be less than the value returned by GetNumAvailablePlatforms().
 284   lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx);
 285
 286   lldb::SBSourceManager GetSourceManager();
 287
 288   // REMOVE: just for a quick fix, need to expose platforms through
 289   // SBPlatform from this class.
 290   lldb::SBError SetCurrentPlatform(const char *platform_name);
 291
 292   bool SetCurrentPlatformSDKRoot(const char *sysroot);
 293
 294   // FIXME: Once we get the set show stuff in place, the driver won't need
 295   // an interface to the Set/Get UseExternalEditor.
 296   bool SetUseExternalEditor(bool input);
 297
 298   bool GetUseExternalEditor();
 299
 300   bool SetUseColor(bool use_color);
 301
 302   bool GetUseColor() const;
 303
 304   bool SetUseSourceCache(bool use_source_cache);
 305
 306   bool GetUseSourceCache() const;
 307
 308   static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len);
 309
 310   static bool SetDefaultArchitecture(const char *arch_name);
 311
 312   lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name);
 313
 314   SBStructuredData GetScriptInterpreterInfo(ScriptLanguage);
 315
 316   static const char *GetVersionString();
 317
 318   static const char *StateAsCString(lldb::StateType state);
 319
 320   static SBStructuredData GetBuildConfiguration();
 321
 322   static bool StateIsRunningState(lldb::StateType state);
 323
 324   static bool StateIsStoppedState(lldb::StateType state);
 325
 326   bool EnableLog(const char *channel, const char **categories);
 327
 328   void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
 329
 330   void SetDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback,
 331                           void *baton);
 332
 333 #ifndef SWIG
 334   LLDB_DEPRECATED_FIXME("Use DispatchInput(const void *, size_t)",
 335                         "DispatchInput(const void *, size_t)")
 336   void DispatchInput(void *baton, const void *data, size_t data_len);
 337 #endif
 338
 339   void DispatchInput(const void *data, size_t data_len);
 340
 341   void DispatchInputInterrupt();
 342
 343   void DispatchInputEndOfFile();
 344
 345 #ifndef SWIG
 346   void PushInputReader(lldb::SBInputReader &reader);
 347 #endif
 348
 349   const char *GetInstanceName();
 350
 351   static SBDebugger FindDebuggerWithID(int id);
 352
 353   static lldb::SBError SetInternalVariable(const char *var_name,
 354                                            const char *value,
 355                                            const char *debugger_instance_name);
 356
 357   static lldb::SBStringList
 358   GetInternalVariableValue(const char *var_name,
 359                            const char *debugger_instance_name);
 360
 361   bool GetDescription(lldb::SBStream &description);
 362
 363   uint32_t GetTerminalWidth() const;
 364
 365   void SetTerminalWidth(uint32_t term_width);
 366
 367   lldb::user_id_t GetID();
 368
 369   const char *GetPrompt() const;
 370
 371   void SetPrompt(const char *prompt);
 372
 373   const char *GetReproducerPath() const;
 374
 375   lldb::ScriptLanguage GetScriptLanguage() const;
 376
 377   void SetScriptLanguage(lldb::ScriptLanguage script_lang);
 378
 379   lldb::LanguageType GetREPLLanguage() const;
 380
 381   void SetREPLLanguage(lldb::LanguageType repl_lang);
 382
 383   bool GetCloseInputOnEOF() const;
 384
 385   void SetCloseInputOnEOF(bool b);
 386
 387   SBTypeCategory GetCategory(const char *category_name);
 388
 389   SBTypeCategory GetCategory(lldb::LanguageType lang_type);
 390
 391   SBTypeCategory CreateCategory(const char *category_name);
 392
 393   bool DeleteCategory(const char *category_name);
 394
 395   uint32_t GetNumCategories();
 396
 397   SBTypeCategory GetCategoryAtIndex(uint32_t);
 398
 399   SBTypeCategory GetDefaultCategory();
 400
 401   SBTypeFormat GetFormatForType(SBTypeNameSpecifier);
 402
 403   SBTypeSummary GetSummaryForType(SBTypeNameSpecifier);
 404
 405   SBTypeFilter GetFilterForType(SBTypeNameSpecifier);
 406
 407   SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier);
 408
 409 #ifndef SWIG
 410   /// Run the command interpreter.
 411   ///
 412   /// \param[in] auto_handle_events
 413   ///     If true, automatically handle resulting events. This takes precedence
 414   ///     and overrides the corresponding option in
 415   ///     SBCommandInterpreterRunOptions.
 416   ///
 417   /// \param[in] spawn_thread
 418   ///     If true, start a new thread for IO handling. This takes precedence
 419   ///     and overrides the corresponding option in
 420   ///     SBCommandInterpreterRunOptions.
 421   void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread);
 422 #endif
 423
 424   /// Run the command interpreter.
 425   ///
 426   /// \param[in] auto_handle_events
 427   ///     If true, automatically handle resulting events. This takes precedence
 428   ///     and overrides the corresponding option in
 429   ///     SBCommandInterpreterRunOptions.
 430   ///
 431   /// \param[in] spawn_thread
 432   ///     If true, start a new thread for IO handling. This takes precedence
 433   ///     and overrides the corresponding option in
 434   ///     SBCommandInterpreterRunOptions.
 435   ///
 436   /// \param[in] options
 437   ///     Parameter collection of type SBCommandInterpreterRunOptions.
 438   ///
 439   /// \param[out] num_errors
 440   ///     The number of errors.
 441   ///
 442   /// \param[out] quit_requested
 443   ///     Whether a quit was requested.
 444   ///
 445   /// \param[out] stopped_for_crash
 446   ///     Whether the interpreter stopped for a crash.
 447 #ifdef SWIG
 448   %apply int& INOUT { int& num_errors };
 449   %apply bool& INOUT { bool& quit_requested };
 450   %apply bool& INOUT { bool& stopped_for_crash };
 451 #endif
 452   void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread,
 453                              SBCommandInterpreterRunOptions &options,
 454                              int &num_errors, bool &quit_requested,
 455                              bool &stopped_for_crash);
 456
 457 #ifndef SWIG
 458   SBCommandInterpreterRunResult
 459   RunCommandInterpreter(const SBCommandInterpreterRunOptions &options);
 460 #endif
 461
 462   SBError RunREPL(lldb::LanguageType language, const char *repl_options);
 463
 464   /// Load a trace from a trace description file and create Targets,
 465   /// Processes and Threads based on the contents of such file.
 466   ///
 467   /// \param[out] error
 468   ///   An error if the trace could not be created.
 469   ///
 470   /// \param[in] trace_description_file
 471   ///   The file containing the necessary information to load the trace.
 472   SBTrace LoadTraceFromFile(SBError &error,
 473                             const SBFileSpec &trace_description_file);
 474
 475 protected:
 476   friend class lldb_private::CommandPluginInterfaceImplementation;
 477   friend class lldb_private::python::SWIGBridge;
 478
 479   SBDebugger(const lldb::DebuggerSP &debugger_sp);
 480
 481 private:
 482   friend class SBCommandInterpreter;
 483   friend class SBInputReader;
 484   friend class SBListener;
 485   friend class SBProcess;
 486   friend class SBSourceManager;
 487   friend class SBStructuredData;
 488   friend class SBTarget;
 489   friend class SBTrace;
 490
 491   lldb::SBTarget FindTargetWithLLDBProcess(const lldb::ProcessSP &processSP);
 492
 493   void reset(const lldb::DebuggerSP &debugger_sp);
 494
 495   lldb_private::Debugger *get() const;
 496
 497   lldb_private::Debugger &ref() const;
 498
 499   const lldb::DebuggerSP &get_sp() const;
 500
 501   lldb::DebuggerSP m_opaque_sp;
 502
 503 }; // class SBDebugger
 504
 505 } // namespace lldb
 506
 507 #endif // LLDB_API_SBDEBUGGER_H