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: 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 Terminate(); 98 99 // Deprecated, use the one that takes a source_init_files bool. 100 static lldb::SBDebugger Create(); 101 102 static lldb::SBDebugger Create(bool source_init_files); 103 104 static lldb::SBDebugger Create(bool source_init_files, 105 lldb::LogOutputCallback log_callback, 106 void *baton); 107 108 static void Destroy(lldb::SBDebugger &debugger); 109 110 static void MemoryPressureDetected(); 111 112 explicit operator bool() const; 113 114 bool IsValid() const; 115 116 void Clear(); 117 118 void SetAsync(bool b); 119 120 bool GetAsync(); 121 122 void SkipLLDBInitFiles(bool b); 123 124 void SkipAppInitFiles(bool b); 125 126 void SetInputFileHandle(FILE *f, bool transfer_ownership); 127 128 void SetOutputFileHandle(FILE *f, bool transfer_ownership); 129 130 void SetErrorFileHandle(FILE *f, bool transfer_ownership); 131 132 FILE *GetInputFileHandle(); 133 134 FILE *GetOutputFileHandle(); 135 136 FILE *GetErrorFileHandle(); 137 138 SBError SetInputString(const char *data); 139 140 SBError SetInputFile(SBFile file); 141 142 SBError SetOutputFile(SBFile file); 143 144 SBError SetErrorFile(SBFile file); 145 146 SBError SetInputFile(FileSP file); 147 148 SBError SetOutputFile(FileSP file); 149 150 SBError SetErrorFile(FileSP file); 151 152 SBFile GetInputFile(); 153 154 SBFile GetOutputFile(); 155 156 SBFile GetErrorFile(); 157 158 void SaveInputTerminalState(); 159 160 void RestoreInputTerminalState(); 161 162 lldb::SBCommandInterpreter GetCommandInterpreter(); 163 164 void HandleCommand(const char *command); 165 166 lldb::SBListener GetListener(); 167 168 void HandleProcessEvent(const lldb::SBProcess &process, 169 const lldb::SBEvent &event, FILE *out, 170 FILE *err); // DEPRECATED 171 172 void HandleProcessEvent(const lldb::SBProcess &process, 173 const lldb::SBEvent &event, SBFile out, SBFile err); 174 175 void HandleProcessEvent(const lldb::SBProcess &process, 176 const lldb::SBEvent &event, FileSP out, FileSP err); 177 178 lldb::SBTarget CreateTarget(const char *filename, const char *target_triple, 179 const char *platform_name, 180 bool add_dependent_modules, lldb::SBError &error); 181 182 lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename, 183 const char *target_triple); 184 185 lldb::SBTarget CreateTargetWithFileAndArch(const char *filename, 186 const char *archname); 187 188 lldb::SBTarget CreateTarget(const char *filename); 189 190 lldb::SBTarget GetDummyTarget(); 191 192 // Return true if target is deleted from the target list of the debugger. 193 bool DeleteTarget(lldb::SBTarget &target); 194 195 lldb::SBTarget GetTargetAtIndex(uint32_t idx); 196 197 uint32_t GetIndexOfTarget(lldb::SBTarget target); 198 199 lldb::SBTarget FindTargetWithProcessID(pid_t pid); 200 201 lldb::SBTarget FindTargetWithFileAndArch(const char *filename, 202 const char *arch); 203 204 uint32_t GetNumTargets(); 205 206 lldb::SBTarget GetSelectedTarget(); 207 208 void SetSelectedTarget(SBTarget &target); 209 210 lldb::SBPlatform GetSelectedPlatform(); 211 212 void SetSelectedPlatform(lldb::SBPlatform &platform); 213 214 /// Get the number of currently active platforms. 215 uint32_t GetNumPlatforms(); 216 217 /// Get one of the currently active platforms. 218 lldb::SBPlatform GetPlatformAtIndex(uint32_t idx); 219 220 /// Get the number of available platforms. 221 /// 222 /// The return value should match the number of entries output by the 223 /// "platform list" command. 224 uint32_t GetNumAvailablePlatforms(); 225 226 /// Get the name and description of one of the available platforms. 227 /// 228 /// \param[in] idx 229 /// Zero-based index of the platform for which info should be retrieved, 230 /// must be less than the value returned by GetNumAvailablePlatforms(). 231 lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx); 232 233 lldb::SBSourceManager GetSourceManager(); 234 235 // REMOVE: just for a quick fix, need to expose platforms through 236 // SBPlatform from this class. 237 lldb::SBError SetCurrentPlatform(const char *platform_name); 238 239 bool SetCurrentPlatformSDKRoot(const char *sysroot); 240 241 // FIXME: Once we get the set show stuff in place, the driver won't need 242 // an interface to the Set/Get UseExternalEditor. 243 bool SetUseExternalEditor(bool input); 244 245 bool GetUseExternalEditor(); 246 247 bool SetUseColor(bool use_color); 248 249 bool GetUseColor() const; 250 251 bool SetUseSourceCache(bool use_source_cache); 252 253 bool GetUseSourceCache() const; 254 255 static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len); 256 257 static bool SetDefaultArchitecture(const char *arch_name); 258 259 lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name); 260 261 SBStructuredData GetScriptInterpreterInfo(ScriptLanguage); 262 263 static const char *GetVersionString(); 264 265 static const char *StateAsCString(lldb::StateType state); 266 267 static SBStructuredData GetBuildConfiguration(); 268 269 static bool StateIsRunningState(lldb::StateType state); 270 271 static bool StateIsStoppedState(lldb::StateType state); 272 273 bool EnableLog(const char *channel, const char **categories); 274 275 void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton); 276 277 // DEPRECATED 278 void DispatchInput(void *baton, const void *data, size_t data_len); 279 280 void DispatchInput(const void *data, size_t data_len); 281 282 void DispatchInputInterrupt(); 283 284 void DispatchInputEndOfFile(); 285 286 void PushInputReader(lldb::SBInputReader &reader); 287 288 const char *GetInstanceName(); 289 290 static SBDebugger FindDebuggerWithID(int id); 291 292 static lldb::SBError SetInternalVariable(const char *var_name, 293 const char *value, 294 const char *debugger_instance_name); 295 296 static lldb::SBStringList 297 GetInternalVariableValue(const char *var_name, 298 const char *debugger_instance_name); 299 300 bool GetDescription(lldb::SBStream &description); 301 302 uint32_t GetTerminalWidth() const; 303 304 void SetTerminalWidth(uint32_t term_width); 305 306 lldb::user_id_t GetID(); 307 308 const char *GetPrompt() const; 309 310 void SetPrompt(const char *prompt); 311 312 const char *GetReproducerPath() const; 313 314 lldb::ScriptLanguage GetScriptLanguage() const; 315 316 void SetScriptLanguage(lldb::ScriptLanguage script_lang); 317 318 lldb::LanguageType GetREPLLanguage() const; 319 320 void SetREPLLanguage(lldb::LanguageType repl_lang); 321 322 bool GetCloseInputOnEOF() const; 323 324 void SetCloseInputOnEOF(bool b); 325 326 SBTypeCategory GetCategory(const char *category_name); 327 328 SBTypeCategory GetCategory(lldb::LanguageType lang_type); 329 330 SBTypeCategory CreateCategory(const char *category_name); 331 332 bool DeleteCategory(const char *category_name); 333 334 uint32_t GetNumCategories(); 335 336 SBTypeCategory GetCategoryAtIndex(uint32_t); 337 338 SBTypeCategory GetDefaultCategory(); 339 340 SBTypeFormat GetFormatForType(SBTypeNameSpecifier); 341 342 SBTypeSummary GetSummaryForType(SBTypeNameSpecifier); 343 344 SBTypeFilter GetFilterForType(SBTypeNameSpecifier); 345 346 SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier); 347 348 /// Run the command interpreter. 349 /// 350 /// \param[in] auto_handle_events 351 /// If true, automatically handle resulting events. This takes precedence 352 /// and overrides the corresponding option in 353 /// SBCommandInterpreterRunOptions. 354 /// 355 /// \param[in] spawn_thread 356 /// If true, start a new thread for IO handling. This takes precedence 357 /// and overrides the corresponding option in 358 /// SBCommandInterpreterRunOptions. 359 void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread); 360 361 /// Run the command interpreter. 362 /// 363 /// \param[in] auto_handle_events 364 /// If true, automatically handle resulting events. This takes precedence 365 /// and overrides the corresponding option in 366 /// SBCommandInterpreterRunOptions. 367 /// 368 /// \param[in] spawn_thread 369 /// If true, start a new thread for IO handling. This takes precedence 370 /// and overrides the corresponding option in 371 /// SBCommandInterpreterRunOptions. 372 /// 373 /// \param[in] options 374 /// Parameter collection of type SBCommandInterpreterRunOptions. 375 /// 376 /// \param[out] num_errors 377 /// The number of errors. 378 /// 379 /// \param[out] quit_requested 380 /// Whether a quit was requested. 381 /// 382 /// \param[out] stopped_for_crash 383 /// Whether the interpreter stopped for a crash. 384 void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread, 385 SBCommandInterpreterRunOptions &options, 386 int &num_errors, bool &quit_requested, 387 bool &stopped_for_crash); 388 389 SBCommandInterpreterRunResult 390 RunCommandInterpreter(const SBCommandInterpreterRunOptions &options); 391 392 SBError RunREPL(lldb::LanguageType language, const char *repl_options); 393 394 /// Load a trace from a trace description file and create Targets, 395 /// Processes and Threads based on the contents of such file. 396 /// 397 /// \param[out] error 398 /// An error if the trace could not be created. 399 /// 400 /// \param[in] trace_description_file 401 /// The file containing the necessary information to load the trace. 402 SBTrace LoadTraceFromFile(SBError &error, 403 const SBFileSpec &trace_description_file); 404 405 private: 406 friend class SBCommandInterpreter; 407 friend class SBInputReader; 408 friend class SBListener; 409 friend class SBProcess; 410 friend class SBSourceManager; 411 friend class SBTarget; 412 friend class SBTrace; 413 414 lldb::SBTarget FindTargetWithLLDBProcess(const lldb::ProcessSP &processSP); 415 416 void reset(const lldb::DebuggerSP &debugger_sp); 417 418 lldb_private::Debugger *get() const; 419 420 lldb_private::Debugger &ref() const; 421 422 const lldb::DebuggerSP &get_sp() const; 423 424 lldb::DebuggerSP m_opaque_sp; 425 426 }; // class SBDebugger 427 428 } // namespace lldb 429 430 #endif // LLDB_API_SBDEBUGGER_H 431