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