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