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