diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h index 192fbee9c0c6d..f77b0c1d7f0ee 100644 --- a/lldb/include/lldb/API/SBDebugger.h +++ b/lldb/include/lldb/API/SBDebugger.h @@ -44,6 +44,7 @@ class LLDB_API SBInputReader { class LLDB_API SBDebugger { public: + /// Broadcast bit definitions for the SBDebugger. FLAGS_ANONYMOUS_ENUM() { eBroadcastBitProgress = lldb::DebuggerBroadcastBit::eBroadcastBitProgress, eBroadcastBitWarning = lldb::DebuggerBroadcastBit::eBroadcastBitWarning, @@ -55,16 +56,22 @@ class LLDB_API SBDebugger { eBroadcastBitExternalProgressCategory = lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgressCategory, }; + + /// Default constructor creates an invalid SBDebugger instance. SBDebugger(); SBDebugger(const lldb::SBDebugger &rhs); ~SBDebugger(); + /// Get the broadcaster class name. static const char *GetBroadcasterClass(); + /// Check if a specific language is supported by LLDB. static bool SupportsLanguage(lldb::LanguageType language); + /// Get the broadcaster that allows subscribing to events from this + /// debugger. lldb::SBBroadcaster GetBroadcaster(); /// Get progress data from a SBEvent whose type is eBroadcastBitProgress. @@ -106,44 +113,80 @@ class LLDB_API SBDebugger { bool &is_debugger_specific); #endif + /// Get progress data from an event. static lldb::SBStructuredData GetProgressDataFromEvent(const lldb::SBEvent &event); + /// Get diagnostic information from an event. static lldb::SBStructuredData GetDiagnosticFromEvent(const lldb::SBEvent &event); + /// Assignment operator. lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs); + /// Initialize LLDB and its subsystems. + /// + /// This function should be called before any other LLDB functions. It + /// initializes all required subsystems for proper LLDB functionality. static void Initialize(); + /// Initialize the LLDB debugger subsystem with error handling. + /// + /// Similar to Initialize(), but returns an error if initialization fails. static lldb::SBError InitializeWithErrorHandling(); + /// Configure LLDB to print a stack trace when it crashes. static void PrintStackTraceOnError(); + /// Configure LLDB to print diagnostic information when it crashes. static void PrintDiagnosticsOnError(); + /// Terminate LLDB and its subsystems. + /// + /// This should be called when LLDB is no longer needed. static void Terminate(); + /// Create a new debugger instance (deprecated). LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)") static lldb::SBDebugger Create(); + /// Create a new debugger instance. + /// + /// If source_init_files is true, the debugger will source .lldbinit files + /// from the home directory and current directory. static lldb::SBDebugger Create(bool source_init_files); + /// Create a new debugger instance with a custom log handler and user data + /// passed to the log callback. + /// + /// If source_init_files is true, the debugger will source .lldbinit files + /// from the home directory and current directory. static lldb::SBDebugger Create(bool source_init_files, lldb::LogOutputCallback log_callback, void *baton); + /// Destroy a debugger instance. static void Destroy(lldb::SBDebugger &debugger); + /// Notify the debugger that system memory pressure has been detected. + /// + /// This can be used to free up memory resources by clearing caches. static void MemoryPressureDetected(); + /// Check if this is a valid SBDebugger object. explicit operator bool() const; + /// Check if this is a valid SBDebugger object. bool IsValid() const; + /// Clear this debugger instance. + /// + /// This will close all IO handlers and reset the debugger to its initial + /// state. void Clear(); - /// Getting a specific setting value into SBStructuredData format. + /// Get debugger settings as structured data. + /// /// Client can specify empty string or null to get all settings. /// /// Example usages: @@ -152,71 +195,102 @@ class LLDB_API SBDebugger { /// lldb::SBStructuredData settings = debugger.GetSetting(""); /// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0"); /// lldb::SBStructuredData settings = debugger.GetSetting("target"); - /// - /// \param[out] setting - /// Property setting path to retrieve values. e.g "target.source-map" - /// lldb::SBStructuredData GetSetting(const char *setting = nullptr); + /// Set whether the debugger should run in asynchronous mode. + /// + /// When in asynchronous mode, events are processed on a background thread. void SetAsync(bool b); + /// Get whether the debugger is running in asynchronous mode. bool GetAsync(); + /// Set whether to skip loading .lldbinit files. void SkipLLDBInitFiles(bool b); + /// Set whether to skip loading application-specific .lldbinit files. void SkipAppInitFiles(bool b); #ifndef SWIG + /// Set the input file handle for the debugger. void SetInputFileHandle(FILE *f, bool transfer_ownership); + /// Set the output file handle for the debugger. void SetOutputFileHandle(FILE *f, bool transfer_ownership); + /// Set the error file handle for the debugger. void SetErrorFileHandle(FILE *f, bool transfer_ownership); #endif #ifndef SWIG + /// Get the input file handle for the debugger. FILE *GetInputFileHandle(); + /// Get the output file handle for the debugger. FILE *GetOutputFileHandle(); + /// Get the error file handle for the debugger. FILE *GetErrorFileHandle(); #endif + /// Set the input from a string. SBError SetInputString(const char *data); + /// Set the input file for the debugger. SBError SetInputFile(SBFile file); + /// Set the output file for the debugger. SBError SetOutputFile(SBFile file); + /// Set the error file for the debugger. SBError SetErrorFile(SBFile file); + /// Set the input file for the debugger using a FileSP. SBError SetInputFile(FileSP file); + /// Set the output file for the debugger using a FileSP. SBError SetOutputFile(FileSP file); + /// Set the error file for the debugger using a FileSP. SBError SetErrorFile(FileSP file); + /// Get the input file for the debugger. SBFile GetInputFile(); + /// Get the output file for the debugger. SBFile GetOutputFile(); + /// Get the error file for the debugger. SBFile GetErrorFile(); + /// Save the current terminal state. + /// + /// This should be called before modifying terminal settings. void SaveInputTerminalState(); + /// Restore the previously saved terminal state. void RestoreInputTerminalState(); + /// Get the command interpreter for this debugger. lldb::SBCommandInterpreter GetCommandInterpreter(); + /// Execute a command in the command interpreter. void HandleCommand(const char *command); + /// Request an interrupt of the current operation. void RequestInterrupt(); + + /// Cancel a previously requested interrupt. void CancelInterruptRequest(); + + /// Check if an interrupt has been requested. bool InterruptRequested(); + /// Get the listener associated with this debugger. lldb::SBListener GetListener(); #ifndef SWIG + /// Handle a process event (deprecated). LLDB_DEPRECATED_FIXME( "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, " "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, " @@ -226,58 +300,78 @@ class LLDB_API SBDebugger { const lldb::SBEvent &event, FILE *out, FILE *err); #endif + /// Handle a process event. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, SBFile out, SBFile err); #ifdef SWIG + /// Handle a process event using FileSP objects. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED); #else + /// Handle a process event using FileSP objects. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, FileSP out, FileSP err); #endif + /// Create a target with the specified parameters. lldb::SBTarget CreateTarget(const char *filename, const char *target_triple, const char *platform_name, bool add_dependent_modules, lldb::SBError &error); + /// Create a target with the specified file and target triple. lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename, const char *target_triple); + /// Create a target with the specified file and architecture. lldb::SBTarget CreateTargetWithFileAndArch(const char *filename, const char *archname); + /// Create a target with the specified file. lldb::SBTarget CreateTarget(const char *filename); + /// Get the dummy target. + /// + /// The dummy target is used when no target is available. lldb::SBTarget GetDummyTarget(); #ifndef SWIG - // Dispatch telemery from client to server if client-telemetry is enabled - // (by vendor), otherwise the data is ignored. - // Invoking this from python client (with SWIG) is not supported. + /// Dispatch telemetry data from client to server. + /// + /// This is used to send telemetry data from the client to the server if + /// client-telemetry is enabled. If not enabled, the data is ignored. void DispatchClientTelemetry(const lldb::SBStructuredData &data); #endif - // Return true if target is deleted from the target list of the debugger. + /// Delete a target from the debugger. bool DeleteTarget(lldb::SBTarget &target); + /// Get a target by index. lldb::SBTarget GetTargetAtIndex(uint32_t idx); + /// Get the index of a target. uint32_t GetIndexOfTarget(lldb::SBTarget target); + /// Find a target with the specified process ID. lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid); + /// Find a target with the specified file and architecture. lldb::SBTarget FindTargetWithFileAndArch(const char *filename, const char *arch); + /// Get the number of targets in the debugger. uint32_t GetNumTargets(); + /// Get the currently selected target. lldb::SBTarget GetSelectedTarget(); + /// Set the selected target. void SetSelectedTarget(SBTarget &target); + /// Get the selected platform. lldb::SBPlatform GetSelectedPlatform(); + /// Set the selected platform. void SetSelectedPlatform(lldb::SBPlatform &platform); /// Get the number of currently active platforms. @@ -292,200 +386,247 @@ class LLDB_API SBDebugger { /// "platform list" command. uint32_t GetNumAvailablePlatforms(); - /// Get the name and description of one of the available platforms. - /// - /// \param[in] idx - /// Zero-based index of the platform for which info should be retrieved, - /// must be less than the value returned by GetNumAvailablePlatforms(). + /// Get information about the available platform at the given index as + /// structured data. lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx); + /// Get the source manager for this debugger. lldb::SBSourceManager GetSourceManager(); - // REMOVE: just for a quick fix, need to expose platforms through - // SBPlatform from this class. + /// Set the current platform by name. lldb::SBError SetCurrentPlatform(const char *platform_name); + /// Set the SDK root for the current platform. bool SetCurrentPlatformSDKRoot(const char *sysroot); - // FIXME: Once we get the set show stuff in place, the driver won't need - // an interface to the Set/Get UseExternalEditor. + /// Set whether to use an external editor. bool SetUseExternalEditor(bool input); + /// Get whether an external editor is being used. bool GetUseExternalEditor(); + /// Set whether to use color in output. bool SetUseColor(bool use_color); + /// Get whether color is being used in output. bool GetUseColor() const; - bool SetShowInlineDiagnostics(bool); + /// Set whether to show inline diagnostics. + bool SetShowInlineDiagnostics(bool b); + /// Set whether to use the source cache. bool SetUseSourceCache(bool use_source_cache); + /// Get whether the source cache is being used. bool GetUseSourceCache() const; + /// Get the default architecture. static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len); + /// Set the default architecture. static bool SetDefaultArchitecture(const char *arch_name); + /// Get the scripting language by name. lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name); - SBStructuredData GetScriptInterpreterInfo(ScriptLanguage); + /// Get information about a script interpreter as structured data. + SBStructuredData GetScriptInterpreterInfo(ScriptLanguage language); + /// Get the LLDB version string. static const char *GetVersionString(); + /// Convert a state type to a string. static const char *StateAsCString(lldb::StateType state); + /// Get the build configuration as structured data. static SBStructuredData GetBuildConfiguration(); + /// Check if a state is a running state. static bool StateIsRunningState(lldb::StateType state); + /// Check if a state is a stopped state. static bool StateIsStoppedState(lldb::StateType state); + /// Enable logging for a specific channel and category. bool EnableLog(const char *channel, const char **categories); + /// Set a callback for log output. void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton); - /// Clear all previously added callbacks and only add the given one. + /// Set a callback for when the debugger is destroyed (deprecated). LLDB_DEPRECATED_FIXME("Use AddDestroyCallback and RemoveDestroyCallback", "AddDestroyCallback") void SetDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback, void *baton); - /// Add a callback for when the debugger is destroyed. Return a token, which - /// can be used to remove said callback. Multiple callbacks can be added by - /// calling this function multiple times, and will be invoked in FIFO order. + /// Add a callback for when the debugger is destroyed. Returns a token that + /// can be used to remove the callback. lldb::callback_token_t AddDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback, void *baton); - /// Remove the specified callback. Return true if successful. + /// Remove a destroy callback. bool RemoveDestroyCallback(lldb::callback_token_t token); #ifndef SWIG + /// Dispatch input to the debugger (deprecated). LLDB_DEPRECATED_FIXME("Use DispatchInput(const void *, size_t)", "DispatchInput(const void *, size_t)") void DispatchInput(void *baton, const void *data, size_t data_len); #endif + /// Dispatch input to the debugger. void DispatchInput(const void *data, size_t data_len); + /// Interrupt the current input dispatch. void DispatchInputInterrupt(); + /// Signal end-of-file to the current input dispatch. void DispatchInputEndOfFile(); #ifndef SWIG + /// Push an input reader onto the IO handler stack. void PushInputReader(lldb::SBInputReader &reader); #endif + /// Get the instance name of this debugger. const char *GetInstanceName(); + /// Find a debugger by ID. Returns an invalid debugger if not found. static SBDebugger FindDebuggerWithID(int id); + /// Set an internal variable. static lldb::SBError SetInternalVariable(const char *var_name, const char *value, const char *debugger_instance_name); + /// Get the value of an internal variable. static lldb::SBStringList GetInternalVariableValue(const char *var_name, const char *debugger_instance_name); + /// Get a description of this debugger. bool GetDescription(lldb::SBStream &description); + /// Get the terminal width. uint32_t GetTerminalWidth() const; + /// Set the terminal width. void SetTerminalWidth(uint32_t term_width); + /// Get the terminal height. uint32_t GetTerminalHeight() const; + /// Set the terminal height. void SetTerminalHeight(uint32_t term_height); + /// Get the unique ID of this debugger. lldb::user_id_t GetID(); + /// Get the command prompt string. const char *GetPrompt() const; + /// Set the command prompt string. void SetPrompt(const char *prompt); + /// Get the path to the reproducer. const char *GetReproducerPath() const; + /// Get the current scripting language. lldb::ScriptLanguage GetScriptLanguage() const; + /// Set the current scripting language. void SetScriptLanguage(lldb::ScriptLanguage script_lang); + /// Get the current REPL language. lldb::LanguageType GetREPLLanguage() const; + /// Set the current REPL language. void SetREPLLanguage(lldb::LanguageType repl_lang); + /// Get whether to close input on EOF (deprecated). LLDB_DEPRECATED("SBDebugger::GetCloseInputOnEOF() is deprecated.") bool GetCloseInputOnEOF() const; + /// Set whether to close input on EOF (deprecated). LLDB_DEPRECATED("SBDebugger::SetCloseInputOnEOF() is deprecated.") void SetCloseInputOnEOF(bool b); + /// Get a type category by name. SBTypeCategory GetCategory(const char *category_name); + /// Get a type category by language. SBTypeCategory GetCategory(lldb::LanguageType lang_type); + /// Create a new type category. SBTypeCategory CreateCategory(const char *category_name); + /// Delete a type category. bool DeleteCategory(const char *category_name); + /// Get the number of type categories. uint32_t GetNumCategories(); - SBTypeCategory GetCategoryAtIndex(uint32_t); + /// Get a type category by index. + SBTypeCategory GetCategoryAtIndex(uint32_t index); + /// Get the default type category. SBTypeCategory GetDefaultCategory(); - SBTypeFormat GetFormatForType(SBTypeNameSpecifier); + /// Get the format for a type. + SBTypeFormat GetFormatForType(SBTypeNameSpecifier type_name_spec); - SBTypeSummary GetSummaryForType(SBTypeNameSpecifier); + /// Get the summary for a type. + SBTypeSummary GetSummaryForType(SBTypeNameSpecifier type_name_spec); - SBTypeFilter GetFilterForType(SBTypeNameSpecifier); + /// Get the filter for a type. + SBTypeFilter GetFilterForType(SBTypeNameSpecifier type_name_spec); - SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier); + /// Get the synthetic for a type. + SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier type_name_spec); - /// Clear collected statistics for targets belonging to this debugger. This - /// includes clearing symbol table and debug info parsing/index time for all - /// modules, breakpoint resolve time and target statistics. + /// Clear collected statistics for targets belonging to this debugger. + /// + /// This includes clearing symbol table and debug info parsing/index time for + /// all modules, breakpoint resolve time, and target statistics. void ResetStatistics(); #ifndef SWIG /// Run the command interpreter. /// /// \param[in] auto_handle_events - /// If true, automatically handle resulting events. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, automatically handle resulting events. This takes precedence + /// and overrides the corresponding option in + /// SBCommandInterpreterRunOptions. /// /// \param[in] spawn_thread - /// If true, start a new thread for IO handling. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, start a new thread for IO handling. This takes precedence and + /// overrides the corresponding option in SBCommandInterpreterRunOptions. void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread); #endif - /// Run the command interpreter. + /// Run the command interpreter with options. /// /// \param[in] auto_handle_events - /// If true, automatically handle resulting events. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, automatically handle resulting events. This takes precedence + /// and overrides the corresponding option in + /// SBCommandInterpreterRunOptions. /// /// \param[in] spawn_thread - /// If true, start a new thread for IO handling. This takes precedence - /// and overrides the corresponding option in - /// SBCommandInterpreterRunOptions. + /// If true, start a new thread for IO handling. This takes precedence and + /// overrides the corresponding option in SBCommandInterpreterRunOptions. /// /// \param[in] options - /// Parameter collection of type SBCommandInterpreterRunOptions. + /// Parameter collection of type SBCommandInterpreterRunOptions. /// /// \param[out] num_errors - /// The number of errors. + /// The number of errors. /// /// \param[out] quit_requested - /// Whether a quit was requested. + /// Whether a quit was requested. /// /// \param[out] stopped_for_crash - /// Whether the interpreter stopped for a crash. + /// Whether the interpreter stopped for a crash. #ifdef SWIG %apply int& INOUT { int& num_errors }; %apply bool& INOUT { bool& quit_requested }; @@ -497,20 +638,27 @@ class LLDB_API SBDebugger { bool &stopped_for_crash); #ifndef SWIG + /// Run the command interpreter with options and return a result object. SBCommandInterpreterRunResult RunCommandInterpreter(const SBCommandInterpreterRunOptions &options); #endif + /// Run a REPL (Read-Eval-Print Loop) for the specified language. SBError RunREPL(lldb::LanguageType language, const char *repl_options); - /// Load a trace from a trace description file and create Targets, - /// Processes and Threads based on the contents of such file. + /// Load a trace from a trace description file. + /// + /// This will create Targets, Processes and Threads based on the contents of + /// the file. /// /// \param[out] error /// An error if the trace could not be created. /// /// \param[in] trace_description_file /// The file containing the necessary information to load the trace. + /// + /// \return + /// An SBTrace object representing the loaded trace. SBTrace LoadTraceFromFile(SBError &error, const SBFileSpec &trace_description_file);