lldb/API/SBDebugger.h

0001 //===-- SBDebugger.h --------------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLDB_API_SBDEBUGGER_H
0010 #define LLDB_API_SBDEBUGGER_H
0011
0012 #include <cstdio>
0013
0014 #include "lldb/API/SBDefines.h"
0015 #include "lldb/API/SBPlatform.h"
0016
0017 namespace lldb_private {
0018 class CommandPluginInterfaceImplementation;
0019 namespace python {
0020 class SWIGBridge;
0021 }
0022 } // namespace lldb_private
0023
0024 namespace lldb {
0025
0026 #ifndef SWIG
0027 class LLDB_API SBInputReader {
0028 public:
0029   SBInputReader() = default;
0030   ~SBInputReader() = default;
0031
0032   SBError Initialize(lldb::SBDebugger &sb_debugger,
0033                      unsigned long (*callback)(void *, lldb::SBInputReader *,
0034                                                lldb::InputReaderAction,
0035                                                char const *, unsigned long),
0036                      void *a, lldb::InputReaderGranularity b, char const *c,
0037                      char const *d, bool e);
0038   void SetIsDone(bool);
0039   bool IsActive() const;
0040 };
0041 #endif
0042
0043 class LLDB_API SBDebugger {
0044 public:
0045   FLAGS_ANONYMOUS_ENUM() {
0046     eBroadcastBitProgress = lldb::DebuggerBroadcastBit::eBroadcastBitProgress,
0047     eBroadcastBitWarning = lldb::DebuggerBroadcastBit::eBroadcastBitWarning,
0048     eBroadcastBitError = lldb::DebuggerBroadcastBit::eBroadcastBitError,
0049     eBroadcastBitProgressCategory =
0050         lldb::DebuggerBroadcastBit::eBroadcastBitProgressCategory,
0051     eBroadcastBitExternalProgress =
0052         lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgress,
0053     eBroadcastBitExternalProgressCategory =
0054         lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgressCategory,
0055   };
0056   SBDebugger();
0057
0058   SBDebugger(const lldb::SBDebugger &rhs);
0059
0060   ~SBDebugger();
0061
0062   static const char *GetBroadcasterClass();
0063
0064   static bool SupportsLanguage(lldb::LanguageType language);
0065
0066   lldb::SBBroadcaster GetBroadcaster();
0067
0068   /// Get progress data from a SBEvent whose type is eBroadcastBitProgress.
0069   ///
0070   /// \param [in] event
0071   ///   The event to extract the progress information from.
0072   ///
0073   /// \param [out] progress_id
0074   ///   The unique integer identifier for the progress to report.
0075   ///
0076   /// \param [out] completed
0077   ///   The amount of work completed. If \a completed is zero, then this event
0078   ///   is a progress started event. If \a completed is equal to \a total, then
0079   ///   this event is a progress end event. Otherwise completed indicates the
0080   ///   current progress update.
0081   ///
0082   /// \param [out] total
0083   ///   The total amount of work units that need to be completed. If this value
0084   ///   is UINT64_MAX, then an indeterminate progress indicator should be
0085   ///   displayed.
0086   ///
0087   /// \param [out] is_debugger_specific
0088   ///   Set to true if this progress is specific to this debugger only. Many
0089   ///   progress events are not specific to a debugger instance, like any
0090   ///   progress events for loading information in modules since LLDB has a
0091   ///   global module cache that all debuggers use.
0092   ///
0093   /// \return The message for the progress. If the returned value is NULL, then
0094   ///   \a event was not a eBroadcastBitProgress event.
0095 #ifdef SWIG
0096   static const char *GetProgressFromEvent(const lldb::SBEvent &event,
0097                                           uint64_t &OUTPUT,
0098                                           uint64_t &OUTPUT, uint64_t &OUTPUT,
0099                                           bool &OUTPUT);
0100 #else
0101   static const char *GetProgressFromEvent(const lldb::SBEvent &event,
0102                                           uint64_t &progress_id,
0103                                           uint64_t &completed, uint64_t &total,
0104                                           bool &is_debugger_specific);
0105 #endif
0106
0107   static lldb::SBStructuredData
0108   GetProgressDataFromEvent(const lldb::SBEvent &event);
0109
0110   static lldb::SBStructuredData
0111   GetDiagnosticFromEvent(const lldb::SBEvent &event);
0112
0113   lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs);
0114
0115   static void Initialize();
0116
0117   static lldb::SBError InitializeWithErrorHandling();
0118
0119   static void PrintStackTraceOnError();
0120
0121   static void PrintDiagnosticsOnError();
0122
0123   static void Terminate();
0124
0125   LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)")
0126   static lldb::SBDebugger Create();
0127
0128   static lldb::SBDebugger Create(bool source_init_files);
0129
0130   static lldb::SBDebugger Create(bool source_init_files,
0131                                  lldb::LogOutputCallback log_callback,
0132                                  void *baton);
0133
0134   static void Destroy(lldb::SBDebugger &debugger);
0135
0136   static void MemoryPressureDetected();
0137
0138   explicit operator bool() const;
0139
0140   bool IsValid() const;
0141
0142   void Clear();
0143
0144   /// Getting a specific setting value into SBStructuredData format.
0145   /// Client can specify empty string or null to get all settings.
0146   ///
0147   /// Example usages:
0148   /// lldb::SBStructuredData settings = debugger.GetSetting();
0149   /// lldb::SBStructuredData settings = debugger.GetSetting(nullptr);
0150   /// lldb::SBStructuredData settings = debugger.GetSetting("");
0151   /// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0");
0152   /// lldb::SBStructuredData settings = debugger.GetSetting("target");
0153   ///
0154   /// \param[out] setting
0155   ///   Property setting path to retrieve values. e.g "target.source-map"
0156   ///
0157   lldb::SBStructuredData GetSetting(const char *setting = nullptr);
0158
0159   void SetAsync(bool b);
0160
0161   bool GetAsync();
0162
0163   void SkipLLDBInitFiles(bool b);
0164
0165   void SkipAppInitFiles(bool b);
0166
0167 #ifndef SWIG
0168   void SetInputFileHandle(FILE *f, bool transfer_ownership);
0169
0170   void SetOutputFileHandle(FILE *f, bool transfer_ownership);
0171
0172   void SetErrorFileHandle(FILE *f, bool transfer_ownership);
0173 #endif
0174
0175 #ifndef SWIG
0176   FILE *GetInputFileHandle();
0177
0178   FILE *GetOutputFileHandle();
0179
0180   FILE *GetErrorFileHandle();
0181 #endif
0182
0183   SBError SetInputString(const char *data);
0184
0185   SBError SetInputFile(SBFile file);
0186
0187   SBError SetOutputFile(SBFile file);
0188
0189   SBError SetErrorFile(SBFile file);
0190
0191   SBError SetInputFile(FileSP file);
0192
0193   SBError SetOutputFile(FileSP file);
0194
0195   SBError SetErrorFile(FileSP file);
0196
0197   SBFile GetInputFile();
0198
0199   SBFile GetOutputFile();
0200
0201   SBFile GetErrorFile();
0202
0203   void SaveInputTerminalState();
0204
0205   void RestoreInputTerminalState();
0206
0207   lldb::SBCommandInterpreter GetCommandInterpreter();
0208
0209   void HandleCommand(const char *command);
0210
0211   void RequestInterrupt();
0212   void CancelInterruptRequest();
0213   bool InterruptRequested();
0214
0215   lldb::SBListener GetListener();
0216
0217 #ifndef SWIG
0218   LLDB_DEPRECATED_FIXME(
0219       "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, "
0220       "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, "
0221       "FileSP, FileSP)",
0222       "HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, SBFile)")
0223   void HandleProcessEvent(const lldb::SBProcess &process,
0224                           const lldb::SBEvent &event, FILE *out, FILE *err);
0225 #endif
0226
0227   void HandleProcessEvent(const lldb::SBProcess &process,
0228                           const lldb::SBEvent &event, SBFile out, SBFile err);
0229
0230 #ifdef SWIG
0231   void HandleProcessEvent(const lldb::SBProcess &process,
0232                           const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED);
0233 #else
0234   void HandleProcessEvent(const lldb::SBProcess &process,
0235                           const lldb::SBEvent &event, FileSP out, FileSP err);
0236 #endif
0237
0238   lldb::SBTarget CreateTarget(const char *filename, const char *target_triple,
0239                               const char *platform_name,
0240                               bool add_dependent_modules, lldb::SBError &error);
0241
0242   lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename,
0243                                                      const char *target_triple);
0244
0245   lldb::SBTarget CreateTargetWithFileAndArch(const char *filename,
0246                                              const char *archname);
0247
0248   lldb::SBTarget CreateTarget(const char *filename);
0249
0250   lldb::SBTarget GetDummyTarget();
0251
0252   // Return true if target is deleted from the target list of the debugger.
0253   bool DeleteTarget(lldb::SBTarget &target);
0254
0255   lldb::SBTarget GetTargetAtIndex(uint32_t idx);
0256
0257   uint32_t GetIndexOfTarget(lldb::SBTarget target);
0258
0259   lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid);
0260
0261   lldb::SBTarget FindTargetWithFileAndArch(const char *filename,
0262                                            const char *arch);
0263
0264   uint32_t GetNumTargets();
0265
0266   lldb::SBTarget GetSelectedTarget();
0267
0268   void SetSelectedTarget(SBTarget &target);
0269
0270   lldb::SBPlatform GetSelectedPlatform();
0271
0272   void SetSelectedPlatform(lldb::SBPlatform &platform);
0273
0274   /// Get the number of currently active platforms.
0275   uint32_t GetNumPlatforms();
0276
0277   /// Get one of the currently active platforms.
0278   lldb::SBPlatform GetPlatformAtIndex(uint32_t idx);
0279
0280   /// Get the number of available platforms.
0281   ///
0282   /// The return value should match the number of entries output by the
0283   /// "platform list" command.
0284   uint32_t GetNumAvailablePlatforms();
0285
0286   /// Get the name and description of one of the available platforms.
0287   ///
0288   /// \param[in] idx
0289   ///     Zero-based index of the platform for which info should be retrieved,
0290   ///     must be less than the value returned by GetNumAvailablePlatforms().
0291   lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx);
0292
0293   lldb::SBSourceManager GetSourceManager();
0294
0295   // REMOVE: just for a quick fix, need to expose platforms through
0296   // SBPlatform from this class.
0297   lldb::SBError SetCurrentPlatform(const char *platform_name);
0298
0299   bool SetCurrentPlatformSDKRoot(const char *sysroot);
0300
0301   // FIXME: Once we get the set show stuff in place, the driver won't need
0302   // an interface to the Set/Get UseExternalEditor.
0303   bool SetUseExternalEditor(bool input);
0304
0305   bool GetUseExternalEditor();
0306
0307   bool SetUseColor(bool use_color);
0308
0309   bool GetUseColor() const;
0310
0311   bool SetShowInlineDiagnostics(bool);
0312
0313   bool SetUseSourceCache(bool use_source_cache);
0314
0315   bool GetUseSourceCache() const;
0316
0317   static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len);
0318
0319   static bool SetDefaultArchitecture(const char *arch_name);
0320
0321   lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name);
0322
0323   SBStructuredData GetScriptInterpreterInfo(ScriptLanguage);
0324
0325   static const char *GetVersionString();
0326
0327   static const char *StateAsCString(lldb::StateType state);
0328
0329   static SBStructuredData GetBuildConfiguration();
0330
0331   static bool StateIsRunningState(lldb::StateType state);
0332
0333   static bool StateIsStoppedState(lldb::StateType state);
0334
0335   bool EnableLog(const char *channel, const char **categories);
0336
0337   void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
0338
0339   /// Clear all previously added callbacks and only add the given one.
0340   LLDB_DEPRECATED_FIXME("Use AddDestroyCallback and RemoveDestroyCallback",
0341                         "AddDestroyCallback")
0342   void SetDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback,
0343                           void *baton);
0344
0345   /// Add a callback for when the debugger is destroyed. Return a token, which
0346   /// can be used to remove said callback. Multiple callbacks can be added by
0347   /// calling this function multiple times, and will be invoked in FIFO order.
0348   lldb::callback_token_t
0349   AddDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback,
0350                      void *baton);
0351
0352   /// Remove the specified callback. Return true if successful.
0353   bool RemoveDestroyCallback(lldb::callback_token_t token);
0354
0355 #ifndef SWIG
0356   LLDB_DEPRECATED_FIXME("Use DispatchInput(const void *, size_t)",
0357                         "DispatchInput(const void *, size_t)")
0358   void DispatchInput(void *baton, const void *data, size_t data_len);
0359 #endif
0360
0361   void DispatchInput(const void *data, size_t data_len);
0362
0363   void DispatchInputInterrupt();
0364
0365   void DispatchInputEndOfFile();
0366
0367 #ifndef SWIG
0368   void PushInputReader(lldb::SBInputReader &reader);
0369 #endif
0370
0371   const char *GetInstanceName();
0372
0373   static SBDebugger FindDebuggerWithID(int id);
0374
0375   static lldb::SBError SetInternalVariable(const char *var_name,
0376                                            const char *value,
0377                                            const char *debugger_instance_name);
0378
0379   static lldb::SBStringList
0380   GetInternalVariableValue(const char *var_name,
0381                            const char *debugger_instance_name);
0382
0383   bool GetDescription(lldb::SBStream &description);
0384
0385   uint32_t GetTerminalWidth() const;
0386
0387   void SetTerminalWidth(uint32_t term_width);
0388
0389   uint32_t GetTerminalHeight() const;
0390
0391   void SetTerminalHeight(uint32_t term_height);
0392
0393   lldb::user_id_t GetID();
0394
0395   const char *GetPrompt() const;
0396
0397   void SetPrompt(const char *prompt);
0398
0399   const char *GetReproducerPath() const;
0400
0401   lldb::ScriptLanguage GetScriptLanguage() const;
0402
0403   void SetScriptLanguage(lldb::ScriptLanguage script_lang);
0404
0405   lldb::LanguageType GetREPLLanguage() const;
0406
0407   void SetREPLLanguage(lldb::LanguageType repl_lang);
0408
0409   LLDB_DEPRECATED("SBDebugger::GetCloseInputOnEOF() is deprecated.")
0410   bool GetCloseInputOnEOF() const;
0411
0412   LLDB_DEPRECATED("SBDebugger::SetCloseInputOnEOF() is deprecated.")
0413   void SetCloseInputOnEOF(bool b);
0414
0415   SBTypeCategory GetCategory(const char *category_name);
0416
0417   SBTypeCategory GetCategory(lldb::LanguageType lang_type);
0418
0419   SBTypeCategory CreateCategory(const char *category_name);
0420
0421   bool DeleteCategory(const char *category_name);
0422
0423   uint32_t GetNumCategories();
0424
0425   SBTypeCategory GetCategoryAtIndex(uint32_t);
0426
0427   SBTypeCategory GetDefaultCategory();
0428
0429   SBTypeFormat GetFormatForType(SBTypeNameSpecifier);
0430
0431   SBTypeSummary GetSummaryForType(SBTypeNameSpecifier);
0432
0433   SBTypeFilter GetFilterForType(SBTypeNameSpecifier);
0434
0435   SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier);
0436
0437   /// Clear collected statistics for targets belonging to this debugger. This
0438   /// includes clearing symbol table and debug info parsing/index time for all
0439   /// modules, breakpoint resolve time and target statistics.
0440   void ResetStatistics();
0441
0442 #ifndef SWIG
0443   /// Run the command interpreter.
0444   ///
0445   /// \param[in] auto_handle_events
0446   ///     If true, automatically handle resulting events. This takes precedence
0447   ///     and overrides the corresponding option in
0448   ///     SBCommandInterpreterRunOptions.
0449   ///
0450   /// \param[in] spawn_thread
0451   ///     If true, start a new thread for IO handling. This takes precedence
0452   ///     and overrides the corresponding option in
0453   ///     SBCommandInterpreterRunOptions.
0454   void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread);
0455 #endif
0456
0457   /// Run the command interpreter.
0458   ///
0459   /// \param[in] auto_handle_events
0460   ///     If true, automatically handle resulting events. This takes precedence
0461   ///     and overrides the corresponding option in
0462   ///     SBCommandInterpreterRunOptions.
0463   ///
0464   /// \param[in] spawn_thread
0465   ///     If true, start a new thread for IO handling. This takes precedence
0466   ///     and overrides the corresponding option in
0467   ///     SBCommandInterpreterRunOptions.
0468   ///
0469   /// \param[in] options
0470   ///     Parameter collection of type SBCommandInterpreterRunOptions.
0471   ///
0472   /// \param[out] num_errors
0473   ///     The number of errors.
0474   ///
0475   /// \param[out] quit_requested
0476   ///     Whether a quit was requested.
0477   ///
0478   /// \param[out] stopped_for_crash
0479   ///     Whether the interpreter stopped for a crash.
0480 #ifdef SWIG
0481   %apply int& INOUT { int& num_errors };
0482   %apply bool& INOUT { bool& quit_requested };
0483   %apply bool& INOUT { bool& stopped_for_crash };
0484 #endif
0485   void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread,
0486                              SBCommandInterpreterRunOptions &options,
0487                              int &num_errors, bool &quit_requested,
0488                              bool &stopped_for_crash);
0489
0490 #ifndef SWIG
0491   SBCommandInterpreterRunResult
0492   RunCommandInterpreter(const SBCommandInterpreterRunOptions &options);
0493 #endif
0494
0495   SBError RunREPL(lldb::LanguageType language, const char *repl_options);
0496
0497   /// Load a trace from a trace description file and create Targets,
0498   /// Processes and Threads based on the contents of such file.
0499   ///
0500   /// \param[out] error
0501   ///   An error if the trace could not be created.
0502   ///
0503   /// \param[in] trace_description_file
0504   ///   The file containing the necessary information to load the trace.
0505   SBTrace LoadTraceFromFile(SBError &error,
0506                             const SBFileSpec &trace_description_file);
0507
0508 protected:
0509   friend class lldb_private::CommandPluginInterfaceImplementation;
0510   friend class lldb_private::python::SWIGBridge;
0511
0512   SBDebugger(const lldb::DebuggerSP &debugger_sp);
0513
0514 private:
0515   friend class SBCommandInterpreter;
0516   friend class SBInputReader;
0517   friend class SBListener;
0518   friend class SBProcess;
0519   friend class SBSourceManager;
0520   friend class SBStructuredData;
0521   friend class SBPlatform;
0522   friend class SBTarget;
0523   friend class SBTrace;
0524   friend class SBProgress;
0525
0526   lldb::SBTarget FindTargetWithLLDBProcess(const lldb::ProcessSP &processSP);
0527
0528   void reset(const lldb::DebuggerSP &debugger_sp);
0529
0530   lldb_private::Debugger *get() const;
0531
0532   lldb_private::Debugger &ref() const;
0533
0534   const lldb::DebuggerSP &get_sp() const;
0535
0536   lldb::DebuggerSP m_opaque_sp;
0537
0538 }; // class SBDebugger
0539
0540 } // namespace lldb
0541
0542 #endif // LLDB_API_SBDEBUGGER_H