This changes '@' prefix to '\'.
llvm-svn: 355841
#include <vector>
//----------------------------------------------------------------------
-/// @def DISALLOW_COPY_AND_ASSIGN(TypeName)
+/// \def DISALLOW_COPY_AND_ASSIGN(TypeName)
/// Macro definition for easily disallowing copy constructor and
/// assignment operators in C++ classes.
//----------------------------------------------------------------------
/// This function implies that a future call to SBTarget::Attach(...)
/// will be synchronous.
///
- /// @param[in] path
+ /// \param[in] path
/// A full or partial name for the process to attach to.
///
- /// @param[in] wait_for
+ /// \param[in] wait_for
/// If \b false, attach to an existing process whose name matches.
/// If \b true, then wait for the next process whose name matches.
//------------------------------------------------------------------
/// Future calls to SBTarget::Attach(...) will be synchronous or
/// asynchronous depending on the \a async argument.
///
- /// @param[in] path
+ /// \param[in] path
/// A full or partial name for the process to attach to.
///
- /// @param[in] wait_for
+ /// \param[in] wait_for
/// If \b false, attach to an existing process whose name matches.
/// If \b true, then wait for the next process whose name matches.
///
- /// @param[in] async
+ /// \param[in] async
/// If \b false, then the SBTarget::Attach(...) call will be a
/// synchronous call with no way to cancel the attach in
/// progress.
/// This function implies that a call to SBTarget::Attach(...) will
/// be synchronous.
///
- /// @param[in] b
+ /// \param[in] b
/// If \b false, attach to an existing process whose name matches.
/// If \b true, then wait for the next process whose name matches.
//------------------------------------------------------------------
/// Future calls to SBTarget::Attach(...) will be synchronous or
/// asynchronous depending on the \a async argument.
///
- /// @param[in] b
+ /// \param[in] b
/// If \b false, attach to an existing process whose name matches.
/// If \b true, then wait for the next process whose name matches.
///
- /// @param[in] async
+ /// \param[in] async
/// If \b false, then the SBTarget::Attach(...) call will be a
/// synchronous call with no way to cancel the attach in
/// progress.
//------------------------------------------------------------------
/// Get the inlined block that contains this block.
///
- /// @return
+ /// \return
/// If this block is inlined, it will return this block, else
/// parent blocks will be searched to see if any contain this
/// block and are themselves inlined. An invalid SBBlock will
/// terminal, so this function allows GUI programs to emulate this
/// functionality.
///
- /// @param[in] ch
+ /// \param[in] ch
/// The character that was typed along with the control key
///
- /// @return
+ /// \return
/// The string that should be written into the file handle that is
/// feeding the input stream for the debugger, or nullptr if there is
/// no string for this control key.
/// Get all types matching \a type_mask from debug info in this
/// compile unit.
///
- /// @param[in] type_mask
+ /// \param[in] type_mask
/// A bitfield that consists of one or more bits logically OR'ed
/// together from the lldb::TypeClass enumeration. This allows
/// you to request only structure types, or only class, struct
/// all types found in the debug information for this compile
/// unit.
///
- /// @return
+ /// \return
/// A list of types in this compile unit that match \a type_mask
//------------------------------------------------------------------
lldb::SBTypeList GetTypes(uint32_t type_mask = lldb::eTypeClassAny);
/// Get the name and description of one of the available platforms.
///
- /// @param[in] idx
+ /// \param[in] idx
/// Zero-based index of the platform for which info should be retrieved,
/// must be less than the value returned by GetNumAvailablePlatforms().
lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx);
/// SBTarget::Launch(...), the target will use the resolved executable
/// path that was used to create the target.
///
- /// @param[in] exe_file
+ /// \param[in] exe_file
/// The override path to use when launching the executable.
///
- /// @param[in] add_as_first_arg
+ /// \param[in] add_as_first_arg
/// If true, then the path will be inserted into the argument vector
/// prior to launching. Otherwise the argument vector will be left
/// alone.
//------------------------------------------------------------------
/// Get the base address of this memory range.
///
- /// @return
+ /// \return
/// The base address of this memory range.
//------------------------------------------------------------------
lldb::addr_t GetRegionBase();
//------------------------------------------------------------------
/// Get the end address of this memory range.
///
- /// @return
+ /// \return
/// The base address of this memory range.
//------------------------------------------------------------------
lldb::addr_t GetRegionEnd();
//------------------------------------------------------------------
/// Check if this memory address is marked readable to the process.
///
- /// @return
+ /// \return
/// true if this memory address is marked readable
//------------------------------------------------------------------
bool IsReadable();
//------------------------------------------------------------------
/// Check if this memory address is marked writable to the process.
///
- /// @return
+ /// \return
/// true if this memory address is marked writable
//------------------------------------------------------------------
bool IsWritable();
//------------------------------------------------------------------
/// Check if this memory address is marked executable to the process.
///
- /// @return
+ /// \return
/// true if this memory address is marked executable
//------------------------------------------------------------------
bool IsExecutable();
/// Check if this memory address is mapped into the process address
/// space.
///
- /// @return
+ /// \return
/// true if this memory address is in the process address space.
//------------------------------------------------------------------
bool IsMapped();
/// Returns the name of the memory region mapped at the given
/// address.
///
- /// @return
+ /// \return
/// In case of memory mapped files it is the absolute path of
/// the file otherwise it is a name associated with the memory
/// region. If no name can be determined the returns nullptr.
/// that is running LLDB. This can differ from the path on the
/// platform since we might be doing remote debugging.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
lldb::SBFileSpec GetFileSpec() const;
/// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
/// The file could also be cached in a local developer kit directory.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
lldb::SBFileSpec GetPlatformFileSpec() const;
/// the target will install this module on the remote platform prior
/// to launching.
///
- /// @return
+ /// \return
/// A file specification object.
//------------------------------------------------------------------
lldb::SBFileSpec GetRemoteInstallFileSpec();
/// or "./usr/lib", then the install path will be resolved using
/// the platform's current working directory as the base path.
///
- /// @param[in] file
+ /// \param[in] file
/// A file specification object.
//------------------------------------------------------------------
bool SetRemoteInstallFileSpec(lldb::SBFileSpec &file);
/// Find compile units related to *this module and passed source
/// file.
///
- /// @param[in] sb_file_spec
+ /// \param[in] sb_file_spec
/// A lldb::SBFileSpec object that contains source file
/// specification.
///
- /// @return
+ /// \return
/// A lldb::SBSymbolContextList that gets filled in with all of
/// the symbol contexts for all the matches.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find functions by name.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the function we are looking for.
///
- /// @param[in] name_type_mask
+ /// \param[in] name_type_mask
/// A logical OR of one or more FunctionNameType enum bits that
/// indicate what kind of names should be used when doing the
/// lookup. Bits include fully qualified names, base names,
/// C++ methods, or ObjC selectors.
/// See FunctionNameType for more details.
///
- /// @return
+ /// \return
/// A lldb::SBSymbolContextList that gets filled in with all of
/// the symbol contexts for all the matches.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find global and static variables by name.
///
- /// @param[in] target
+ /// \param[in] target
/// A valid SBTarget instance representing the debuggee.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the global or static variable we are looking
/// for.
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a max_matches.
///
- /// @return
+ /// \return
/// A list of matched variables in an SBValueList.
//------------------------------------------------------------------
lldb::SBValueList FindGlobalVariables(lldb::SBTarget &target,
//------------------------------------------------------------------
/// Find the first global (or static) variable by name.
///
- /// @param[in] target
+ /// \param[in] target
/// A valid SBTarget instance representing the debuggee.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the global or static variable we are looking
/// for.
///
- /// @return
+ /// \return
/// An SBValue that gets filled in with the found variable (if any).
//------------------------------------------------------------------
lldb::SBValue FindFirstGlobalVariable(lldb::SBTarget &target,
///
/// For DWARF debug info, the type ID is the DIE offset.
///
- /// @param[in] uid
+ /// \param[in] uid
/// The type user ID.
///
- /// @return
+ /// \return
/// An SBType for the given type ID, or an empty SBType if the
/// type was not found.
//------------------------------------------------------------------
/// Get all types matching \a type_mask from debug info in this
/// module.
///
- /// @param[in] type_mask
+ /// \param[in] type_mask
/// A bitfield that consists of one or more bits logically OR'ed
/// together from the lldb::TypeClass enumeration. This allows
/// you to request only structure types, or only class, struct
/// and union types. Passing in lldb::eTypeClassAny will return
/// all types found in the debug information for this module.
///
- /// @return
+ /// \return
/// A list of types in this module that match \a type_mask
//------------------------------------------------------------------
lldb::SBTypeList GetTypes(uint32_t type_mask = lldb::eTypeClassAny);
/// function with a value of \a versions and \a num_versions that
/// has enough storage to store some or all version numbers.
///
- /// @param[out] versions
+ /// \param[out] versions
/// A pointer to an array of uint32_t types that is \a num_versions
/// long. If this value is NULL, the return value will indicate
/// how many version numbers are required for a subsequent call
/// will be filled with \a num_versions UINT32_MAX values
/// and zero will be returned.
///
- /// @param[in] num_versions
+ /// \param[in] num_versions
/// The maximum number of entries to fill into \a versions. If
/// this value is zero, then the return value will indicate
/// how many version numbers there are in total so another call
/// numbers in this object file, only \a num_versions will be
/// filled into \a versions (if \a versions is non-NULL).
///
- /// @return
+ /// \return
/// This function always returns the number of version numbers
/// that this object file has regardless of the number of
/// version numbers that were copied into \a versions.
/// like '/usr/lib/liba.dylib' then debug information can be located
/// in folder like '/usr/lib/liba.dylib.dSYM/'.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
lldb::SBFileSpec GetSymbolFileSpec() const;
/// that is running LLDB. This can differ from the path on the
/// platform since we might be doing remote debugging.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
lldb::SBFileSpec GetFileSpec();
/// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
/// The file could also be cached in a local developer kit directory.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
lldb::SBFileSpec GetPlatformFileSpec();
/// this is typically the same as if you called "getpid()" in the
/// process.
///
- /// @return
+ /// \return
/// Returns LLDB_INVALID_PROCESS_ID if this object does not
/// contain a valid process object, or if the process has not
/// been launched. Returns a valid process ID if the process is
/// create a process with the same process ID, there needs to be a
/// way to tell two process instances apart.
///
- /// @return
+ /// \return
/// Returns a non-zero integer ID if this object contains a
/// valid process object, zero if this object does not contain
/// a valid process object.
/// Note that it wasn't fully implemented and tracks only the stop
/// event for the last natural stop ID.
///
- /// @param [in] stop_id
+ /// \param [in] stop_id
/// The ID of the stop event to return.
///
- /// @return
+ /// \return
/// The stop event corresponding to stop ID.
//------------------------------------------------------------------
lldb::SBEvent GetStopEventForStopID(uint32_t stop_id);
//------------------------------------------------------------------
/// Start Tracing with the given SBTraceOptions.
///
- /// @param[in] options
+ /// \param[in] options
/// Class containing trace options like trace buffer size, meta
/// data buffer size, TraceType and any custom parameters
/// {formatted as a JSON Dictionary}. In case of errors in
/// parameters, only the parameters recognized by the target
/// would be used and others would be ignored.
///
- /// @param[out] error
+ /// \param[out] error
/// An error explaining what went wrong.
///
- /// @return
+ /// \return
/// A SBTrace instance, which should be used
/// to get the trace data or other trace related operations.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Load a shared library into this process.
///
- /// @param[in] remote_image_spec
+ /// \param[in] remote_image_spec
/// The path for the shared library on the target what you want
/// to load.
///
- /// @param[out] error
+ /// \param[out] error
/// An error object that gets filled in with any errors that
/// might occur when trying to load the shared library.
///
- /// @return
+ /// \return
/// A token that represents the shared library that can be
/// later used to unload the shared library. A value of
/// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
//------------------------------------------------------------------
/// Load a shared library into this process.
///
- /// @param[in] local_image_spec
+ /// \param[in] local_image_spec
/// The file spec that points to the shared library that you
/// want to load if the library is located on the host. The
/// library will be copied over to the location specified by
/// remote_image_spec or into the current working directory with
/// the same filename if the remote_image_spec isn't specified.
///
- /// @param[in] remote_image_spec
+ /// \param[in] remote_image_spec
/// If local_image_spec is specified then the location where the
/// library should be copied over from the host. If
/// local_image_spec isn't specified, then the path for the
/// shared library on the target what you want to load.
///
- /// @param[out] error
+ /// \param[out] error
/// An error object that gets filled in with any errors that
/// might occur when trying to load the shared library.
///
- /// @return
+ /// \return
/// A token that represents the shared library that can be
/// later used to unload the shared library. A value of
/// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
/// library name and a list of paths, searching along the list of
/// paths till you find a matching library.
///
- /// @param[in] image_spec
+ /// \param[in] image_spec
/// The name of the shared library that you want to load.
/// If image_spec is a relative path, the relative path will be
/// appended to the search paths.
/// If the image_spec is an absolute path, just the basename is used.
///
- /// @param[in] paths
+ /// \param[in] paths
/// A list of paths to search for the library whose basename is
/// local_spec.
///
- /// @param[out] loaded_path
+ /// \param[out] loaded_path
/// If the library was found along the paths, this will store the
/// full path to the found library.
///
- /// @param[out] error
+ /// \param[out] error
/// An error object that gets filled in with any errors that
/// might occur when trying to search for the shared library.
///
- /// @return
+ /// \return
/// A token that represents the shared library that can be
/// later passed to UnloadImage. A value of
/// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
/// or the work item was enqueued to it (in the case of a libdispatch
/// queue).
///
- /// @return
+ /// \return
/// The number of thread-origin extended backtrace types that may be
/// available.
//------------------------------------------------------------------
/// Return the name of one of the thread-origin extended backtrace
/// methods.
///
- /// @param [in] idx
+ /// \param [in] idx
/// The index of the name to return. They will be returned in
/// the order that the user will most likely want to see them.
/// e.g. if the type at index 0 is not available for a thread,
/// see if the type at index 1 provides an extended backtrace.
///
- /// @return
+ /// \return
/// The name at that index.
//------------------------------------------------------------------
const char *GetExtendedBacktraceTypeAtIndex(uint32_t idx);
/// region that contains it in the supplied SBMemoryRegionInfo object.
/// To iterate over all memory regions use GetMemoryRegionList.
///
- /// @param[in] load_addr
+ /// \param[in] load_addr
/// The address to be queried.
///
- /// @param[out] region_info
+ /// \param[out] region_info
/// A reference to an SBMemoryRegionInfo object that will contain
/// the details of the memory region containing load_addr.
///
- /// @return
+ /// \return
/// An error object describes any errors that occurred while
/// querying load_addr.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return the list of memory regions within the process.
///
- /// @return
+ /// \return
/// A list of all witin the process memory regions.
//------------------------------------------------------------------
lldb::SBMemoryRegionInfoList GetMemoryRegions();
/// i.e. for a section having read and execute permissions, the value
/// returned is 6
///
- /// @return
+ /// \return
/// Returns an unsigned value for Permissions for the section.
//------------------------------------------------------------------
uint32_t
/// varying minimum addressable unit (i.e. byte) size for their
/// CODE or DATA buses.
///
- /// @return
+ /// \return
/// The number of host (8-bit) bytes needed to hold a target byte
//------------------------------------------------------------------
uint32_t GetTargetByteSize();
//------------------------------------------------------------------
/// Provides the string value if this data structure is a string type.
///
- /// @param[out] dst
+ /// \param[out] dst
/// pointer where the string value will be written. In case it is null,
/// nothing will be written at @dst.
///
- /// @param[in] dst_len
+ /// \param[in] dst_len
/// max number of characters that can be written at @dst. In case it is
/// zero, nothing will be written at @dst. If this length is not enough
/// to write the complete string value, (dst_len-1) bytes of the string
/// value will be written at @dst followed by a null character.
///
- /// @return
+ /// \return
/// Returns the byte size needed to completely write the string value at
/// @dst in all cases.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Sets whether we should collect statistics on lldb or not.
///
- /// @param[in] v
+ /// \param[in] v
/// A boolean to control the collection.
//------------------------------------------------------------------
void SetCollectingStats(bool v);
//------------------------------------------------------------------
/// Returns whether statistics collection are enabled.
///
- /// @return
+ /// \return
/// true if statistics are currently being collected, false
/// otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns a dump of the collected statistics.
///
- /// @return
+ /// \return
/// A SBStructuredData with the statistics collected.
//------------------------------------------------------------------
lldb::SBStructuredData GetStatistics();
/// After return, the platform object should be checked for
/// validity.
///
- /// @return
+ /// \return
/// A platform object.
//------------------------------------------------------------------
lldb::SBPlatform GetPlatform();
/// have an install location set, it will be installed in the remote
/// platform's working directory.
///
- /// @return
+ /// \return
/// An error describing anything that went wrong during
/// installation.
//------------------------------------------------------------------
/// optionally re-directed to \a stdin_path, \a stdout_path, and
/// \a stderr_path.
///
- /// @param[in] listener
+ /// \param[in] listener
/// An optional listener that will receive all process events.
/// If \a listener is valid then \a listener will listen to all
/// process events. If not valid, then this target's debugger
/// (SBTarget::GetDebugger()) will listen to all process events.
///
- /// @param[in] argv
+ /// \param[in] argv
/// The argument array.
///
- /// @param[in] envp
+ /// \param[in] envp
/// The environment array.
///
- /// @param[in] stdin_path
+ /// \param[in] stdin_path
/// The path to use when re-directing the STDIN of the new
/// process. If all stdXX_path arguments are nullptr, a pseudo
/// terminal will be used.
///
- /// @param[in] stdout_path
+ /// \param[in] stdout_path
/// The path to use when re-directing the STDOUT of the new
/// process. If all stdXX_path arguments are nullptr, a pseudo
/// terminal will be used.
///
- /// @param[in] stderr_path
+ /// \param[in] stderr_path
/// The path to use when re-directing the STDERR of the new
/// process. If all stdXX_path arguments are nullptr, a pseudo
/// terminal will be used.
///
- /// @param[in] working_directory
+ /// \param[in] working_directory
/// The working directory to have the child process run in
///
- /// @param[in] launch_flags
+ /// \param[in] launch_flags
/// Some launch options specified by logical OR'ing
/// lldb::LaunchFlags enumeration values together.
///
- /// @param[in] stop_at_entry
+ /// \param[in] stop_at_entry
/// If false do not stop the inferior at the entry point.
///
- /// @param[out] error
+ /// \param[out] error
/// An error object. Contains the reason if there is some failure.
///
- /// @return
+ /// \return
/// A process object for the newly created process.
//------------------------------------------------------------------
lldb::SBProcess Launch(SBListener &listener, char const **argv,
//------------------------------------------------------------------
/// Launch a new process with sensible defaults.
///
- /// @param[in] argv
+ /// \param[in] argv
/// The argument array.
///
- /// @param[in] envp
+ /// \param[in] envp
/// The environment array.
///
- /// @param[in] working_directory
+ /// \param[in] working_directory
/// The working directory to have the child process run in
///
/// Default: listener
/// Default: stderr_path
/// A pseudo terminal will be used.
///
- /// @return
+ /// \return
/// A process object for the newly created process.
//------------------------------------------------------------------
SBProcess LaunchSimple(const char **argv, const char **envp,
//------------------------------------------------------------------
/// Attach to process with pid.
///
- /// @param[in] listener
+ /// \param[in] listener
/// An optional listener that will receive all process events.
/// If \a listener is valid then \a listener will listen to all
/// process events. If not valid, then this target's debugger
/// (SBTarget::GetDebugger()) will listen to all process events.
///
- /// @param[in] pid
+ /// \param[in] pid
/// The process ID to attach to.
///
- /// @param[out] error
+ /// \param[out] error
/// An error explaining what went wrong if attach fails.
///
- /// @return
+ /// \return
/// A process object for the attached process.
//------------------------------------------------------------------
lldb::SBProcess AttachToProcessWithID(SBListener &listener, lldb::pid_t pid,
//------------------------------------------------------------------
/// Attach to process with name.
///
- /// @param[in] listener
+ /// \param[in] listener
/// An optional listener that will receive all process events.
/// If \a listener is valid then \a listener will listen to all
/// process events. If not valid, then this target's debugger
/// (SBTarget::GetDebugger()) will listen to all process events.
///
- /// @param[in] name
+ /// \param[in] name
/// Basename of process to attach to.
///
- /// @param[in] wait_for
+ /// \param[in] wait_for
/// If true wait for a new instance of 'name' to be launched.
///
- /// @param[out] error
+ /// \param[out] error
/// An error explaining what went wrong if attach fails.
///
- /// @return
+ /// \return
/// A process object for the attached process.
//------------------------------------------------------------------
lldb::SBProcess AttachToProcessWithName(SBListener &listener,
//------------------------------------------------------------------
/// Connect to a remote debug server with url.
///
- /// @param[in] listener
+ /// \param[in] listener
/// An optional listener that will receive all process events.
/// If \a listener is valid then \a listener will listen to all
/// process events. If not valid, then this target's debugger
/// (SBTarget::GetDebugger()) will listen to all process events.
///
- /// @param[in] url
+ /// \param[in] url
/// The url to connect to, e.g., 'connect://localhost:12345'.
///
- /// @param[in] plugin_name
+ /// \param[in] plugin_name
/// The plugin name to be used; can be nullptr.
///
- /// @param[out] error
+ /// \param[out] error
/// An error explaining what went wrong if the connect fails.
///
- /// @return
+ /// \return
/// A process object for the connected process.
//------------------------------------------------------------------
lldb::SBProcess ConnectRemote(SBListener &listener, const char *url,
/// Find compile units related to *this target and passed source
/// file.
///
- /// @param[in] sb_file_spec
+ /// \param[in] sb_file_spec
/// A lldb::SBFileSpec object that contains source file
/// specification.
///
- /// @return
+ /// \return
/// A lldb::SBSymbolContextList that gets filled in with all of
/// the symbol contexts for all the matches.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Architecture data byte width accessor
///
- /// @return
+ /// \return
/// The size in 8-bit (host) bytes of a minimum addressable
/// unit from the Architecture's data bus
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Architecture code byte width accessor
///
- /// @return
+ /// \return
/// The size in 8-bit (host) bytes of a minimum addressable
/// unit from the Architecture's code bus
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the base load address for a module section.
///
- /// @param[in] section
+ /// \param[in] section
/// The section whose base load address will be set within this
/// target.
///
- /// @param[in] section_base_addr
+ /// \param[in] section_base_addr
/// The base address for the section.
///
- /// @return
+ /// \return
/// An error to indicate success, fail, and any reason for
/// failure.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Clear the base load address for a module section.
///
- /// @param[in] section
+ /// \param[in] section
/// The section whose base load address will be cleared within
/// this target.
///
- /// @return
+ /// \return
/// An error to indicate success, fail, and any reason for
/// failure.
//------------------------------------------------------------------
/// this function will allow you to easily and quickly slide all
/// module sections.
///
- /// @param[in] module
+ /// \param[in] module
/// The module to load.
///
- /// @param[in] sections_offset
+ /// \param[in] sections_offset
/// An offset that will be applied to all section file addresses
/// (the virtual addresses found in the object file itself).
///
- /// @return
+ /// \return
/// An error to indicate success, fail, and any reason for
/// failure.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Clear the section base load addresses for all sections in a module.
///
- /// @param[in] module
+ /// \param[in] module
/// The module to unload.
///
- /// @return
+ /// \return
/// An error to indicate success, fail, and any reason for
/// failure.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find functions by name.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the function we are looking for.
///
- /// @param[in] name_type_mask
+ /// \param[in] name_type_mask
/// A logical OR of one or more FunctionNameType enum bits that
/// indicate what kind of names should be used when doing the
/// lookup. Bits include fully qualified names, base names,
/// C++ methods, or ObjC selectors.
/// See FunctionNameType for more details.
///
- /// @return
+ /// \return
/// A lldb::SBSymbolContextList that gets filled in with all of
/// the symbol contexts for all the matches.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find global and static variables by name.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the global or static variable we are looking
/// for.
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a max_matches.
///
- /// @return
+ /// \return
/// A list of matched variables in an SBValueList.
//------------------------------------------------------------------
lldb::SBValueList FindGlobalVariables(const char *name, uint32_t max_matches);
//------------------------------------------------------------------
/// Find the first global (or static) variable by name.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the global or static variable we are looking
/// for.
///
- /// @return
+ /// \return
/// An SBValue that gets filled in with the found variable (if any).
//------------------------------------------------------------------
lldb::SBValue FindFirstGlobalVariable(const char *name);
//------------------------------------------------------------------
/// Find global and static variables by pattern.
///
- /// @param[in] name
+ /// \param[in] name
/// The pattern to search for global or static variables
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a max_matches.
///
- /// @param[in] matchtype
+ /// \param[in] matchtype
/// The match type to use.
///
- /// @return
+ /// \return
/// A list of matched variables in an SBValueList.
//------------------------------------------------------------------
lldb::SBValueList FindGlobalVariables(const char *name, uint32_t max_matches,
//------------------------------------------------------------------
/// Find global functions by their name with pattern matching.
///
- /// @param[in] name
+ /// \param[in] name
/// The pattern to search for global or static variables
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a max_matches.
///
- /// @param[in] matchtype
+ /// \param[in] matchtype
/// The match type to use.
///
- /// @return
+ /// \return
/// A list of matched variables in an SBValueList.
//------------------------------------------------------------------
lldb::SBSymbolContextList FindGlobalFunctions(const char *name,
//------------------------------------------------------------------
/// Resolve a current file address into a section offset address.
///
- /// @param[in] file_addr
+ /// \param[in] file_addr
/// The file address to resolve.
///
- /// @return
+ /// \return
/// An SBAddress which will be valid if...
//------------------------------------------------------------------
lldb::SBAddress ResolveFileAddress(lldb::addr_t file_addr);
//------------------------------------------------------------------
/// Resolve a current load address into a section offset address.
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// A virtual address from the current process state that is to
/// be translated into a section offset address.
///
- /// @return
+ /// \return
/// An SBAddress which will be valid if \a vm_addr was
/// successfully resolved into a section offset address, or an
/// invalid SBAddress if \a vm_addr doesn't resolve to a section
/// Resolve a current load address into a section offset address
/// using the process stop ID to identify a time in the past.
///
- /// @param[in] stop_id
+ /// \param[in] stop_id
/// Each time a process stops, the process stop ID integer gets
/// incremented. These stop IDs are used to identify past times
/// and can be used in history objects as a cheap way to store
/// UINT32_MAX will always resolve the address using the
/// currently loaded sections.
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// A virtual address from the current process state that is to
/// be translated into a section offset address.
///
- /// @return
+ /// \return
/// An SBAddress which will be valid if \a vm_addr was
/// successfully resolved into a section offset address, or an
/// invalid SBAddress if \a vm_addr doesn't resolve to a section
/// files. For a target whose bytes are sized as a multiple of host
/// bytes, the data read back will preserve the target's byte order.
///
- /// @param[in] addr
+ /// \param[in] addr
/// A target address to read from.
///
- /// @param[out] buf
+ /// \param[out] buf
/// The buffer to read memory into.
///
- /// @param[in] size
+ /// \param[in] size
/// The maximum number of host bytes to read in the buffer passed
/// into this call
///
- /// @param[out] error
+ /// \param[out] error
/// Status information is written here if the memory read fails.
///
- /// @return
+ /// \return
/// The amount of data read in host bytes.
//------------------------------------------------------------------
size_t ReadMemory(const SBAddress addr, void *buf, size_t size,
//------------------------------------------------------------------
/// Create a breakpoint using a scripted resolver.
///
- /// @param[in] class_name
+ /// \param[in] class_name
/// This is the name of the class that implements a scripted resolver.
///
- /// @param[in] extra_args
+ /// \param[in] extra_args
/// This is an SBStructuredData object that will get passed to the
/// constructor of the class in class_name. You can use this to
/// reuse the same class, parametrizing with entries from this
/// dictionary.
///
- /// @param module_list
+ /// \param module_list
/// If this is non-empty, this will be used as the module filter in the
/// SearchFilter created for this breakpoint.
///
- /// @param file_list
+ /// \param file_list
/// If this is non-empty, this will be used as the comp unit filter in the
/// SearchFilter created for this breakpoint.
///
- /// @return
+ /// \return
/// An SBBreakpoint that will set locations based on the logic in the
/// resolver's search callback.
//------------------------------------------------------------------
/// Read breakpoints from source_file and return the newly created
/// breakpoints in bkpt_list.
///
- /// @param[in] source_file
+ /// \param[in] source_file
/// The file from which to read the breakpoints.
///
- /// @param[out] new_bps
+ /// \param[out] new_bps
/// A list of the newly created breakpoints.
///
- /// @return
+ /// \return
/// An SBError detailing any errors in reading in the breakpoints.
//------------------------------------------------------------------
lldb::SBError BreakpointsCreateFromFile(SBFileSpec &source_file,
/// Read breakpoints from source_file and return the newly created
/// breakpoints in bkpt_list.
///
- /// @param[in] source_file
+ /// \param[in] source_file
/// The file from which to read the breakpoints.
///
- /// @param[in] matching_names
+ /// \param[in] matching_names
/// Only read in breakpoints whose names match one of the names in this
/// list.
///
- /// @param[out] new_bps
+ /// \param[out] new_bps
/// A list of the newly created breakpoints.
///
- /// @return
+ /// \return
/// An SBError detailing any errors in reading in the breakpoints.
//------------------------------------------------------------------
lldb::SBError BreakpointsCreateFromFile(SBFileSpec &source_file,
//------------------------------------------------------------------
/// Write breakpoints to dest_file.
///
- /// @param[in] dest_file
+ /// \param[in] dest_file
/// The file to which to write the breakpoints.
///
- /// @return
+ /// \return
/// An SBError detailing any errors in writing in the breakpoints.
//------------------------------------------------------------------
lldb::SBError BreakpointsWriteToFile(SBFileSpec &dest_file);
//------------------------------------------------------------------
/// Write breakpoints listed in bkpt_list to dest_file.
///
- /// @param[in] dest_file
+ /// \param[in] dest_file
/// The file to which to write the breakpoints.
///
- /// @param[in] bkpt_list
+ /// \param[in] bkpt_list
/// Only write breakpoints from this list.
///
- /// @param[in] append
+ /// \param[in] append
/// If \btrue, append the breakpoints in bkpt_list to the others
/// serialized in dest_file. If dest_file doesn't exist, then a new
/// file will be created and the breakpoints in bkpt_list written to it.
///
- /// @return
+ /// \return
/// An SBError detailing any errors in writing in the breakpoints.
//------------------------------------------------------------------
lldb::SBError BreakpointsWriteToFile(SBFileSpec &dest_file,
//------------------------------------------------------------------
/// Obtain the trace data as raw bytes.
///
- /// @param[out] error
+ /// \param[out] error
/// An error explaining what went wrong.
///
- /// @param[in] buf
+ /// \param[in] buf
/// Buffer to write the trace data to.
///
- /// @param[in] size
+ /// \param[in] size
/// The size of the buffer used to read the data. This is
/// also the size of the data intended to read. It is also
/// possible to partially read the trace data for some trace
/// technologies by specifying a smaller buffer.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The start offset to begin reading the trace data.
///
- /// @param[in] thread_id
+ /// \param[in] thread_id
/// Tracing could be started for the complete process or a
/// single thread, in the first case the traceid obtained would
/// map to all the threads existing within the process and the
/// such a scenario to select the trace data for a specific
/// thread.
///
- /// @return
+ /// \return
/// The size of the trace data effectively read by the API call.
//------------------------------------------------------------------
size_t GetTraceData(SBError &error, void *buf, size_t size, size_t offset = 0,
/// Stop the tracing instance. Stopping the trace will also
/// lead to deletion of any gathered trace data.
///
- /// @param[out] error
+ /// \param[out] error
/// An error explaining what went wrong.
///
- /// @param[in] thread_id
+ /// \param[in] thread_id
/// The trace id could map to a tracing instance for a thread
/// or could also map to a group of threads being traced with
/// the same trace options. A thread_id is normally optional
/// The threadid in the SBTraceOptions needs to be set when the
/// configuration used by a specific thread is being requested.
///
- /// @param[out] options
+ /// \param[out] options
/// The trace options actually used by the trace instance
/// would be filled by the API.
///
- /// @param[out] error
+ /// \param[out] error
/// An error explaining what went wrong.
//------------------------------------------------------------------
void GetTraceConfig(SBTraceOptions &options, SBError &error);
/// that aren't in the array bounds using positive or negative
/// indexes.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The index of the child value to get
///
- /// @param[in] use_dynamic
+ /// \param[in] use_dynamic
/// An enumeration that specifies whether to get dynamic values,
/// and also if the target can be run to figure out the dynamic
/// type of the child value.
///
- /// @param[in] can_create_synthetic
+ /// \param[in] can_create_synthetic
/// If \b true, then allow child values to be created by index
/// for pointers and arrays for indexes that normally wouldn't
/// be allowed.
///
- /// @return
+ /// \return
/// A new SBValue object that represents the child member value.
//------------------------------------------------------------------
lldb::SBValue GetChildAtIndex(uint32_t idx,
/// data type is a T* or T[], and extract item_count elements
/// of type T from it, copying their contents in an SBData.
///
- /// @param[in] item_idx
+ /// \param[in] item_idx
/// The index of the first item to retrieve. For an array
/// this is equivalent to array[item_idx], for a pointer
/// to *(pointer + item_idx). In either case, the measurement
/// unit for item_idx is the sizeof(T) rather than the byte
///
- /// @param[in] item_count
+ /// \param[in] item_count
/// How many items should be copied into the output. By default
/// only one item is copied, but more can be asked for.
///
- /// @return
+ /// \return
/// An SBData with the contents of the copied items, on success.
/// An empty SBData otherwise.
//------------------------------------------------------------------
/// This method will read the contents of this object in memory
/// and copy them into an SBData for future use.
///
- /// @return
+ /// \return
/// An SBData with the contents of this SBValue, on success.
/// An empty SBData otherwise.
//------------------------------------------------------------------
/// pointers, references, arrays and more. Again, it does so without
/// doing any expensive type completion.
///
- /// @return
+ /// \return
/// Returns \b true if the SBValue might have children, or \b
/// false otherwise.
//------------------------------------------------------------------
///
/// Sets a watchpoint on the value.
///
- /// @param[in] resolve_location
+ /// \param[in] resolve_location
/// Resolve the location of this value once and watch its address.
/// This value must currently be set to \b true as watching all
/// locations of a variable or a variable path is not yet supported,
/// though we plan to support it in the future.
///
- /// @param[in] read
+ /// \param[in] read
/// Stop when this value is accessed.
///
- /// @param[in] write
+ /// \param[in] write
/// Stop when this value is modified
///
- /// @param[out] error
+ /// \param[out] error
/// An error object. Contains the reason if there is some failure.
///
- /// @return
+ /// \return
/// An SBWatchpoint object. This object might not be valid upon
/// return due to a value not being contained in memory, too
/// large, or watchpoint resources are not available or all in
///
/// Sets a watchpoint on the value.
///
- /// @param[in] resolve_location
+ /// \param[in] resolve_location
/// Resolve the location of this value once and watch its address.
/// This value must currently be set to \b true as watching all
/// locations of a variable or a variable path is not yet supported,
/// though we plan to support it in the future.
///
- /// @param[in] read
+ /// \param[in] read
/// Stop when this value is accessed.
///
- /// @param[in] write
+ /// \param[in] write
/// Stop when this value is modified
///
- /// @param[out] error
+ /// \param[out] error
/// An error object. Contains the reason if there is some failure.
///
- /// @return
+ /// \return
/// An SBWatchpoint object. This object might not be valid upon
/// return due to a value not being contained in memory, too
/// large, or watchpoint resources are not available or all in
/// already
/// holding the two above-mentioned locks.
///
- /// @return
+ /// \return
/// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
/// can cons up, in accordance with the SBValue's settings.
//------------------------------------------------------------------
/// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so
/// far.
///
- /// @param[in] value_locker
+ /// \param[in] value_locker
/// An object that will hold the Target API, and Process RunLocks, and
/// auto-destroy them when it goes out of scope. Currently this is only
/// useful in
/// SBValue.cpp.
///
- /// @return
+ /// \return
/// A ValueObjectSP of the best kind (static, dynamic or synthetic) we
/// can cons up, in accordance with the SBValue's settings.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" Class that
+/// \class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" Class that
/// manages logical breakpoint setting.
//----------------------------------------------------------------------
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// Tell whether this breakpoint is an "internal" breakpoint. @return
+ /// Tell whether this breakpoint is an "internal" breakpoint. \return
/// Returns \b true if this is an internal breakpoint, \b false otherwise.
//------------------------------------------------------------------
bool IsInternal() const;
/// Tell this breakpoint to scan a given module list and resolve any new
/// locations that match the breakpoint's specifications.
///
- /// @param[in] module_list
+ /// \param[in] module_list
/// The list of modules to look in for new locations.
///
- /// @param[in] send_event
+ /// \param[in] send_event
/// If \b true, send a breakpoint location added event for non-internal
/// breakpoints.
//------------------------------------------------------------------
/// Tell this breakpoint to scan a given module list and resolve any new
/// locations that match the breakpoint's specifications.
///
- /// @param[in] changed_modules
+ /// \param[in] changed_modules
/// The list of modules to look in for new locations.
///
- /// @param[in] new_locations
+ /// \param[in] new_locations
/// Fills new_locations with the new locations that were made.
//------------------------------------------------------------------
void ResolveBreakpointInModules(ModuleList &module_list,
/// which case we will remove any locations that are in modules that got
/// unloaded.
///
- /// @param[in] changedModules
+ /// \param[in] changedModules
/// The list of modules to look in for new locations.
- /// @param[in] load_event
+ /// \param[in] load_event
/// If \b true then the modules were loaded, if \b false, unloaded.
- /// @param[in] delete_locations
+ /// \param[in] delete_locations
/// If \b true then the modules were unloaded delete any locations in the
/// changed modules.
//------------------------------------------------------------------
/// by new_module_sp (usually because the underlying file has been rebuilt,
/// and the old version is gone.)
///
- /// @param[in] old_module_sp
+ /// \param[in] old_module_sp
/// The old module that is going away.
- /// @param[in] new_module_sp
+ /// \param[in] new_module_sp
/// The new module that is replacing it.
//------------------------------------------------------------------
void ModuleReplaced(lldb::ModuleSP old_module_sp,
/// Add a location to the breakpoint's location list. This is only meant to
/// be called by the breakpoint's resolver. FIXME: how do I ensure that?
///
- /// @param[in] addr
+ /// \param[in] addr
/// The Address specifying the new location.
- /// @param[out] new_location
+ /// \param[out] new_location
/// Set to \b true if a new location was created, to \b false if there
/// already was a location at this Address.
- /// @return
+ /// \return
/// Returns a pointer to the new location.
//------------------------------------------------------------------
lldb::BreakpointLocationSP AddLocation(const Address &addr,
//------------------------------------------------------------------
/// Find a breakpoint location by Address.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The Address specifying the location.
- /// @return
+ /// \return
/// Returns a shared pointer to the location at \a addr. The pointer
/// in the shared pointer will be nullptr if there is no location at that
/// address.
//------------------------------------------------------------------
/// Find a breakpoint location ID by Address.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The Address specifying the location.
- /// @return
+ /// \return
/// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if
/// there is no breakpoint location at that address.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find a breakpoint location for a given breakpoint location ID.
///
- /// @param[in] bp_loc_id
+ /// \param[in] bp_loc_id
/// The ID specifying the location.
- /// @return
+ /// \return
/// Returns a shared pointer to the location with ID \a bp_loc_id. The
/// pointer
/// in the shared pointer will be nullptr if there is no location with that
//------------------------------------------------------------------
/// Get breakpoint locations by index.
///
- /// @param[in] index
+ /// \param[in] index
/// The location index.
///
- /// @return
+ /// \return
/// Returns a shared pointer to the location with index \a
/// index. The shared pointer might contain nullptr if \a index is
/// greater than then number of actual locations.
/// This is typically used after the process calls exec, or anytime the
/// architecture of the target changes.
///
- /// @param[in] arch
+ /// \param[in] arch
/// If valid, check the module in each breakpoint to make sure
/// they are compatible, otherwise, ignore architecture.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check the Enable/Disable state.
- /// @return
+ /// \return
/// \b true if the breakpoint is enabled, \b false if disabled.
//------------------------------------------------------------------
bool IsEnabled() override;
//------------------------------------------------------------------
/// Set the breakpoint to ignore the next \a count breakpoint hits.
- /// @param[in] count
+ /// \param[in] count
/// The number of breakpoint hits to ignore.
//------------------------------------------------------------------
void SetIgnoreCount(uint32_t count);
//------------------------------------------------------------------
/// Return the current ignore count/
- /// @return
+ /// \return
/// The number of breakpoint hits to be ignored.
//------------------------------------------------------------------
uint32_t GetIgnoreCount() const;
//------------------------------------------------------------------
- /// Return the current hit count for all locations. @return
+ /// Return the current hit count for all locations. \return
/// The current hit count for all locations.
//------------------------------------------------------------------
uint32_t GetHitCount() const;
//------------------------------------------------------------------
/// Check the OneShot state.
- /// @return
+ /// \return
/// \b true if the breakpoint is one shot, \b false otherwise.
//------------------------------------------------------------------
bool IsOneShot() const;
//------------------------------------------------------------------
/// Check the AutoContinue state.
- /// @return
+ /// \return
/// \b true if the breakpoint is set to auto-continue, \b false otherwise.
//------------------------------------------------------------------
bool IsAutoContinue() const;
//------------------------------------------------------------------
/// Set the valid thread to be checked when the breakpoint is hit.
- /// @param[in] thread_id
+ /// \param[in] thread_id
/// If this thread hits the breakpoint, we stop, otherwise not.
//------------------------------------------------------------------
void SetThreadID(lldb::tid_t thread_id);
//------------------------------------------------------------------
/// Return the current stop thread value.
- /// @return
+ /// \return
/// The thread id for which the breakpoint hit will stop,
/// LLDB_INVALID_THREAD_ID for all threads.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the callback action invoked when the breakpoint is hit.
///
- /// @param[in] callback
+ /// \param[in] callback
/// The method that will get called when the breakpoint is hit.
- /// @param[in] baton
+ /// \param[in] baton
/// A void * pointer that will get passed back to the callback function.
- /// @param[in] is_synchronous
+ /// \param[in] is_synchronous
/// If \b true the callback will be run on the private event thread
/// before the stop event gets reported. If false, the callback will get
/// handled on the public event thread after the stop has been posted.
///
- /// @return
+ /// \return
/// \b true if the process should stop when you hit the breakpoint.
/// \b false if it should continue.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the breakpoint's condition.
///
- /// @param[in] condition
+ /// \param[in] condition
/// The condition expression to evaluate when the breakpoint is hit.
/// Pass in nullptr to clear the condition.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return a pointer to the text of the condition expression.
///
- /// @return
+ /// \return
/// A pointer to the condition expression text, or nullptr if no
// condition has been set.
//------------------------------------------------------------------
/// Return the number of breakpoint locations that have resolved to actual
/// breakpoint sites.
///
- /// @return
+ /// \return
/// The number locations resolved breakpoint sites.
//------------------------------------------------------------------
size_t GetNumResolvedLocations() const;
//------------------------------------------------------------------
/// Return whether this breakpoint has any resolved locations.
///
- /// @return
+ /// \return
/// True if GetNumResolvedLocations > 0
//------------------------------------------------------------------
bool HasResolvedLocations() const;
//------------------------------------------------------------------
/// Return the number of breakpoint locations.
///
- /// @return
+ /// \return
/// The number breakpoint locations.
//------------------------------------------------------------------
size_t GetNumLocations() const;
//------------------------------------------------------------------
/// Put a description of this breakpoint into the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// Stream into which to dump the description.
///
- /// @param[in] level
+ /// \param[in] level
/// The description level that indicates the detail level to
/// provide.
///
- /// @see lldb::DescriptionLevel
+ /// \see lldb::DescriptionLevel
//------------------------------------------------------------------
void GetDescription(Stream *s, lldb::DescriptionLevel level,
bool show_locations = false);
/// breakpoint number. Mostly useful for internal breakpoints, where the
/// breakpoint number doesn't have meaning to the user.
///
- /// @param[in] kind
+ /// \param[in] kind
/// New "kind" description.
//------------------------------------------------------------------
void SetBreakpointKind(const char *kind) { m_kind_description.assign(kind); }
//------------------------------------------------------------------
/// Return the "kind" description for a breakpoint.
///
- /// @return
+ /// \return
/// The breakpoint kind, or nullptr if none is set.
//------------------------------------------------------------------
const char *GetBreakpointKind() const { return m_kind_description.c_str(); }
//------------------------------------------------------------------
/// Accessor for the breakpoint Target.
- /// @return
+ /// \return
/// This breakpoint's Target.
//------------------------------------------------------------------
Target &GetTarget() { return m_target; }
/// matching locations. It should be initialized with 0 size by the API
/// client.
///
- /// @return
+ /// \return
/// True if there is a match
///
/// The locations which match the filename and line_number in loc_coll.
///
/// Meant to be used by the BreakpointLocation class.
///
- /// @return
+ /// \return
/// A pointer to this breakpoint's BreakpointOptions.
//------------------------------------------------------------------
BreakpointOptions *GetOptions();
///
/// Meant to be used by the BreakpointLocation class.
///
- /// @return
+ /// \return
/// A pointer to this breakpoint's BreakpointOptions.
//------------------------------------------------------------------
const BreakpointOptions *GetOptions() const;
///
/// Meant to be used by the BreakpointLocation class.
///
- /// @param[in] context
+ /// \param[in] context
/// Described the breakpoint event.
///
- /// @param[in] bp_loc_id
+ /// \param[in] bp_loc_id
/// Which breakpoint location hit this breakpoint.
///
- /// @return
+ /// \return
/// \b true if the target should stop at this breakpoint and \b false not.
//------------------------------------------------------------------
bool InvokeCallback(StoppointCallbackContext *context,
/// there are convenience variants that make breakpoints for some common
/// cases.
///
- /// @param[in] target
+ /// \param[in] target
/// The target in which the breakpoint will be set.
///
- /// @param[in] filter_sp
+ /// \param[in] filter_sp
/// Shared pointer to the search filter that restricts the search domain of
/// the breakpoint.
///
- /// @param[in] resolver_sp
+ /// \param[in] resolver_sp
/// Shared pointer to the resolver object that will determine breakpoint
/// matches.
///
- /// @param hardware
+ /// \param hardware
/// If true, request a hardware breakpoint to be used to implement the
/// breakpoint locations.
///
- /// @param resolve_indirect_symbols
+ /// \param resolve_indirect_symbols
/// If true, and the address of a given breakpoint location in this
/// breakpoint is set on an
/// indirect symbol (i.e. Symbol::IsIndirect returns true) then the actual
/// breakpoint and location and returns a BreakpointID filled out with
/// the proper id and location.
///
- /// @param[in] input
+ /// \param[in] input
/// A string containing JUST the breakpoint description.
- /// @return
+ /// \return
/// If \p input was not a valid breakpoint ID string, returns
/// \b llvm::None. Otherwise returns a BreakpointID with members filled
/// out accordingly.
/// If it is a mal-formed breakpoint name, error will be set to an appropriate
/// error string.
///
- /// @param[in] input
+ /// \param[in] input
/// A string containing JUST the breakpoint description.
- /// @param[out] error
+ /// \param[out] error
/// If the name is a well-formed breakpoint name, set to success,
/// otherwise set to an error.
- /// @return
+ /// \return
/// \b true if the name is a breakpoint name (as opposed to an ID or
/// range) false otherwise.
//------------------------------------------------------------------
/// a string containing the canonical description for the breakpoint
/// or breakpoint location.
///
- /// @param[out] break_id
+ /// \param[out] break_id
/// This is the break id.
///
- /// @param[out] break_loc_id
+ /// \param[out] break_loc_id
/// This is breakpoint location id, or LLDB_INVALID_BREAK_ID is no
/// location is to be specified.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointList BreakpointList.h "lldb/Breakpoint/BreakpointList.h"
+/// \class BreakpointList BreakpointList.h "lldb/Breakpoint/BreakpointList.h"
/// This class manages a list of breakpoints.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Add the breakpoint \a bp_sp to the list.
///
- /// @param[in] bp_sp
+ /// \param[in] bp_sp
/// Shared pointer to the breakpoint that will get added to the list.
///
- /// @result
+ /// \result
/// Returns breakpoint id.
//------------------------------------------------------------------
lldb::break_id_t Add(lldb::BreakpointSP &bp_sp, bool notify);
/// Returns a shared pointer to the breakpoint with id \a breakID. Const
/// version.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// The breakpoint ID to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a NULL pointer if the
/// breakpoint doesn't exist.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint with index \a i.
///
- /// @param[in] i
+ /// \param[in] i
/// The breakpoint index to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a NULL pointer if the
/// breakpoint doesn't exist.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find all the breakpoints with a given name
///
- /// @param[in] name
+ /// \param[in] name
/// The breakpoint name for which to search.
///
- /// @result
+ /// \result
/// \bfalse if the input name was not a legal breakpoint name.
//------------------------------------------------------------------
bool FindBreakpointsByName(const char *name, BreakpointList &matching_bps);
//------------------------------------------------------------------
/// Returns the number of elements in this breakpoint list.
///
- /// @result
+ /// \result
/// The number of elements.
//------------------------------------------------------------------
size_t GetSize() const {
//------------------------------------------------------------------
/// Removes the breakpoint given by \b breakID from this list.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// The breakpoint index to remove.
///
- /// @result
+ /// \result
/// \b true if the breakpoint \a breakID was in the list.
//------------------------------------------------------------------
bool Remove(lldb::break_id_t breakID, bool notify);
/// This is typically used after the process calls exec, or anytime the
/// architecture of the target changes.
///
- /// @param[in] arch
+ /// \param[in] arch
/// If valid, check the module in each breakpoint to make sure
/// they are compatible, otherwise, ignore architecture.
//------------------------------------------------------------------
/// modules in \a module_list. \a added says whether the module was loaded
/// or unloaded.
///
- /// @param[in] module_list
+ /// \param[in] module_list
/// The module list that has changed.
///
- /// @param[in] load
+ /// \param[in] load
/// \b true if the modules are loaded, \b false if unloaded.
///
- /// @param[in] delete_locations
+ /// \param[in] delete_locations
/// If \a load is \b false, then delete breakpoint locations when
/// when updating breakpoints.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Sets the passed in Locker to hold the Breakpoint List mutex.
///
- /// @param[in] locker
+ /// \param[in] locker
/// The locker object that is set.
//------------------------------------------------------------------
void GetListMutex(std::unique_lock<std::recursive_mutex> &lock);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointLocation BreakpointLocation.h
+/// \class BreakpointLocation BreakpointLocation.h
/// "lldb/Breakpoint/BreakpointLocation.h" Class that manages one unique (by
/// address) instance of a logical breakpoint.
//----------------------------------------------------------------------
~BreakpointLocation() override;
//------------------------------------------------------------------
- /// Gets the load address for this breakpoint location @return
+ /// Gets the load address for this breakpoint location \return
/// Returns breakpoint location load address, \b
/// LLDB_INVALID_ADDRESS if not yet set.
//------------------------------------------------------------------
lldb::addr_t GetLoadAddress() const override;
//------------------------------------------------------------------
- /// Gets the Address for this breakpoint location @return
+ /// Gets the Address for this breakpoint location \return
/// Returns breakpoint location Address.
//------------------------------------------------------------------
Address &GetAddress();
//------------------------------------------------------------------
- /// Gets the Breakpoint that created this breakpoint location @return
+ /// Gets the Breakpoint that created this breakpoint location \return
/// Returns the owning breakpoint.
//------------------------------------------------------------------
Breakpoint &GetBreakpoint();
/// Side Effects: This may evaluate the breakpoint condition, and run the
/// callback. So this command may do a considerable amount of work.
///
- /// @return
+ /// \return
/// \b true if this breakpoint location thinks we should stop,
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check the Enable/Disable state.
///
- /// @return
+ /// \return
/// \b true if the breakpoint is enabled, \b false if disabled.
//------------------------------------------------------------------
bool IsEnabled() const;
//------------------------------------------------------------------
/// Check the AutoContinue state.
///
- /// @return
+ /// \return
/// \b true if the breakpoint is set to auto-continue, \b false if not.
//------------------------------------------------------------------
bool IsAutoContinue() const;
//------------------------------------------------------------------
/// Return the current Ignore Count.
///
- /// @return
+ /// \return
/// The number of breakpoint hits to be ignored.
//------------------------------------------------------------------
uint32_t GetIgnoreCount();
//------------------------------------------------------------------
/// Set the breakpoint to ignore the next \a count breakpoint hits.
///
- /// @param[in] count
+ /// \param[in] count
/// The number of breakpoint hits to ignore.
//------------------------------------------------------------------
void SetIgnoreCount(uint32_t n);
/// The callback will return a bool indicating whether the target should
/// stop at this breakpoint or not.
///
- /// @param[in] callback
+ /// \param[in] callback
/// The method that will get called when the breakpoint is hit.
///
- /// @param[in] callback_baton_sp
+ /// \param[in] callback_baton_sp
/// A shared pointer to a Baton that provides the void * needed
/// for the callback.
///
- /// @see lldb_private::Baton
+ /// \see lldb_private::Baton
//------------------------------------------------------------------
void SetCallback(BreakpointHitCallback callback,
const lldb::BatonSP &callback_baton_sp, bool is_synchronous);
//------------------------------------------------------------------
/// Set the breakpoint location's condition.
///
- /// @param[in] condition
+ /// \param[in] condition
/// The condition expression to evaluate when the breakpoint is hit.
//------------------------------------------------------------------
void SetCondition(const char *condition);
//------------------------------------------------------------------
/// Return a pointer to the text of the condition expression.
///
- /// @return
+ /// \return
/// A pointer to the condition expression text, or nullptr if no
// condition has been set.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the valid thread to be checked when the breakpoint is hit.
///
- /// @param[in] thread_id
+ /// \param[in] thread_id
/// If this thread hits the breakpoint, we stop, otherwise not.
//------------------------------------------------------------------
void SetThreadID(lldb::tid_t thread_id);
//------------------------------------------------------------------
/// Try to resolve the breakpoint site for this location.
///
- /// @return
+ /// \return
/// \b true if we were successful at setting a breakpoint site,
/// \b false otherwise.
//------------------------------------------------------------------
/// Clear this breakpoint location's breakpoint site - for instance when
/// disabling the breakpoint.
///
- /// @return
+ /// \return
/// \b true if there was a breakpoint site to be cleared, \b false
/// otherwise.
//------------------------------------------------------------------
bool ClearBreakpointSite();
//------------------------------------------------------------------
- /// Return whether this breakpoint location has a breakpoint site. @return
+ /// Return whether this breakpoint location has a breakpoint site. \return
/// \b true if there was a breakpoint site for this breakpoint
/// location, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Print a description of this breakpoint location to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to print the description.
///
- /// @param[in] level
+ /// \param[in] level
/// The description level that indicates the detail level to
/// provide.
///
- /// @see lldb::DescriptionLevel
+ /// \see lldb::DescriptionLevel
//------------------------------------------------------------------
void GetDescription(Stream *s, lldb::DescriptionLevel level);
/// It will create a copy of the containing breakpoint's options if that
/// hasn't been done already
///
- /// @return
+ /// \return
/// A pointer to the breakpoint options.
//------------------------------------------------------------------
BreakpointOptions *GetLocationOptions();
/// This will return the options that have a setting for the specified
/// BreakpointOptions kind.
///
- /// @param[in] kind
+ /// \param[in] kind
/// The particular option you are looking up.
- /// @return
+ /// \return
/// A pointer to the containing breakpoint's options if this
/// location doesn't have its own copy.
//------------------------------------------------------------------
///
/// Meant to be used by the BreakpointLocation class.
///
- /// @param[in] context
+ /// \param[in] context
/// Described the breakpoint event.
///
- /// @param[in] bp_loc_id
+ /// \param[in] bp_loc_id
/// Which breakpoint location hit this breakpoint.
///
- /// @return
+ /// \return
/// \b true if the target should stop at this breakpoint and \b
/// false not.
//------------------------------------------------------------------
/// Returns whether we should resolve Indirect functions in setting the
/// breakpoint site for this location.
///
- /// @return
+ /// \return
/// \b true if the breakpoint SITE for this location should be set on the
/// resolved location for Indirect functions.
//------------------------------------------------------------------
/// Returns whether the address set in the breakpoint site for this location
/// was found by resolving an indirect symbol.
///
- /// @return
+ /// \return
/// \b true or \b false as given in the description above.
//------------------------------------------------------------------
bool IsIndirect() { return m_is_indirect; }
/// Returns whether the address set in the breakpoint location was re-routed
/// to the target of a re-exported symbol.
///
- /// @return
+ /// \return
/// \b true or \b false as given in the description above.
//------------------------------------------------------------------
bool IsReExported() { return m_is_reexported; }
/// locations". This is used when modules changed to determine if a Location
/// in the old module might be the "same as" the input location.
///
- /// @param[in] location
+ /// \param[in] location
/// The location to compare against.
///
- /// @return
+ /// \return
/// \b true or \b false as given in the description above.
//------------------------------------------------------------------
bool EquivalentToLocation(BreakpointLocation &location);
//------------------------------------------------------------------
/// Set the breakpoint site for this location to \a bp_site_sp.
///
- /// @param[in] bp_site_sp
+ /// \param[in] bp_site_sp
/// The breakpoint site we are setting for this location.
///
- /// @return
+ /// \return
/// \b true if we were successful at setting the breakpoint site,
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Constructor.
///
- /// @param[in] owner
+ /// \param[in] owner
/// A back pointer to the breakpoint that owns this location.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The Address defining this location.
///
- /// @param[in] tid
+ /// \param[in] tid
/// The thread for which this breakpoint location is valid, or
/// LLDB_INVALID_THREAD_ID if it is valid for all threads.
///
- /// @param[in] hardware
+ /// \param[in] hardware
/// \b true if a hardware breakpoint is requested.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Add the breakpoint \a bp_loc_sp to the list.
///
- /// @param[in] bp_sp
+ /// \param[in] bp_sp
/// Shared pointer to the breakpoint location that will get added
/// to the list.
///
- /// @result
+ /// \result
/// Returns breakpoint location id.
//------------------------------------------------------------------
void Add(const lldb::BreakpointLocationSP &bp_loc_sp);
/// Removes the breakpoint location given by \b breakID from this
/// list.
///
- /// @param[in] break_id
+ /// \param[in] break_id
/// The breakpoint index to remove.
///
- /// @param[in] break_loc_id
+ /// \param[in] break_loc_id
/// The breakpoint location index in break_id to remove.
///
- /// @result
+ /// \result
/// \b true if the breakpoint was in the list.
//------------------------------------------------------------------
bool Remove(lldb::break_id_t break_id, lldb::break_id_t break_loc_id);
/// Returns a shared pointer to the breakpoint location with id \a
/// breakID.
///
- /// @param[in] break_id
+ /// \param[in] break_id
/// The breakpoint ID to seek for.
///
- /// @param[in] break_loc_id
+ /// \param[in] break_loc_id
/// The breakpoint location ID in \a break_id to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a NULL
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint location with id \a
/// breakID, const version.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// The breakpoint location ID to seek for.
///
- /// @param[in] break_loc_id
+ /// \param[in] break_loc_id
/// The breakpoint location ID in \a break_id to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a NULL
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint location with index
/// \a i.
///
- /// @param[in] i
+ /// \param[in] i
/// The breakpoint location index to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a NULL
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint location with index
/// \a i, const version.
///
- /// @param[in] i
+ /// \param[in] i
/// The breakpoint location index to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a NULL
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns the number of elements in this breakpoint location list.
///
- /// @result
+ /// \result
/// The number of elements.
//------------------------------------------------------------------
size_t GetSize() const { return m_break_loc_collection.size(); }
/// Enquires of all the breakpoint locations in this list whether
/// we should stop at a hit at \a breakID.
///
- /// @param[in] context
+ /// \param[in] context
/// This contains the information about this stop.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// This break ID that we hit.
///
- /// @return
+ /// \return
/// \b true if we should stop, \b false otherwise.
//------------------------------------------------------------------
bool ShouldStop(StoppointCallbackContext *context);
/// Print a description of the breakpoint locations in this list
/// to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to print the description.
///
- /// @param[in] level
+ /// \param[in] level
/// The description level that indicates the detail level to
/// provide.
///
- /// @see lldb::DescriptionLevel
+ /// \see lldb::DescriptionLevel
//------------------------------------------------------------------
void GetDescription(Stream *s, lldb::DescriptionLevel level);
/// thread specifiers, and if yes, is \a thread_id contained in any
/// of these specifiers.
///
- /// @param[in] thread
+ /// \param[in] thread
/// The thread against which to test.
///
/// return
//------------------------------------------------------------------
/// Tell whether ALL the breakpoints in the location collection are internal.
///
- /// @result
+ /// \result
/// \b true if all breakpoint locations are owned by internal breakpoints,
/// \b false otherwise.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointLocationList BreakpointLocationList.h
+/// \class BreakpointLocationList BreakpointLocationList.h
/// "lldb/Breakpoint/BreakpointLocationList.h" This class is used by
/// Breakpoint to manage a list of breakpoint locations, each breakpoint
/// location in the list has a unique ID, and is unique by Address as well.
/// Returns a shared pointer to the breakpoint location at address \a addr -
/// const version.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to look for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a nullptr
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint location with id \a breakID,
/// const version.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// The breakpoint location ID to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a nullptr
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
/// Returns the breakpoint location id to the breakpoint location at address
/// \a addr.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to match.
///
- /// @result
+ /// \result
/// The ID of the breakpoint location, or LLDB_INVALID_BREAK_ID.
//------------------------------------------------------------------
lldb::break_id_t FindIDByAddress(const Address &addr);
/// Returns a breakpoint location list of the breakpoint locations in the
/// module \a module. This list is allocated, and owned by the caller.
///
- /// @param[in] module
+ /// \param[in] module
/// The module to seek in.
///
- /// @param[in]
+ /// \param[in]
/// A breakpoint collection that gets any breakpoint locations
/// that match \a module appended to.
///
- /// @result
+ /// \result
/// The number of matches
//------------------------------------------------------------------
size_t FindInModule(Module *module,
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint location with index \a i.
///
- /// @param[in] i
+ /// \param[in] i
/// The breakpoint location index to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a nullptr
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint location with index \a i,
/// const version.
///
- /// @param[in] i
+ /// \param[in] i
/// The breakpoint location index to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint. May contain a nullptr
/// pointer if the breakpoint doesn't exist.
//------------------------------------------------------------------
/// Returns the number of breakpoint locations in this list with resolved
/// breakpoints.
///
- /// @result
+ /// \result
/// Number of qualifying breakpoint locations.
//------------------------------------------------------------------
size_t GetNumResolvedLocations() const;
//------------------------------------------------------------------
/// Returns the number hit count of all locations in this list.
///
- /// @result
+ /// \result
/// Hit count of all locations in this list.
//------------------------------------------------------------------
uint32_t GetHitCount() const;
/// Enquires of the breakpoint location in this list with ID \a breakID
/// whether we should stop.
///
- /// @param[in] context
+ /// \param[in] context
/// This contains the information about this stop.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// This break ID that we hit.
///
- /// @return
+ /// \return
/// \b true if we should stop, \b false otherwise.
//------------------------------------------------------------------
bool ShouldStop(StoppointCallbackContext *context, lldb::break_id_t breakID);
//------------------------------------------------------------------
/// Returns the number of elements in this breakpoint location list.
///
- /// @result
+ /// \result
/// The number of elements.
//------------------------------------------------------------------
size_t GetSize() const { return m_locations.size(); }
/// Print a description of the breakpoint locations in this list to the
/// stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to print the description.
///
- /// @param[in] level
+ /// \param[in] level
/// The description level that indicates the detail level to
/// provide.
///
- /// @see lldb::DescriptionLevel
+ /// \see lldb::DescriptionLevel
//------------------------------------------------------------------
void GetDescription(Stream *s, lldb::DescriptionLevel level);
//------------------------------------------------------------------
/// Add the breakpoint \a bp_loc_sp to the list.
///
- /// @param[in] bp_sp
+ /// \param[in] bp_sp
/// Shared pointer to the breakpoint location that will get
/// added to the list.
///
- /// @result
+ /// \result
/// Returns breakpoint location id.
//------------------------------------------------------------------
lldb::BreakpointLocationSP Create(const Address &addr,
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointOptions BreakpointOptions.h
+/// \class BreakpointOptions BreakpointOptions.h
/// "lldb/Breakpoint/BreakpointOptions.h" Class that manages the options on a
/// breakpoint or breakpoint location.
//----------------------------------------------------------------------
/// This constructor allows you to specify all the breakpoint options except
/// the callback. That one is more complicated, and better to do by hand.
///
- /// @param[in] condition
+ /// \param[in] condition
/// The expression which if it evaluates to \b true if we are to stop
///
- /// @param[in] enabled
+ /// \param[in] enabled
/// Is this breakpoint enabled.
///
- /// @param[in] ignore
+ /// \param[in] ignore
/// How many breakpoint hits we should ignore before stopping.
///
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Adds a callback to the breakpoint option set.
///
- /// @param[in] callback
+ /// \param[in] callback
/// The function to be called when the breakpoint gets hit.
///
- /// @param[in] baton_sp
+ /// \param[in] baton_sp
/// A baton which will get passed back to the callback when it is invoked.
///
- /// @param[in] synchronous
+ /// \param[in] synchronous
/// Whether this is a synchronous or asynchronous callback. See discussion
/// above.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns the command line commands for the callback on this breakpoint.
///
- /// @param[out] command_list
+ /// \param[out] command_list
/// The commands will be appended to this list.
///
- /// @return
+ /// \return
/// \btrue if the command callback is a command-line callback,
/// \bfalse otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Use this function to invoke the callback for a specific stop.
///
- /// @param[in] context
+ /// \param[in] context
/// The context in which the callback is to be invoked. This includes the
/// stop event, the
/// execution context of the stop (since you might hit the same breakpoint
/// whether we are currently executing synchronous or asynchronous
/// callbacks.
///
- /// @param[in] break_id
+ /// \param[in] break_id
/// The breakpoint ID that owns this option set.
///
- /// @param[in] break_loc_id
+ /// \param[in] break_loc_id
/// The breakpoint location ID that owns this option set.
///
- /// @return
+ /// \return
/// The callback return value.
//------------------------------------------------------------------
bool InvokeCallback(StoppointCallbackContext *context,
/// Used in InvokeCallback to tell whether it is the right time to run this
/// kind of callback.
///
- /// @return
+ /// \return
/// The synchronicity of our callback.
//------------------------------------------------------------------
bool IsCallbackSynchronous() const { return m_callback_is_synchronous; }
//------------------------------------------------------------------
/// Fetch the baton from the callback.
///
- /// @return
+ /// \return
/// The baton.
//------------------------------------------------------------------
Baton *GetBaton();
//------------------------------------------------------------------
/// Fetch a const version of the baton from the callback.
///
- /// @return
+ /// \return
/// The baton.
//------------------------------------------------------------------
const Baton *GetBaton() const;
//------------------------------------------------------------------
/// Set the breakpoint option's condition.
///
- /// @param[in] condition
+ /// \param[in] condition
/// The condition expression to evaluate when the breakpoint is hit.
//------------------------------------------------------------------
void SetCondition(const char *condition);
//------------------------------------------------------------------
/// Return a pointer to the text of the condition expression.
///
- /// @return
+ /// \return
/// A pointer to the condition expression text, or nullptr if no
// condition has been set.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check the Enable/Disable state.
- /// @return
+ /// \return
/// \b true if the breakpoint is enabled, \b false if disabled.
//------------------------------------------------------------------
bool IsEnabled() const { return m_enabled; }
//------------------------------------------------------------------
/// Check the auto-continue state.
- /// @return
+ /// \return
/// \b true if the breakpoint is set to auto-continue, \b false otherwise.
//------------------------------------------------------------------
bool IsAutoContinue() const { return m_auto_continue; }
//------------------------------------------------------------------
/// Check the One-shot state.
- /// @return
+ /// \return
/// \b true if the breakpoint is one-shot, \b false otherwise.
//------------------------------------------------------------------
bool IsOneShot() const { return m_one_shot; }
//------------------------------------------------------------------
/// Set the breakpoint to ignore the next \a count breakpoint hits.
- /// @param[in] count
+ /// \param[in] count
/// The number of breakpoint hits to ignore.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return the current Ignore Count.
- /// @return
+ /// \return
/// The number of breakpoint hits to be ignored.
//------------------------------------------------------------------
uint32_t GetIgnoreCount() const { return m_ignore_count; }
//------------------------------------------------------------------
/// Return the current thread spec for this option. This will return nullptr
/// if the no thread specifications have been set for this Option yet.
- /// @return
+ /// \return
/// The thread specification pointer for this option, or nullptr if none
/// has
/// been set yet.
lldb::user_id_t break_loc_id);
//------------------------------------------------------------------
- /// Set a callback based on BreakpointOptions::CommandData. @param[in]
+ /// Set a callback based on BreakpointOptions::CommandData. \param[in]
/// cmd_data
/// A UP holding the new'ed CommandData object.
/// The breakpoint will take ownership of pointer held by this object.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointResolver BreakpointResolver.h
+/// \class BreakpointResolver BreakpointResolver.h
/// "lldb/Breakpoint/BreakpointResolver.h" This class works with SearchFilter
/// to resolve logical breakpoints to their of concrete breakpoint locations.
//----------------------------------------------------------------------
/// to make sense. It can be constructed without a breakpoint, but you have
/// to call SetBreakpoint before ResolveBreakpoint.
///
- /// @param[in] bkpt
+ /// \param[in] bkpt
/// The breakpoint that owns this resolver.
- /// @param[in] resolverType
+ /// \param[in] resolverType
/// The concrete breakpoint resolver type for this breakpoint.
///
- /// @result
+ /// \result
/// Returns breakpoint location id.
//------------------------------------------------------------------
BreakpointResolver(Breakpoint *bkpt, unsigned char resolverType,
//------------------------------------------------------------------
/// This sets the breakpoint for this resolver.
///
- /// @param[in] bkpt
+ /// \param[in] bkpt
/// The breakpoint that owns this resolver.
//------------------------------------------------------------------
void SetBreakpoint(Breakpoint *bkpt);
/// currently set for this breakpoint will have their offset adjusted when
/// this is called.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset to add to all locations.
//------------------------------------------------------------------
void SetOffset(lldb::addr_t offset);
/// currently set for this breakpoint will have their offset adjusted when
/// this is called.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset to add to all locations.
//------------------------------------------------------------------
lldb::addr_t GetOffset() const { return m_offset; }
/// In response to this method the resolver scans all the modules in the
/// breakpoint's target, and adds any new locations it finds.
///
- /// @param[in] filter
+ /// \param[in] filter
/// The filter that will manage the search for this resolver.
//------------------------------------------------------------------
virtual void ResolveBreakpoint(SearchFilter &filter);
/// In response to this method the resolver scans the modules in the module
/// list \a modules, and adds any new locations it finds.
///
- /// @param[in] filter
+ /// \param[in] filter
/// The filter that will manage the search for this resolver.
//------------------------------------------------------------------
virtual void ResolveBreakpointInModules(SearchFilter &filter,
//------------------------------------------------------------------
/// Prints a canonical description for the breakpoint to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// Stream to which the output is copied.
//------------------------------------------------------------------
void GetDescription(Stream *s) override = 0;
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointResolverAddress BreakpointResolverAddress.h
+/// \class BreakpointResolverAddress BreakpointResolverAddress.h
/// "lldb/Breakpoint/BreakpointResolverAddress.h" This class sets breakpoints
/// on a given Address. This breakpoint only takes once, and then it won't
/// attempt to reset itself.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointResolverFileLine BreakpointResolverFileLine.h
+/// \class BreakpointResolverFileLine BreakpointResolverFileLine.h
/// "lldb/Breakpoint/BreakpointResolverFileLine.h" This class sets breakpoints
/// by file and line. Optionally, it will look for inlined instances of the
/// file and line specification.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointResolverFileRegex BreakpointResolverFileRegex.h
+/// \class BreakpointResolverFileRegex BreakpointResolverFileRegex.h
/// "lldb/Breakpoint/BreakpointResolverFileRegex.h" This class sets
/// breakpoints by file and line. Optionally, it will look for inlined
/// instances of the file and line specification.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointResolverName BreakpointResolverName.h
+/// \class BreakpointResolverName BreakpointResolverName.h
/// "lldb/Breakpoint/BreakpointResolverName.h" This class sets breakpoints on
/// a given function name, either by exact match or by regular expression.
//----------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointResolverScripted BreakpointResolverScripted.h
+/// \class BreakpointResolverScripted BreakpointResolverScripted.h
/// "lldb/Breakpoint/BreakpointResolverScripted.h" This class sets breakpoints
/// on a given Address. This breakpoint only takes once, and then it won't
/// attempt to reset itself.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointSite BreakpointSite.h "lldb/Breakpoint/BreakpointSite.h"
+/// \class BreakpointSite BreakpointSite.h "lldb/Breakpoint/BreakpointSite.h"
/// Class that manages the actual breakpoint that will be inserted into the
/// running program.
///
//------------------------------------------------------------------
/// Sets whether the current breakpoint site is enabled or not
///
- /// @param[in] enabled
+ /// \param[in] enabled
/// \b true if the breakpoint is enabled, \b false otherwise.
//------------------------------------------------------------------
void SetEnabled(bool enabled);
/// Enquires of the breakpoint locations that produced this breakpoint site
/// whether we should stop at this location.
///
- /// @param[in] context
+ /// \param[in] context
/// This contains the information about this stop.
///
- /// @return
+ /// \return
/// \b true if we should stop, \b false otherwise.
//------------------------------------------------------------------
bool ShouldStop(StoppointCallbackContext *context) override;
//------------------------------------------------------------------
/// Standard Dump method
///
- /// @param[in] context
+ /// \param[in] context
/// The stream to dump this output.
//------------------------------------------------------------------
void Dump(Stream *s) const override;
/// The "Owners" are the breakpoint locations that share this breakpoint
/// site. The method adds the \a owner to this breakpoint site's owner list.
///
- /// @param[in] context
+ /// \param[in] context
/// \a owner is the Breakpoint Location to add.
//------------------------------------------------------------------
void AddOwner(const lldb::BreakpointLocationSP &owner);
/// This method returns the number of breakpoint locations currently located
/// at this breakpoint site.
///
- /// @return
+ /// \return
/// The number of owners.
//------------------------------------------------------------------
size_t GetNumberOfOwners();
/// GetNumberOfOwners() - 1 so you can use this method to iterate over the
/// owners
///
- /// @param[in] index
+ /// \param[in] index
/// The index in the list of owners for which you wish the owner location.
- /// @return
+ /// \return
/// A shared pointer to the breakpoint location at that index.
//------------------------------------------------------------------
lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx);
/// This method copies the breakpoint site's owners into a new collection.
/// It does this while the owners mutex is locked.
///
- /// @param[out] out_collection
+ /// \param[out] out_collection
/// The BreakpointLocationCollection into which to put the owners
/// of this breakpoint site.
///
- /// @return
+ /// \return
/// The number of elements copied into out_collection.
//------------------------------------------------------------------
size_t CopyOwnersList(BreakpointLocationCollection &out_collection);
/// specifiers, and if yes, is \a thread contained in any of these
/// specifiers.
///
- /// @param[in] thread
+ /// \param[in] thread
/// The thread against which to test.
///
/// return
/// BreakpointSite::Dump(Stream *) to get information about the breakpoint
/// site itself.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to print the description.
///
- /// @param[in] level
+ /// \param[in] level
/// The description level that indicates the detail level to
/// provide.
///
- /// @see lldb::DescriptionLevel
+ /// \see lldb::DescriptionLevel
//------------------------------------------------------------------
void GetDescription(Stream *s, lldb::DescriptionLevel level);
//------------------------------------------------------------------
/// Tell whether a breakpoint has a location at this site.
///
- /// @param[in] bp_id
+ /// \param[in] bp_id
/// The breakpoint id to query.
///
- /// @result
+ /// \result
/// \b true if bp_id has a location that is at this site,
/// \b false otherwise.
//------------------------------------------------------------------
/// Tell whether ALL the breakpoints in the location collection are
/// internal.
///
- /// @result
+ /// \result
/// \b true if all breakpoint locations are owned by internal breakpoints,
/// \b false otherwise.
//------------------------------------------------------------------
/// The method removes the owner at \a break_loc_id from this breakpoint
/// list.
///
- /// @param[in] context
+ /// \param[in] context
/// \a break_loc_id is the Breakpoint Location to remove.
//------------------------------------------------------------------
size_t RemoveOwner(lldb::break_id_t break_id, lldb::break_id_t break_loc_id);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class BreakpointSiteList BreakpointSiteList.h
+/// \class BreakpointSiteList BreakpointSiteList.h
/// "lldb/Breakpoint/BreakpointSiteList.h" Class that manages lists of
/// BreakpointSite shared pointers.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Add a BreakpointSite to the list.
///
- /// @param[in] bp_site_sp
+ /// \param[in] bp_site_sp
/// A shared pointer to a breakpoint site being added to the list.
///
- /// @return
+ /// \return
/// The ID of the BreakpointSite in the list.
//------------------------------------------------------------------
lldb::break_id_t Add(const lldb::BreakpointSiteSP &bp_site_sp);
//------------------------------------------------------------------
- /// Standard Dump routine, doesn't do anything at present. @param[in] s
+ /// Standard Dump routine, doesn't do anything at present. \param[in] s
/// Stream into which to dump the description.
//------------------------------------------------------------------
void Dump(Stream *s) const;
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint site at address \a addr.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to look for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint site. May contain a NULL
/// pointer if no breakpoint site exists with a matching address.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns a shared pointer to the breakpoint site with id \a breakID.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// The breakpoint site ID to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint site. May contain a NULL pointer if
/// the
/// breakpoint doesn't exist.
/// Returns a shared pointer to the breakpoint site with id \a breakID -
/// const version.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// The breakpoint site ID to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the breakpoint site. May contain a NULL pointer if
/// the
/// breakpoint doesn't exist.
/// Returns the breakpoint site id to the breakpoint site at address \a
/// addr.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to match.
///
- /// @result
+ /// \result
/// The ID of the breakpoint site, or LLDB_INVALID_BREAK_ID.
//------------------------------------------------------------------
lldb::break_id_t FindIDByAddress(lldb::addr_t addr);
/// Returns whether the breakpoint site \a bp_site_id has \a bp_id
// as one of its owners.
///
- /// @param[in] bp_site_id
+ /// \param[in] bp_site_id
/// The breakpoint site id to query.
///
- /// @param[in] bp_id
+ /// \param[in] bp_id
/// The breakpoint id to look for in \a bp_site_id.
///
- /// @result
+ /// \result
/// True if \a bp_site_id exists in the site list AND \a bp_id is one of the
/// owners of that site.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Removes the breakpoint site given by \b breakID from this list.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// The breakpoint site index to remove.
///
- /// @result
+ /// \result
/// \b true if the breakpoint site \a breakID was in the list.
//------------------------------------------------------------------
bool Remove(lldb::break_id_t breakID);
//------------------------------------------------------------------
/// Removes the breakpoint site at address \a addr from this list.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address from which to remove a breakpoint site.
///
- /// @result
+ /// \result
/// \b true if \a addr had a breakpoint site to remove from the list.
//------------------------------------------------------------------
bool RemoveByAddress(lldb::addr_t addr);
/// Enquires of the breakpoint site on in this list with ID \a breakID
/// whether we should stop for the breakpoint or not.
///
- /// @param[in] context
+ /// \param[in] context
/// This contains the information about this stop.
///
- /// @param[in] breakID
+ /// \param[in] breakID
/// This break ID that we hit.
///
- /// @return
+ /// \return
/// \b true if we should stop, \b false otherwise.
//------------------------------------------------------------------
bool ShouldStop(StoppointCallbackContext *context, lldb::break_id_t breakID);
//------------------------------------------------------------------
/// Returns the number of elements in the list.
///
- /// @result
+ /// \result
/// The number of elements.
//------------------------------------------------------------------
size_t GetSize() const {
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class StoppointCallbackContext StoppointCallbackContext.h
+/// \class StoppointCallbackContext StoppointCallbackContext.h
/// "lldb/Breakpoint/StoppointCallbackContext.h" Class holds the information
/// that a breakpoint callback needs to evaluate this stop.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns the WatchpointOptions structure set for this watchpoint.
///
- /// @return
+ /// \return
/// A pointer to this watchpoint's WatchpointOptions.
//------------------------------------------------------------------
WatchpointOptions *GetOptions() { return &m_options; }
//------------------------------------------------------------------
/// Set the callback action invoked when the watchpoint is hit.
///
- /// @param[in] callback
+ /// \param[in] callback
/// The method that will get called when the watchpoint is hit.
- /// @param[in] callback_baton
+ /// \param[in] callback_baton
/// A void * pointer that will get passed back to the callback function.
- /// @param[in] is_synchronous
+ /// \param[in] is_synchronous
/// If \b true the callback will be run on the private event thread
/// before the stop event gets reported. If false, the callback will get
/// handled on the public event thread after the stop has been posted.
///
- /// @return
+ /// \return
/// \b true if the process should stop when you hit the watchpoint.
/// \b false if it should continue.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Invoke the callback action when the watchpoint is hit.
///
- /// @param[in] context
+ /// \param[in] context
/// Described the watchpoint event.
///
- /// @return
+ /// \return
/// \b true if the target should stop at this watchpoint and \b false not.
//------------------------------------------------------------------
bool InvokeCallback(StoppointCallbackContext *context);
//------------------------------------------------------------------
/// Set the watchpoint's condition.
///
- /// @param[in] condition
+ /// \param[in] condition
/// The condition expression to evaluate when the watchpoint is hit.
/// Pass in nullptr to clear the condition.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return a pointer to the text of the condition expression.
///
- /// @return
+ /// \return
/// A pointer to the condition expression text, or nullptr if no
// condition has been set.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class WatchpointList WatchpointList.h "lldb/Breakpoint/WatchpointList.h"
+/// \class WatchpointList WatchpointList.h "lldb/Breakpoint/WatchpointList.h"
/// This class is used by Watchpoint to manage a list of watchpoints,
// each watchpoint in the list has a unique ID, and is unique by Address as
// well.
//------------------------------------------------------------------
/// Add a Watchpoint to the list.
///
- /// @param[in] wp_sp
+ /// \param[in] wp_sp
/// A shared pointer to a watchpoint being added to the list.
///
- /// @return
+ /// \return
/// The ID of the Watchpoint in the list.
//------------------------------------------------------------------
lldb::watch_id_t Add(const lldb::WatchpointSP &wp_sp, bool notify);
/// Returns a shared pointer to the watchpoint at address \a addr - const
/// version.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to look for.
///
- /// @result
+ /// \result
/// A shared pointer to the watchpoint. May contain a NULL
/// pointer if the watchpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the watchpoint with watchpoint spec \a spec
/// - const version.
///
- /// @param[in] spec
+ /// \param[in] spec
/// The watchpoint spec to look for.
///
- /// @result
+ /// \result
/// A shared pointer to the watchpoint. May contain a NULL
/// pointer if the watchpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the watchpoint with id \a watchID, const
/// version.
///
- /// @param[in] watchID
+ /// \param[in] watchID
/// The watchpoint location ID to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the watchpoint. May contain a NULL
/// pointer if the watchpoint doesn't exist.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns the watchpoint id to the watchpoint at address \a addr.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to match.
///
- /// @result
+ /// \result
/// The ID of the watchpoint, or LLDB_INVALID_WATCH_ID.
//------------------------------------------------------------------
lldb::watch_id_t FindIDByAddress(lldb::addr_t addr);
/// Returns the watchpoint id to the watchpoint with watchpoint spec \a
/// spec.
///
- /// @param[in] spec
+ /// \param[in] spec
/// The watchpoint spec to match.
///
- /// @result
+ /// \result
/// The ID of the watchpoint, or LLDB_INVALID_WATCH_ID.
//------------------------------------------------------------------
lldb::watch_id_t FindIDBySpec(std::string spec);
//------------------------------------------------------------------
/// Returns a shared pointer to the watchpoint with index \a i.
///
- /// @param[in] i
+ /// \param[in] i
/// The watchpoint index to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the watchpoint. May contain a NULL pointer if
/// the watchpoint doesn't exist.
//------------------------------------------------------------------
/// Returns a shared pointer to the watchpoint with index \a i, const
/// version.
///
- /// @param[in] i
+ /// \param[in] i
/// The watchpoint index to seek for.
///
- /// @result
+ /// \result
/// A shared pointer to the watchpoint. May contain a NULL pointer if
/// the watchpoint location doesn't exist.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Removes the watchpoint given by \b watchID from this list.
///
- /// @param[in] watchID
+ /// \param[in] watchID
/// The watchpoint ID to remove.
///
- /// @result
+ /// \result
/// \b true if the watchpoint \a watchID was in the list.
//------------------------------------------------------------------
bool Remove(lldb::watch_id_t watchID, bool notify);
//------------------------------------------------------------------
/// Returns the number hit count of all watchpoints in this list.
///
- /// @result
+ /// \result
/// Hit count of all watchpoints in this list.
//------------------------------------------------------------------
uint32_t GetHitCount() const;
/// Enquires of the watchpoint in this list with ID \a watchID whether we
/// should stop.
///
- /// @param[in] context
+ /// \param[in] context
/// This contains the information about this stop.
///
- /// @param[in] watchID
+ /// \param[in] watchID
/// This watch ID that we hit.
///
- /// @return
+ /// \return
/// \b true if we should stop, \b false otherwise.
//------------------------------------------------------------------
bool ShouldStop(StoppointCallbackContext *context, lldb::watch_id_t watchID);
//------------------------------------------------------------------
/// Returns the number of elements in this watchpoint list.
///
- /// @result
+ /// \result
/// The number of elements.
//------------------------------------------------------------------
size_t GetSize() const {
//------------------------------------------------------------------
/// Print a description of the watchpoints in this list to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to print the description.
///
- /// @param[in] level
+ /// \param[in] level
/// The description level that indicates the detail level to
/// provide.
///
- /// @see lldb::DescriptionLevel
+ /// \see lldb::DescriptionLevel
//------------------------------------------------------------------
void GetDescription(Stream *s, lldb::DescriptionLevel level);
//------------------------------------------------------------------
/// Sets the passed in Locker to hold the Watchpoint List mutex.
///
- /// @param[in] locker
+ /// \param[in] locker
/// The locker object that is set.
//------------------------------------------------------------------
void GetListMutex(std::unique_lock<std::recursive_mutex> &lock);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class WatchpointOptions WatchpointOptions.h
+/// \class WatchpointOptions WatchpointOptions.h
/// "lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a
/// watchpoint.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// This constructor allows you to specify all the watchpoint options.
///
- /// @param[in] callback
+ /// \param[in] callback
/// This is the plugin for some code that gets run, returns \b true if we
/// are to stop.
///
- /// @param[in] baton
+ /// \param[in] baton
/// Client data that will get passed to the callback.
///
- /// @param[in] thread_id
+ /// \param[in] thread_id
/// Only stop if \a thread_id hits the watchpoint.
//------------------------------------------------------------------
WatchpointOptions(WatchpointHitCallback callback, void *baton,
//------------------------------------------------------------------
/// Adds a callback to the watchpoint option set.
///
- /// @param[in] callback
+ /// \param[in] callback
/// The function to be called when the watchpoint gets hit.
///
- /// @param[in] baton_sp
+ /// \param[in] baton_sp
/// A baton which will get passed back to the callback when it is invoked.
///
- /// @param[in] synchronous
+ /// \param[in] synchronous
/// Whether this is a synchronous or asynchronous callback. See discussion
/// above.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Use this function to invoke the callback for a specific stop.
///
- /// @param[in] context
+ /// \param[in] context
/// The context in which the callback is to be invoked. This includes the
/// stop event, the
/// execution context of the stop (since you might hit the same watchpoint
/// whether we are currently executing synchronous or asynchronous
/// callbacks.
///
- /// @param[in] watch_id
+ /// \param[in] watch_id
/// The watchpoint ID that owns this option set.
///
- /// @return
+ /// \return
/// The callback return value.
//------------------------------------------------------------------
bool InvokeCallback(StoppointCallbackContext *context,
/// Used in InvokeCallback to tell whether it is the right time to run this
/// kind of callback.
///
- /// @return
+ /// \return
/// The synchronicity of our callback.
//------------------------------------------------------------------
bool IsCallbackSynchronous() { return m_callback_is_synchronous; }
//------------------------------------------------------------------
/// Fetch the baton from the callback.
///
- /// @return
+ /// \return
/// The baton.
//------------------------------------------------------------------
Baton *GetBaton();
//------------------------------------------------------------------
/// Fetch a const version of the baton from the callback.
///
- /// @return
+ /// \return
/// The baton.
//------------------------------------------------------------------
const Baton *GetBaton() const;
//------------------------------------------------------------------
/// Return the current thread spec for this option. This will return nullptr
/// if the no thread specifications have been set for this Option yet.
- /// @return
+ /// \return
/// The thread specification pointer for this option, or nullptr if none
/// has
/// been set yet.
//------------------------------------------------------------------
/// This is the default empty callback.
- /// @return
+ /// \return
/// The thread id for which the watchpoint hit will stop,
/// LLDB_INVALID_THREAD_ID for all threads.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Address Address.h "lldb/Core/Address.h"
+/// \class Address Address.h "lldb/Core/Address.h"
/// A section + offset based address class.
///
/// The Address class allows addresses to be relative to a section that can
/// frameworks) being loaded at different addresses than the addresses found
/// in the object file that represents them on disk. There are currently two
/// types of addresses for a section:
-/// @li file addresses
-/// @li load addresses
+/// \li file addresses
+/// \li load addresses
///
/// File addresses represent the virtual addresses that are in the "on disk"
/// object files. These virtual addresses are converted to be relative to
///
/// Makes a copy of the another Address object \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const Address object reference to copy.
//------------------------------------------------------------------
Address(const Address &rhs)
///
/// Initialize the address with the supplied \a section and \a offset.
///
- /// @param[in] section
+ /// \param[in] section
/// A section pointer to a valid lldb::Section, or NULL if the
/// address doesn't have a section or will get resolved later.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset in bytes into \a section.
//------------------------------------------------------------------
Address(const lldb::SectionSP §ion_sp, lldb::addr_t offset)
/// Initialize and resolve the address with the supplied virtual address \a
/// file_addr.
///
- /// @param[in] file_addr
+ /// \param[in] file_addr
/// A virtual file address.
///
- /// @param[in] section_list
+ /// \param[in] section_list
/// A list of sections, one of which may contain the \a file_addr.
//------------------------------------------------------------------
Address(lldb::addr_t file_addr, const SectionList *section_list);
/// Copies the address value from another Address object \a rhs into \a this
/// object.
///
-/// @param[in] rhs
+/// \param[in] rhs
/// A const Address object reference to copy.
///
-/// @return
+/// \return
/// A const Address object reference to \a this.
//------------------------------------------------------------------
#ifndef SWIG
//------------------------------------------------------------------
/// Compare two Address objects.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// The Left Hand Side const Address object reference.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Right Hand Side const Address object reference.
///
- /// @return
- /// @li -1 if lhs < rhs
- /// @li 0 if lhs == rhs
- /// @li 1 if lhs > rhs
+ /// \return
+ /// \li -1 if lhs < rhs
+ /// \li 0 if lhs == rhs
+ /// \li 1 if lhs > rhs
//------------------------------------------------------------------
static int CompareFileAddress(const Address &lhs, const Address &rhs);
/// \a s. There are many ways to display a section offset based address, and
/// \a style lets the user choose.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] style
+ /// \param[in] style
/// The display style for the address.
///
- /// @param[in] fallback_style
+ /// \param[in] fallback_style
/// The display style for the address.
///
- /// @return
+ /// \return
/// Returns \b true if the address was able to be displayed.
/// File and load addresses may be unresolved and it may not be
/// possible to display a valid value, \b false will be returned
/// in such cases.
///
- /// @see Address::DumpStyle
+ /// \see Address::DumpStyle
//------------------------------------------------------------------
bool Dump(Stream *s, ExecutionContextScope *exe_scope, DumpStyle style,
DumpStyle fallback_style = DumpStyleInvalid,
/// addresses, then it has a virtual address that is relative to unique
/// section in the object file.
///
- /// @return
+ /// \return
/// The valid file virtual address, or LLDB_INVALID_ADDRESS if
/// the address doesn't have a file virtual address (image is
/// from memory only with no representation on disk).
/// loaded/unloaded. If a section is loaded, then the load address can be
/// resolved.
///
- /// @return
+ /// \return
/// The valid load virtual address, or LLDB_INVALID_ADDRESS if
/// the address is currently not loaded.
//------------------------------------------------------------------
/// target) that are required when changing the program counter to setting a
/// return address.
///
- /// @return
+ /// \return
/// The valid load virtual address, or LLDB_INVALID_ADDRESS if
/// the address is currently not loaded.
//------------------------------------------------------------------
/// special purposes. The result of this function can be used to safely
/// write a software breakpoint trap to memory.
///
- /// @return
+ /// \return
/// The valid load virtual address with extra callable bits
/// removed, or LLDB_INVALID_ADDRESS if the address is currently
/// not loaded.
//------------------------------------------------------------------
/// Get the section relative offset value.
///
- /// @return
+ /// \return
/// The current offset, or LLDB_INVALID_ADDRESS if this address
/// doesn't contain a valid offset.
//------------------------------------------------------------------
/// returns true if the current value contained in this object is section
/// offset based.
///
- /// @return
+ /// \return
/// Returns \b true if the address has a valid section and
/// offset, \b false otherwise.
//------------------------------------------------------------------
/// offset (for section offset based addresses), or just a valid offset
/// (for absolute addresses that have no section).
///
- /// @return
+ /// \return
/// Returns \b true if the offset is valid, \b false
/// otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
//------------------------------------------------------------------
size_t MemorySize() const;
/// Given a list of sections, attempt to resolve \a addr as an offset into
/// one of the file sections.
///
- /// @return
+ /// \return
/// Returns \b true if \a addr was able to be resolved, \b false
/// otherwise.
//------------------------------------------------------------------
/// valid section and offset. Else this address object will have no section
/// (NULL) and the offset will be \a load_addr.
///
- /// @param[in] load_addr
+ /// \param[in] load_addr
/// A load address from a current process.
///
- /// @param[in] target
+ /// \param[in] target
/// The target to use when trying resolve the address into
/// a section + offset. The Target's SectionLoadList object
/// is used to resolve the address.
///
- /// @param[in] allow_section_end
+ /// \param[in] allow_section_end
/// If true, treat an address pointing to the end of the module as
/// belonging to that module.
///
- /// @return
+ /// \return
/// Returns \b true if the load address was resolved to be
/// section/offset, \b false otherwise. It is often ok for an
/// address no not resolve to a section in a module, this often
//------------------------------------------------------------------
/// Get accessor for the module for this address.
///
- /// @return
+ /// \return
/// Returns the Module pointer that this address is an offset
/// in, or NULL if this address doesn't belong in a module, or
/// isn't resolved yet.
//------------------------------------------------------------------
/// Get const accessor for the section.
///
- /// @return
+ /// \return
/// Returns the const lldb::Section pointer that this address is an
/// offset in, or NULL if this address is absolute.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set accessor for the offset.
///
- /// @param[in] offset
+ /// \param[in] offset
/// A new offset value for this object.
///
- /// @return
+ /// \return
/// Returns \b true if the offset changed, \b false otherwise.
//------------------------------------------------------------------
bool SetOffset(lldb::addr_t offset) {
//------------------------------------------------------------------
/// Set accessor for the section.
///
- /// @param[in] section
+ /// \param[in] section
/// A new lldb::Section pointer to use as the section base. Can
/// be NULL for absolute addresses that are not relative to
/// any section.
/// can reconstruct their symbol context by looking up the address in the
/// module found in the section.
///
- /// @see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
+ /// \see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
//------------------------------------------------------------------
uint32_t CalculateSymbolContext(SymbolContext *sc,
lldb::SymbolContextItem resolve_scope =
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class AddressRange AddressRange.h "lldb/Core/AddressRange.h"
+/// \class AddressRange AddressRange.h "lldb/Core/AddressRange.h"
/// A section + offset based address range class.
//----------------------------------------------------------------------
class AddressRange {
/// Initialize the address with the supplied \a section, \a offset and \a
/// byte_size.
///
- /// @param[in] section
+ /// \param[in] section
/// A section pointer to a valid lldb::Section, or NULL if the
/// address doesn't have a section or will get resolved later.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset in bytes into \a section.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in bytes of the address range.
//------------------------------------------------------------------
AddressRange(const lldb::SectionSP §ion, lldb::addr_t offset,
/// Initialize and resolve the address with the supplied virtual address \a
/// file_addr, and byte size \a byte_size.
///
- /// @param[in] file_addr
+ /// \param[in] file_addr
/// A virtual address.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in bytes of the address range.
///
- /// @param[in] section_list
+ /// \param[in] section_list
/// A list of sections, one of which may contain the \a vaddr.
//------------------------------------------------------------------
AddressRange(lldb::addr_t file_addr, lldb::addr_t byte_size,
/// Initialize by copying the section offset address in \a so_addr, and
/// setting the byte size to \a byte_size.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A section offset address object.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in bytes of the address range.
//------------------------------------------------------------------
AddressRange(const Address &so_addr, lldb::addr_t byte_size);
//------------------------------------------------------------------
/// Check if a section offset address is contained in this range.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A section offset address object reference.
///
- /// @return
+ /// \return
/// Returns \b true if \a so_addr is contained in this range,
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check if a section offset address is contained in this range.
///
- /// @param[in] so_addr_ptr
+ /// \param[in] so_addr_ptr
/// A section offset address object pointer.
///
- /// @return
+ /// \return
/// Returns \b true if \a so_addr is contained in this range,
/// \b false otherwise.
//------------------------------------------------------------------
/// Check if a section offset \a so_addr when represented as a file address
/// is contained within this object's file address range.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A section offset address object reference.
///
- /// @return
+ /// \return
/// Returns \b true if both \a this and \a so_addr have
/// resolvable file address values and \a so_addr is contained
/// in the address range, \b false otherwise.
/// Check if the resolved file address \a file_addr is contained within this
/// object's file address range.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A section offset address object reference.
///
- /// @return
+ /// \return
/// Returns \b true if both \a this has a resolvable file
/// address value and \a so_addr is contained in the address
/// range, \b false otherwise.
/// Check if a section offset \a so_addr when represented as a load address
/// is contained within this object's load address range.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A section offset address object reference.
///
- /// @return
+ /// \return
/// Returns \b true if both \a this and \a so_addr have
/// resolvable load address values and \a so_addr is contained
/// in the address range, \b false otherwise.
/// Check if the resolved load address \a load_addr is contained within this
/// object's load address range.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A section offset address object reference.
///
- /// @return
+ /// \return
/// Returns \b true if both \a this has a resolvable load
/// address value and \a so_addr is contained in the address
/// range, \b false otherwise.
/// range, and \a style lets the user choose how the base address gets
/// displayed.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] style
+ /// \param[in] style
/// The display style for the address.
///
- /// @return
+ /// \return
/// Returns \b true if the address was able to be displayed.
/// File and load addresses may be unresolved and it may not be
/// possible to display a valid value, \b false will be returned
/// in such cases.
///
- /// @see Address::DumpStyle
+ /// \see Address::DumpStyle
//------------------------------------------------------------------
bool
Dump(Stream *s, Target *target, Address::DumpStyle style,
/// The debug description contains verbose internal state such and pointer
/// values, reference counts, etc.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void DumpDebug(Stream *s) const;
//------------------------------------------------------------------
/// Get accessor for the base address of the range.
///
- /// @return
+ /// \return
/// A reference to the base address object.
//------------------------------------------------------------------
Address &GetBaseAddress() { return m_base_addr; }
//------------------------------------------------------------------
/// Get const accessor for the base address of the range.
///
- /// @return
+ /// \return
/// A const reference to the base address object.
//------------------------------------------------------------------
const Address &GetBaseAddress() const { return m_base_addr; }
//------------------------------------------------------------------
/// Get accessor for the byte size of this range.
///
- /// @return
+ /// \return
/// The size in bytes of this address range.
//------------------------------------------------------------------
lldb::addr_t GetByteSize() const { return m_byte_size; }
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
//------------------------------------------------------------------
size_t MemorySize() const {
//------------------------------------------------------------------
/// Set accessor for the byte size of this range.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The new size in bytes of this address range.
//------------------------------------------------------------------
void SetByteSize(lldb::addr_t byte_size) { m_byte_size = byte_size; }
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class AddressResolver AddressResolver.h "lldb/Core/AddressResolver.h"
+/// \class AddressResolver AddressResolver.h "lldb/Core/AddressResolver.h"
/// This class works with SearchFilter to resolve function names and source
/// file locations to their concrete addresses.
//----------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class AddressResolverFileLine AddressResolverFileLine.h
+/// \class AddressResolverFileLine AddressResolverFileLine.h
/// "lldb/Core/AddressResolverFileLine.h" This class finds address for source
/// file and line. Optionally, it will look for inlined instances of the file
/// and line specification.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class AddressResolverName AddressResolverName.h
+/// \class AddressResolverName AddressResolverName.h
/// "lldb/Core/AddressResolverName.h" This class finds addresses for a given
/// function name, either by exact match or by regular expression.
//----------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Communication Communication.h "lldb/Core/Communication.h" An
+/// \class Communication Communication.h "lldb/Core/Communication.h" An
/// abstract communications class.
///
/// Communication is an class that handles data communication between two data
/// "eBroadcastBit" below).
///
/// There are two modes in which communications can occur:
-/// @li single-threaded
-/// @li multi-threaded
+/// \li single-threaded
+/// \li multi-threaded
///
/// In single-threaded mode, all reads and writes happen synchronously on the
/// calling thread.
/// Construct the Communication object with the specified name for the
/// Broadcaster that this object inherits from.
///
- /// @param[in] broadcaster_name
+ /// \param[in] broadcaster_name
/// The name of the broadcaster object. This name should be as
/// complete as possible to uniquely identify this object. The
/// broadcaster name can be updated after the connect function
/// Connect using the current connection by passing \a url to its connect
/// function. string.
///
- /// @param[in] url
+ /// \param[in] url
/// A string that contains all information needed by the
/// subclass to connect to another client.
///
- /// @return
+ /// \return
/// \b True if the connect succeeded, \b false otherwise. The
/// internal error object should be filled in with an
/// appropriate value based on the result of this function.
///
- /// @see Status& Communication::GetError ();
- /// @see bool Connection::Connect (const char *url);
+ /// \see Status& Communication::GetError ();
+ /// \see bool Connection::Connect (const char *url);
//------------------------------------------------------------------
lldb::ConnectionStatus Connect(const char *url, Status *error_ptr);
//------------------------------------------------------------------
/// Disconnect the communications connection if one is currently connected.
///
- /// @return
+ /// \return
/// \b True if the disconnect succeeded, \b false otherwise. The
/// internal error object should be filled in with an
/// appropriate value based on the result of this function.
///
- /// @see Status& Communication::GetError ();
- /// @see bool Connection::Disconnect ();
+ /// \see Status& Communication::GetError ();
+ /// \see bool Connection::Disconnect ();
//------------------------------------------------------------------
lldb::ConnectionStatus Disconnect(Status *error_ptr = nullptr);
//------------------------------------------------------------------
/// Check if the connection is valid.
///
- /// @return
+ /// \return
/// \b True if this object is currently connected, \b false
/// otherwise.
//------------------------------------------------------------------
/// event. If this function consumes all of the bytes in the cache, it will
/// reset the \a eBroadcastBitReadThreadGotBytes event bit.
///
- /// @param[in] dst
+ /// \param[in] dst
/// A destination buffer that must be at least \a dst_len bytes
/// long.
///
- /// @param[in] dst_len
+ /// \param[in] dst_len
/// The number of bytes to attempt to read, and also the max
/// number of bytes that can be placed into \a dst.
///
- /// @param[in] timeout
+ /// \param[in] timeout
/// A timeout value or llvm::None for no timeout.
///
- /// @return
+ /// \return
/// The number of bytes actually read.
///
- /// @see size_t Connection::Read (void *, size_t);
+ /// \see size_t Connection::Read (void *, size_t);
//------------------------------------------------------------------
size_t Read(void *dst, size_t dst_len, const Timeout<std::micro> &timeout,
lldb::ConnectionStatus &status, Status *error_ptr);
///
/// Subclasses must override this function.
///
- /// @param[in] src
+ /// \param[in] src
/// A source buffer that must be at least \a src_len bytes
/// long.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// The number of bytes to attempt to write, and also the
/// number of bytes are currently available in \a src.
///
- /// @return
+ /// \return
/// The number of bytes actually Written.
//------------------------------------------------------------------
size_t Write(const void *src, size_t src_len, lldb::ConnectionStatus &status,
/// connection without any interruption to the client. It also allows the
/// Communication class to be subclassed for packet based communication.
///
- /// @param[in] connection
+ /// \param[in] connection
/// A connection that this class will own and destroy.
///
- /// @see
+ /// \see
/// class Connection
//------------------------------------------------------------------
void SetConnection(Connection *connection);
/// default action of caching the bytes and broadcasting a \b
/// eBroadcastBitReadThreadGotBytes event.
///
- /// @return
+ /// \return
/// \b True if the read thread was successfully started, \b
/// false otherwise.
///
- /// @see size_t Connection::Read (void *, size_t);
- /// @see void Communication::AppendBytesToCache (const uint8_t * bytes,
+ /// \see size_t Connection::Read (void *, size_t);
+ /// \see void Communication::AppendBytesToCache (const uint8_t * bytes,
/// size_t len, bool broadcast);
//------------------------------------------------------------------
virtual bool StartReadThread(Status *error_ptr = nullptr);
//------------------------------------------------------------------
/// Stops the read thread by cancelling it.
///
- /// @return
+ /// \return
/// \b True if the read thread was successfully canceled, \b
/// false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Checks if there is a currently running read thread.
///
- /// @return
+ /// \return
/// \b True if the read thread is running, \b false otherwise.
//------------------------------------------------------------------
bool ReadThreadIsRunning();
/// is received it will append the available data to the internal cache and
/// broadcast a \b eBroadcastBitReadThreadGotBytes event.
///
- /// @param[in] comm_ptr
+ /// \param[in] comm_ptr
/// A pointer to an instance of this class.
///
- /// @return
+ /// \return
/// \b NULL.
///
- /// @see void Communication::ReadThreadGotBytes (const uint8_t *, size_t);
+ /// \see void Communication::ReadThreadGotBytes (const uint8_t *, size_t);
//------------------------------------------------------------------
static lldb::thread_result_t ReadThread(lldb::thread_arg_t comm_ptr);
/// of the \a eBroadcastBitReadThreadGotBytes event by setting \a broadcast
/// to false.
///
- /// @param[in] src
+ /// \param[in] src
/// A source buffer that must be at least \a src_len bytes
/// long.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// The number of bytes to append to the cache.
//------------------------------------------------------------------
virtual void AppendBytesToCache(const uint8_t *src, size_t src_len,
/// data cache, the \b eBroadcastBitReadThreadGotBytes event will be reset
/// to signify no more bytes are available.
///
- /// @param[in] dst
+ /// \param[in] dst
/// A destination buffer that must be at least \a dst_len bytes
/// long.
///
- /// @param[in] dst_len
+ /// \param[in] dst_len
/// The number of bytes to attempt to read from the cache,
/// and also the max number of bytes that can be placed into
/// \a dst.
///
- /// @return
+ /// \return
/// The number of bytes extracted from the data cache.
//------------------------------------------------------------------
size_t GetCachedBytes(void *dst, size_t dst_len);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Debugger Debugger.h "lldb/Core/Debugger.h"
+/// \class Debugger Debugger.h "lldb/Core/Debugger.h"
/// A class to manage flag bits.
///
/// Provides a global root objects for the debugger core.
/// debugger shared instance to control where targets get created and to
/// allow for tracking and searching for targets based on certain criteria.
///
- /// @return
+ /// \return
/// A global shared target list.
//------------------------------------------------------------------
TargetList &GetTargetList() { return m_target_list; }
/// Print the (optional) address, (optional) bytes, opcode,
/// operands, and instruction comments to a stream.
///
- /// @param[in] s
+ /// \param[in] s
/// The Stream to add the text to.
///
- /// @param[in] show_address
+ /// \param[in] show_address
/// Whether the address (using disassembly_addr_format_spec formatting)
/// should be printed.
///
- /// @param[in] show_bytes
+ /// \param[in] show_bytes
/// Whether the bytes of the assembly instruction should be printed.
///
- /// @param[in] max_opcode_byte_size
+ /// \param[in] max_opcode_byte_size
/// The size (in bytes) of the largest instruction in the list that
/// we are printing (for text justification/alignment purposes)
/// Only needed if show_bytes is true.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The current execution context, if available. May be used in
/// the assembling of the operands+comments for this instruction.
/// Pass NULL if not applicable.
///
- /// @param[in] sym_ctx
+ /// \param[in] sym_ctx
/// The SymbolContext for this instruction.
/// Pass NULL if not available/computed.
/// Only needed if show_address is true.
///
- /// @param[in] prev_sym_ctx
+ /// \param[in] prev_sym_ctx
/// The SymbolContext for the previous instruction. Depending on
/// the disassembly address format specification, a change in
/// Symbol / Function may mean that a line is printed with the new
/// the InstructionList.
/// Only needed if show_address is true.
///
- /// @param[in] disassembly_addr_format
+ /// \param[in] disassembly_addr_format
/// The format specification for how addresses are printed.
/// Only needed if show_address is true.
///
- /// @param[in] max_address_text_size
+ /// \param[in] max_address_text_size
/// The length of the longest address string at the start of the
/// disassembly line that will be printed (the
/// Debugger::FormatDisassemblerAddress() string)
/// same start offset, format and size, yet differing \a
/// item_bit_size and \a item_bit_offset values.
///
-/// @param[in] s
+/// \param[in] s
/// The stream to dump the output to. This value can not be nullptr.
///
-/// @param[in] offset
+/// \param[in] offset
/// The offset into the data at which to start dumping.
///
-/// @param[in] item_format
+/// \param[in] item_format
/// The format to use when dumping each item.
///
-/// @param[in] item_byte_size
+/// \param[in] item_byte_size
/// The byte size of each item.
///
-/// @param[in] item_count
+/// \param[in] item_count
/// The number of items to dump.
///
-/// @param[in] num_per_line
+/// \param[in] num_per_line
/// The number of items to display on each line.
///
-/// @param[in] base_addr
+/// \param[in] base_addr
/// The base address that gets added to the offset displayed on
/// each line if the value is valid. Is \a base_addr is
/// LLDB_INVALID_ADDRESS then no address values will be prepended
/// to any lines.
///
-/// @param[in] item_bit_size
+/// \param[in] item_bit_size
/// If the value to display is a bitfield, this value should
/// be the number of bits that the bitfield item has within the
/// item's byte size value. This function will need to be called
/// exist within the same integer value. If the items being
/// displayed are not bitfields, this value should be zero.
///
-/// @param[in] item_bit_offset
+/// \param[in] item_bit_offset
/// If the value to display is a bitfield, this value should
/// be the offset in bits, or shift right amount, that the
/// bitfield item occupies within the item's byte size value.
/// same integer value. If the items being displayed are not
/// bitfields, this value should be zero.
///
-/// @return
+/// \return
/// The offset at which dumping ended.
//------------------------------------------------------------------
lldb::offset_t
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class EmulateInstruction EmulateInstruction.h
+/// \class EmulateInstruction EmulateInstruction.h
/// "lldb/Core/EmulateInstruction.h"
/// A class that allows emulation of CPU opcodes.
///
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class FileLineResolver FileLineResolver.h "lldb/Core/FileLineResolver.h"
+/// \class FileLineResolver FileLineResolver.h "lldb/Core/FileLineResolver.h"
/// This class finds address for source file and line. Optionally, it will
/// look for inlined instances of the file and line specification.
//----------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class FileSpecList FileSpecList.h "lldb/Core/FileSpecList.h"
+/// \class FileSpecList FileSpecList.h "lldb/Core/FileSpecList.h"
/// A file collection class.
///
/// A class that contains a mutable list of FileSpec objects.
///
/// Replace the file list in this object with the file list from \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A file list object to copy.
///
- /// @return
+ /// \return
/// A const reference to this object.
//------------------------------------------------------------------
FileSpecList &operator=(const FileSpecList &rhs) = default;
///
/// Appends \a file to the end of the file list.
///
- /// @param[in] file
+ /// \param[in] file
/// A new file to append to this file list.
//------------------------------------------------------------------
void Append(const FileSpec &file);
/// Appends \a file to the end of the file list if it doesn't already exist
/// in the file list.
///
- /// @param[in] file
+ /// \param[in] file
/// A new file to append to this file list.
///
- /// @return
+ /// \return
/// \b true if the file was appended, \b false otherwise.
//------------------------------------------------------------------
bool AppendIfUnique(const FileSpec &file);
//------------------------------------------------------------------
/// Dumps the file list to the supplied stream pointer "s".
///
- /// @param[in] s
+ /// \param[in] s
/// The stream that will be used to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s, const char *separator_cstr = "\n") const;
/// Find the index of the file in the file spec list that matches \a file
/// starting \a idx entries into the file spec list.
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into the file list.
///
- /// @param[in] file
+ /// \param[in] file
/// The file specification to search for.
///
- /// @param[in] full
+ /// \param[in] full
/// Should FileSpec::Equal be called with "full" true or false.
///
- /// @return
+ /// \return
/// The index of the file that matches \a file if it is found,
/// else UINT32_MAX is returned.
//------------------------------------------------------------------
/// FileSpec object will be returned. The file objects that are returned can
/// be tested using FileSpec::operator void*().
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into the file list.
///
- /// @return
+ /// \return
/// A copy of the FileSpec object at index \a idx. If \a idx
/// is out of range, then an empty FileSpec object will be
/// returned.
/// Gets a file from the file list. The file objects that are returned can
/// be tested using FileSpec::operator void*().
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into the file list.
///
- /// @return
+ /// \return
/// A pointer to a contained FileSpec object at index \a idx.
/// If \a idx is out of range, then an NULL is returned.
//------------------------------------------------------------------
/// the size in bytes of this object, not any shared string values it may
/// refer to.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//------------------------------------------------------------------
size_t MemorySize() const;
//------------------------------------------------------------------
/// Get the number of files in the file list.
///
- /// @return
+ /// \return
/// The number of files in the file spec list.
//------------------------------------------------------------------
size_t GetSize() const;
void Apply(Stream &s, llvm::StringRef value) const;
/// Sets the prefix and suffix strings.
- /// @param prefix
- /// @param suffix
+ /// \param prefix
+ /// \param suffix
void Set(llvm::StringRef prefix, llvm::StringRef suffix);
};
/// This function determines how much indentation should be added
/// or removed to match the recommended amount for the final line.
///
- /// @param[in] io_handler
+ /// \param[in] io_handler
/// The IOHandler that responsible for input.
///
- /// @param[in] lines
+ /// \param[in] lines
/// The current input up to the line to be corrected. Lines
/// following the line containing the cursor are not included.
///
- /// @param[in] cursor_position
+ /// \param[in] cursor_position
/// The number of characters preceding the cursor on the final
/// line at the time.
///
- /// @return
+ /// \return
/// Returns an integer describing the number of spaces needed
/// to correct the indentation level. Positive values indicate
/// that spaces should be added, while negative values represent
/// Called to determine whether typing enter after the last line in
/// \a lines should end input. This function will not be called on
/// IOHandler objects that are getting single lines.
- /// @param[in] io_handler
+ /// \param[in] io_handler
/// The IOHandler that responsible for updating the lines.
///
- /// @param[in] lines
+ /// \param[in] lines
/// The current multi-line content. May be altered to provide
/// alternative input when complete.
///
- /// @return
+ /// \return
/// Return an boolean to indicate whether input is complete,
/// true indicates that no additional input is necessary, while
/// false indicates that more input is required.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Mangled Mangled.h "lldb/Core/Mangled.h"
+/// \class Mangled Mangled.h "lldb/Core/Mangled.h"
/// A class that handles mangled names.
///
/// Designed to handle mangled names. The demangled version of any names will
/// Constructor with an optional string and a boolean indicating if it is
/// the mangled version.
///
- /// @param[in] name
+ /// \param[in] name
/// The already const name to copy into this object.
///
- /// @param[in] is_mangled
+ /// \param[in] is_mangled
/// If \b true then \a name is a mangled name, if \b false then
/// \a name is demangled.
//----------------------------------------------------------------------
/// Constructor with an optional string and auto-detect if \a name is
/// mangled or not.
///
- /// @param[in] name
+ /// \param[in] name
/// The already const name to copy into this object.
//----------------------------------------------------------------------
explicit Mangled(ConstString name);
/// This allows code to check a Mangled object to see if it contains a valid
/// mangled name using code such as:
///
- /// @code
+ /// \code
/// Mangled mangled(...);
/// if (mangled)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// A pointer to this object if either the mangled or unmangled
/// name is set, NULL otherwise.
//----------------------------------------------------------------------
/// This allows code to check a Mangled object to see if it contains an
/// empty mangled name using code such as:
///
- /// @code
+ /// \code
/// Mangled mangled(...);
/// if (!mangled)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// Returns \b true if the object has an empty mangled and
/// unmangled name, \b false otherwise.
//----------------------------------------------------------------------
///
/// Compares the Mangled::GetName() string in \a lhs and \a rhs.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// A const reference to the Left Hand Side object to compare.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const reference to the Right Hand Side object to compare.
///
- /// @return
- /// @li -1 if \a lhs is less than \a rhs
- /// @li 0 if \a lhs is equal to \a rhs
- /// @li 1 if \a lhs is greater than \a rhs
+ /// \return
+ /// \li -1 if \a lhs is less than \a rhs
+ /// \li 0 if \a lhs is equal to \a rhs
+ /// \li 1 if \a lhs is greater than \a rhs
//----------------------------------------------------------------------
static int Compare(const Mangled &lhs, const Mangled &rhs);
/// Dump a Mangled object to stream \a s. We don't force our demangled name
/// to be computed currently (we don't use the accessor).
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//----------------------------------------------------------------------
void Dump(Stream *s) const;
//----------------------------------------------------------------------
/// Dump a debug description of this object to a Stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//----------------------------------------------------------------------
void DumpDebug(Stream *s) const;
//----------------------------------------------------------------------
/// Demangled name get accessor.
///
- /// @return
+ /// \return
/// A const reference to the demangled name string object.
//----------------------------------------------------------------------
ConstString GetDemangledName(lldb::LanguageType language) const;
//----------------------------------------------------------------------
/// Display demangled name get accessor.
///
- /// @return
+ /// \return
/// A const reference to the display demangled name string object.
//----------------------------------------------------------------------
ConstString GetDisplayDemangledName(lldb::LanguageType language) const;
//----------------------------------------------------------------------
/// Mangled name get accessor.
///
- /// @return
+ /// \return
/// A reference to the mangled name string object.
//----------------------------------------------------------------------
ConstString &GetMangledName() { return m_mangled; }
//----------------------------------------------------------------------
/// Mangled name get accessor.
///
- /// @return
+ /// \return
/// A const reference to the mangled name string object.
//----------------------------------------------------------------------
ConstString GetMangledName() const { return m_mangled; }
//----------------------------------------------------------------------
/// Best name get accessor.
///
- /// @param[in] preference
+ /// \param[in] preference
/// Which name would you prefer to get?
///
- /// @return
+ /// \return
/// A const reference to the preferred name string object if this
/// object has a valid name of that kind, else a const reference to the
/// other name is returned.
//----------------------------------------------------------------------
/// Check if "name" matches either the mangled or demangled name.
///
- /// @param[in] name
+ /// \param[in] name
/// A name to match against both strings.
///
- /// @return
+ /// \return
/// \b True if \a name matches either name, \b false otherwise.
//----------------------------------------------------------------------
bool NameMatches(ConstString name, lldb::LanguageType language) const {
/// the size in bytes of this object, not any shared string values it may
/// refer to.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//----------------------------------------------------------------------
size_t MemorySize() const;
/// If \a is_mangled is \b true, then the mangled named is set to \a name,
/// else the demangled name is set to \a name.
///
- /// @param[in] name
+ /// \param[in] name
/// The already const version of the name for this object.
///
- /// @param[in] is_mangled
+ /// \param[in] is_mangled
/// If \b true then \a name is a mangled name, if \b false then
/// \a name is demangled.
//----------------------------------------------------------------------
/// This version auto detects if the string is mangled by inspecting the
/// string value and looking for common mangling prefixes.
///
- /// @param[in] name
+ /// \param[in] name
/// The already const version of the name for this object.
//----------------------------------------------------------------------
void SetValue(ConstString name);
/// aren't mangled and it isn't clear what language the name represents
/// (there will be no mangled name).
///
- /// @return
+ /// \return
/// The language for the mangled/demangled name, eLanguageTypeUnknown
/// if there is no mangled or demangled counterpart.
//----------------------------------------------------------------------
/// This function is thread-safe when used with different \a context
/// instances in different threads.
///
- /// @param[in] context
+ /// \param[in] context
/// The context for this function. A single instance can be stack-
/// allocated in the caller's frame and used for multiple calls.
///
- /// @param[in] skip_mangled_name
+ /// \param[in] skip_mangled_name
/// A filtering function for skipping entities based on name and mangling
/// scheme. This can be null if unused.
///
- /// @return
+ /// \return
/// True on success, false otherwise.
//----------------------------------------------------------------------
bool DemangleWithRichManglingInfo(RichManglingContext &context,
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Module Module.h "lldb/Core/Module.h"
+/// \class Module Module.h "lldb/Core/Module.h"
/// A class that describes an executable image and its associated
/// object and symbol files.
///
/// Clients that wish to share modules with other targets should use
/// ModuleList::GetSharedModule().
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// The file specification for the on disk representation of
/// this executable image.
///
- /// @param[in] arch
+ /// \param[in] arch
/// The architecture to set as the current architecture in
/// this module.
///
- /// @param[in] object_name
+ /// \param[in] object_name
/// The name of an object in a module used to extract a module
/// within a module (.a files and modules that contain multiple
/// architectures).
///
- /// @param[in] object_offset
+ /// \param[in] object_offset
/// The offset within an existing module used to extract a
/// module within a module (.a files and modules that contain
/// multiple architectures).
/// address for all top level sections to be the section file address +
/// offset.
///
- /// @param[in] target
+ /// \param[in] target
/// The target in which to apply the section load addresses.
///
- /// @param[in] value
+ /// \param[in] value
/// if \a value_is_offset is true, then value is the offset to
/// apply to all file addresses for all top level sections in
/// the object file as each section load address is being set.
/// If \a value_is_offset is false, then "value" is the new
/// absolute base address for the image.
///
- /// @param[in] value_is_offset
+ /// \param[in] value_is_offset
/// If \b true, then \a value is an offset to apply to each
/// file address of each top level section.
/// If \b false, then \a value is the image base address that
/// will be used to rigidly slide all loadable sections.
///
- /// @param[out] changed
+ /// \param[out] changed
/// If any section load addresses were changed in \a target,
/// then \a changed will be set to \b true. Else \a changed
/// will be set to false. This allows this function to be
/// be false and no module updated notification will need to
/// be sent out.
///
- /// @return
+ /// \return
/// /b True if any sections were successfully loaded in \a target,
/// /b false otherwise.
//------------------------------------------------------------------
bool &changed);
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
+ /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void CalculateSymbolContext(SymbolContext *sc) override;
/// There are many places where logging wants to log this fully qualified
/// specification, so we centralize this functionality here.
///
- /// @return
+ /// \return
/// The object path + object name if there is one.
//------------------------------------------------------------------
std::string GetSpecificationDescription() const;
/// to this point at which this function is called, so this is a good way to
/// see what has been parsed in a module.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s);
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
+ /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void DumpSymbolContext(Stream *s) override;
//------------------------------------------------------------------
/// Find a symbol in the object file's symbol table.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the symbol that we are looking for.
///
- /// @param[in] symbol_type
+ /// \param[in] symbol_type
/// If set to eSymbolTypeAny, find a symbol of any type that
/// has a name that matches \a name. If set to any other valid
/// SymbolType enumeration value, then search only for
/// symbols that match \a symbol_type.
///
- /// @return
+ /// \return
/// Returns a valid symbol pointer if a symbol was found,
/// nullptr otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find a function symbols in the object file's symbol table.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the symbol that we are looking for.
///
- /// @param[in] name_type_mask
+ /// \param[in] name_type_mask
/// A mask that has one or more bitwise OR'ed values from the
/// lldb::FunctionNameType enumeration type that indicate what
/// kind of names we are looking for.
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A list to append any matching symbol contexts to.
///
- /// @return
+ /// \return
/// The number of symbol contexts that were added to \a sc_list
//------------------------------------------------------------------
size_t FindFunctionSymbols(ConstString name, uint32_t name_type_mask,
/// Finds all compile units that match \a path in all of the modules and
/// returns the results in \a sc_list.
///
- /// @param[in] path
+ /// \param[in] path
/// The name of the function we are looking for.
///
- /// @param[in] append
+ /// \param[in] append
/// If \b true, then append any compile units that were found
/// to \a sc_list. If \b false, then the \a sc_list is cleared
/// and the contents of \a sc_list are replaced.
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A symbol context list that gets filled in with all of the
/// matches.
///
- /// @return
+ /// \return
/// The number of matches added to \a sc_list.
//------------------------------------------------------------------
size_t FindCompileUnits(const FileSpec &path, bool append,
/// representing the inlined function, and the function will be the
/// containing function. If it is not inlined, then the block will be NULL.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the compile unit we are looking for.
///
- /// @param[in] namespace_decl
+ /// \param[in] namespace_decl
/// If valid, a namespace to search in.
///
- /// @param[in] name_type_mask
+ /// \param[in] name_type_mask
/// A bit mask of bits that indicate what kind of names should
/// be used when doing the lookup. Bits include fully qualified
/// names, base names, C++ methods, or ObjC selectors.
/// See FunctionNameType for more details.
///
- /// @param[in] append
+ /// \param[in] append
/// If \b true, any matches will be appended to \a sc_list, else
/// matches replace the contents of \a sc_list.
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A symbol context list that gets filled in with all of the
/// matches.
///
- /// @return
+ /// \return
/// The number of matches added to \a sc_list.
//------------------------------------------------------------------
size_t FindFunctions(ConstString name,
/// representing the inlined function, and the function will be the
/// containing function. If it is not inlined, then the block will be NULL.
///
- /// @param[in] regex
+ /// \param[in] regex
/// A regular expression to use when matching the name.
///
- /// @param[in] append
+ /// \param[in] append
/// If \b true, any matches will be appended to \a sc_list, else
/// matches replace the contents of \a sc_list.
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A symbol context list that gets filled in with all of the
/// matches.
///
- /// @return
+ /// \return
/// The number of matches added to \a sc_list.
//------------------------------------------------------------------
size_t FindFunctions(const RegularExpression ®ex, bool symbols_ok,
//------------------------------------------------------------------
/// Find addresses by file/line
///
- /// @param[in] target_sp
+ /// \param[in] target_sp
/// The target the addresses are desired for.
///
- /// @param[in] file
+ /// \param[in] file
/// Source file to locate.
///
- /// @param[in] line
+ /// \param[in] line
/// Source line to locate.
///
- /// @param[in] function
+ /// \param[in] function
/// Optional filter function. Addresses within this function will be
/// added to the 'local' list. All others will be added to the 'extern'
/// list.
///
- /// @param[out] output_local
+ /// \param[out] output_local
/// All matching addresses within 'function'
///
- /// @param[out] output_extern
+ /// \param[out] output_extern
/// All matching addresses not within 'function'
void FindAddressesForLine(const lldb::TargetSP target_sp,
const FileSpec &file, uint32_t line,
//------------------------------------------------------------------
/// Find global and static variables by name.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the global or static variable we are looking
/// for.
///
- /// @param[in] parent_decl_ctx
+ /// \param[in] parent_decl_ctx
/// If valid, a decl context that results must exist within
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a
/// max_matches. Specify UINT32_MAX to get all possible matches.
///
- /// @param[in] variable_list
+ /// \param[in] variable_list
/// A list of variables that gets the matches appended to.
///
- /// @return
+ /// \return
/// The number of matches added to \a variable_list.
//------------------------------------------------------------------
size_t FindGlobalVariables(ConstString name,
//------------------------------------------------------------------
/// Find global and static variables by regular expression.
///
- /// @param[in] regex
+ /// \param[in] regex
/// A regular expression to use when matching the name.
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a
/// max_matches. Specify UINT32_MAX to get all possible matches.
///
- /// @param[in] variable_list
+ /// \param[in] variable_list
/// A list of variables that gets the matches appended to.
///
- /// @return
+ /// \return
/// The number of matches added to \a variable_list.
//------------------------------------------------------------------
size_t FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
/// have to specify complete scoping on all expressions, but it also allows
/// for exact matching when required.
///
- /// @param[in] type_name
+ /// \param[in] type_name
/// The name of the type we are looking for that is a fully
/// or partially qualified type name.
///
- /// @param[in] exact_match
+ /// \param[in] exact_match
/// If \b true, \a type_name is fully qualified and must match
/// exactly. If \b false, \a type_name is a partially qualified
/// name where the leading namespaces or classes can be
/// omitted to make finding types that a user may type
/// easier.
///
- /// @param[out] type_list
+ /// \param[out] type_list
/// A type list gets populated with any matches.
///
- /// @return
+ /// \return
/// The number of matches added to \a type_list.
//------------------------------------------------------------------
size_t
/// expression parser when searches need to happen in an exact namespace
/// scope.
///
- /// @param[in] type_name
+ /// \param[in] type_name
/// The name of a type within a namespace that should not include
/// any qualifying namespaces (just a type basename).
///
- /// @param[in] namespace_decl
+ /// \param[in] namespace_decl
/// The namespace declaration that this type must exist in.
///
- /// @param[out] type_list
+ /// \param[out] type_list
/// A type list gets populated with any matches.
///
- /// @return
+ /// \return
/// The number of matches added to \a type_list.
//------------------------------------------------------------------
size_t FindTypesInNamespace(ConstString type_name,
//------------------------------------------------------------------
/// Get const accessor for the module architecture.
///
- /// @return
+ /// \return
/// A const reference to the architecture object.
//------------------------------------------------------------------
const ArchSpec &GetArchitecture() const;
/// running LLDB. This can differ from the path on the platform since we
/// might be doing remote debugging.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
const FileSpec &GetFileSpec() const { return m_file; }
/// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The
/// file could also be cached in a local developer kit directory.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
const FileSpec &GetPlatformFileSpec() const {
/// Tells whether this module is capable of being the main executable for a
/// process.
///
- /// @return
+ /// \return
/// \b true if it is, \b false otherwise.
//------------------------------------------------------------------
bool IsExecutable();
/// call doesn't distinguish between whether the module is loaded by the
/// dynamic loader, or by a "target module add" type call.
///
- /// @param[in] target
+ /// \param[in] target
/// The target to check whether this is loaded in.
///
- /// @return
+ /// \return
/// \b true if it is, \b false otherwise.
//------------------------------------------------------------------
bool IsLoadedInTarget(Target *target);
//------------------------------------------------------------------
/// Get the number of compile units for this module.
///
- /// @return
+ /// \return
/// The number of compile units that the symbol vendor plug-in
/// finds.
//------------------------------------------------------------------
/// If the object file has not been located or parsed yet, this function
/// will find the best ObjectFile plug-in that can parse Module::m_file.
///
- /// @return
+ /// \return
/// If Module::m_file does not exist, or no plug-in was found
/// that can parse the file, or the object file doesn't contain
/// the current architecture in Module::m_arch, nullptr will be
/// If the symbol vendor has not been loaded yet, this function will return
/// the section list for the object file.
///
- /// @return
+ /// \return
/// Unified module section list.
//------------------------------------------------------------------
virtual SectionList *GetSectionList();
/// requested. Specifically, we do not create FuncUnwinders objects for
/// functions until they are needed.
///
- /// @return
+ /// \return
/// Returns the unwind table for this module. If this object has no
/// associated object file, an empty UnwindTable is returned.
//------------------------------------------------------------------
/// enable the ObjectFile plugins to read the header of the object file
/// without going back to the process.
///
- /// @return
+ /// \return
/// The object file loaded from memory or nullptr, if the operation
/// failed (see the `error` for more information in that case).
//------------------------------------------------------------------
/// If the symbol vendor file has not been located yet, this function will
/// find the best SymbolVendor plug-in that can use the current object file.
///
- /// @return
+ /// \return
/// If this module does not have a valid object file, or no
/// plug-in can be found that can use the object file, nullptr will
/// be returned, else a valid symbol vendor plug-in interface
//------------------------------------------------------------------
/// Get accessor the type list for this module.
///
- /// @return
+ /// \return
/// A valid type list pointer, or nullptr if there is no valid
/// symbol vendor for this module.
//------------------------------------------------------------------
/// the file format, an MD5 checksum of the entire file, or slice of the
/// file for the current architecture should be used.
///
- /// @return
+ /// \return
/// A const pointer to the internal copy of the UUID value in
/// this module if this module has a valid UUID value, NULL
/// otherwise.
/// line entry. Use the return value to determine which of these properties
/// have been modified.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A load address to resolve.
///
- /// @param[in] resolve_scope
+ /// \param[in] resolve_scope
/// The scope that should be resolved (see SymbolContext::Scope).
/// A combination of flags from the enumeration SymbolContextItem
/// requesting a resolution depth. Note that the flags that are
/// eSymbolContextModule, and eSymbolContextFunction requires
/// eSymbolContextSymbol.
///
- /// @param[out] sc
+ /// \param[out] sc
/// The SymbolContext that is modified based on symbol resolution.
///
- /// @param[in] resolve_tail_call_address
+ /// \param[in] resolve_tail_call_address
/// Determines if so_addr should resolve to a symbol in the case
/// of a function whose last instruction is a call. In this case,
/// the PC can be one past the address range of the function.
///
- /// @return
+ /// \return
/// The scope that has been resolved (see SymbolContext::Scope).
///
- /// @see SymbolContext::Scope
+ /// \see SymbolContext::Scope
//------------------------------------------------------------------
uint32_t ResolveSymbolContextForAddress(
const Address &so_addr, lldb::SymbolContextItem resolve_scope,
/// to only what is needed -- typically the module, compile unit, line table
/// and line table entry are sufficient.
///
- /// @param[in] file_path
+ /// \param[in] file_path
/// A path to a source file to match. If \a file_path does not
/// specify a directory, then this query will match all files
/// whose base filename matches. If \a file_path does specify
/// a directory, the fullpath to the file must match.
///
- /// @param[in] line
+ /// \param[in] line
/// The source line to match, or zero if just the compile unit
/// should be resolved.
///
- /// @param[in] check_inlines
+ /// \param[in] check_inlines
/// Check for inline file and line number matches. This option
/// should be used sparingly as it will cause all line tables
/// for every compile unit to be parsed and searched for
/// matching inline file entries.
///
- /// @param[in] resolve_scope
+ /// \param[in] resolve_scope
/// The scope that should be resolved (see
/// SymbolContext::Scope).
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A symbol context list that gets matching symbols contexts
/// appended to.
///
- /// @return
+ /// \return
/// The number of matches that were added to \a sc_list.
///
- /// @see SymbolContext::Scope
+ /// \see SymbolContext::Scope
//------------------------------------------------------------------
uint32_t ResolveSymbolContextForFilePath(
const char *file_path, uint32_t line, bool check_inlines,
/// to only what is needed -- typically the module, compile unit, line table
/// and line table entry are sufficient.
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// A file spec to a source file to match. If \a file_path does
/// not specify a directory, then this query will match all
/// files whose base filename matches. If \a file_path does
/// specify a directory, the fullpath to the file must match.
///
- /// @param[in] line
+ /// \param[in] line
/// The source line to match, or zero if just the compile unit
/// should be resolved.
///
- /// @param[in] check_inlines
+ /// \param[in] check_inlines
/// Check for inline file and line number matches. This option
/// should be used sparingly as it will cause all line tables
/// for every compile unit to be parsed and searched for
/// matching inline file entries.
///
- /// @param[in] resolve_scope
+ /// \param[in] resolve_scope
/// The scope that should be resolved (see
/// SymbolContext::Scope).
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A symbol context list that gets filled in with all of the
/// matches.
///
- /// @return
+ /// \return
/// A integer that contains SymbolContext::Scope bits set for
/// each item that was successfully resolved.
///
- /// @see SymbolContext::Scope
+ /// \see SymbolContext::Scope
//------------------------------------------------------------------
uint32_t ResolveSymbolContextsForFileSpec(
const FileSpec &file_spec, uint32_t line, bool check_inlines,
/// if the remappings are on a network file system, so use this function
/// sparingly (not in a tight debug info parsing loop).
///
- /// @param[in] orig_spec
+ /// \param[in] orig_spec
/// The original source file path to try and remap.
///
- /// @param[out] new_spec
+ /// \param[out] new_spec
/// The newly remapped filespec that is guaranteed to exist.
///
- /// @return
+ /// \return
/// /b true if \a orig_spec was successfully located and
/// \a new_spec is filled in with an existing file spec,
/// \b false otherwise.
/// stat the file system so it can be used in tight loops where debug info
/// is being parsed.
///
- /// @param[in] path
+ /// \param[in] path
/// The original source file path to try and remap.
///
- /// @param[out] new_path
+ /// \param[out] new_path
/// The newly remapped filespec that is may or may not exist.
///
- /// @return
+ /// \return
/// /b true if \a path was successfully located and \a new_path
/// is filled in with a new source path, \b false otherwise.
//------------------------------------------------------------------
bool RemapSourceFile(const char *, std::string &) const = delete;
//----------------------------------------------------------------------
- /// @class LookupInfo Module.h "lldb/Core/Module.h"
+ /// \class LookupInfo Module.h "lldb/Core/Module.h"
/// A class that encapsulates name lookup information.
///
/// Users can type a wide variety of partial names when setting breakpoints
/// indicates what clients wish to resolve and can be used to limit the
/// scope of what is parsed.
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// The load virtual address to resolve.
///
- /// @param[in] vm_addr_is_file_addr
+ /// \param[in] vm_addr_is_file_addr
/// If \b true, \a vm_addr is a file address, else \a vm_addr
/// if a load address.
///
- /// @param[in] resolve_scope
+ /// \param[in] resolve_scope
/// The scope that should be resolved (see
/// SymbolContext::Scope).
///
- /// @param[out] so_addr
+ /// \param[out] so_addr
/// The section offset based address that got resolved if
/// any bits are returned.
///
- /// @param[out] sc
+ /// \param[out] sc
// The symbol context that has objects filled in. Each bit
/// in the \a resolve_scope pertains to a member in the \a sc.
///
- /// @return
+ /// \return
/// A integer that contains SymbolContext::Scope bits set for
/// each item that was successfully resolved.
///
- /// @see SymbolContext::Scope
+ /// \see SymbolContext::Scope
//------------------------------------------------------------------
uint32_t ResolveSymbolContextForAddress(lldb::addr_t vm_addr,
bool vm_addr_is_file_addr,
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ModuleChild ModuleChild.h "lldb/Core/ModuleChild.h"
+/// \class ModuleChild ModuleChild.h "lldb/Core/ModuleChild.h"
/// A mix in class that contains a pointer back to the module
/// that owns the object which inherits from it.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Construct with owning module.
///
- /// @param[in] module
+ /// \param[in] module
/// The module that owns the object that inherits from this
/// class.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Copy constructor.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const ModuleChild class reference to copy.
//------------------------------------------------------------------
ModuleChild(const ModuleChild &rhs);
//------------------------------------------------------------------
/// Assignment operator.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const ModuleChild class reference to copy.
///
- /// @return
+ /// \return
/// A const reference to this object.
//------------------------------------------------------------------
const ModuleChild &operator=(const ModuleChild &rhs);
//------------------------------------------------------------------
/// Get const accessor for the module pointer.
///
- /// @return
+ /// \return
/// A const pointer to the module that owns the object that
/// inherits from this class.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set accessor for the module pointer.
///
- /// @param[in] module
+ /// \param[in] module
/// A new module that owns the object that inherits from this
/// class.
//------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
+/// \class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
/// A collection class for Module objects.
///
/// Modules in the module collection class are stored as reference counted
///
/// Creates a new module list object with a copy of the modules from \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// Another module list object.
//------------------------------------------------------------------
ModuleList(const ModuleList &rhs);
///
/// Copies the module list from \a rhs into this list.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// Another module list object.
///
- /// @return
+ /// \return
/// A const reference to this object.
//------------------------------------------------------------------
const ModuleList &operator=(const ModuleList &rhs);
///
/// Appends the module to the collection.
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// A shared pointer to a module to add to this collection.
//------------------------------------------------------------------
void Append(const lldb::ModuleSP &module_sp);
///
/// Replaces the module to the collection.
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// A shared pointer to a module to replace in this collection.
//------------------------------------------------------------------
void ReplaceEquivalent(const lldb::ModuleSP &module_sp);
/// Dump the description of each module contained in this list to the
/// supplied stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @see Module::Dump(Stream *) const
+ /// \see Module::Dump(Stream *) const
//------------------------------------------------------------------
void Dump(Stream *s) const;
//------------------------------------------------------------------
/// Get the module shared pointer for the module at index \a idx.
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into this module collection.
///
- /// @return
+ /// \return
/// A shared pointer to a Module which can contain NULL if
/// \a idx is out of range.
///
- /// @see ModuleList::GetSize()
+ /// \see ModuleList::GetSize()
//------------------------------------------------------------------
lldb::ModuleSP GetModuleAtIndex(size_t idx) const;
/// acquiring the ModuleList mutex. This MUST already have been acquired
/// with ModuleList::GetMutex and locked for this call to be safe.
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into this module collection.
///
- /// @return
+ /// \return
/// A shared pointer to a Module which can contain NULL if
/// \a idx is out of range.
///
- /// @see ModuleList::GetSize()
+ /// \see ModuleList::GetSize()
//------------------------------------------------------------------
lldb::ModuleSP GetModuleAtIndexUnlocked(size_t idx) const;
//------------------------------------------------------------------
/// Get the module pointer for the module at index \a idx.
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into this module collection.
///
- /// @return
+ /// \return
/// A pointer to a Module which can by nullptr if \a idx is out
/// of range.
///
- /// @see ModuleList::GetSize()
+ /// \see ModuleList::GetSize()
//------------------------------------------------------------------
Module *GetModulePointerAtIndex(size_t idx) const;
/// the ModuleList mutex. This MUST already have been acquired with
/// ModuleList::GetMutex and locked for this call to be safe.
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into this module collection.
///
- /// @return
+ /// \return
/// A pointer to a Module which can by nullptr if \a idx is out
/// of range.
///
- /// @see ModuleList::GetSize()
+ /// \see ModuleList::GetSize()
//------------------------------------------------------------------
Module *GetModulePointerAtIndexUnlocked(size_t idx) const;
/// Finds all compile units that match \a path in all of the modules and
/// returns the results in \a sc_list.
///
- /// @param[in] path
+ /// \param[in] path
/// The name of the compile unit we are looking for.
///
- /// @param[in] append
+ /// \param[in] append
/// If \b true, then append any compile units that were found
/// to \a sc_list. If \b false, then the \a sc_list is cleared
/// and the contents of \a sc_list are replaced.
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A symbol context list that gets filled in with all of the
/// matches.
///
- /// @return
+ /// \return
/// The number of matches added to \a sc_list.
//------------------------------------------------------------------
size_t FindCompileUnits(const FileSpec &path, bool append,
SymbolContextList &sc_list) const;
//------------------------------------------------------------------
- /// @see Module::FindFunctions ()
+ /// \see Module::FindFunctions ()
//------------------------------------------------------------------
size_t FindFunctions(ConstString name,
lldb::FunctionNameType name_type_mask,
SymbolContextList &sc_list) const;
//------------------------------------------------------------------
- /// @see Module::FindFunctionSymbols ()
+ /// \see Module::FindFunctionSymbols ()
//------------------------------------------------------------------
size_t FindFunctionSymbols(ConstString name,
lldb::FunctionNameType name_type_mask,
SymbolContextList &sc_list);
//------------------------------------------------------------------
- /// @see Module::FindFunctions ()
+ /// \see Module::FindFunctions ()
//------------------------------------------------------------------
size_t FindFunctions(const RegularExpression &name, bool include_symbols,
bool include_inlines, bool append,
//------------------------------------------------------------------
/// Find global and static variables by name.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the global or static variable we are looking
/// for.
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a
/// max_matches. Specify UINT32_MAX to get all possible matches.
///
- /// @param[in] variable_list
+ /// \param[in] variable_list
/// A list of variables that gets the matches appended to.
///
- /// @return
+ /// \return
/// The number of matches added to \a variable_list.
//------------------------------------------------------------------
size_t FindGlobalVariables(ConstString name, size_t max_matches,
//------------------------------------------------------------------
/// Find global and static variables by regular expression.
///
- /// @param[in] regex
+ /// \param[in] regex
/// A regular expression to use when matching the name.
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a
/// max_matches. Specify UINT32_MAX to get all possible matches.
///
- /// @param[in] variable_list
+ /// \param[in] variable_list
/// A list of variables that gets the matches appended to.
///
- /// @return
+ /// \return
/// The number of matches added to \a variable_list.
//------------------------------------------------------------------
size_t FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
//------------------------------------------------------------------
/// Finds the first module whose file specification matches \a file_spec.
///
- /// @param[in] file_spec_ptr
+ /// \param[in] file_spec_ptr
/// A file specification object to match against the Module's
/// file specifications. If \a file_spec does not have
/// directory information, matches will occur by matching only
/// NULL, then file specifications won't be compared when
/// searching for matching modules.
///
- /// @param[in] arch_ptr
+ /// \param[in] arch_ptr
/// The architecture to search for if non-NULL. If this value
/// is NULL no architecture matching will be performed.
///
- /// @param[in] uuid_ptr
+ /// \param[in] uuid_ptr
/// The uuid to search for if non-NULL. If this value is NULL
/// no uuid matching will be performed.
///
- /// @param[in] object_name
+ /// \param[in] object_name
/// An optional object name that must match as well. This value
/// can be NULL.
///
- /// @param[out] matching_module_list
+ /// \param[out] matching_module_list
/// A module list that gets filled in with any modules that
/// match the search criteria.
///
- /// @return
+ /// \return
/// The number of matching modules found by the search.
//------------------------------------------------------------------
size_t FindModules(const ModuleSpec &module_spec,
//------------------------------------------------------------------
/// Find types by name.
///
- /// @param[in] search_first
+ /// \param[in] search_first
/// If non-null, this module will be searched before any other
/// modules.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the type we are looking for.
///
- /// @param[in] append
+ /// \param[in] append
/// If \b true, any matches will be appended to \a
/// variable_list, else matches replace the contents of
/// \a variable_list.
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// Allow the number of matches to be limited to \a
/// max_matches. Specify UINT32_MAX to get all possible matches.
///
- /// @param[in] encoding
+ /// \param[in] encoding
/// Limit the search to specific types, or get all types if
/// set to Type::invalid.
///
- /// @param[in] udt_name
+ /// \param[in] udt_name
/// If the encoding is a user defined type, specify the name
/// of the user defined type ("struct", "union", "class", etc).
///
- /// @param[out] type_list
+ /// \param[out] type_list
/// A type list gets populated with any matches.
///
- /// @return
+ /// \return
/// The number of matches added to \a type_list.
//------------------------------------------------------------------
size_t FindTypes(Module *search_first, ConstString name,
//------------------------------------------------------------------
/// Find addresses by file/line
///
- /// @param[in] target_sp
+ /// \param[in] target_sp
/// The target the addresses are desired for.
///
- /// @param[in] file
+ /// \param[in] file
/// Source file to locate.
///
- /// @param[in] line
+ /// \param[in] line
/// Source line to locate.
///
- /// @param[in] function
+ /// \param[in] function
/// Optional filter function. Addresses within this function will be
/// added to the 'local' list. All others will be added to the 'extern'
/// list.
///
- /// @param[out] output_local
+ /// \param[out] output_local
/// All matching addresses within 'function'
///
- /// @param[out] output_extern
+ /// \param[out] output_extern
/// All matching addresses not within 'function'
void FindAddressesForLine(const lldb::TargetSP target_sp,
const FileSpec &file, uint32_t line,
bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr) const;
//------------------------------------------------------------------
- /// @copydoc Module::ResolveSymbolContextForAddress (const Address
+ /// \copydoc Module::ResolveSymbolContextForAddress (const Address
/// &,uint32_t,SymbolContext&)
//------------------------------------------------------------------
uint32_t ResolveSymbolContextForAddress(const Address &so_addr,
SymbolContext &sc) const;
//------------------------------------------------------------------
- /// @copydoc Module::ResolveSymbolContextForFilePath (const char
+ /// \copydoc Module::ResolveSymbolContextForFilePath (const char
/// *,uint32_t,bool,uint32_t,SymbolContextList&)
//------------------------------------------------------------------
uint32_t ResolveSymbolContextForFilePath(
lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
//------------------------------------------------------------------
- /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
+ /// \copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
/// &,uint32_t,bool,uint32_t,SymbolContextList&)
//------------------------------------------------------------------
uint32_t ResolveSymbolContextsForFileSpec(
//------------------------------------------------------------------
/// Gets the size of the module list.
///
- /// @return
+ /// \return
/// The number of modules in the module list.
//------------------------------------------------------------------
size_t GetSize() const;
/// callbacks for debugger initialization and Process launch info
/// filtering and manipulation.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the plugin.
///
- /// @param[in] description
+ /// \param[in] description
/// A description string for the plugin.
///
- /// @param[in] create_callback
+ /// \param[in] create_callback
/// The callback that will be invoked to create an instance of
/// the callback. This may not be nullptr.
///
- /// @param[in] debugger_init_callback
+ /// \param[in] debugger_init_callback
/// An optional callback that will be made when a Debugger
/// instance is initialized.
///
- /// @param[in] filter_callback
+ /// \param[in] filter_callback
/// An optional callback that will be invoked before LLDB
/// launches a process for debugging. The callback must
/// do the following:
/// plugin if, for instance, additional environment variables
/// are needed to support the feature when enabled.
///
- /// @return
+ /// \return
/// Returns true upon success; otherwise, false.
//------------------------------------------------------------------
static bool
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h" Class that is
+/// \class Searcher SearchFilter.h "lldb/Core/SearchFilter.h" Class that is
/// driven by the SearchFilter to search the SymbolContext space of the target
/// program.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Prints a canonical description for the searcher to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// Stream to which the output is copied.
//------------------------------------------------------------------
virtual void GetDescription(Stream *s);
};
//----------------------------------------------------------------------
-/// @class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h" Class
+/// \class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h" Class
/// descends through the SymbolContext space of the target, applying a filter
/// at each stage till it reaches the depth specified by the GetDepth method
/// of the searcher, and calls its callback at that point.
//------------------------------------------------------------------
/// The basic constructor takes a Target, which gives the space to search.
///
- /// @param[in] target
+ /// \param[in] target
/// The Target that provides the module list to search.
//------------------------------------------------------------------
SearchFilter(const lldb::TargetSP &target_sp);
//------------------------------------------------------------------
/// Call this method with a file spec to see if that spec passes the filter.
///
- /// @param[in] spec
+ /// \param[in] spec
/// The file spec to check against the filter.
- /// @return
+ /// \return
/// \b true if \a spec passes, and \b false otherwise.
//------------------------------------------------------------------
virtual bool ModulePasses(const FileSpec &spec);
//------------------------------------------------------------------
/// Call this method with a Module to see if that module passes the filter.
///
- /// @param[in] module
+ /// \param[in] module
/// The Module to check against the filter.
///
- /// @return
+ /// \return
/// \b true if \a module passes, and \b false otherwise.
//------------------------------------------------------------------
virtual bool ModulePasses(const lldb::ModuleSP &module_sp);
//------------------------------------------------------------------
/// Call this method with a Address to see if \a address passes the filter.
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to check against the filter.
///
- /// @return
+ /// \return
/// \b true if \a address passes, and \b false otherwise.
//------------------------------------------------------------------
virtual bool AddressPasses(Address &addr);
/// Call this method with a FileSpec to see if \a file spec passes the
/// filter as the name of a compilation unit.
///
- /// @param[in] fileSpec
+ /// \param[in] fileSpec
/// The file spec to check against the filter.
///
- /// @return
+ /// \return
/// \b true if \a file spec passes, and \b false otherwise.
//------------------------------------------------------------------
virtual bool CompUnitPasses(FileSpec &fileSpec);
/// Call this method with a CompileUnit to see if \a comp unit passes the
/// filter.
///
- /// @param[in] compUnit
+ /// \param[in] compUnit
/// The CompileUnit to check against the filter.
///
- /// @return
+ /// \return
/// \b true if \a Comp Unit passes, and \b false otherwise.
//------------------------------------------------------------------
virtual bool CompUnitPasses(CompileUnit &compUnit);
/// Call this method with a Function to see if \a function passes the
/// filter.
///
- /// @param[in] function
+ /// \param[in] function
/// The Functions to check against the filter.
///
- /// @return
+ /// \return
/// \b true if \a function passes, and \b false otherwise.
//------------------------------------------------------------------
virtual bool FunctionPasses(Function &function);
//------------------------------------------------------------------
/// Call this method to do the search using the Searcher.
///
- /// @param[in] searcher
+ /// \param[in] searcher
/// The searcher to drive with this search.
///
//------------------------------------------------------------------
/// Call this method to do the search using the Searcher in the module list
/// \a modules.
///
- /// @param[in] searcher
+ /// \param[in] searcher
/// The searcher to drive with this search.
///
- /// @param[in] modules
+ /// \param[in] modules
/// The module list within which to restrict the search.
///
//------------------------------------------------------------------
/// search callbacks can then short cut the search to avoid looking at
/// things that obviously won't pass.
///
- /// @return
+ /// \return
/// The required elements for the search, which is an or'ed together
/// set of lldb:SearchContextItem enum's.
///
//------------------------------------------------------------------
/// Prints a canonical description for the search filter to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// Stream to which the output is copied.
//------------------------------------------------------------------
virtual void GetDescription(Stream *s);
};
//----------------------------------------------------------------------
-/// @class SearchFilterForUnconstrainedSearches SearchFilter.h
+/// \class SearchFilterForUnconstrainedSearches SearchFilter.h
/// "lldb/Core/SearchFilter.h" This is a SearchFilter that searches through
/// all modules. It also consults the
/// Target::ModuleIsExcludedForUnconstrainedSearches.
};
//----------------------------------------------------------------------
-/// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h" This
+/// \class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h" This
/// is a SearchFilter that restricts the search to a given module.
//----------------------------------------------------------------------
/// The basic constructor takes a Target, which gives the space to search,
/// and the module to restrict the search to.
///
- /// @param[in] target
+ /// \param[in] target
/// The Target that provides the module list to search.
///
- /// @param[in] module
+ /// \param[in] module
/// The Module that limits the search.
//------------------------------------------------------------------
SearchFilterByModule(const lldb::TargetSP &targetSP, const FileSpec &module);
/// The basic constructor takes a Target, which gives the space to search,
/// and the module list to restrict the search to.
///
- /// @param[in] target
+ /// \param[in] target
/// The Target that provides the module list to search.
///
- /// @param[in] module
+ /// \param[in] module
/// The Module that limits the search.
//------------------------------------------------------------------
SearchFilterByModuleList(const lldb::TargetSP &targetSP,
/// The basic constructor takes a Target, which gives the space to search,
/// and the module list to restrict the search to.
///
- /// @param[in] target
+ /// \param[in] target
/// The Target that provides the module list to search.
///
- /// @param[in] module
+ /// \param[in] module
/// The Module that limits the search.
//------------------------------------------------------------------
SearchFilterByModuleListAndCU(const lldb::TargetSP &targetSP,
/// Read the section data from the object file that the section
/// resides in.
///
- /// @param[in] dst
+ /// \param[in] dst
/// Where to place the data
///
- /// @param[in] dst_len
+ /// \param[in] dst_len
/// How many bytes of section data to read
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset in bytes within this section's data at which to
/// start copying data from.
///
- /// @return
+ /// \return
/// The number of bytes read from the section, or zero if the
/// section has no data or \a offset is not a valid offset
/// in this section.
/// object file is on disk, it will shared the mmap data for the
/// entire object file.
///
- /// @param[in] data
+ /// \param[in] data
/// Where to place the data, address byte size, and byte order
///
- /// @return
+ /// \return
/// The number of bytes read from the section, or zero if the
/// section has no data or \a offset is not a valid offset
/// in this section.
/// pointers, references, arrays and more. Again, it does so without
/// doing any expensive type completion.
///
- /// @return
+ /// \return
/// Returns \b true if the ValueObject might have children, or \b
/// false otherwise.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DWARFExpression DWARFExpression.h
+/// \class DWARFExpression DWARFExpression.h
/// "lldb/Expression/DWARFExpression.h" Encapsulates a DWARF location
/// expression and interprets it.
///
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] data
+ /// \param[in] data
/// A data extractor configured to read the DWARF location expression's
/// bytecode.
///
- /// @param[in] data_offset
+ /// \param[in] data_offset
/// The offset of the location expression in the extractor.
///
- /// @param[in] data_length
+ /// \param[in] data_length
/// The byte length of the location expression.
//------------------------------------------------------------------
DWARFExpression(lldb::ModuleSP module, const DataExtractor &data,
//------------------------------------------------------------------
/// Print the description of the expression to a stream
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to print to.
///
- /// @param[in] level
+ /// \param[in] level
/// The level of verbosity to use.
///
- /// @param[in] location_list_base_addr
+ /// \param[in] location_list_base_addr
/// If this is a location list based expression, this is the
/// address of the object that owns it. NOTE: this value is
/// different from the DWARF version of the location list base
/// address which is compile unit relative. This base address
/// is the address of the object that owns the location list.
///
- /// @param[in] abi
+ /// \param[in] abi
/// An optional ABI plug-in that can be used to resolve register
/// names.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Search for a load address in the location list
///
- /// @param[in] process
+ /// \param[in] process
/// The process to use when resolving the load address
///
- /// @param[in] addr
+ /// \param[in] addr
/// The address to resolve
///
- /// @return
+ /// \return
/// True if IsLocationList() is true and the address was found;
/// false otherwise.
//------------------------------------------------------------------
/// static variable since there is no other indication from DWARF debug
/// info.
///
- /// @param[in] op_addr_idx
+ /// \param[in] op_addr_idx
/// The DW_OP_addr index to retrieve in case there is more than
/// one DW_OP_addr opcode in the location byte stream.
///
- /// @param[out] error
+ /// \param[out] error
/// If the location stream contains unknown DW_OP opcodes or the
/// data is missing, \a error will be set to \b true.
///
- /// @return
+ /// \return
/// LLDB_INVALID_ADDRESS if the location doesn't contain a
/// DW_OP_addr for \a op_addr_idx, otherwise a valid file address
//------------------------------------------------------------------
/// Make the expression parser read its location information from a given
/// data source. Does not change the offset and length
///
- /// @param[in] data
+ /// \param[in] data
/// A data extractor configured to read the DWARF location expression's
/// bytecode.
//------------------------------------------------------------------
/// Make the expression parser read its location information from a given
/// data source
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// The module that defines the DWARF expression.
///
- /// @param[in] data
+ /// \param[in] data
/// A data extractor configured to read the DWARF location expression's
/// bytecode.
///
- /// @param[in] data_offset
+ /// \param[in] data_offset
/// The offset of the location expression in the extractor.
///
- /// @param[in] data_length
+ /// \param[in] data_length
/// The byte length of the location expression.
//------------------------------------------------------------------
void SetOpcodeData(lldb::ModuleSP module_sp, const DataExtractor &data,
/// though we are copying the data, it shouldn't amount to that much for the
/// variables we end up parsing.
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// The module that defines the DWARF expression.
///
- /// @param[in] data
+ /// \param[in] data
/// A data extractor configured to read and copy the DWARF
/// location expression's bytecode.
///
- /// @param[in] data_offset
+ /// \param[in] data_offset
/// The offset of the location expression in the extractor.
///
- /// @param[in] data_length
+ /// \param[in] data_length
/// The byte length of the location expression.
//------------------------------------------------------------------
void CopyOpcodeData(lldb::ModuleSP module_sp, const DataExtractor &data,
//------------------------------------------------------------------
/// Tells the expression that it refers to a location list.
///
- /// @param[in] slide
+ /// \param[in] slide
/// This value should be a slide that is applied to any values
/// in the location list data so the values become zero based
/// offsets into the object that owns the location list. We need
//------------------------------------------------------------------
/// Set the call-frame-info style register kind
///
- /// @param[in] reg_kind
+ /// \param[in] reg_kind
/// The register kind.
//------------------------------------------------------------------
void SetRegisterKind(lldb::RegisterKind reg_kind);
//------------------------------------------------------------------
/// Evaluate a DWARF location expression in a particular context
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context in which to evaluate the location
/// expression. The location expression may access the target's
/// memory, especially if it comes from the expression parser.
///
- /// @param[in] opcode_ctx
+ /// \param[in] opcode_ctx
/// The module which defined the expression.
///
- /// @param[in] opcodes
+ /// \param[in] opcodes
/// This is a static method so the opcodes need to be provided
/// explicitly.
///
- /// @param[in] expr_locals
+ /// \param[in] expr_locals
/// If the location expression was produced by the expression parser,
/// the list of local variables referenced by the DWARF expression.
/// This list should already have been populated during parsing;
/// the DWARF expression refers to variables by index. Can be NULL if
/// the location expression uses no locals.
///
- /// @param[in] decl_map
+ /// \param[in] decl_map
/// If the location expression was produced by the expression parser,
/// the list of external variables referenced by the location
/// expression. Can be NULL if the location expression uses no
/// external variables.
///
- /// @param[in] reg_ctx
+ /// \param[in] reg_ctx
/// An optional parameter which provides a RegisterContext for use
/// when evaluating the expression (i.e. for fetching register values).
/// Normally this will come from the ExecutionContext's StackFrame but
/// in the case where an expression needs to be evaluated while building
/// the stack frame list, this short-cut is available.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset of the location expression in the data extractor.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of the location expression.
///
- /// @param[in] reg_set
+ /// \param[in] reg_set
/// The call-frame-info style register kind.
///
- /// @param[in] initial_value_ptr
+ /// \param[in] initial_value_ptr
/// A value to put on top of the interpreter stack before evaluating
/// the expression, if the expression is parametrized. Can be NULL.
///
- /// @param[in] result
+ /// \param[in] result
/// A value into which the result of evaluating the expression is
/// to be placed.
///
- /// @param[in] error_ptr
+ /// \param[in] error_ptr
/// If non-NULL, used to report errors in expression evaluation.
///
- /// @return
+ /// \return
/// True on success; false otherwise. If error_ptr is non-NULL,
/// details of the failure are provided through it.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Pretty-prints the location expression to a stream
///
- /// @param[in] stream
+ /// \param[in] stream
/// The stream to use for pretty-printing.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset into the data buffer of the opcodes to be printed.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of the opcodes to be printed.
///
- /// @param[in] level
+ /// \param[in] level
/// The level of detail to use in pretty-printing.
///
- /// @param[in] abi
+ /// \param[in] abi
/// An optional ABI plug-in that can be used to resolve register
/// names.
//------------------------------------------------------------------
class RecordingMemoryManager;
//----------------------------------------------------------------------
-/// @class Expression Expression.h "lldb/Expression/Expression.h" Encapsulates
+/// \class Expression Expression.h "lldb/Expression/Expression.h" Encapsulates
/// a single expression for use in lldb
///
/// LLDB uses expressions for various purposes, notably to call functions
class IRExecutionUnit;
//----------------------------------------------------------------------
-/// @class ExpressionParser ExpressionParser.h
+/// \class ExpressionParser ExpressionParser.h
/// "lldb/Expression/ExpressionParser.h" Encapsulates an instance of a
/// compiler that can parse expressions.
///
///
/// Initializes class variables.
///
- /// @param[in] exe_scope,
+ /// \param[in] exe_scope,
/// If non-NULL, an execution context scope that can help to
/// correctly create an expression with a valid process for
/// optional tuning Objective-C runtime support. Can be NULL.
///
- /// @param[in] expr
+ /// \param[in] expr
/// The expression to be parsed.
//------------------------------------------------------------------
ExpressionParser(ExecutionContextScope *exe_scope, Expression &expr,
/// Attempts to find possible command line completions for the given
/// expression.
///
- /// @param[out] request
+ /// \param[out] request
/// The completion request to fill out. The completion should be a string
/// that would complete the current token at the cursor position.
/// Note that the string in the list replaces the current token
/// in the command line.
///
- /// @param[in] line
+ /// \param[in] line
/// The line with the completion cursor inside the expression as a string.
/// The first line in the expression has the number 0.
///
- /// @param[in] pos
+ /// \param[in] pos
/// The character position in the line with the completion cursor.
/// If the value is 0, then the cursor is on top of the first character
/// in the line (i.e. the user has requested completion from the start of
/// the expression).
///
- /// @param[in] typed_pos
+ /// \param[in] typed_pos
/// The cursor position in the line as typed by the user. If the user
/// expression has not been transformed in some form (e.g. wrapping it
/// in a function body for C languages), then this is equal to the
/// 'pos' (e.g. a value of 0 means the cursor is at start of the
/// expression).
///
- /// @return
+ /// \return
/// True if we added any completion results to the output;
/// false otherwise.
//------------------------------------------------------------------
/// Parse a single expression and convert it to IR using Clang. Don't wrap
/// the expression in anything at all.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager in which to store the errors and warnings.
///
- /// @return
+ /// \return
/// The number of errors encountered during parsing. 0 means
/// success.
//------------------------------------------------------------------
/// expression. If successful, the rewritten expression is stored in the
/// diagnostic_manager, get it out with GetFixedExpression.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager containing fixit's to apply.
///
- /// @return
+ /// \return
/// \b true if the rewrite was successful, \b false otherwise.
//------------------------------------------------------------------
virtual bool RewriteExpression(DiagnosticManager &diagnostic_manager) {
/// Ready an already-parsed expression for execution, possibly evaluating it
/// statically.
///
- /// @param[out] func_addr
+ /// \param[out] func_addr
/// The address to which the function has been written.
///
- /// @param[out] func_end
+ /// \param[out] func_end
/// The end of the function's allocated memory region. (func_addr
/// and func_end do not delimit an allocated region; the allocated
/// region may begin before func_addr.)
///
- /// @param[in] execution_unit_sp
+ /// \param[in] execution_unit_sp
/// After parsing, ownership of the execution unit for
/// for the expression is handed to this shared pointer.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to write the function into.
///
- /// @param[out] can_interpret
+ /// \param[out] can_interpret
/// Set to true if the expression could be interpreted statically;
/// untouched otherwise.
///
- /// @param[in] execution_policy
+ /// \param[in] execution_policy
/// Determines whether the expression must be JIT-compiled, must be
/// evaluated statically, or whether this decision may be made
/// opportunistically.
///
- /// @return
+ /// \return
/// An error code indicating the success or failure of the operation.
/// Test with Success().
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ExpressionTypeSystemHelper ExpressionTypeSystemHelper.h
+/// \class ExpressionTypeSystemHelper ExpressionTypeSystemHelper.h
/// "lldb/Expression/ExpressionTypeSystemHelper.h"
/// A helper object that the Expression can pass to its ExpressionParser
/// to provide generic information that
};
//----------------------------------------------------------------------
-/// @class ExpressionVariableList ExpressionVariable.h
+/// \class ExpressionVariableList ExpressionVariable.h
/// "lldb/Expression/ExpressionVariable.h"
/// A list of variable references.
///
//----------------------------------------------------------------------
/// Finds a variable by name in the list.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the requested variable.
///
- /// @return
+ /// \return
/// The variable requested, or nullptr if that variable is not in the
/// list.
//----------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h"
+/// \class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h"
/// Encapsulates a function that can be called.
///
/// A given FunctionCaller object can handle a single function signature.
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] exe_scope
+ /// \param[in] exe_scope
/// An execution context scope that gets us at least a target and
/// process.
///
- /// @param[in] ast_context
+ /// \param[in] ast_context
/// The AST context to evaluate argument types in.
///
- /// @param[in] return_qualtype
+ /// \param[in] return_qualtype
/// An opaque Clang QualType for the function result. Should be
/// defined in ast_context.
///
- /// @param[in] function_address
+ /// \param[in] function_address
/// The address of the function to call.
///
- /// @param[in] arg_value_list
+ /// \param[in] arg_value_list
/// The default values to use when calling this function. Can
/// be overridden using WriteFunctionArguments().
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Compile the wrapper function
///
- /// @param[in] thread_to_use_sp
+ /// \param[in] thread_to_use_sp
/// Compilation might end up calling functions. Pass in the thread you
/// want the compilation to use. If you pass in an empty ThreadSP it will
/// use the currently selected thread.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report parser errors to.
///
- /// @return
+ /// \return
/// The number of errors.
//------------------------------------------------------------------
virtual unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp,
//------------------------------------------------------------------
/// Insert the default function wrapper and its default argument struct
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to insert the function and its arguments
/// into.
///
- /// @param[in,out] args_addr_ref
+ /// \param[in,out] args_addr_ref
/// The address of the structure to write the arguments into. May
/// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
/// and args_addr_ref is pointed to it.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool InsertFunction(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref,
//------------------------------------------------------------------
/// Insert the default function wrapper (using the JIT)
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to insert the function and its arguments
/// into.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool WriteFunctionWrapper(ExecutionContext &exe_ctx,
//------------------------------------------------------------------
/// Insert the default function argument struct
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to insert the function and its arguments
/// into.
///
- /// @param[in,out] args_addr_ref
+ /// \param[in,out] args_addr_ref
/// The address of the structure to write the arguments into. May
/// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
/// and args_addr_ref is pointed to it.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool WriteFunctionArguments(ExecutionContext &exe_ctx,
/// Insert an argument struct with a non-default function address and non-
/// default argument values
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to insert the function and its arguments
/// into.
///
- /// @param[in,out] args_addr_ref
+ /// \param[in,out] args_addr_ref
/// The address of the structure to write the arguments into. May
/// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
/// and args_addr_ref is pointed at it.
///
- /// @param[in] arg_values
+ /// \param[in] arg_values
/// The values of the function's arguments.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool WriteFunctionArguments(ExecutionContext &exe_ctx,
///
/// This is the full version.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The thread & process in which this function will run.
///
- /// @param[in] args_addr_ptr
+ /// \param[in] args_addr_ptr
/// If nullptr, the function will take care of allocating & deallocating
/// the wrapper
/// args structure. Otherwise, if set to LLDB_INVALID_ADDRESS, a new
/// this should point to an already allocated structure with the values
/// already written.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
///
- /// @param[in] options
+ /// \param[in] options
/// The options for this expression execution.
///
- /// @param[out] results
+ /// \param[out] results
/// The result value will be put here after running the function.
///
- /// @return
+ /// \return
/// Returns one of the ExpressionResults enum indicating function call
/// status.
//------------------------------------------------------------------
/// Get a thread plan to run the function this FunctionCaller was created
/// with.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to insert the function and its arguments
/// into.
///
- /// @param[in] func_addr
+ /// \param[in] func_addr
/// The address of the function in the target process.
///
- /// @param[in] args_addr
+ /// \param[in] args_addr
/// The address of the argument struct.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
///
- /// @param[in] stop_others
+ /// \param[in] stop_others
/// True if other threads should pause during execution.
///
- /// @param[in] unwind_on_error
+ /// \param[in] unwind_on_error
/// True if the thread plan may simply be discarded if an error occurs.
///
- /// @return
+ /// \return
/// A ThreadPlan shared pointer for executing the function.
//------------------------------------------------------------------
lldb::ThreadPlanSP
//------------------------------------------------------------------
/// Get the result of the function from its struct
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to retrieve the result from.
///
- /// @param[in] args_addr
+ /// \param[in] args_addr
/// The address of the argument struct.
///
- /// @param[out] ret_value
+ /// \param[out] ret_value
/// The value returned by the function.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool FetchFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr,
//------------------------------------------------------------------
/// Deallocate the arguments structure
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to insert the function and its arguments
/// into.
///
- /// @param[in] args_addr
+ /// \param[in] args_addr
/// The address of the argument struct.
//------------------------------------------------------------------
void DeallocateFunctionResults(ExecutionContext &exe_ctx,
class Stream;
//----------------------------------------------------------------------
-/// @class DynamicCheckerFunctions IRDynamicChecks.h
+/// \class DynamicCheckerFunctions IRDynamicChecks.h
/// "lldb/Expression/IRDynamicChecks.h" Encapsulates dynamic check functions
/// used by expressions.
///
/// Install the utility functions into a process. This binds the instance
/// of DynamicCheckerFunctions to that process.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// A diagnostic manager to report errors to.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to install the functions into.
///
- /// @return
+ /// \return
/// True on success; false on failure, or if the functions have
/// already been installed.
//------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class IRDynamicChecks IRDynamicChecks.h
+/// \class IRDynamicChecks IRDynamicChecks.h
/// "lldb/Expression/IRDynamicChecks.h" Adds dynamic checks to a user-entered
/// expression to reduce its likelihood of crashing
///
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] checker_functions
+ /// \param[in] checker_functions
/// The checker functions for the target process.
///
- /// @param[in] func_name
+ /// \param[in] func_name
/// The name of the function to prepare for execution in the target.
///
- /// @param[in] decl_map
+ /// \param[in] decl_map
/// The mapping used to look up entities in the target process. In
/// this case, used to find objc_msgSend
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Run this IR transformer on a single module
///
- /// @param[in] M
+ /// \param[in] M
/// The module to run on. This module is searched for the function
/// $__lldb_expr, and that function is passed to the passes one by
/// one.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool runOnModule(llvm::Module &M) override;
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] M
+ /// \param[in] M
/// The module currently being processed.
///
- /// @param[in] BB
+ /// \param[in] BB
/// The basic block currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool FindDataLoads(llvm::Module &M, llvm::BasicBlock &BB);
class Status;
//----------------------------------------------------------------------
-/// @class IRExecutionUnit IRExecutionUnit.h
+/// \class IRExecutionUnit IRExecutionUnit.h
/// "lldb/Expression/IRExecutionUnit.h" Contains the IR and, optionally, JIT-
/// compiled code for a module.
///
void GetStaticInitializers(std::vector<lldb::addr_t> &static_initializers);
//----------------------------------------------------------------------
- /// @class JittedFunction IRExecutionUnit.h
+ /// \class JittedFunction IRExecutionUnit.h
/// "lldb/Expression/IRExecutionUnit.h"
/// Encapsulates a single function that has been generated by the JIT.
///
///
/// Initializes class variabes.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the function.
///
- /// @param[in] local_addr
+ /// \param[in] local_addr
/// The address of the function in LLDB, or LLDB_INVALID_ADDRESS if
/// it is not present in LLDB's memory.
///
- /// @param[in] remote_addr
+ /// \param[in] remote_addr
/// The address of the function in the target, or LLDB_INVALID_ADDRESS
/// if it is not present in the target's memory.
//------------------------------------------------------------------
/// where it was copied to, and return the remote address at the same offset
/// into the copied entity
///
- /// @param[in] local_address
+ /// \param[in] local_address
/// The address in the debugger.
///
- /// @return
+ /// \return
/// The address in the target process.
//------------------------------------------------------------------
lldb::addr_t GetRemoteAddressForLocal(lldb::addr_t local_address);
/// where it was copied to, and return its address range in the target
/// process
///
- /// @param[in] local_address
+ /// \param[in] local_address
/// The address in the debugger.
///
- /// @return
+ /// \return
/// The range of the containing object in the target process.
//------------------------------------------------------------------
typedef std::pair<lldb::addr_t, uintptr_t> AddrRange;
//------------------------------------------------------------------
/// Commit all allocations to the process and record where they were stored.
///
- /// @param[in] process
+ /// \param[in] process
/// The process to allocate memory in.
///
- /// @return
+ /// \return
/// True <=> all allocations were performed successfully.
/// This method will attempt to free allocated memory if the
/// operation fails.
//------------------------------------------------------------------
/// Report all committed allocations to the execution engine.
///
- /// @param[in] engine
+ /// \param[in] engine
/// The execution engine to notify.
//------------------------------------------------------------------
void ReportAllocations(llvm::ExecutionEngine &engine);
//------------------------------------------------------------------
/// Write the contents of all allocations to the process.
///
- /// @param[in] local_address
+ /// \param[in] local_address
/// The process containing the allocations.
///
- /// @return
+ /// \return
/// True <=> all allocations were performed successfully.
//------------------------------------------------------------------
bool WriteData(lldb::ProcessSP &process_sp);
/// Allocate space for executable code, and add it to the m_spaceBlocks
/// map
///
- /// @param[in] Size
+ /// \param[in] Size
/// The size of the area.
///
- /// @param[in] Alignment
+ /// \param[in] Alignment
/// The required alignment of the area.
///
- /// @param[in] SectionID
+ /// \param[in] SectionID
/// A unique identifier for the section.
///
- /// @return
+ /// \return
/// Allocated space.
//------------------------------------------------------------------
uint8_t *allocateCodeSection(uintptr_t Size, unsigned Alignment,
//------------------------------------------------------------------
/// Allocate space for data, and add it to the m_spaceBlocks map
///
- /// @param[in] Size
+ /// \param[in] Size
/// The size of the area.
///
- /// @param[in] Alignment
+ /// \param[in] Alignment
/// The required alignment of the area.
///
- /// @param[in] SectionID
+ /// \param[in] SectionID
/// A unique identifier for the section.
///
- /// @param[in] IsReadOnly
+ /// \param[in] IsReadOnly
/// Flag indicating the section is read-only.
///
- /// @return
+ /// \return
/// Allocated space.
//------------------------------------------------------------------
uint8_t *allocateDataSection(uintptr_t Size, unsigned Alignment,
/// Called when object loading is complete and section page permissions
/// can be applied. Currently unimplemented for LLDB.
///
- /// @param[out] ErrMsg
+ /// \param[out] ErrMsg
/// The error that prevented the page protection from succeeding.
///
- /// @return
+ /// \return
/// True in case of failure, false in case of success.
//------------------------------------------------------------------
bool finalizeMemory(std::string *ErrMsg) override {
static const unsigned eSectionIDInvalid = (unsigned)-1;
//----------------------------------------------------------------------
- /// @class AllocationRecord IRExecutionUnit.h
+ /// \class AllocationRecord IRExecutionUnit.h
/// "lldb/Expression/IRExecutionUnit.h" Encapsulates a single allocation
/// request made by the JIT.
///
}
//----------------------------------------------------------------------
-/// @class IRInterpreter IRInterpreter.h "lldb/Expression/IRInterpreter.h"
+/// \class IRInterpreter IRInterpreter.h "lldb/Expression/IRInterpreter.h"
/// Attempt to interpret the function's code if it does not require
/// running the target.
///
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class IRMemoryMap IRMemoryMap.h "lldb/Expression/IRMemoryMap.h"
+/// \class IRMemoryMap IRMemoryMap.h "lldb/Expression/IRMemoryMap.h"
/// Encapsulates memory that may exist in the process but must
/// also be available in the host process.
///
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class LLVMUserExpression LLVMUserExpression.h
+/// \class LLVMUserExpression LLVMUserExpression.h
/// "lldb/Expression/LLVMUserExpression.h" Encapsulates a one-time expression
/// for use in lldb.
///
/// Get a REPL with an existing target (or, failing that, a debugger to use),
/// and (optional) extra arguments for the compiler.
///
- /// @param[out] error
+ /// \param[out] error
/// If this language is supported but the REPL couldn't be created, this
/// error is populated with the reason.
///
- /// @param[in] language
+ /// \param[in] language
/// The language to create a REPL for.
///
- /// @param[in] debugger
+ /// \param[in] debugger
/// If provided, and target is nullptr, the debugger to use when setting
/// up a top-level REPL.
///
- /// @param[in] target
+ /// \param[in] target
/// If provided, the target to put the REPL inside.
///
- /// @param[in] repl_options
+ /// \param[in] repl_options
/// If provided, additional options for the compiler when parsing REPL
/// expressions.
///
- /// @return
+ /// \return
/// The range of the containing object in the target process.
//------------------------------------------------------------------
static lldb::REPLSP Create(Status &Status, lldb::LanguageType language,
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class UserExpression UserExpression.h "lldb/Expression/UserExpression.h"
+/// \class UserExpression UserExpression.h "lldb/Expression/UserExpression.h"
/// Encapsulates a one-time expression for use in lldb.
///
/// LLDB uses expressions for various purposes, notably to call functions
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] expr
+ /// \param[in] expr
/// The expression to parse.
///
- /// @param[in] expr_prefix
+ /// \param[in] expr_prefix
/// If non-nullptr, a C string containing translation-unit level
/// definitions to be included when the expression is parsed.
///
- /// @param[in] language
+ /// \param[in] language
/// If not eLanguageTypeUnknown, a language to use when parsing
/// the expression. Currently restricted to those languages
/// supported by Clang.
///
- /// @param[in] desired_type
+ /// \param[in] desired_type
/// If not eResultTypeAny, the type to use for the expression
/// result.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Parse the expression
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// A diagnostic manager to report parse errors and warnings to.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when looking up entities that
/// are needed for parsing (locations of functions, types of
/// variables, persistent variables, etc.)
///
- /// @param[in] execution_policy
+ /// \param[in] execution_policy
/// Determines whether interpretation is possible or mandatory.
///
- /// @param[in] keep_result_in_memory
+ /// \param[in] keep_result_in_memory
/// True if the resulting persistent variable should reside in
/// target memory, if applicable.
///
- /// @return
+ /// \return
/// True on success (no errors); false otherwise.
//------------------------------------------------------------------
virtual bool Parse(DiagnosticManager &diagnostic_manager,
/// Attempts to find possible command line completions for the given
/// (possible incomplete) user expression.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when looking up entities that
/// are needed for parsing and completing (locations of functions, types
/// of variables, persistent variables, etc.)
///
- /// @param[out] request
+ /// \param[out] request
/// The completion request to fill out. The completion should be a string
/// that would complete the current token at the cursor position.
/// Note that the string in the list replaces the current token
/// in the command line.
///
- /// @param[in] complete_pos
+ /// \param[in] complete_pos
/// The position of the cursor inside the user expression string.
/// The completion process starts on the token that the cursor is in.
///
- /// @return
+ /// \return
/// True if we added any completion results to the output;
/// false otherwise.
//------------------------------------------------------------------
/// Execute the parsed expression by callinng the derived class's DoExecute
/// method.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// A diagnostic manager to report errors to.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when looking up entities that
/// are needed for parsing (locations of variables, etc.)
///
- /// @param[in] options
+ /// \param[in] options
/// Expression evaluation options.
///
- /// @param[in] shared_ptr_to_me
+ /// \param[in] shared_ptr_to_me
/// This is a shared pointer to this UserExpression. This is
/// needed because Execute can push a thread plan that will hold onto
/// the UserExpression for an unbounded period of time. So you
/// need to give the thread plan a reference to this object that can
/// keep it alive.
///
- /// @param[in] result
+ /// \param[in] result
/// A pointer to direct at the persistent variable in which the
/// expression's result is stored.
///
- /// @return
+ /// \return
/// A Process::Execution results value.
//------------------------------------------------------------------
lldb::ExpressionResults Execute(DiagnosticManager &diagnostic_manager,
//------------------------------------------------------------------
/// Apply the side effects of the function to program state.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// A diagnostic manager to report errors to.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when looking up entities that
/// are needed for parsing (locations of variables, etc.)
///
- /// @param[in] result
+ /// \param[in] result
/// A pointer to direct at the persistent variable in which the
/// expression's result is stored.
///
- /// @param[in] function_stack_pointer
+ /// \param[in] function_stack_pointer
/// A pointer to the base of the function's stack frame. This
/// is used to determine whether the expression result resides in
/// memory that will still be valid, or whether it needs to be
/// treated as homeless for the purpose of future expressions.
///
- /// @return
+ /// \return
/// A Process::Execution results value.
//------------------------------------------------------------------
virtual bool FinalizeJITExecution(
/// Evaluate one expression in the scratch context of the target passed in
/// the exe_ctx and return its result.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when evaluating the expression.
///
- /// @param[in] options
+ /// \param[in] options
/// Expression evaluation options. N.B. The language in the
/// evaluation options will be used to determine the language used for
/// expression evaluation.
///
- /// @param[in] expr_cstr
+ /// \param[in] expr_cstr
/// A C string containing the expression to be evaluated.
///
- /// @param[in] expr_prefix
+ /// \param[in] expr_prefix
/// If non-nullptr, a C string containing translation-unit level
/// definitions to be included when the expression is parsed.
///
- /// @param[in,out] result_valobj_sp
+ /// \param[in,out] result_valobj_sp
/// If execution is successful, the result valobj is placed here.
///
- /// @param[out] error
+ /// \param[out] error
/// Filled in with an error in case the expression evaluation
/// fails to parse, run, or evaluated.
///
- /// @param[out] fixed_expression
+ /// \param[out] fixed_expression
/// If non-nullptr, the fixed expression is copied into the provided
/// string.
///
- /// @param[out] jit_module_sp_ptr
+ /// \param[out] jit_module_sp_ptr
/// If non-nullptr, used to persist the generated IR module.
///
- /// @param[in] ctx_obj
+ /// \param[in] ctx_obj
/// If specified, then the expression will be evaluated in the context of
/// this object. It means that the context object's address will be
/// treated as `this` for the expression (the expression will be
/// Currently there is a limitation: the context object must be located
/// in the debuggee process' memory (and have the load address).
///
- /// @result
+ /// \result
/// A Process::ExpressionResults value. eExpressionCompleted for
/// success.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class UtilityFunction UtilityFunction.h
+/// \class UtilityFunction UtilityFunction.h
/// "lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that
/// provides a function that is callable
///
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] text
+ /// \param[in] text
/// The text of the function. Must be a full translation unit.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the function, as used in the text.
//------------------------------------------------------------------
UtilityFunction(ExecutionContextScope &exe_scope, const char *text,
//------------------------------------------------------------------
/// Install the utility function into a process
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// A diagnostic manager to print parse errors and warnings to.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to install the utility function to.
///
- /// @return
+ /// \return
/// True on success (no errors); false otherwise.
//------------------------------------------------------------------
virtual bool Install(DiagnosticManager &diagnostic_manager,
/// Especially useful if the function dereferences nullptr to indicate a
/// failed assert.
///
- /// @param[in] pc
+ /// \param[in] pc
/// The program counter to check.
///
- /// @return
+ /// \return
/// True if the program counter falls within the function's bounds;
/// false if not (or the function is not JIT compiled)
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class File File.h "lldb/Host/File.h"
+/// \class File File.h "lldb/Host/File.h"
/// A file class.
///
/// A file class that divides abstracts the LLDB core from host file
/// This allows code to check a File object to see if it contains anything
/// valid using code such as:
///
- /// @code
+ /// \code
/// File file(...);
/// if (file)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// A pointer to this object if either the directory or filename
/// is valid, nullptr otherwise.
//------------------------------------------------------------------
/// This allows code to check a File object to see if it is invalid using
/// code such as:
///
- /// @code
+ /// \code
/// File file(...);
/// if (!file)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// Returns \b true if the object has an empty directory and
/// filename, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the file spec for this file.
///
- /// @return
+ /// \return
/// A reference to the file specification object.
//------------------------------------------------------------------
Status GetFileSpec(FileSpec &file_spec) const;
/// that takes an "off_t &offset" to ensure correct operation in multi-
/// threaded environments.
///
- /// @param[in] buf
+ /// \param[in] buf
/// A buffer where to put the bytes that are read.
///
- /// @param[in,out] num_bytes
+ /// \param[in,out] num_bytes
/// The number of bytes to read form the current file position
/// which gets modified with the number of bytes that were read.
///
- /// @return
+ /// \return
/// An error object that indicates success or the reason for
/// failure.
//------------------------------------------------------------------
/// that takes an "off_t &offset" to ensure correct operation in multi-
/// threaded environments.
///
- /// @param[in] buf
+ /// \param[in] buf
/// A buffer where to put the bytes that are read.
///
- /// @param[in,out] num_bytes
+ /// \param[in,out] num_bytes
/// The number of bytes to write to the current file position
/// which gets modified with the number of bytes that were
/// written.
///
- /// @return
+ /// \return
/// An error object that indicates success or the reason for
/// failure.
//------------------------------------------------------------------
/// NOTE: This function is NOT thread safe, other threads that
/// access this object might also change the current file position. For
/// thread safe reads and writes see the following functions: @see
- /// File::Read (void *, size_t, off_t &) @see File::Write (const void *,
+ /// File::Read (void *, size_t, off_t &) \see File::Write (const void *,
/// size_t, off_t &)
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset to seek to within the file relative to the
/// beginning of the file.
///
- /// @param[in] error_ptr
+ /// \param[in] error_ptr
/// A pointer to a lldb_private::Status object that will be
/// filled in if non-nullptr.
///
- /// @return
+ /// \return
/// The resulting seek offset, or -1 on error.
//------------------------------------------------------------------
off_t SeekFromStart(off_t offset, Status *error_ptr = nullptr);
/// NOTE: This function is NOT thread safe, other threads that
/// access this object might also change the current file position. For
/// thread safe reads and writes see the following functions: @see
- /// File::Read (void *, size_t, off_t &) @see File::Write (const void *,
+ /// File::Read (void *, size_t, off_t &) \see File::Write (const void *,
/// size_t, off_t &)
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset to seek to within the file relative to the
/// current file position.
///
- /// @param[in] error_ptr
+ /// \param[in] error_ptr
/// A pointer to a lldb_private::Status object that will be
/// filled in if non-nullptr.
///
- /// @return
+ /// \return
/// The resulting seek offset, or -1 on error.
//------------------------------------------------------------------
off_t SeekFromCurrent(off_t offset, Status *error_ptr = nullptr);
/// NOTE: This function is NOT thread safe, other threads that
/// access this object might also change the current file position. For
/// thread safe reads and writes see the following functions: @see
- /// File::Read (void *, size_t, off_t &) @see File::Write (const void *,
+ /// File::Read (void *, size_t, off_t &) \see File::Write (const void *,
/// size_t, off_t &)
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// The offset to seek to within the file relative to the
/// end of the file which gets filled in with the resulting
/// absolute file offset.
///
- /// @param[in] error_ptr
+ /// \param[in] error_ptr
/// A pointer to a lldb_private::Status object that will be
/// filled in if non-nullptr.
///
- /// @return
+ /// \return
/// The resulting seek offset, or -1 on error.
//------------------------------------------------------------------
off_t SeekFromEnd(off_t offset, Status *error_ptr = nullptr);
/// own file position markers and reads on other threads won't mess up the
/// current read.
///
- /// @param[in] dst
+ /// \param[in] dst
/// A buffer where to put the bytes that are read.
///
- /// @param[in,out] num_bytes
+ /// \param[in,out] num_bytes
/// The number of bytes to read form the current file position
/// which gets modified with the number of bytes that were read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// The offset within the file from which to read \a num_bytes
/// bytes. This offset gets incremented by the number of bytes
/// that were read.
///
- /// @return
+ /// \return
/// An error object that indicates success or the reason for
/// failure.
//------------------------------------------------------------------
/// own file position markers and reads on other threads won't mess up the
/// current read.
///
- /// @param[in,out] num_bytes
+ /// \param[in,out] num_bytes
/// The number of bytes to read form the current file position
/// which gets modified with the number of bytes that were read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// The offset within the file from which to read \a num_bytes
/// bytes. This offset gets incremented by the number of bytes
/// that were read.
///
- /// @param[in] null_terminate
+ /// \param[in] null_terminate
/// Ensure that the data that is read is terminated with a NULL
/// character so that the data can be used as a C string.
///
- /// @param[out] data_buffer_sp
+ /// \param[out] data_buffer_sp
/// A data buffer to create and fill in that will contain any
/// data that is read from the file. This buffer will be reset
/// if an error occurs.
///
- /// @return
+ /// \return
/// An error object that indicates success or the reason for
/// failure.
//------------------------------------------------------------------
/// own locking externally to avoid multiple people writing to the file at
/// the same time.
///
- /// @param[in] src
+ /// \param[in] src
/// A buffer containing the bytes to write.
///
- /// @param[in,out] num_bytes
+ /// \param[in,out] num_bytes
/// The number of bytes to write to the file at offset \a offset.
/// \a num_bytes gets modified with the number of bytes that
/// were read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// The offset within the file at which to write \a num_bytes
/// bytes. This offset gets incremented by the number of bytes
/// that were written.
///
- /// @return
+ /// \return
/// An error object that indicates success or the reason for
/// failure.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Flush the current stream
///
- /// @return
+ /// \return
/// An error object that indicates success or the reason for
/// failure.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Sync to disk.
///
- /// @return
+ /// \return
/// An error object that indicates success or the reason for
/// failure.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the permissions for a this file.
///
- /// @return
+ /// \return
/// Bits logical OR'ed together from the permission bits defined
/// in lldb_private::File::Permissions.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return true if this file is interactive.
///
- /// @return
+ /// \return
/// True if this file is a terminal (tty or pty), false
/// otherwise.
//------------------------------------------------------------------
/// if the terminal has a width and height so we can do cursor movement and
/// other terminal manipulations by sending escape sequences.
///
- /// @return
+ /// \return
/// True if this file is a terminal (tty, not a pty) that has
/// a non-zero width and height, false otherwise.
//------------------------------------------------------------------
///
/// Print some formatted output to the stream.
///
- /// @param[in] format
+ /// \param[in] format
/// A printf style format string.
///
- /// @param[in] ...
+ /// \param[in] ...
/// Variable arguments that are needed for the printf style
/// format string \a format.
//------------------------------------------------------------------
bool should_close_fd = true);
/// Get a directory iterator.
- /// @{
+ /// \{
llvm::vfs::directory_iterator DirBegin(const FileSpec &file_spec,
std::error_code &ec);
llvm::vfs::directory_iterator DirBegin(const llvm::Twine &dir,
std::error_code &ec);
- /// @}
+ /// \}
/// Returns the Status object for the given file.
- /// @{
+ /// \{
llvm::ErrorOr<llvm::vfs::Status> GetStatus(const FileSpec &file_spec) const;
llvm::ErrorOr<llvm::vfs::Status> GetStatus(const llvm::Twine &path) const;
- /// @}
+ /// \}
/// Returns the modification time of the given file.
- /// @{
+ /// \{
llvm::sys::TimePoint<> GetModificationTime(const FileSpec &file_spec) const;
llvm::sys::TimePoint<> GetModificationTime(const llvm::Twine &path) const;
- /// @}
+ /// \}
/// Returns the on-disk size of the given file in bytes.
- /// @{
+ /// \{
uint64_t GetByteSize(const FileSpec &file_spec) const;
uint64_t GetByteSize(const llvm::Twine &path) const;
- /// @}
+ /// \}
/// Return the current permissions of the given file.
///
/// Returns a bitmask for the current permissions of the file (zero or more
/// of the permission bits defined in File::Permissions).
- /// @{
+ /// \{
uint32_t GetPermissions(const FileSpec &file_spec) const;
uint32_t GetPermissions(const llvm::Twine &path) const;
uint32_t GetPermissions(const FileSpec &file_spec, std::error_code &ec) const;
uint32_t GetPermissions(const llvm::Twine &path, std::error_code &ec) const;
- /// @}
+ /// \}
/// Returns whether the given file exists.
- /// @{
+ /// \{
bool Exists(const FileSpec &file_spec) const;
bool Exists(const llvm::Twine &path) const;
- /// @}
+ /// \}
/// Returns whether the given file is readable.
- /// @{
+ /// \{
bool Readable(const FileSpec &file_spec) const;
bool Readable(const llvm::Twine &path) const;
- /// @}
+ /// \}
/// Returns whether the given path is a directory.
- /// @{
+ /// \{
bool IsDirectory(const FileSpec &file_spec) const;
bool IsDirectory(const llvm::Twine &path) const;
- /// @}
+ /// \}
/// Returns whether the given path is local to the file system.
- /// @{
+ /// \{
bool IsLocal(const FileSpec &file_spec) const;
bool IsLocal(const llvm::Twine &path) const;
- /// @}
+ /// \}
/// Make the given file path absolute.
- /// @{
+ /// \{
std::error_code MakeAbsolute(llvm::SmallVectorImpl<char> &path) const;
std::error_code MakeAbsolute(FileSpec &file_spec) const;
- /// @}
+ /// \}
/// Resolve path to make it canonical.
- /// @{
+ /// \{
void Resolve(llvm::SmallVectorImpl<char> &path);
void Resolve(FileSpec &file_spec);
- /// @}
+ /// \}
//// Create memory buffer from path.
- /// @{
+ /// \{
std::shared_ptr<DataBufferLLVM> CreateDataBuffer(const llvm::Twine &path,
uint64_t size = 0,
uint64_t offset = 0);
std::shared_ptr<DataBufferLLVM> CreateDataBuffer(const FileSpec &file_spec,
uint64_t size = 0,
uint64_t offset = 0);
- /// @}
+ /// \}
/// Call into the Host to see if it can help find the file.
bool ResolveExecutableLocation(FileSpec &file_spec);
inline bool operator!=(WaitStatus a, WaitStatus b) { return !(a == b); }
//----------------------------------------------------------------------
-/// @class Host Host.h "lldb/Host/Host.h"
+/// \class Host Host.h "lldb/Host/Host.h"
/// A class that provides host computer information.
///
/// Host is a class that answers information about the host operating system.
/// If the child process exits, the monitoring will automatically stop after
/// the callback returned regardless of the callback return value.
///
- /// @param[in] callback
+ /// \param[in] callback
/// A function callback to call when a child receives a signal
/// (if \a monitor_signals is true) or a child exits.
///
- /// @param[in] pid
+ /// \param[in] pid
/// The process ID of a child process to monitor, -1 for all
/// processes.
///
- /// @param[in] monitor_signals
+ /// \param[in] monitor_signals
/// If \b true the callback will get called when the child
/// process gets a signal. If \b false, the callback will only
/// get called if the child process exits.
///
- /// @return
+ /// \return
/// A thread handle that can be used to cancel the thread that
/// was spawned to monitor \a pid.
///
- /// @see static void Host::StopMonitoringChildProcess (uint32_t)
+ /// \see static void Host::StopMonitoringChildProcess (uint32_t)
//------------------------------------------------------------------
static HostThread
StartMonitoringChildProcess(const MonitorChildProcessCallback &callback,
//------------------------------------------------------------------
/// Get the process ID for the calling process.
///
- /// @return
+ /// \return
/// The process ID for the current process.
//------------------------------------------------------------------
static lldb::pid_t GetCurrentProcessID();
/// Get the thread token (the one returned by ThreadCreate when the thread
/// was created) for the calling thread in the current process.
///
- /// @return
+ /// \return
/// The thread token for the calling thread in the current process.
//------------------------------------------------------------------
static lldb::thread_t GetCurrentThread();
/// code is running in for loading resources that are relative to your
/// binary.
///
- /// @param[in] host_addr
+ /// \param[in] host_addr
/// The pointer to some code in the current process.
///
- /// @return
+ /// \return
/// \b A file spec with the module that contains \a host_addr,
/// which may be invalid if \a host_addr doesn't fall into
/// any valid module address range.
/// the bundle directory from the path itself, this function will change a
/// path to a file within a bundle to the bundle directory itself.
///
- /// @param[in] file
+ /// \param[in] file
/// A file spec that might point to a file in a bundle.
///
- /// @param[out] bundle_directory
+ /// \param[out] bundle_directory
/// An object will be filled in with the bundle directory for
/// the bundle when \b true is returned. Otherwise \a file is
/// left untouched and \b false is returned.
///
- /// @return
+ /// \return
/// \b true if \a file was resolved in \a bundle_directory,
/// \b false otherwise.
//------------------------------------------------------------------
/// represents an executable bundle (like the MacOSX app bundles), then
/// locate the executable within the containing bundle.
///
- /// @param[in,out] file
+ /// \param[in,out] file
/// A file spec that currently points to the bundle that will
/// be filled in with the executable path within the bundle
/// if \b true is returned. Otherwise \a file is left untouched.
///
- /// @return
+ /// \return
/// \b true if \a file was resolved, \b false if this function
/// was not able to resolve the path.
//------------------------------------------------------------------
#define lldb_Host_HostInfo_h_
//----------------------------------------------------------------------
-/// @class HostInfo HostInfo.h "lldb/Host/HostInfo.h"
+/// \class HostInfo HostInfo.h "lldb/Host/HostInfo.h"
/// A class that provides host computer information.
///
/// HostInfo is a class that answers information about the host operating
//------------------------------------------------------------------
/// Gets the host target triple as a const string.
///
- /// @return
+ /// \return
/// A const string object containing the host target triple.
//------------------------------------------------------------------
static llvm::StringRef GetTargetTriple();
//------------------------------------------------------------------
/// Gets the host architecture.
///
- /// @return
+ /// \return
/// A const architecture object that represents the host
/// architecture.
//------------------------------------------------------------------
#include "lldb/lldb-types.h"
//----------------------------------------------------------------------
-/// @class HostInfo HostInfo.h "lldb/Host/HostProcess.h"
+/// \class HostInfo HostInfo.h "lldb/Host/HostProcess.h"
/// A class that represents a running process on the host machine.
///
/// HostProcess allows querying and manipulation of processes running on the
class HostNativeThreadBase;
//----------------------------------------------------------------------
-/// @class HostInfo HostInfo.h "lldb/Host/HostThread.h"
+/// \class HostInfo HostInfo.h "lldb/Host/HostThread.h"
/// A class that represents a thread running inside of a process on the
/// local machine.
///
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ProcessRunLock ProcessRunLock.h "lldb/Host/ProcessRunLock.h"
+/// \class ProcessRunLock ProcessRunLock.h "lldb/Host/ProcessRunLock.h"
/// A class used to prevent the process from starting while other
/// threads are accessing its data, and prevent access to its data while it is
/// running.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class PseudoTerminal PseudoTerminal.h "lldb/Host/PseudoTerminal.h"
+/// \class PseudoTerminal PseudoTerminal.h "lldb/Host/PseudoTerminal.h"
/// A pseudo terminal helper class.
///
/// The pseudo terminal class abstracts the use of pseudo terminals on the
/// PseudoTerminal::ReleaseMasterFileDescriptor() @li
/// PseudoTerminal::ReleaseSaveFileDescriptor()
///
- /// @param[out] error
+ /// \param[out] error
/// An pointer to an error that can describe any errors that
/// occur. This can be NULL if no error status is desired.
///
- /// @return
- /// @li \b Parent process: a child process ID that is greater
+ /// \return
+ /// \li \b Parent process: a child process ID that is greater
/// than zero, or -1 if the fork fails.
- /// @li \b Child process: zero.
+ /// \li \b Child process: zero.
//------------------------------------------------------------------
lldb::pid_t Fork(char *error_str, size_t error_len);
/// PseudoTerminal::ReleaseMasterFileDescriptor() if this object should
/// release ownership of the slave file descriptor.
///
- /// @return
+ /// \return
/// The master file descriptor, or PseudoTerminal::invalid_fd
/// if the master file descriptor is not currently valid.
///
- /// @see PseudoTerminal::ReleaseMasterFileDescriptor()
+ /// \see PseudoTerminal::ReleaseMasterFileDescriptor()
//------------------------------------------------------------------
int GetMasterFileDescriptor() const;
/// PseudoTerminal::ReleaseSlaveFileDescriptor() if this object should
/// release ownership of the slave file descriptor.
///
- /// @return
+ /// \return
/// The slave file descriptor, or PseudoTerminal::invalid_fd
/// if the slave file descriptor is not currently valid.
///
- /// @see PseudoTerminal::ReleaseSlaveFileDescriptor()
+ /// \see PseudoTerminal::ReleaseSlaveFileDescriptor()
//------------------------------------------------------------------
int GetSlaveFileDescriptor() const;
/// A master pseudo terminal should already be valid prior to
/// calling this function.
///
- /// @param[out] error
+ /// \param[out] error
/// An pointer to an error that can describe any errors that
/// occur. This can be NULL if no error status is desired.
///
- /// @return
+ /// \return
/// The name of the slave pseudo terminal as a NULL terminated
/// C. This string that comes from static memory, so a copy of
/// the string should be made as subsequent calls can change
/// a valid master pseudo terminal opened or if the call to
/// \c ptsname() fails.
///
- /// @see PseudoTerminal::OpenFirstAvailableMaster()
+ /// \see PseudoTerminal::OpenFirstAvailableMaster()
//------------------------------------------------------------------
const char *GetSlaveName(char *error_str, size_t error_len) const;
/// If this object still has a valid master file descriptor when its
/// destructor is called, it will close it.
///
- /// @param[in] oflag
+ /// \param[in] oflag
/// Flags to use when calling \c posix_openpt(\a oflag).
/// A value of "O_RDWR|O_NOCTTY" is suggested.
///
- /// @param[out] error
+ /// \param[out] error
/// An pointer to an error that can describe any errors that
/// occur. This can be NULL if no error status is desired.
///
- /// @return
- /// @li \b true when the master files descriptor is
+ /// \return
+ /// \li \b true when the master files descriptor is
/// successfully opened.
- /// @li \b false if anything goes wrong.
+ /// \li \b false if anything goes wrong.
///
- /// @see PseudoTerminal::GetMasterFileDescriptor() @see
+ /// \see PseudoTerminal::GetMasterFileDescriptor() @see
/// PseudoTerminal::ReleaseMasterFileDescriptor()
//------------------------------------------------------------------
bool OpenFirstAvailableMaster(int oflag, char *error_str, size_t error_len);
/// If this object still has a valid slave file descriptor when its
/// destructor is called, it will close it.
///
- /// @param[in] oflag
+ /// \param[in] oflag
/// Flags to use when calling \c open(\a oflag).
///
- /// @param[out] error
+ /// \param[out] error
/// An pointer to an error that can describe any errors that
/// occur. This can be NULL if no error status is desired.
///
- /// @return
- /// @li \b true when the master files descriptor is
+ /// \return
+ /// \li \b true when the master files descriptor is
/// successfully opened.
- /// @li \b false if anything goes wrong.
+ /// \li \b false if anything goes wrong.
///
- /// @see PseudoTerminal::OpenFirstAvailableMaster() @see
+ /// \see PseudoTerminal::OpenFirstAvailableMaster() @see
/// PseudoTerminal::GetSlaveFileDescriptor() @see
/// PseudoTerminal::ReleaseSlaveFileDescriptor()
//------------------------------------------------------------------
/// descriptor if the ownership isn't released using this call and the
/// master file descriptor has been opened.
///
- /// @return
+ /// \return
/// The master file descriptor, or PseudoTerminal::invalid_fd
/// if the mast file descriptor is not currently valid.
//------------------------------------------------------------------
/// descriptor if the ownership isn't released using this call and the slave
/// file descriptor has been opened.
///
- /// @return
+ /// \return
/// The slave file descriptor, or PseudoTerminal::invalid_fd
/// if the slave file descriptor is not currently valid.
//------------------------------------------------------------------
namespace StringConvert {
//----------------------------------------------------------------------
-/// @namespace StringConvert StringConvert.h "lldb/Host/StringConvert.h"
+/// \namespace StringConvert StringConvert.h "lldb/Host/StringConvert.h"
/// Utility classes for converting strings into Integers
//----------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class State Terminal.h "lldb/Host/Terminal.h"
+/// \class State Terminal.h "lldb/Host/Terminal.h"
/// A terminal state saving/restoring class.
///
/// This class can be used to remember the terminal state for a file
/// "save_process_group" is true, attempt to save the process group info for
/// the TTY.
///
- /// @param[in] fd
+ /// \param[in] fd
/// The file descriptor to save the state of.
///
- /// @param[in] save_process_group
+ /// \param[in] save_process_group
/// If \b true, save the process group settings, else do not
/// save the process group settings for a TTY.
///
- /// @return
+ /// \return
/// Returns \b true if \a fd describes a TTY and if the state
/// was able to be saved, \b false otherwise.
//------------------------------------------------------------------
/// Restore the state of the TTY using the cached values from a previous
/// call to TerminalState::Save(int,bool).
///
- /// @return
+ /// \return
/// Returns \b true if the TTY state was successfully restored,
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Test for valid cached TTY state information.
///
- /// @return
+ /// \return
/// Returns \b true if this object has valid saved TTY state
/// settings that can be used to restore a previous state,
/// \b false otherwise.
//------------------------------------------------------------------
/// Test if tflags is valid.
///
- /// @return
+ /// \return
/// Returns \b true if \a m_tflags is valid and can be restored,
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Test if ttystate is valid.
///
- /// @return
+ /// \return
/// Returns \b true if \a m_ttystate is valid and can be
/// restored, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Test if the process group information is valid.
///
- /// @return
+ /// \return
/// Returns \b true if \a m_process_group is valid and can be
/// restored, \b false otherwise.
//------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class TerminalStateSwitcher Terminal.h "lldb/Host/Terminal.h"
+/// \class TerminalStateSwitcher Terminal.h "lldb/Host/Terminal.h"
/// A TTY state switching class.
///
/// This class can be used to remember 2 TTY states for a given file
//------------------------------------------------------------------
/// Get the number of possible states to save.
///
- /// @return
+ /// \return
/// The number of states that this TTY switcher object contains.
//------------------------------------------------------------------
uint32_t GetNumberOfStates() const;
//------------------------------------------------------------------
/// Restore the TTY state for state at index \a idx.
///
- /// @return
+ /// \return
/// Returns \b true if the TTY state was successfully restored,
/// \b false otherwise.
//------------------------------------------------------------------
/// state is saved for the file descriptor \a fd and the process group
/// information will also be saved if requested by \a save_process_group.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The index into the state array where the state should be
/// saved.
///
- /// @param[in] fd
+ /// \param[in] fd
/// The file descriptor for which to save the settings.
///
- /// @param[in] save_process_group
+ /// \param[in] save_process_group
/// If \b true, save the process group information for the TTY.
///
- /// @return
+ /// \return
/// Returns \b true if the save was successful, \b false
/// otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Sends a process a UNIX signal \a signal.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status Signal(int signo) = 0;
/// a SIGSTOP to the process via the NativeProcessProtocol::Signal()
/// operation.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status Interrupt();
/// Note: it is required that the lifetime of the
/// native_delegate outlive the NativeProcessProtocol.
///
- /// @param[in] native_delegate
+ /// \param[in] native_delegate
/// A NativeDelegate impl to be called when certain events
/// happen within the NativeProcessProtocol or related threads.
///
- /// @return
+ /// \return
/// true if the delegate was registered successfully;
/// false if the delegate was already registered.
///
- /// @see NativeProcessProtocol::NativeDelegate.
+ /// \see NativeProcessProtocol::NativeDelegate.
//------------------------------------------------------------------
bool RegisterNativeDelegate(NativeDelegate &native_delegate);
//------------------------------------------------------------------
/// Unregister a native delegate previously registered.
///
- /// @param[in] native_delegate
+ /// \param[in] native_delegate
/// A NativeDelegate impl previously registered with this process.
///
- /// @return Returns \b true if the NativeDelegate was
+ /// \return Returns \b true if the NativeDelegate was
/// successfully removed from the process, \b false otherwise.
///
- /// @see NativeProcessProtocol::NativeDelegate
+ /// \see NativeProcessProtocol::NativeDelegate
//------------------------------------------------------------------
bool UnregisterNativeDelegate(NativeDelegate &native_delegate);
//------------------------------------------------------------------
/// Launch a process for debugging.
///
- /// @param[in] launch_info
+ /// \param[in] launch_info
/// Information required to launch the process.
///
- /// @param[in] native_delegate
+ /// \param[in] native_delegate
/// The delegate that will receive messages regarding the
/// inferior. Must outlive the NativeProcessProtocol
/// instance.
///
- /// @param[in] mainloop
+ /// \param[in] mainloop
/// The mainloop instance with which the process can register
/// callbacks. Must outlive the NativeProcessProtocol
/// instance.
///
- /// @return
+ /// \return
/// A NativeProcessProtocol shared pointer if the operation succeeded or
/// an error object if it failed.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Attach to an existing process.
///
- /// @param[in] pid
+ /// \param[in] pid
/// pid of the process locatable
///
- /// @param[in] native_delegate
+ /// \param[in] native_delegate
/// The delegate that will receive messages regarding the
/// inferior. Must outlive the NativeProcessProtocol
/// instance.
///
- /// @param[in] mainloop
+ /// \param[in] mainloop
/// The mainloop instance with which the process can register
/// callbacks. Must outlive the NativeProcessProtocol
/// instance.
///
- /// @return
+ /// \return
/// A NativeProcessProtocol shared pointer if the operation succeeded or
/// an error object if it failed.
//------------------------------------------------------------------
/// StartTracing API for starting a tracing instance with the
/// TraceOptions on a specific thread or process.
///
- /// @param[in] config
+ /// \param[in] config
/// The configuration to use when starting tracing.
///
- /// @param[out] error
+ /// \param[out] error
/// Status indicates what went wrong.
///
- /// @return
+ /// \return
/// The API returns a user_id which can be used to get trace
/// data, trace configuration or stopping the trace instance.
/// The user_id is a key to identify and operate with a tracing
//------------------------------------------------------------------
/// StopTracing API as the name suggests stops a tracing instance.
///
- /// @param[in] traceid
+ /// \param[in] traceid
/// The user id of the trace intended to be stopped. Now a
/// user_id may map to multiple threads in which case this API
/// could be used to stop the tracing for a specific thread by
/// supplying its thread id.
///
- /// @param[in] thread
+ /// \param[in] thread
/// Thread is needed when the complete process is being traced
/// and the user wishes to stop tracing on a particular thread.
///
- /// @return
+ /// \return
/// Status indicating what went wrong.
//------------------------------------------------------------------
virtual Status StopTrace(lldb::user_id_t traceid,
/// This API provides the trace data collected in the form of raw
/// data.
///
- /// @param[in] traceid thread
+ /// \param[in] traceid thread
/// The traceid and thread provide the context for the trace
/// instance.
///
- /// @param[in] buffer
+ /// \param[in] buffer
/// The buffer provides the destination buffer where the trace
/// data would be read to. The buffer should be truncated to the
/// filled length by this function.
///
- /// @param[in] offset
+ /// \param[in] offset
/// There is possibility to read partially the trace data from
/// a specified offset where in such cases the buffer provided
/// may be smaller than the internal trace collection container.
///
- /// @return
+ /// \return
/// The size of the data actually read.
//------------------------------------------------------------------
virtual Status GetData(lldb::user_id_t traceid, lldb::tid_t thread,
//------------------------------------------------------------------
/// API to query the TraceOptions for a given user id
///
- /// @param[in] traceid
+ /// \param[in] traceid
/// The user id of the tracing instance.
///
- /// @param[in] config
+ /// \param[in] config
/// The thread id of the tracing instance, in case configuration
/// for a specific thread is needed should be specified in the
/// config.
///
- /// @param[out] error
+ /// \param[out] error
/// Status indicates what went wrong.
///
- /// @param[out] config
+ /// \param[out] config
/// The actual configuration being used for tracing.
//------------------------------------------------------------------
virtual Status GetTraceConfig(lldb::user_id_t traceid, TraceOptions &config) {
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class PipePosix PipePosix.h "lldb/Host/posix/PipePosix.h"
+/// \class PipePosix PipePosix.h "lldb/Host/posix/PipePosix.h"
/// A posix-based implementation of Pipe, a class that abtracts
/// unix style pipes.
///
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Pipe PipeWindows.h "lldb/Host/windows/PipeWindows.h"
+/// \class Pipe PipeWindows.h "lldb/Host/windows/PipeWindows.h"
/// A windows-based implementation of Pipe, a class that abtracts
/// unix style pipes.
///
///
/// The meanings of the options in this object are:
///
- /// @param[in] stop_on_continue
+ /// \param[in] stop_on_continue
/// If \b true, execution will end on the first command that causes the
/// process in the execution context to continue. If \b false, we won't
/// check the execution status.
- /// @param[in] stop_on_error
+ /// \param[in] stop_on_error
/// If \b true, execution will end on the first command that causes an
/// error.
- /// @param[in] stop_on_crash
+ /// \param[in] stop_on_crash
/// If \b true, when a command causes the target to run, and the end of the
/// run is a signal or exception, stop executing the commands.
- /// @param[in] echo_commands
+ /// \param[in] echo_commands
/// If \b true, echo the command before executing it. If \b false, execute
/// silently.
- /// @param[in] echo_comments
+ /// \param[in] echo_comments
/// If \b true, echo command even if it is a pure comment line. If
/// \b false, print no ouput in this case. This setting has an effect only
/// if \param echo_commands is \b true.
- /// @param[in] print_results
+ /// \param[in] print_results
/// If \b true print the results of the command after executing it. If
/// \b false, execute silently.
- /// @param[in] add_to_history
+ /// \param[in] add_to_history
/// If \b true add the commands to the command history. If \b false, don't
/// add them.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Execute a list of commands in sequence.
///
- /// @param[in] commands
+ /// \param[in] commands
/// The list of commands to execute.
- /// @param[in,out] context
+ /// \param[in,out] context
/// The execution context in which to run the commands. Can be nullptr in
/// which case the default
/// context will be used.
- /// @param[in] options
+ /// \param[in] options
/// This object holds the options used to control when to stop, whether to
/// execute commands,
/// etc.
- /// @param[out] result
+ /// \param[out] result
/// This is marked as succeeding with no output if all commands execute
/// safely,
/// and failed with some explanation if we aborted executing the commands
//------------------------------------------------------------------
/// Execute a list of commands from a file.
///
- /// @param[in] file
+ /// \param[in] file
/// The file from which to read in commands.
- /// @param[in,out] context
+ /// \param[in,out] context
/// The execution context in which to run the commands. Can be nullptr in
/// which case the default
/// context will be used.
- /// @param[in] options
+ /// \param[in] options
/// This object holds the options used to control when to stop, whether to
/// execute commands,
/// etc.
- /// @param[out] result
+ /// \param[out] result
/// This is marked as succeeding with no output if all commands execute
/// safely,
/// and failed with some explanation if we aborted executing the commands
//------------------------------------------------------------------
/// Sets the exit code for the quit command.
- /// @param[in] exit_code
+ /// \param[in] exit_code
/// The exit code that the driver should return on exit.
- /// @return True if the exit code was successfully set; false if the
+ /// \return True if the exit code was successfully set; false if the
/// interpreter doesn't allow custom exit codes.
- /// @see AllowExitCodeOnQuit
+ /// \see AllowExitCodeOnQuit
//------------------------------------------------------------------
LLVM_NODISCARD bool SetQuitExitCode(int exit_code);
//------------------------------------------------------------------
/// Returns the exit code that the user has specified when running the
/// 'quit' command.
- /// @param[out] exited
+ /// \param[out] exited
/// Set to true if the user has called quit with a custom exit code.
//------------------------------------------------------------------
int GetQuitExitCode(bool &exited) const;
/// option. Don't override this method, override HandleArgumentCompletion
/// instead unless you have special reasons.
///
- /// @param[in/out] request
+ /// \param[in/out] request
/// The completion request that needs to be answered.
///
/// FIXME: This is the wrong return value, since we also need to make a
/// distinction between
/// total number of matches, and the window the user wants returned.
///
- /// @return
+ /// \return
/// \btrue if we were in an option, \bfalse otherwise.
//------------------------------------------------------------------
virtual int HandleCompletion(CompletionRequest &request);
/// We've constructed the map of options and their arguments as well if that
/// is helpful for the completion.
///
- /// @param[in/out] request
+ /// \param[in/out] request
/// The completion request that needs to be answered.
///
/// FIXME: This is the wrong return value, since we also need to make a
/// distinction between
/// total number of matches, and the window the user wants returned.
///
- /// @return
+ /// \return
/// The number of completions.
//------------------------------------------------------------------
virtual int
//------------------------------------------------------------------
/// The flags accessor.
///
- /// @return
+ /// \return
/// A reference to the Flags member variable.
//------------------------------------------------------------------
Flags &GetFlags() { return m_flags; }
//------------------------------------------------------------------
/// The flags const accessor.
///
- /// @return
+ /// \return
/// A const reference to the Flags member variable.
//------------------------------------------------------------------
const Flags &GetFlags() const { return m_flags; }
//------------------------------------------------------------------
/// Get the command that appropriate for a "repeat" of the current command.
///
- /// @param[in] current_command_line
+ /// \param[in] current_command_line
/// The complete current command line.
///
- /// @return
+ /// \return
/// nullptr if there is no special repeat command - it will use the
/// current command line.
/// Otherwise a pointer to the command to be repeated.
/// Check the command to make sure anything required by this
/// command is available.
///
- /// @param[out] result
+ /// \param[out] result
/// A command result object, if it is not okay to run the command
/// this will be filled in with a suitable error.
///
- /// @return
+ /// \return
/// \b true if it is okay to run this command, \b false otherwise.
//------------------------------------------------------------------
bool CheckRequirements(CommandReturnObject &result);
///
/// This allows code to check a OptionValueBoolean in conditions.
///
- /// @code
+ /// \code
/// OptionValueBoolean bool_value(...);
/// if (bool_value)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// /b True this object contains a valid namespace decl, \b
/// false otherwise.
//------------------------------------------------------------------
}
//----------------------------------------------------------------------
-/// @class Options Options.h "lldb/Interpreter/Options.h"
+/// \class Options Options.h "lldb/Interpreter/Options.h"
/// A command line option parsing protocol class.
///
/// Options is designed to be subclassed to contain all needed options for a
//------------------------------------------------------------------
/// Get the option definitions to use when parsing Args options.
///
- /// @see Args::ParseOptions (Options&)
- /// @see man getopt_long_only
+ /// \see Args::ParseOptions (Options&)
+ /// \see man getopt_long_only
//------------------------------------------------------------------
Option *GetLongOptions();
//------------------------------------------------------------------
/// Set the value of an option.
///
- /// @param[in] option_idx
+ /// \param[in] option_idx
/// The index into the "struct option" array that was returned
/// by Options::GetLongOptions().
///
- /// @param[in] option_arg
+ /// \param[in] option_arg
/// The argument value for the option that the user entered, or
/// nullptr if there is no argument for the current option.
///
- /// @param[in] execution_context
+ /// \param[in] execution_context
/// The execution context to use for evaluating the option.
/// May be nullptr if the option is to be evaluated outside any
/// particular context.
///
- /// @see Args::ParseOptions (Options&)
- /// @see man getopt_long_only
+ /// \see Args::ParseOptions (Options&)
+ /// \see man getopt_long_only
//------------------------------------------------------------------
virtual Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
ExecutionContext *execution_context) = 0;
/// Handles the generic bits of figuring out whether we are in an option,
/// and if so completing it.
///
- /// @param[in/out] request
+ /// \param[in/out] request
/// The completion request that we need to act upon.
///
- /// @param[in] interpreter
+ /// \param[in] interpreter
/// The interpreter that's doing the completing.
///
/// FIXME: This is the wrong return value, since we also need to
/// make a distinction between total number of matches, and the window the
/// user wants returned.
///
- /// @return
+ /// \return
/// \btrue if we were in an option, \bfalse otherwise.
//------------------------------------------------------------------
bool HandleOptionCompletion(lldb_private::CompletionRequest &request,
/// Handles the generic bits of figuring out whether we are in an option,
/// and if so completing it.
///
- /// @param[in/out] request
+ /// \param[in/out] request
/// The completion request that we need to act upon.
///
- /// @param[in] interpreter
+ /// \param[in] interpreter
/// The command interpreter doing the completion.
///
/// FIXME: This is the wrong return value, since we also need to
/// make a distinction between total number of matches, and the window the
/// user wants returned.
///
- /// @return
+ /// \return
/// \btrue if we were in an option, \bfalse otherwise.
//------------------------------------------------------------------
virtual bool
/// Append all options from \a group using the exact same option groups that
/// each option is defined with.
///
- /// @param[in] group
+ /// \param[in] group
/// A group of options to take option values from and copy their
/// definitions into this class.
//----------------------------------------------------------------------
/// "src_mask" set. After the option definition is copied into the options
/// definitions in this class, set the usage_mask to "dst_mask".
///
- /// @param[in] group
+ /// \param[in] group
/// A group of options to take option values from and copy their
/// definitions into this class.
///
- /// @param[in] src_mask
+ /// \param[in] src_mask
/// When copying options from \a group, you might only want some of
/// the options to be appended to this group. This mask allows you
/// to control which options from \a group get added. It also allows
/// you to specify the same options from \a group multiple times
/// for different option sets.
///
- /// @param[in] dst_mask
+ /// \param[in] dst_mask
/// Set the usage mask for any copied options to \a dst_mask after
/// copying the option definition.
//----------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Block Block.h "lldb/Symbol/Block.h"
+/// \class Block Block.h "lldb/Symbol/Block.h"
/// A class that describes a single lexical block.
///
/// A Function object owns a BlockList object which owns one or more
/// \a block_list is used to represent the parent, sibling, and child block
/// information and also allows for partial parsing at the block level.
///
- /// @param[in] uid
+ /// \param[in] uid
/// The UID for a given block. This value is given by the
/// SymbolFile plug-in and can be any value that helps the
/// SymbolFile plug-in to match this block back to the debug
/// depth parsing. Common values would be the index into a
/// table, or an offset into the debug information.
///
- /// @param[in] depth
+ /// \param[in] depth
/// The integer depth of this block in the block list hierarchy.
///
- /// @param[in] block_list
+ /// \param[in] block_list
/// The block list that this object belongs to.
///
- /// @see BlockList
+ /// \see BlockList
//------------------------------------------------------------------
Block(lldb::user_id_t uid);
//------------------------------------------------------------------
/// Add a child to this object.
///
- /// @param[in] child_block_sp
+ /// \param[in] child_block_sp
/// A shared pointer to a child block that will get added to
/// this block.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Add a new offset range to this block.
///
- /// @param[in] start_offset
+ /// \param[in] start_offset
/// An offset into this Function's address range that
/// describes the start address of a range for this block.
///
- /// @param[in] end_offset
+ /// \param[in] end_offset
/// An offset into this Function's address range that
/// describes the end address of a range for this block.
//------------------------------------------------------------------
void FinalizeRanges();
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
+ /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void CalculateSymbolContext(SymbolContext *sc) override;
//------------------------------------------------------------------
/// Check if an offset is in one of the block offset ranges.
///
- /// @param[in] range_offset
+ /// \param[in] range_offset
/// An offset into the Function's address range.
///
- /// @return
+ /// \return
/// Returns \b true if \a range_offset falls in one of this
/// block's ranges, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check if a offset range is in one of the block offset ranges.
///
- /// @param[in] range
+ /// \param[in] range
/// An offset range into the Function's address range.
///
- /// @return
+ /// \return
/// Returns \b true if \a range falls in one of this
/// block's ranges, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check if this object contains "block" as a child block at any depth.
///
- /// @param[in] block
+ /// \param[in] block
/// A potential child block.
///
- /// @return
+ /// \return
/// Returns \b true if \a block is a child of this block, \b
/// false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Dump the block contents.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] base_addr
+ /// \param[in] base_addr
/// The resolved start address of the Function's address
/// range. This should be resolved as the file or load address
/// prior to passing the value into this function for dumping.
///
- /// @param[in] depth
+ /// \param[in] depth
/// Limit the number of levels deep that this function should
/// print as this block can contain child blocks. Specify
/// INT_MAX to dump all child blocks.
///
- /// @param[in] show_context
+ /// \param[in] show_context
/// If \b true, variables will dump their context information.
//------------------------------------------------------------------
void Dump(Stream *s, lldb::addr_t base_addr, int32_t depth,
bool show_context) const;
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
+ /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void DumpSymbolContext(Stream *s) override;
//------------------------------------------------------------------
/// Get the parent block.
///
- /// @return
+ /// \return
/// The parent block pointer, or nullptr if this block has no
/// parent.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the inlined block that contains this block.
///
- /// @return
+ /// \return
/// If this block contains inlined function info, it will return
/// this block, else parent blocks will be searched to see if
/// any contain this block. nullptr will be returned if this block
//------------------------------------------------------------------
/// Get the inlined parent block for this block.
///
- /// @return
+ /// \return
/// The parent block pointer, or nullptr if this block has no
/// parent.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the sibling block for this block.
///
- /// @return
+ /// \return
/// The sibling block pointer, or nullptr if this block has no
/// sibling.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the first child block.
///
- /// @return
+ /// \return
/// The first child block pointer, or nullptr if this block has no
/// children.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the variable list for this block only.
///
- /// @param[in] can_create
+ /// \param[in] can_create
/// If \b true, the variables can be parsed if they already
/// haven't been, else the current state of the block will be
/// returned.
///
- /// @return
+ /// \return
/// A variable list shared pointer that contains all variables
/// for this block.
//------------------------------------------------------------------
/// Get the variable list for this block and optionally all child blocks if
/// \a get_child_variables is \b true.
///
- /// @param[in] get_child_variables
+ /// \param[in] get_child_variables
/// If \b true, all variables from all child blocks will be
/// added to the variable list.
///
- /// @param[in] can_create
+ /// \param[in] can_create
/// If \b true, the variables can be parsed if they already
/// haven't been, else the current state of the block will be
/// returned. Passing \b true for this parameter can be used
/// to see the current state of what has been parsed up to this
/// point.
///
- /// @param[in] add_inline_child_block_variables
+ /// \param[in] add_inline_child_block_variables
/// If this is \b false, no child variables of child blocks
/// that are inlined functions will be gotten. If \b true then
/// all child variables will be added regardless of whether they
/// come from inlined functions or not.
///
- /// @return
+ /// \return
/// A variable list shared pointer that contains all variables
/// for this block.
//------------------------------------------------------------------
/// Appends the variables from this block, and optionally from all parent
/// blocks, to \a variable_list.
///
- /// @param[in] can_create
+ /// \param[in] can_create
/// If \b true, the variables can be parsed if they already
/// haven't been, else the current state of the block will be
/// returned. Passing \b true for this parameter can be used
/// to see the current state of what has been parsed up to this
/// point.
///
- /// @param[in] get_parent_variables
+ /// \param[in] get_parent_variables
/// If \b true, all variables from all parent blocks will be
/// added to the variable list.
///
- /// @param[in] stop_if_block_is_inlined_function
+ /// \param[in] stop_if_block_is_inlined_function
/// If \b true, all variables from all parent blocks will be
/// added to the variable list until there are no parent blocks
/// or the parent block has inlined function info.
///
- /// @param[in,out] variable_list
+ /// \param[in,out] variable_list
/// All variables in this block, and optionally all parent
/// blocks will be added to this list.
///
- /// @return
+ /// \return
/// The number of variable that were appended to \a
/// variable_list.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get const accessor for any inlined function information.
///
- /// @return
+ /// \return
/// A const pointer to any inlined function information, or nullptr
/// if this is a regular block.
//------------------------------------------------------------------
/// Get the symbol file which contains debug info for this block's
/// symbol context module.
///
- /// @return A pointer to the symbol file or nullptr.
+ /// \return A pointer to the symbol file or nullptr.
//------------------------------------------------------------------
SymbolFile *GetSymbolFile();
/// Returns the cost of this object plus any owned objects from the ranges,
/// variables, and inline function information.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
//------------------------------------------------------------------
size_t MemorySize() const;
//------------------------------------------------------------------
/// Set accessor for any inlined function information.
///
- /// @param[in] name
+ /// \param[in] name
/// The method name for the inlined function. This value should
/// not be nullptr.
///
- /// @param[in] mangled
+ /// \param[in] mangled
/// The mangled method name for the inlined function. This can
/// be nullptr if there is no mangled name for an inlined function
/// or if the name is the same as \a name.
///
- /// @param[in] decl_ptr
+ /// \param[in] decl_ptr
/// A optional pointer to declaration information for the
/// inlined function information. This value can be nullptr to
/// indicate that no declaration information is available.
///
- /// @param[in] call_decl_ptr
+ /// \param[in] call_decl_ptr
/// Optional calling location declaration information that
/// describes from where this inlined function was called.
//------------------------------------------------------------------
/// Called by the SymbolFile plug-ins after they have parsed the variable
/// lists and are ready to hand ownership of the list over to this object.
///
- /// @param[in] variable_list_sp
+ /// \param[in] variable_list_sp
/// A shared pointer to a VariableList.
//------------------------------------------------------------------
void SetVariableList(lldb::VariableListSP &variable_list_sp) {
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
+/// \class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
/// A class that describes a compilation unit.
///
/// A representation of a compilation unit, or compiled source file.
/// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
/// source language type.
///
- /// @param[in] module
+ /// \param[in] module
/// The parent module that owns this compile unit. This value
/// must be a valid pointer value.
///
- /// @param[in] user_data
+ /// \param[in] user_data
/// User data where the SymbolFile parser can store data.
///
- /// @param[in] pathname
+ /// \param[in] pathname
/// The path to the source file for this compile unit.
///
- /// @param[in] uid
+ /// \param[in] uid
/// The user ID of the compile unit. This value is supplied by
/// the SymbolFile plug-in and should be a value that allows
/// the SymbolFile plug-in to easily locate and parse additional
/// information for the compile unit.
///
- /// @param[in] language
+ /// \param[in] language
/// A language enumeration type that describes the main language
/// of this compile unit.
///
- /// @param[in] is_optimized
+ /// \param[in] is_optimized
/// A value that can initialized with eLazyBoolYes, eLazyBoolNo
/// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
/// an extra call into SymbolVendor will be made to calculate if
/// the compile unit is optimized will be made when
/// CompileUnit::GetIsOptimized() is called.
///
- /// @see lldb::LanguageType
+ /// \see lldb::LanguageType
//------------------------------------------------------------------
CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
const char *pathname, lldb::user_id_t uid,
/// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
/// source language type.
///
- /// @param[in] module
+ /// \param[in] module
/// The parent module that owns this compile unit. This value
/// must be a valid pointer value.
///
- /// @param[in] user_data
+ /// \param[in] user_data
/// User data where the SymbolFile parser can store data.
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// The file specification for the source file of this compile
/// unit.
///
- /// @param[in] uid
+ /// \param[in] uid
/// The user ID of the compile unit. This value is supplied by
/// the SymbolFile plug-in and should be a value that allows
/// the plug-in to easily locate and parse
/// additional information for the compile unit.
///
- /// @param[in] language
+ /// \param[in] language
/// A language enumeration type that describes the main language
/// of this compile unit.
///
- /// @param[in] is_optimized
+ /// \param[in] is_optimized
/// A value that can initialized with eLazyBoolYes, eLazyBoolNo
/// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
/// an extra call into SymbolVendor will be made to calculate if
/// the compile unit is optimized will be made when
/// CompileUnit::GetIsOptimized() is called.
///
- /// @see lldb::LanguageType
+ /// \see lldb::LanguageType
//------------------------------------------------------------------
CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
const FileSpec &file_spec, lldb::user_id_t uid,
/// Typically called by the SymbolFile plug-ins as they partially parse the
/// debug information.
///
- /// @param[in] function_sp
+ /// \param[in] function_sp
/// A shared pointer to the Function object.
//------------------------------------------------------------------
void AddFunction(lldb::FunctionSP &function_sp);
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
+ /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void CalculateSymbolContext(SymbolContext *sc) override;
CompileUnit *CalculateSymbolContextCompileUnit() override;
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
+ /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void DumpSymbolContext(Stream *s) override;
/// This provides raw access to the function shared pointer list and will not
/// cause the SymbolFile plug-in to parse any unparsed functions.
///
- /// @note Prefer using FindFunctionByUID over this if possible.
+ /// \note Prefer using FindFunctionByUID over this if possible.
///
- /// @param[in] lambda
+ /// \param[in] lambda
/// The lambda that should be applied to every function. The lambda can
/// return true if the iteration should be aborted earlier.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Dump the compile unit contents to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] show_context
+ /// \param[in] show_context
/// If \b true, variables will dump their symbol context
/// information.
//------------------------------------------------------------------
/// file and line by starting with \a start_idx equal to zero, and calling
/// this function back with the return value + 1.
///
- /// @param[in] start_idx
+ /// \param[in] start_idx
/// The zero based index at which to start looking for matches.
///
- /// @param[in] line
+ /// \param[in] line
/// The line number to search for.
///
- /// @param[in] file_spec_ptr
+ /// \param[in] file_spec_ptr
/// If non-NULL search for entries that match this file spec,
/// else if NULL, search for line entries that match the compile
/// unit file.
///
- /// @param[in] exact
+ /// \param[in] exact
/// If \btrue match only if there is a line table entry for this line
/// number.
/// If \bfalse, find the line table entry equal to or after this line
/// number.
///
- /// @param[out] line_entry
+ /// \param[out] line_entry
/// If non-NULL, a copy of the line entry that was found.
///
- /// @return
+ /// \return
/// The zero based index of a matching line entry, or UINT32_MAX
/// if no matching line entry is found.
//------------------------------------------------------------------
/// use this function to determine if the line table has be parsed yet.
/// Clients use this function to get the line table from a compile unit.
///
- /// @return
+ /// \return
/// The line table object pointer, or NULL if this line table
/// hasn't been parsed yet.
//------------------------------------------------------------------
/// The support file list is used by the line table, and any objects that
/// have valid Declaration objects.
///
- /// @return
+ /// \return
/// A support file list object.
//------------------------------------------------------------------
FileSpecList &GetSupportFiles();
/// This reports all the imports that the compile unit made, including the
/// current module.
///
- /// @return
+ /// \return
/// A list of imported module names.
//------------------------------------------------------------------
const std::vector<SourceModule> &GetImportedModules();
/// SymbolFile plug-ins can store user data to internal state or objects to
/// quickly allow them to parse more information for a given object.
///
- /// @return
+ /// \return
/// The user data stored with the CompileUnit when it was
/// constructed.
//------------------------------------------------------------------
/// variable list will contain all global and static variables that were
/// defined at the compile unit level.
///
- /// @param[in] can_create
+ /// \param[in] can_create
/// If \b true, the variable list will be parsed on demand. If
/// \b false, the current variable list will be returned even
/// if it contains a NULL VariableList object (typically
/// called by dumping routines that want to display only what
/// has currently been parsed).
///
- /// @return
+ /// \return
/// A shared pointer to a variable list, that can contain NULL
/// VariableList pointer if there are no global or static
/// variables.
/// Typically used by SymbolFile plug-ins when partially parsing the debug
/// information to see if the function has been parsed yet.
///
- /// @param[in] uid
+ /// \param[in] uid
/// The user ID of the function to find. This value is supplied
/// by the SymbolFile plug-in and should be a value that
/// allows the plug-in to easily locate and parse additional
/// information in the function.
///
- /// @return
+ /// \return
/// A shared pointer to the function object that might contain
/// a NULL Function pointer.
//------------------------------------------------------------------
/// hands ownership of the line table to this object. The compile unit owns
/// the line table object and will delete the object when it is deleted.
///
- /// @param[in] line_table
+ /// \param[in] line_table
/// A line table object pointer that this object now owns.
//------------------------------------------------------------------
void SetLineTable(LineTable *line_table);
/// Called by the SymbolFile plug-ins after they have parsed the variable
/// lists and are ready to hand ownership of the list over to this object.
///
- /// @param[in] variable_list_sp
+ /// \param[in] variable_list_sp
/// A shared pointer to a VariableList.
//------------------------------------------------------------------
void SetVariableList(lldb::VariableListSP &variable_list_sp);
/// Given a file in \a file_spec, and a line number, find all instances and
/// append them to the supplied symbol context list \a sc_list.
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// A file specification. If \a file_spec contains no directory
/// information, only the basename will be used when matching
/// contexts. If the directory in \a file_spec is valid, a
/// complete file specification match will be performed.
///
- /// @param[in] line
+ /// \param[in] line
/// The line number to match against the compile unit's line
/// tables.
///
- /// @param[in] check_inlines
+ /// \param[in] check_inlines
/// If \b true this function will also match any inline
/// file and line matches. If \b false, the compile unit's
/// file specification must match \a file_spec for any matches
/// to be returned.
///
- /// @param[in] exact
+ /// \param[in] exact
/// If true, only resolve the context if \a line exists in the line table.
/// If false, resolve the context to the closest line greater than \a line
/// in the line table.
///
- /// @param[in] resolve_scope
+ /// \param[in] resolve_scope
/// For each matching line entry, this bitfield indicates what
/// values within each SymbolContext that gets added to \a
/// sc_list will be resolved. See the SymbolContext::Scope
/// resolved. Only SymbolContext entries that can be resolved
/// using a LineEntry base address will be able to be resolved.
///
- /// @param[out] sc_list
+ /// \param[out] sc_list
/// A SymbolContext list class that will get any matching
/// entries appended to.
///
- /// @return
+ /// \return
/// The number of new matches that were added to \a sc_list.
///
- /// @see enum SymbolContext::Scope
+ /// \see enum SymbolContext::Scope
//------------------------------------------------------------------
uint32_t ResolveSymbolContext(const FileSpec &file_spec, uint32_t line,
bool check_inlines, bool exact,
/// would expect them, stepping through the source lines in the function may
/// appear strange, etc.
///
- /// @return
+ /// \return
/// Returns 'true' if this compile unit was compiled with
/// optimization. 'false' indicates that either the optimization
/// is unknown, or this compile unit was built without optimization.
//----------------------------------------------------------------------
/// Checks if this decl context represents a method of a class.
///
- /// @param[out] language_ptr
+ /// \param[out] language_ptr
/// If non NULL and \b true is returned from this function,
/// this will indicate if the language that respresents the method.
///
- /// @param[out] is_instance_method_ptr
+ /// \param[out] is_instance_method_ptr
/// If non NULL and \b true is returned from this function,
/// this will indicate if the method is an instance function (true)
/// or a class method (false indicating the function is static, or
/// doesn't require an instance of the class to be called).
///
- /// @param[out] language_object_name_ptr
+ /// \param[out] language_object_name_ptr
/// If non NULL and \b true is returned from this function,
/// this will indicate if implicit object name for the language
/// like "this" for C++, and "self" for Objective C.
///
- /// @return
+ /// \return
/// Returns true if this is a decl context that represents a method
/// in a struct, union or class.
//----------------------------------------------------------------------
// functions in the Module. But the eh_frame can help to give the addresses
// of these stripped symbols, at least.
//
- // @param[out] function_info
+ // \param[out] function_info
// A vector provided by the caller is filled out. May be empty if no
// FDEs/no eh_frame
// is present in this Module.
/// Look up the set of Decls that the DeclVendor currently knows about
/// matching a given name.
///
- /// @param[in] name
+ /// \param[in] name
/// The name to look for.
///
- /// @param[in] append
+ /// \param[in] append
/// If true, FindDecls will clear "decls" when it starts.
///
- /// @param[in] max_matches
+ /// \param[in] max_matches
/// The maximum number of Decls to return. UINT32_MAX means "as
/// many as possible."
///
- /// @return
+ /// \return
/// The number of Decls added to decls; will not exceed
/// max_matches.
//------------------------------------------------------------------
/// Interface for ExternalASTMerger. Returns an ImporterSource
/// allowing type completion.
///
- /// @return
+ /// \return
/// An ImporterSource for this DeclVendor.
//------------------------------------------------------------------
virtual clang::ExternalASTMerger::ImporterSource GetImporterSource() = 0;
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Declaration Declaration.h "lldb/Symbol/Declaration.h"
+/// \class Declaration Declaration.h "lldb/Symbol/Declaration.h"
/// A class that describes the declaration location of a
/// lldb object.
///
//------------------------------------------------------------------
/// Construct with file specification, and optional line and column.
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// The file specification that describes where this was
/// declared.
///
- /// @param[in] line
+ /// \param[in] line
/// The line number that describes where this was declared. Set
/// to zero if there is no line number information.
///
- /// @param[in] column
+ /// \param[in] column
/// The column number that describes where this was declared.
/// Set to zero if there is no column number information.
//------------------------------------------------------------------
/// specifications are equal, then continue to compare the line number and
/// column numbers respectively.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// The Left Hand Side const Declaration object reference.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Right Hand Side const Declaration object reference.
///
- /// @return
- /// @li -1 if lhs < rhs
- /// @li 0 if lhs == rhs
- /// @li 1 if lhs > rhs
+ /// \return
+ /// \li -1 if lhs < rhs
+ /// \li 0 if lhs == rhs
+ /// \li 1 if lhs > rhs
//------------------------------------------------------------------
static int Compare(const Declaration &lhs, const Declaration &rhs);
/// Dump a description of the contents of this object to the supplied stream
/// \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s, bool show_fullpaths) const;
//------------------------------------------------------------------
/// Get accessor for the declaration column number.
///
- /// @return
+ /// \return
/// Non-zero indicates a valid column number, zero indicates no
/// column information is available.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get accessor for file specification.
///
- /// @return
+ /// \return
/// A reference to the file specification object.
//------------------------------------------------------------------
FileSpec &GetFile() { return m_file; }
//------------------------------------------------------------------
/// Get const accessor for file specification.
///
- /// @return
+ /// \return
/// A const reference to the file specification object.
//------------------------------------------------------------------
const FileSpec &GetFile() const { return m_file; }
//------------------------------------------------------------------
/// Get accessor for the declaration line number.
///
- /// @return
+ /// \return
/// Non-zero indicates a valid line number, zero indicates no
/// line information is available.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
/// The returned value does not include the bytes for any
/// shared string values.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//------------------------------------------------------------------
size_t MemorySize() const;
//------------------------------------------------------------------
/// Set accessor for the declaration column number.
///
- /// @param[in] column
+ /// \param[in] column
/// Non-zero indicates a valid column number, zero indicates no
/// column information is available.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set accessor for the declaration file specification.
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// The new declaration file specification.
//------------------------------------------------------------------
void SetFile(const FileSpec &file_spec) { m_file = file_spec; }
//------------------------------------------------------------------
/// Set accessor for the declaration line number.
///
- /// @param[in] line
+ /// \param[in] line
/// Non-zero indicates a valid line number, zero indicates no
/// line information is available.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class FunctionInfo Function.h "lldb/Symbol/Function.h"
+/// \class FunctionInfo Function.h "lldb/Symbol/Function.h"
/// A class that contains generic function information.
///
/// This provides generic function information that gets reused between inline
/// Construct with the function method name and optional declaration
/// information.
///
- /// @param[in] name
+ /// \param[in] name
/// A C string name for the method name for this function. This
/// value should not be the mangled named, but the simple method
/// name.
///
- /// @param[in] decl_ptr
+ /// \param[in] decl_ptr
/// Optional declaration information that describes where the
/// function was declared. This can be NULL.
//------------------------------------------------------------------
/// Construct with the function method name and optional declaration
/// information.
///
- /// @param[in] name
+ /// \param[in] name
/// A name for the method name for this function. This value
/// should not be the mangled named, but the simple method name.
///
- /// @param[in] decl_ptr
+ /// \param[in] decl_ptr
/// Optional declaration information that describes where the
/// function was declared. This can be NULL.
//------------------------------------------------------------------
/// First compares the method names, and if equal, then compares the
/// declaration information.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// The Left Hand Side const FunctionInfo object reference.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Right Hand Side const FunctionInfo object reference.
///
- /// @return
- /// @li -1 if lhs < rhs
- /// @li 0 if lhs == rhs
- /// @li 1 if lhs > rhs
+ /// \return
+ /// \li -1 if lhs < rhs
+ /// \li 0 if lhs == rhs
+ /// \li 1 if lhs > rhs
//------------------------------------------------------------------
static int Compare(const FunctionInfo &lhs, const FunctionInfo &rhs);
/// Dump a description of the contents of this object to the supplied stream
/// \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s, bool show_fullpaths) const;
//------------------------------------------------------------------
/// Get accessor for the declaration information.
///
- /// @return
+ /// \return
/// A reference to the declaration object.
//------------------------------------------------------------------
Declaration &GetDeclaration();
//------------------------------------------------------------------
/// Get const accessor for the declaration information.
///
- /// @return
+ /// \return
/// A const reference to the declaration object.
//------------------------------------------------------------------
const Declaration &GetDeclaration() const;
//------------------------------------------------------------------
/// Get accessor for the method name.
///
- /// @return
+ /// \return
/// A const reference to the method name object.
//------------------------------------------------------------------
ConstString GetName() const;
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
/// The returned value does not include the bytes for any
/// shared string values.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//------------------------------------------------------------------
virtual size_t MemorySize() const;
};
//----------------------------------------------------------------------
-/// @class InlineFunctionInfo Function.h "lldb/Symbol/Function.h"
+/// \class InlineFunctionInfo Function.h "lldb/Symbol/Function.h"
/// A class that describes information for an inlined function.
//----------------------------------------------------------------------
class InlineFunctionInfo : public FunctionInfo {
/// Construct with the function method name, mangled name, and optional
/// declaration information.
///
- /// @param[in] name
+ /// \param[in] name
/// A C string name for the method name for this function. This
/// value should not be the mangled named, but the simple method
/// name.
///
- /// @param[in] mangled
+ /// \param[in] mangled
/// A C string name for the mangled name for this function. This
/// value can be NULL if there is no mangled information.
///
- /// @param[in] decl_ptr
+ /// \param[in] decl_ptr
/// Optional declaration information that describes where the
/// function was declared. This can be NULL.
///
- /// @param[in] call_decl_ptr
+ /// \param[in] call_decl_ptr
/// Optional calling location declaration information that
/// describes from where this inlined function was called.
//------------------------------------------------------------------
/// Construct with the function method name, mangled name, and optional
/// declaration information.
///
- /// @param[in] name
+ /// \param[in] name
/// A name for the method name for this function. This value
/// should not be the mangled named, but the simple method name.
///
- /// @param[in] mangled
+ /// \param[in] mangled
/// A name for the mangled name for this function. This value
/// can be empty if there is no mangled information.
///
- /// @param[in] decl_ptr
+ /// \param[in] decl_ptr
/// Optional declaration information that describes where the
/// function was declared. This can be NULL.
///
- /// @param[in] call_decl_ptr
+ /// \param[in] call_decl_ptr
/// Optional calling location declaration information that
/// describes from where this inlined function was called.
//------------------------------------------------------------------
/// First compares the FunctionInfo objects, and if equal, compares the
/// mangled names.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// The Left Hand Side const InlineFunctionInfo object
/// reference.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Right Hand Side const InlineFunctionInfo object
/// reference.
///
- /// @return
- /// @li -1 if lhs < rhs
- /// @li 0 if lhs == rhs
- /// @li 1 if lhs > rhs
+ /// \return
+ /// \li -1 if lhs < rhs
+ /// \li 0 if lhs == rhs
+ /// \li 1 if lhs > rhs
//------------------------------------------------------------------
int Compare(const InlineFunctionInfo &lhs, const InlineFunctionInfo &rhs);
/// Dump a description of the contents of this object to the supplied stream
/// \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s, bool show_fullpaths) const;
//------------------------------------------------------------------
/// Get accessor for the call site declaration information.
///
- /// @return
+ /// \return
/// A reference to the declaration object.
//------------------------------------------------------------------
Declaration &GetCallSite();
//------------------------------------------------------------------
/// Get const accessor for the call site declaration information.
///
- /// @return
+ /// \return
/// A const reference to the declaration object.
//------------------------------------------------------------------
const Declaration &GetCallSite() const;
//------------------------------------------------------------------
/// Get accessor for the mangled name object.
///
- /// @return
+ /// \return
/// A reference to the mangled name object.
//------------------------------------------------------------------
Mangled &GetMangled();
//------------------------------------------------------------------
/// Get const accessor for the mangled name object.
///
- /// @return
+ /// \return
/// A const reference to the mangled name object.
//------------------------------------------------------------------
const Mangled &GetMangled() const;
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
/// The returned value does not include the bytes for any
/// shared string values.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//------------------------------------------------------------------
size_t MemorySize() const override;
class Function;
//----------------------------------------------------------------------
-/// @class CallEdge Function.h "lldb/Symbol/Function.h"
+/// \class CallEdge Function.h "lldb/Symbol/Function.h"
///
/// Represent a call made within a Function. This can be used to find a path
/// in the call graph between two functions.
};
//----------------------------------------------------------------------
-/// @class Function Function.h "lldb/Symbol/Function.h"
+/// \class Function Function.h "lldb/Symbol/Function.h"
/// A class that describes a function.
///
/// Functions belong to CompileUnit objects (Function::m_comp_unit), have
/// (Function::m_type), and contains lexical blocks (Function::m_blocks).
///
/// The function information is split into a few pieces:
-/// @li The concrete instance information
-/// @li The abstract information
+/// \li The concrete instance information
+/// \li The abstract information
///
/// The abstract information is found in the function type (Type) that
/// describes a function information, return type and parameter types.
/// Construct with a compile unit, function UID, function type UID, optional
/// mangled name, function type, and a section offset based address range.
///
- /// @param[in] comp_unit
+ /// \param[in] comp_unit
/// The compile unit to which this function belongs.
///
- /// @param[in] func_uid
+ /// \param[in] func_uid
/// The UID for this function. This value is provided by the
/// SymbolFile plug-in and can be any value that allows
/// the plug-in to quickly find and parse more detailed
/// information when and if more information is needed.
///
- /// @param[in] func_type_uid
+ /// \param[in] func_type_uid
/// The type UID for the function Type to allow for lazy type
/// parsing from the debug information.
///
- /// @param[in] mangled
+ /// \param[in] mangled
/// The optional mangled name for this function. If empty, there
/// is no mangled information.
///
- /// @param[in] func_type
+ /// \param[in] func_type
/// The optional function type. If NULL, the function type will
/// be parsed on demand when accessed using the
/// Function::GetType() function by asking the SymbolFile
/// plug-in to get the type for \a func_type_uid.
///
- /// @param[in] range
+ /// \param[in] range
/// The section offset based address for this function.
//------------------------------------------------------------------
Function(CompileUnit *comp_unit, lldb::user_id_t func_uid,
~Function() override;
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
+ /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void CalculateSymbolContext(SymbolContext *sc) override;
/// line table if that fails. So there may NOT be a line table entry for
/// this source file/line combo.
///
- /// @param[out] source_file
+ /// \param[out] source_file
/// The source file.
///
- /// @param[out] line_no
+ /// \param[out] line_no
/// The line number.
//------------------------------------------------------------------
void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
/// function.
///
///
- /// @param[out] source_file
+ /// \param[out] source_file
/// The source file.
///
- /// @param[out] line_no
+ /// \param[out] line_no
/// The line number.
//------------------------------------------------------------------
void GetEndLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
//------------------------------------------------------------------
/// Get accessor for the block list.
///
- /// @return
+ /// \return
/// The block list object that describes all lexical blocks
/// in the function.
///
- /// @see BlockList
+ /// \see BlockList
//------------------------------------------------------------------
Block &GetBlock(bool can_create);
//------------------------------------------------------------------
/// Get accessor for the compile unit that owns this function.
///
- /// @return
+ /// \return
/// A compile unit object pointer.
//------------------------------------------------------------------
CompileUnit *GetCompileUnit();
//------------------------------------------------------------------
/// Get const accessor for the compile unit that owns this function.
///
- /// @return
+ /// \return
/// A const compile unit object pointer.
//------------------------------------------------------------------
const CompileUnit *GetCompileUnit() const;
//------------------------------------------------------------------
/// Get accessor for the frame base location.
///
- /// @return
+ /// \return
/// A location expression that describes the function frame
/// base.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get const accessor for the frame base location.
///
- /// @return
+ /// \return
/// A const compile unit object pointer.
//------------------------------------------------------------------
const DWARFExpression &GetFrameBaseExpression() const { return m_frame_base; }
//------------------------------------------------------------------
/// Get the DeclContext for this function, if available.
///
- /// @return
+ /// \return
/// The DeclContext, or NULL if none exists.
//------------------------------------------------------------------
CompilerDeclContext GetDeclContext();
/// Get accessor for the type that describes the function return value type,
/// and parameter types.
///
- /// @return
+ /// \return
/// A type object pointer.
//------------------------------------------------------------------
Type *GetType();
/// Get const accessor for the type that describes the function return value
/// type, and parameter types.
///
- /// @return
+ /// \return
/// A const type object pointer.
//------------------------------------------------------------------
const Type *GetType() const;
/// "prologue" instructions include any instructions given line number 0
/// immediately following the prologue end.
///
- /// @return
+ /// \return
/// The size of the prologue.
//------------------------------------------------------------------
uint32_t GetPrologueByteSize();
/// Dump a description of the contents of this object to the supplied stream
/// \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] show_context
+ /// \param[in] show_context
/// If \b true, variables will dump their symbol context
/// information.
//------------------------------------------------------------------
void Dump(Stream *s, bool show_context) const;
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
+ /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void DumpSymbolContext(Stream *s) override;
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
/// The returned value does not include the bytes for any
/// shared string values.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//------------------------------------------------------------------
size_t MemorySize() const;
/// would expect them, stepping through the source lines in the function may
/// appear strange, etc.
///
- /// @return
+ /// \return
/// Returns 'true' if this function was compiled with
/// optimization. 'false' indicates that either the optimization
/// is unknown, or this function was built without optimization.
/// If stopped in a top-level function, LLDB will expose global variables
/// as-if locals in the 'frame variable' command
///
- /// @return
+ /// \return
/// Returns 'true' if this function is a top-level function,
/// 'false' otherwise.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class LineEntry LineEntry.h "lldb/Symbol/LineEntry.h"
+/// \class LineEntry LineEntry.h "lldb/Symbol/LineEntry.h"
/// A line table entry class.
//----------------------------------------------------------------------
struct LineEntry {
/// Dump a description of the contents of this object to the supplied stream
/// \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] comp_unit
+ /// \param[in] comp_unit
/// The compile unit object that contains the support file
/// list so the line entry can dump the file name (since this
/// object contains a file index into the support file list).
///
- /// @param[in] show_file
+ /// \param[in] show_file
/// If \b true, display the filename with the line entry which
/// requires that the compile unit object \a comp_unit be a
/// valid pointer.
///
- /// @param[in] style
+ /// \param[in] style
/// The display style for the section offset address.
///
- /// @return
+ /// \return
/// Returns \b true if the address was able to be displayed
/// using \a style. File and load addresses may be unresolved
/// and it may not be possible to display a valid address value.
/// Returns \b false if the address was not able to be properly
/// dumped.
///
- /// @see Address::DumpStyle
+ /// \see Address::DumpStyle
//------------------------------------------------------------------
bool Dump(Stream *s, Target *target, bool show_file, Address::DumpStyle style,
Address::DumpStyle fallback_style, bool show_range) const;
/// Dumps information specific to a process that stops at this line entry to
/// the supplied stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] comp_unit
+ /// \param[in] comp_unit
/// The compile unit object that contains the support file
/// list so the line entry can dump the file name (since this
/// object contains a file index into the support file list).
///
- /// @return
+ /// \return
/// Returns \b true if the file and line were properly dumped,
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check if a line entry object is valid.
///
- /// @return
+ /// \return
/// Returns \b true if the line entry contains a valid section
/// offset address, file index, and line number, \b false
/// otherwise.
//------------------------------------------------------------------
/// Compare two LineEntry objects.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// The Left Hand Side const LineEntry object reference.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Right Hand Side const LineEntry object reference.
///
- /// @return
- /// @li -1 if lhs < rhs
- /// @li 0 if lhs == rhs
- /// @li 1 if lhs > rhs
+ /// \return
+ /// \li -1 if lhs < rhs
+ /// \li 0 if lhs == rhs
+ /// \li 1 if lhs > rhs
//------------------------------------------------------------------
static int Compare(const LineEntry &lhs, const LineEntry &rhs);
/// range of contiuous LineEntries with line #0 will be included in the
/// complete range.
///
- /// @return
+ /// \return
/// The contiguous AddressRange for this source line.
//------------------------------------------------------------------
AddressRange GetSameLineContiguousAddressRange() const;
//------------------------------------------------------------------
/// Apply file mappings from target.source-map to the LineEntry's file.
///
- /// @param[in] target_sp
+ /// \param[in] target_sp
/// Shared pointer to the target this LineEntry belongs to.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Less than operator.
///
-/// @param[in] lhs
+/// \param[in] lhs
/// The Left Hand Side const LineEntry object reference.
///
-/// @param[in] rhs
+/// \param[in] rhs
/// The Right Hand Side const LineEntry object reference.
///
-/// @return
+/// \return
/// Returns \b true if lhs < rhs, false otherwise.
//------------------------------------------------------------------
bool operator<(const LineEntry &lhs, const LineEntry &rhs);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class LineSequence LineTable.h "lldb/Symbol/LineTable.h" An abstract base
+/// \class LineSequence LineTable.h "lldb/Symbol/LineTable.h" An abstract base
/// class used during symbol table creation.
//----------------------------------------------------------------------
class LineSequence {
};
//----------------------------------------------------------------------
-/// @class LineTable LineTable.h "lldb/Symbol/LineTable.h"
+/// \class LineTable LineTable.h "lldb/Symbol/LineTable.h"
/// A line table class.
//----------------------------------------------------------------------
class LineTable {
//------------------------------------------------------------------
/// Construct with compile unit.
///
- /// @param[in] comp_unit
+ /// \param[in] comp_unit
/// The compile unit to which this line table belongs.
//------------------------------------------------------------------
LineTable(CompileUnit *comp_unit);
///
/// All line entries are maintained in file address order.
///
- /// @param[in] line_entry
+ /// \param[in] line_entry
/// A const reference to a new line_entry to add to this line
/// table.
///
- /// @see Address::DumpStyle
+ /// \see Address::DumpStyle
//------------------------------------------------------------------
// void
// AddLineEntry (const LineEntry& line_entry);
//------------------------------------------------------------------
/// Dump all line entries in this line table to the stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] style
+ /// \param[in] style
/// The display style for the address.
///
- /// @see Address::DumpStyle
+ /// \see Address::DumpStyle
//------------------------------------------------------------------
void Dump(Stream *s, Target *target, Address::DumpStyle style,
Address::DumpStyle fallback_style, bool show_line_ranges);
//------------------------------------------------------------------
/// Find a line entry that contains the section offset address \a so_addr.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// A section offset address object containing the address we
/// are searching for.
///
- /// @param[out] line_entry
+ /// \param[out] line_entry
/// A copy of the line entry that was found if \b true is
/// returned, otherwise \a entry is left unmodified.
///
- /// @param[out] index_ptr
+ /// \param[out] index_ptr
/// A pointer to a 32 bit integer that will get the actual line
/// entry index if it is not nullptr.
///
- /// @return
+ /// \return
/// Returns \b true if \a so_addr is contained in a line entry
/// in this line table, \b false otherwise.
//------------------------------------------------------------------
/// line number \a line starting at the \a start_idx entries into the line
/// entry collection.
///
- /// @param[in] start_idx
+ /// \param[in] start_idx
/// The number of entries to skip when starting the search.
///
- /// @param[out] file_idx
+ /// \param[out] file_idx
/// The file index to search for that should be found prior
/// to calling this function using the following functions:
/// CompileUnit::GetSupportFiles()
/// FileSpecList::FindFileIndex (uint32_t, const FileSpec &) const
///
- /// @param[in] line
+ /// \param[in] line
/// The source line to match.
///
- /// @param[in] exact
+ /// \param[in] exact
/// If true, match only if you find a line entry exactly matching \a line.
/// If false, return the closest line entry greater than \a line.
///
- /// @param[out] line_entry
+ /// \param[out] line_entry
/// A reference to a line entry object that will get a copy of
/// the line entry if \b true is returned, otherwise \a
/// line_entry is left untouched.
///
- /// @return
+ /// \return
/// Returns \b true if a matching line entry is found in this
/// line table, \b false otherwise.
///
- /// @see CompileUnit::GetSupportFiles()
- /// @see FileSpecList::FindFileIndex (uint32_t, const FileSpec &) const
+ /// \see CompileUnit::GetSupportFiles()
+ /// \see FileSpecList::FindFileIndex (uint32_t, const FileSpec &) const
//------------------------------------------------------------------
uint32_t FindLineEntryIndexByFileIndex(uint32_t start_idx, uint32_t file_idx,
uint32_t line, bool exact,
//------------------------------------------------------------------
/// Get the line entry from the line table at index \a idx.
///
- /// @param[in] idx
+ /// \param[in] idx
/// An index into the line table entry collection.
///
- /// @return
+ /// \return
/// A valid line entry if \a idx is a valid index, or an invalid
/// line entry if \a idx is not valid.
///
- /// @see LineTable::GetSize()
- /// @see LineEntry::IsValid() const
+ /// \see LineTable::GetSize()
+ /// \see LineEntry::IsValid() const
//------------------------------------------------------------------
bool GetLineEntryAtIndex(uint32_t idx, LineEntry &line_entry);
//------------------------------------------------------------------
/// Gets the size of the line table in number of line table entries.
///
- /// @return
+ /// \return
/// The number of line table entries in this line table.
//------------------------------------------------------------------
uint32_t GetSize() const;
//------------------------------------------------------------------
/// Gets all contiguous file address ranges for the entire line table.
///
- /// @param[out] file_ranges
+ /// \param[out] file_ranges
/// A collection of file address ranges that will be filled in
/// by this function.
///
- /// @param[out] append
+ /// \param[out] append
/// If \b true, then append to \a file_ranges, otherwise clear
/// \a file_ranges prior to adding any ranges.
///
- /// @return
+ /// \return
/// The number of address ranges added to \a file_ranges
//------------------------------------------------------------------
size_t GetContiguousFileAddressRanges(FileAddressRanges &file_ranges,
/// Given a file range link map, relink the current line table and return a
/// fixed up line table.
///
- /// @param[out] file_range_map
+ /// \param[out] file_range_map
/// A collection of file ranges that maps to new file ranges
/// that will be used when linking the line table.
///
- /// @return
+ /// \return
/// A new line table if at least one line table entry was able
/// to be mapped.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
+/// \class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
/// A plug-in interface definition class for object containers.
///
/// Object containers contain object files from one or more architectures, and
/// supplied stream \a s. The dumping should include the section list if it
/// has been parsed, and the symbol table if it has been parsed.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
virtual void Dump(Stream *s) const = 0;
///
/// Copies the architecture specification for index \a idx.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The architecture index to extract.
///
- /// @param[out] arch
+ /// \param[out] arch
/// A architecture object that will be filled in if \a idx is a
/// architecture valid index.
///
- /// @return
+ /// \return
/// Returns \b true if \a idx is valid and \a arch has been
/// filled in, \b false otherwise.
///
- /// @see ObjectContainer::GetNumArchitectures() const
+ /// \see ObjectContainer::GetNumArchitectures() const
//------------------------------------------------------------------
virtual bool GetArchitectureAtIndex(uint32_t idx, ArchSpec &arch) const {
return false;
/// Some files contain many object files, and this function allows access to
/// an object's offset within the file.
///
- /// @return
+ /// \return
/// The offset in bytes into the file. Defaults to zero for
/// simple object files that a represented by an entire file.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the number of objects within this object file (archives).
///
- /// @return
+ /// \return
/// Zero for object files that are not archives, or the number
/// of objects contained in the archive.
//------------------------------------------------------------------
/// one architecture should override this function and return an appropriate
/// value.
///
- /// @return
+ /// \return
/// The number of architectures contained in this object file.
//------------------------------------------------------------------
virtual size_t GetNumArchitectures() const { return 0; }
/// false should be returned and the next plug-in can attempt to parse an
/// object file.
///
- /// @return
+ /// \return
/// Returns \b true if the header was parsed successfully, \b
/// false otherwise.
//------------------------------------------------------------------
/// state from any previously selected architecture and prepare to return
/// information for the new architecture.
///
- /// @return
+ /// \return
/// Returns a pointer to the object file of the requested \a
/// arch and optional \a name. Returns nullptr of no such object
/// file exists in the container.
};
//----------------------------------------------------------------------
-/// @class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h"
+/// \class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h"
/// A plug-in interface definition class for object file parsers.
///
/// Object files belong to Module objects and know how to extract information
/// supplied stream \a s. The dumping should include the section list if it
/// has been parsed, and the symbol table if it has been parsed.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
virtual void Dump(Stream *s) = 0;
/// ObjectFile plug-in interface and returns the first instance that can
/// parse the file.
///
- /// @param[in] module
+ /// \param[in] module
/// The parent module that owns this object file.
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// A file specification that indicates which file to use as the
/// object file.
///
- /// @param[in] file_offset
+ /// \param[in] file_offset
/// The offset into the file at which to start parsing the
/// object. This is for files that contain multiple
/// architectures or objects.
///
- /// @param[in] file_size
+ /// \param[in] file_size
/// The size of the current object file if it can be determined
/// or if it is known. This can be zero.
///
- /// @see ObjectFile::ParseHeader()
+ /// \see ObjectFile::ParseHeader()
//------------------------------------------------------------------
static lldb::ObjectFileSP
FindPlugin(const lldb::ModuleSP &module_sp, const FileSpec *file_spec,
/// ObjectFile plug-in interface and returns the first instance that can
/// parse the file.
///
- /// @param[in] module
+ /// \param[in] module
/// The parent module that owns this object file.
///
- /// @param[in] process_sp
+ /// \param[in] process_sp
/// A shared pointer to the process whose memory space contains
/// an object file. This will be stored as a std::weak_ptr.
///
- /// @param[in] header_addr
+ /// \param[in] header_addr
/// The address of the header for the object file in memory.
//------------------------------------------------------------------
static lldb::ObjectFileSP FindPlugin(const lldb::ModuleSP &module_sp,
/// the actual path name and into the object name so we can make a valid
/// object file from it.
///
- /// @param[in] path_with_object
+ /// \param[in] path_with_object
/// A path that might contain an archive path with a .o file
/// specified in parens in the basename of the path.
///
- /// @param[out] archive_file
+ /// \param[out] archive_file
/// If \b true is returned, \a file_spec will be filled in with
/// the path to the archive.
///
- /// @param[out] archive_object
+ /// \param[out] archive_object
/// If \b true is returned, \a object will be filled in with
/// the name of the object inside the archive.
///
- /// @return
+ /// \return
/// \b true if the path matches the pattern of archive + object
/// and \a archive_file and \a archive_object are modified,
/// \b false otherwise and \a archive_file and \a archive_object
//------------------------------------------------------------------
/// Gets the address size in bytes for the current object file.
///
- /// @return
+ /// \return
/// The size of an address in bytes for the currently selected
/// architecture (and object for archives). Returns zero if no
/// architecture or object has been selected.
/// binaries, though it can be applied to any executable file format that
/// supports different opcode types within the same binary. ARM binaries
/// support having both ARM and Thumb within the same executable container.
- /// We need to be able to get @return
+ /// We need to be able to get \return
/// The size of an address in bytes for the currently selected
/// architecture (and object for archives). Returns zero if no
/// architecture or object has been selected.
/// FileSpecList::AppendIfUnique(const FileSpec &) should be used to make
/// sure any files that are added are not already in the list.
///
- /// @param[out] file_list
+ /// \param[out] file_list
/// A list of file specification objects that gets dependent
/// files appended to.
///
- /// @return
+ /// \return
/// The number of new files that were appended to \a file_list.
///
- /// @see FileSpecList::AppendIfUnique(const FileSpec &)
+ /// \see FileSpecList::AppendIfUnique(const FileSpec &)
//------------------------------------------------------------------
virtual uint32_t GetDependentModules(FileSpecList &file_list) = 0;
/// Tells whether this object file is capable of being the main executable
/// for a process.
///
- /// @return
+ /// \return
/// \b true if it is, \b false otherwise.
//------------------------------------------------------------------
virtual bool IsExecutable() const = 0;
/// Some files contain many object files, and this function allows access to
/// an object's offset within the file.
///
- /// @return
+ /// \return
/// The offset in bytes into the file. Defaults to zero for
/// simple object files that a represented by an entire file.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get accessor to the object file specification.
///
- /// @return
+ /// \return
/// The file specification object pointer if there is one, or
/// NULL if this object is only from memory.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get const accessor to the object file specification.
///
- /// @return
+ /// \return
/// The const file specification object pointer if there is one,
/// or NULL if this object is only from memory.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the ArchSpec for this object file.
///
- /// @return
+ /// \return
/// The ArchSpec of this object file. In case of error, an invalid
/// ArchSpec object is returned.
//------------------------------------------------------------------
/// Section list parsing can be deferred by ObjectFile instances until this
/// accessor is called the first time.
///
- /// @return
+ /// \return
/// The list of sections contained in this object file.
//------------------------------------------------------------------
virtual SectionList *GetSectionList(bool update_module_section_list = true);
/// Symbol table parsing can be deferred by ObjectFile instances until this
/// accessor is called the first time.
///
- /// @return
+ /// \return
/// The symbol table for this object file.
//------------------------------------------------------------------
virtual Symtab *GetSymtab() = 0;
/// the first match in the SymbolTable and appends a Symbol only if
/// required/found.
///
- /// @return
+ /// \return
/// The resolved symbol or nullptr. Returns nullptr if a
/// a Symbol could not be found for the specified so_addr.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Detect if this object file has been stripped of local symbols.
///
- /// @return
+ /// \return
/// Return \b true if the object file has been stripped of local
/// symbols.
//------------------------------------------------------------------
///
/// This function should only be used when an object file is
///
- /// @param[in] flags
+ /// \param[in] flags
/// eSymtabFromUnifiedSectionList: Whether to clear symbol table
/// for unified module section list, or object file.
///
- /// @return
+ /// \return
/// The symbol table for this object file.
//------------------------------------------------------------------
virtual void ClearSymtab();
/// Else ObjectFile instances should return the MD5 checksum of all of the
/// bytes for the object file (or memory for memory based object files).
///
- /// @return
+ /// \return
/// The object file's UUID. In case of an error, an empty UUID is
/// returned.
//------------------------------------------------------------------
/// If the object file format contains a debug symbol file link, the values
/// will be returned in the FileSpecList.
///
- /// @return
+ /// \return
/// Returns filespeclist.
//------------------------------------------------------------------
virtual lldb_private::FileSpecList GetDebugSymbolFilePaths() {
/// symbols from another, the re-exported libraries will be returned in the
/// FileSpecList.
///
- /// @return
+ /// \return
/// Returns filespeclist.
//------------------------------------------------------------------
virtual lldb_private::FileSpecList GetReExportedLibraries() {
/// Sets the load address for an entire module, assuming a rigid slide of
/// sections, if possible in the implementation.
///
- /// @return
+ /// \return
/// Returns true iff any section's load address changed.
//------------------------------------------------------------------
virtual bool SetLoadAddress(Target &target, lldb::addr_t value,
/// Gets whether endian swapping should occur when extracting data from this
/// object file.
///
- /// @return
+ /// \return
/// Returns \b true if endian swapping is needed, \b false
/// otherwise.
//------------------------------------------------------------------
/// false should be returned and the next plug-in can attempt to parse an
/// object file.
///
- /// @return
+ /// \return
/// Returns \b true if the header was parsed successfully, \b
/// false otherwise.
//------------------------------------------------------------------
/// that symbol start addresses are unavailable before false is returned.
/// If it is unclear, this should return true.
///
- /// @return
+ /// \return
/// Returns true if assembly emulation should be used for this
/// module.
/// Only returns false if the ObjectFile is sure that symbol
/// runtime linker so that a debugger may monitor the loading and unloading
/// of shared libraries.
///
- /// @return
+ /// \return
/// The address of any auxiliary tables, or an invalid address if this
/// object file format does not support or contain such information.
virtual lldb_private::Address GetImageInfoAddress(Target *target) {
/// object file doesn't have an entry point (because it is not an executable
/// file) then an invalid address is returned.
///
- /// @return
+ /// \return
/// Returns the entry address for this module.
//------------------------------------------------------------------
virtual lldb_private::Address GetEntryPointAddress() { return Address(); }
/// in a Mach-O core file using the LC_IDENT load command (which is
/// obsolete, but can still be found in some old files)
///
- /// @return
+ /// \return
/// Returns the identifier string if one exists, else an empty
/// string.
//------------------------------------------------------------------
/// binary is exactly which removes ambiguity when there are multiple
/// binaries present in the captured memory pages.
///
- /// @param[out] address
+ /// \param[out] address
/// If the address of the binary is specified, this will be set.
/// This is an address is the virtual address space of the core file
/// memory segments; it is not an offset into the object file.
/// If no address is available, will be set to LLDB_INVALID_ADDRESS.
///
- /// @param[out] uuid
+ /// \param[out] uuid
/// If the uuid of the binary is specified, this will be set.
/// If no UUID is available, will be cleared.
///
- /// @return
+ /// \return
/// Returns true if either address or uuid has been set.
//------------------------------------------------------------------
virtual bool GetCorefileMainBinaryInfo (lldb::addr_t &address, UUID &uuid) {
/// eTypeXXX definitions do not match up with the type of file you are
/// loading, please feel free to add a new enumeration value.
///
- /// @return
+ /// \return
/// The calculated file type for the current object file.
//------------------------------------------------------------------
virtual Type CalculateType() = 0;
/// out, it will help with debugger plug-in selection when it comes time to
/// debug.
///
- /// @return
+ /// \return
/// The calculated object file strata for the current object
/// file.
//------------------------------------------------------------------
/// minor and build, but there may be more. This function will extract the
/// versions from object files if they are available.
///
- /// @return
+ /// \return
/// This function returns extracted version numbers as a
/// llvm::VersionTuple. In case of error an empty VersionTuple is
/// returned.
/// Some object files have information that specifies the minimum OS version
/// that they can be used on.
///
- /// @return
+ /// \return
/// This function returns extracted version numbers as a
/// llvm::VersionTuple. In case of error an empty VersionTuple is
/// returned.
/// useful with bare-metal targets where target does not have the ability to
/// start a process itself.
///
- /// @param[in] target
+ /// \param[in] target
/// Target where to load.
///
- /// @return
+ /// \return
//------------------------------------------------------------------
virtual std::vector<LoadableData> GetLoadableData(Target &target);
/// only be set if it is invalid. It is not allowed to switch from one
/// concrete architecture to another.
///
- /// @param[in] new_arch
+ /// \param[in] new_arch
/// The architecture this module will be set to.
///
- /// @return
+ /// \return
/// Returns \b true if the architecture was changed, \b
/// false otherwise.
//------------------------------------------------------------------
m_contains_linker_annotations = b;
}
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
+ /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void CalculateSymbolContext(SymbolContext *sc) override;
Symbol *CalculateSymbolContextSymbol() override;
//------------------------------------------------------------------
- /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
+ /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
///
- /// @see SymbolContextScope
+ /// \see SymbolContextScope
//------------------------------------------------------------------
void DumpSymbolContext(Stream *s) override;
class SymbolContextScope;
//----------------------------------------------------------------------
-/// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h" Defines
+/// \class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h" Defines
/// a symbol context baton that can be handed other debug core functions.
///
/// Many debugger functions require a context when doing lookups. This class
/// provides a common structure that can be used as the result of a query that
/// can contain a single result. Examples of such queries include
-/// @li Looking up a load address.
+/// \li Looking up a load address.
//----------------------------------------------------------------------
class SymbolContext {
public:
/// Construct with an object that knows how to reconstruct its symbol
/// context.
///
- /// @param[in] sc_scope
+ /// \param[in] sc_scope
/// A symbol context scope object that knows how to reconstruct
/// it's context.
//------------------------------------------------------------------
///
/// Initialize all pointer to the specified values.
///
- /// @param[in] module
+ /// \param[in] module
/// A Module pointer to the module for this context.
///
- /// @param[in] comp_unit
+ /// \param[in] comp_unit
/// A CompileUnit pointer to the compile unit for this context.
///
- /// @param[in] function
+ /// \param[in] function
/// A Function pointer to the function for this context.
///
- /// @param[in] block
+ /// \param[in] block
/// A Block pointer to the deepest block for this context.
///
- /// @param[in] line_entry
+ /// \param[in] line_entry
/// A LineEntry pointer to the line entry for this context.
///
- /// @param[in] symbol
+ /// \param[in] symbol
/// A Symbol pointer to the symbol for this context.
//------------------------------------------------------------------
explicit SymbolContext(const lldb::TargetSP &target_sp,
///
/// Makes a copy of the another SymbolContext object \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const SymbolContext object reference to copy.
//------------------------------------------------------------------
SymbolContext(const SymbolContext &rhs);
/// Copies the address value from another SymbolContext object \a rhs into
/// \a this object.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const SymbolContext object reference to copy.
///
- /// @return
+ /// \return
/// A const SymbolContext object reference to \a this.
//------------------------------------------------------------------
const SymbolContext &operator=(const SymbolContext &rhs);
/// Dump a description of the contents of this object to the supplied stream
/// \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s, Target *target) const;
/// is available, that will be output. Else just the address at which the
/// target was stopped will be displayed.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
///
- /// @param[in] so_addr
+ /// \param[in] so_addr
/// The resolved section offset address.
///
- /// @param[in] show_fullpaths
+ /// \param[in] show_fullpaths
/// When printing file paths (with the Module), whether the
/// base name of the Module should be printed or the full path.
///
- /// @param[in] show_module
+ /// \param[in] show_module
/// Whether the module name should be printed followed by a
/// grave accent "`" character.
///
- /// @param[in] show_inlined_frames
+ /// \param[in] show_inlined_frames
/// If a given pc is in inlined function(s), whether the inlined
/// functions should be printed on separate lines in addition to
/// the concrete function containing the pc.
///
- /// @param[in] show_function_arguments
+ /// \param[in] show_function_arguments
/// If false, this method will try to elide the function argument
/// types when printing the function name. This may be ambiguous
/// for languages that have function overloading - but it may
/// make the "function name" too long to include all the argument
/// types.
///
- /// @param[in] show_function_name
+ /// \param[in] show_function_name
/// Normally this should be true - the function/symbol name should
/// be printed. In disassembly formatting, where we want a format
/// like "<*+36>", this should be false and "*" will be printed
/// - symbol address range if symbol is not nullptr and
/// eSymbolContextSymbol is set in \a scope
///
- /// @param[in] scope
+ /// \param[in] scope
/// A mask of symbol context bits telling this function which
/// address ranges it can use when trying to extract one from
/// the valid (non-nullptr) symbol context classes.
///
- /// @param[in] range_idx
+ /// \param[in] range_idx
/// The address range index to grab. Since many functions and
/// blocks are not always contiguous, they may have more than
/// one address range.
///
- /// @param[in] use_inline_block_range
+ /// \param[in] use_inline_block_range
/// If \a scope has the eSymbolContextBlock bit set, and there
/// is a valid block in the symbol context, return the block
/// address range for the containing inline function block, not
/// for the address range of the inlined function block, not
/// the deepest lexical block.
///
- /// @param[out] range
+ /// \param[out] range
/// An address range object that will be filled in if \b true
/// is returned.
///
- /// @return
+ /// \return
/// \b True if this symbol context contains items that describe
/// an address range, \b false otherwise.
//------------------------------------------------------------------
/// - non-extern symbol in the target
/// It is an error if the highest-priority result is ambiguous.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the symbol to search for.
///
- /// @param[out] error
+ /// \param[out] error
/// An error that will be populated with a message if there was an
/// ambiguous result. The error will not be populated if no result
/// was found.
///
- /// @return
+ /// \return
/// The symbol that was found, or \b nullptr if none was found.
//------------------------------------------------------------------
const Symbol *FindBestGlobalDataSymbol(ConstString name, Status &error);
/// represented by this symbol context (whether the function is an inline
/// function or not).
///
- /// @return
+ /// \return
/// The block object pointer that defines the function that is
/// represented by this symbol context object, nullptr otherwise.
//------------------------------------------------------------------
/// If this symbol context represents a function that is a method, return
/// true and provide information about the method.
///
- /// @param[out] language
+ /// \param[out] language
/// If \b true is returned, the language for the method.
///
- /// @param[out] is_instance_method
+ /// \param[out] is_instance_method
/// If \b true is returned, \b true if this is a instance method,
/// \b false if this is a static/class function.
///
- /// @param[out] language_object_name
+ /// \param[out] language_object_name
/// If \b true is returned, the name of the artificial variable
/// for the language ("this" for C++, "self" for ObjC).
///
- /// @return
+ /// \return
/// \b True if this symbol context represents a function that
/// is a method of a class, \b false otherwise.
//------------------------------------------------------------------
/// For instance, if the symbol context contains an inlined block, it will
/// return the inlined function name.
///
- /// @param[in] prefer_mangled
+ /// \param[in] prefer_mangled
/// if \btrue, then the mangled name will be returned if there
/// is one. Otherwise the unmangled name will be returned if it
/// is available.
///
- /// @return
+ /// \return
/// The name of the function represented by this symbol context.
//------------------------------------------------------------------
ConstString GetFunctionName(
/// table information for the symbol context. it will return the inlined
/// function name.
///
- /// @param[in] prefer_mangled
+ /// \param[in] prefer_mangled
/// if \btrue, then the mangled name will be returned if there
/// is one. Otherwise the unmangled name will be returned if it
/// is available.
///
- /// @return
+ /// \return
/// The name of the function represented by this symbol context.
//------------------------------------------------------------------
LineEntry GetFunctionStartLineEntry() const;
/// For instance, if the symbol context contains an inlined block, it will
/// return the inlined function name.
///
- /// @param[in] curr_frame_pc
+ /// \param[in] curr_frame_pc
/// The address within the block of this object.
///
- /// @param[out] next_frame_sc
+ /// \param[out] next_frame_sc
/// A new symbol context that does what the title says it does.
///
- /// @param[out] next_frame_addr
+ /// \param[out] next_frame_addr
/// This is what you should report as the PC in \a next_frame_sc.
///
- /// @return
+ /// \return
/// \b true if this SymbolContext specifies a block contained in an
/// inlined block. If this returns \b true, \a next_frame_sc and
/// \a next_frame_addr will be filled in correctly.
};
//----------------------------------------------------------------------
-/// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
+/// \class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
/// Defines a list of symbol context objects.
///
/// This class provides a common structure that can be used to contain the
/// result of a query that can contain a multiple results. Examples of such
/// queries include:
-/// @li Looking up a function by name.
-/// @li Finding all addresses for a specified file and line number.
+/// \li Looking up a function by name.
+/// \li Finding all addresses for a specified file and line number.
//----------------------------------------------------------------------
class SymbolContextList {
public:
//------------------------------------------------------------------
/// Append a new symbol context to the list.
///
- /// @param[in] sc
+ /// \param[in] sc
/// A symbol context to append to the list.
//------------------------------------------------------------------
void Append(const SymbolContext &sc);
/// Dump a description of the contents of each symbol context in the list to
/// the supplied stream \a s.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s, Target *target) const;
/// Dump a description of the contents of each symbol context in the list to
/// the supplied stream \a s.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The zero based index into the symbol context list.
///
- /// @param[out] sc
+ /// \param[out] sc
/// A reference to the symbol context to fill in.
///
- /// @return
+ /// \return
/// Returns \b true if \a idx was a valid index into this
/// symbol context list and \a sc was filled in, \b false
/// otherwise.
/// The index \a idx must be a valid index, no error checking will be done
/// to ensure that it is valid.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The zero based index into the symbol context list.
///
- /// @return
+ /// \return
/// A const reference to the symbol context to fill in.
//------------------------------------------------------------------
SymbolContext &operator[](size_t idx) { return m_symbol_contexts[idx]; }
//------------------------------------------------------------------
/// Get accessor for a symbol context list size.
///
- /// @return
+ /// \return
/// Returns the number of symbol context objects in the list.
//------------------------------------------------------------------
uint32_t GetSize() const;
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class SymbolContextScope SymbolContextScope.h
+/// \class SymbolContextScope SymbolContextScope.h
/// "lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is
/// part of a symbol context
/// and can reconstruct its symbol context.
/// complete SymbolContext object in the object.
///
/// Examples of these objects include:
-/// @li Module
-/// @li CompileUnit
-/// @li Function
-/// @li Block
-/// @li Symbol
+/// \li Module
+/// \li CompileUnit
+/// \li Function
+/// \li Block
+/// \li Symbol
///
/// Other objects can store a "SymbolContextScope *" using any pointers to one
/// of the above objects. This allows clients to hold onto a pointer that
///
/// Example objects include that currently use "SymbolContextScope *" objects
/// include:
-/// @li Variable objects that can reconstruct where they are scoped
+/// \li Variable objects that can reconstruct where they are scoped
/// by making sure the SymbolContextScope * comes from the scope
/// in which the variable was declared. If a variable is a global,
/// the appropriate CompileUnit * will be used when creating the
/// in which the variable is defined. Function arguments can use
/// the Function object as their scope. The SymbolFile parsers
/// will set these correctly as the variables are parsed.
-/// @li Type objects that know exactly in which scope they
+/// \li Type objects that know exactly in which scope they
/// originated much like the variables above.
-/// @li StackID objects that are able to know that if the CFA
+/// \li StackID objects that are able to know that if the CFA
/// (stack pointer at the beginning of a function) and the
/// start PC for the function/symbol and the SymbolContextScope
/// pointer (a unique pointer that identifies a symbol context
/// function calls that require a symbol context can be made for the given
/// object.
///
- /// @param[out] sc
+ /// \param[out] sc
/// A symbol context object pointer that gets filled in.
//------------------------------------------------------------------
virtual void CalculateSymbolContext(SymbolContext *sc) = 0;
/// function is widely used in the DumpDebug and verbose output for lldb
/// objects.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object's symbol context.
//------------------------------------------------------------------
virtual void DumpSymbolContext(Stream *s) = 0;
/// for "void SymbolFile::InitializeObject()" which will get called
/// on the SymbolFile object with the best set of abilities.
///
- /// @return
+ /// \return
/// A uint32_t mask containing bits from the SymbolFile::Abilities
/// enumeration. Any bits that are set represent an ability that
/// this symbol plug-in can parse from the object file.
/// Obtain a ThreadPlan to get us into C++ constructs such as std::function.
///
- /// @param[in] thread
+ /// \param[in] thread
/// Curent thrad of execution.
///
- /// @param[in] stop_others
+ /// \param[in] stop_others
/// True if other threads should pause during execution.
///
- /// @return
+ /// \return
/// A ThreadPlan Shared pointer
lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread,
bool stop_others);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
+/// \class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
/// A plug-in interface definition class for dynamic loaders.
///
/// Dynamic loader plug-ins track image (shared library) loading and
/// Scans the installed DynamicLoader plug-ins and tries to find an instance
/// that can be used to track image changes in \a process.
///
- /// @param[in] process
+ /// \param[in] process
/// The process for which to try and locate a dynamic loader
/// plug-in instance.
///
- /// @param[in] plugin_name
+ /// \param[in] plugin_name
/// An optional name of a specific dynamic loader plug-in that
/// should be used. If NULL, pick the best plug-in.
//------------------------------------------------------------------
/// DynamicLoader plug-in instances should return this value to ensure
/// consistent debug session behaviour.
///
- /// @return
+ /// \return
/// Returns \b true if the process should stop when images
/// change, \b false if the process should resume.
//------------------------------------------------------------------
/// process stops when images change, but this can be overridden using this
/// function callback.
///
- /// @param[in] stop
+ /// \param[in] stop
/// Boolean value that indicates whether the process should stop
/// when images change.
//------------------------------------------------------------------
/// current state of \a thread.
///
///
- /// @param[in] stop_others
+ /// \param[in] stop_others
/// Whether the plan should be set to stop other threads.
///
- /// @return
+ /// \return
/// A pointer to the plan (caller owned) or NULL if we are not at such
/// a trampoline.
//------------------------------------------------------------------
/// symbols, you really need to set it on all the equivalent symbols.
///
///
- /// @param[in] original_symbol
+ /// \param[in] original_symbol
/// The symbol for which we are finding equivalences.
///
- /// @param[in] module_list
+ /// \param[in] module_list
/// The set of modules in which to search.
///
- /// @param[out] equivalent_symbols
+ /// \param[out] equivalent_symbols
/// The equivalent symbol list - any equivalent symbols found are appended
/// to this list.
///
- /// @return
+ /// \return
/// Number of equivalent symbols found.
//------------------------------------------------------------------
virtual size_t FindEquivalentSymbols(Symbol *original_symbol,
/// plug-ins to check any current dyld state to make sure it is an ok time
/// to load a shared library.
///
- /// @return
+ /// \return
/// \b true if it is currently ok to try and load a shared
/// library into the process, \b false otherwise.
//------------------------------------------------------------------
/// not reliable enough -- we need to consult those function's hand-written
/// eh_frame information.
///
- /// @return
+ /// \return
/// \b True if the symbol context should use eh_frame instructions
/// unconditionally when unwinding from this frame. Else \b false,
/// the normal lldb unwind behavior of only using eh_frame when the
//------------------------------------------------------------------
/// Retrieves the per-module TLS block for a given thread.
///
- /// @param[in] module
+ /// \param[in] module
/// The module to query TLS data for.
///
- /// @param[in] thread
+ /// \param[in] thread
/// The specific thread to query TLS data for.
///
- /// @return
+ /// \return
/// If the given thread has TLS data allocated for the
/// module, the address of the TLS block. Otherwise
/// LLDB_INVALID_ADDRESS is returned.
return LLDB_INVALID_ADDRESS;
}
- /// Locates or creates a module given by @p file and updates/loads the
- /// resulting module at the virtual base address @p base_addr.
+ /// Locates or creates a module given by \p file and updates/loads the
+ /// resulting module at the virtual base address \p base_addr.
virtual lldb::ModuleSP LoadModuleAtAddress(const lldb_private::FileSpec &file,
lldb::addr_t link_map_addr,
lldb::addr_t base_addr,
/// of the cache - or it may be able to return additional information about
/// the cache.
///
- /// @param[out] base_address
+ /// \param[out] base_address
/// The base address (load address) of the shared cache.
/// LLDB_INVALID_ADDRESS if it cannot be determined.
///
- /// @param[out] uuid
+ /// \param[out] uuid
/// The UUID of the shared cache, if it can be determined.
/// If the UUID cannot be fetched, IsValid() will be false.
///
- /// @param[out] using_shared_cache
+ /// \param[out] using_shared_cache
/// If this process is using a shared cache.
/// If unknown, eLazyBoolCalculate is returned.
///
- /// @param[out] private_shared_cache
+ /// \param[out] private_shared_cache
/// A LazyBool indicating whether this process is using a
/// private shared cache.
/// If this information cannot be fetched, eLazyBoolCalculate.
///
- /// @return
+ /// \return
/// Returns false if this DynamicLoader cannot gather information
/// about the shared cache / has no concept of a shared cache.
//------------------------------------------------------------------
/// accordingly and returns the target executable module.
lldb::ModuleSP GetTargetExecutable();
- /// Updates the load address of every allocatable section in @p module.
+ /// Updates the load address of every allocatable section in \p module.
///
- /// @param module The module to traverse.
+ /// \param module The module to traverse.
///
- /// @param link_map_addr The virtual address of the link map for the @p
+ /// \param link_map_addr The virtual address of the link map for the @p
/// module.
///
- /// @param base_addr The virtual base address @p module is loaded at.
+ /// \param base_addr The virtual base address \p module is loaded at.
virtual void UpdateLoadedSections(lldb::ModuleSP module,
lldb::addr_t link_map_addr,
lldb::addr_t base_addr,
void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr,
bool base_addr_is_offset);
- /// Removes the loaded sections from the target in @p module.
+ /// Removes the loaded sections from the target in \p module.
///
- /// @param module The module to traverse.
+ /// \param module The module to traverse.
virtual void UnloadSections(const lldb::ModuleSP module);
// Utility method so base classes can share implementation of UnloadSections
//===----------------------------------------------------------------------===//
//----------------------------------------------------------------------
-/// @class ExecutionContextRef ExecutionContext.h
+/// \class ExecutionContextRef ExecutionContext.h
/// "lldb/Target/ExecutionContext.h"
/// A class that holds a weak reference to an execution context.
///
/// a weak reference to the target's process, use the
/// ExecutionContextRef::SetContext() functions.
///
- /// @see ExecutionContextRef::SetContext(const lldb::TargetSP &, bool)
+ /// \see ExecutionContextRef::SetContext(const lldb::TargetSP &, bool)
//------------------------------------------------------------------
void SetTargetSP(const lldb::TargetSP &target_sp);
/// a weak reference to the target, use the
/// ExecutionContextRef::SetContext() functions.
///
- /// @see ExecutionContextRef::SetContext(const lldb::ProcessSP &)
+ /// \see ExecutionContextRef::SetContext(const lldb::ProcessSP &)
//------------------------------------------------------------------
void SetProcessSP(const lldb::ProcessSP &process_sp);
/// a weak reference to the thread's process and target, use the
/// ExecutionContextRef::SetContext() functions.
///
- /// @see ExecutionContextRef::SetContext(const lldb::ThreadSP &)
+ /// \see ExecutionContextRef::SetContext(const lldb::ThreadSP &)
//------------------------------------------------------------------
void SetThreadSP(const lldb::ThreadSP &thread_sp);
/// a weak reference to the frame's thread, process and target, use the
/// ExecutionContextRef::SetContext() functions.
///
- /// @see ExecutionContextRef::SetContext(const lldb::StackFrameSP &)
+ /// \see ExecutionContextRef::SetContext(const lldb::StackFrameSP &)
//------------------------------------------------------------------
void SetFrameSP(const lldb::StackFrameSP &frame_sp);
/// Get accessor that creates a strong reference from the weak target
/// reference contained in this object.
///
- /// @returns
+ /// \returns
/// A shared pointer to a target that is not guaranteed to be valid.
//------------------------------------------------------------------
lldb::TargetSP GetTargetSP() const;
/// Get accessor that creates a strong reference from the weak process
/// reference contained in this object.
///
- /// @returns
+ /// \returns
/// A shared pointer to a process that is not guaranteed to be valid.
//------------------------------------------------------------------
lldb::ProcessSP GetProcessSP() const;
/// Get accessor that creates a strong reference from the weak thread
/// reference contained in this object.
///
- /// @returns
+ /// \returns
/// A shared pointer to a thread that is not guaranteed to be valid.
//------------------------------------------------------------------
lldb::ThreadSP GetThreadSP() const;
/// Get accessor that creates a strong reference from the weak frame
/// reference contained in this object.
///
- /// @returns
+ /// \returns
/// A shared pointer to a frame that is not guaranteed to be valid.
//------------------------------------------------------------------
lldb::StackFrameSP GetFrameSP() const;
///
/// Create strong references to any execution context objects that are still
/// valid. Any of the returned shared pointers in the ExecutionContext
- /// objects is not guaranteed to be valid. @returns
+ /// objects is not guaranteed to be valid. \returns
/// An execution context object that has strong references to
/// any valid weak references in this object.
//------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class ExecutionContext ExecutionContext.h
+/// \class ExecutionContext ExecutionContext.h
/// "lldb/Target/ExecutionContext.h"
/// A class that contains an execution context.
///
///
/// Initialize with process \a p, thread \a t, and frame index \a f.
///
- /// @param[in] process
+ /// \param[in] process
/// The process for this execution context.
///
- /// @param[in] thread
+ /// \param[in] thread
/// The thread for this execution context.
///
- /// @param[in] frame
+ /// \param[in] frame
/// The frame index for this execution context.
//------------------------------------------------------------------
ExecutionContext(Process *process, Thread *thread = nullptr,
/// validate this pointer so that this accessor can freely be used without
/// having to check for nullptr each time.
///
- /// @see ExecutionContext::HasTargetScope() const @see
+ /// \see ExecutionContext::HasTargetScope() const @see
/// ExecutionContext::HasProcessScope() const @see
/// ExecutionContext::HasThreadScope() const @see
/// ExecutionContext::HasFrameScope() const
/// pointer so that this accessor can freely be used without having to check
/// for nullptr each time.
///
- /// @see ExecutionContext::HasProcessScope() const @see
+ /// \see ExecutionContext::HasProcessScope() const @see
/// ExecutionContext::HasThreadScope() const @see
/// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
/// accessor can freely be used without having to check for nullptr each
/// time.
///
- /// @see ExecutionContext::HasThreadScope() const @see
+ /// \see ExecutionContext::HasThreadScope() const @see
/// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Thread *GetThreadPtr() const { return m_thread_sp.get(); }
/// to pre-validate this pointer so that this accessor can freely be used
/// without having to check for nullptr each time.
///
- /// @see ExecutionContext::HasFrameScope() const
+ /// \see ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
StackFrame *GetFramePtr() const { return m_frame_sp.get(); }
/// HasThreadScope(), or HasFrameScope() prior to calling this function to
/// ensure that this ExecutionContext object contains a valid target.
///
- /// @see ExecutionContext::HasTargetScope() const @see
+ /// \see ExecutionContext::HasTargetScope() const @see
/// ExecutionContext::HasProcessScope() const @see
/// ExecutionContext::HasThreadScope() const @see
/// ExecutionContext::HasFrameScope() const
/// HasFrameScope() prior to calling this function to ensure that this
/// ExecutionContext object contains a valid target.
///
- /// @see ExecutionContext::HasProcessScope() const @see
+ /// \see ExecutionContext::HasProcessScope() const @see
/// ExecutionContext::HasThreadScope() const @see
/// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
/// calling this function to ensure that this ExecutionContext object
/// contains a valid target.
///
- /// @see ExecutionContext::HasThreadScope() const @see
+ /// \see ExecutionContext::HasThreadScope() const @see
/// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Thread &GetThreadRef() const;
/// Clients should call HasFrameScope() prior to calling this function to
/// ensure that this ExecutionContext object contains a valid target.
///
- /// @see ExecutionContext::HasFrameScope() const
+ /// \see ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
StackFrame &GetFrameRef() const;
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ExecutionContextScope ExecutionContextScope.h
+/// \class ExecutionContextScope ExecutionContextScope.h
/// "lldb/Symbol/ExecutionContextScope.h" Inherit from this if your object can
/// reconstruct its
/// execution context.
/// so function calls that require a execution context can be made for the
/// given object.
///
- /// @param[out] exe_ctx
+ /// \param[out] exe_ctx
/// A reference to an execution context object that gets filled
/// in.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class JITLoader JITLoader.h "lldb/Target/JITLoader.h"
+/// \class JITLoader JITLoader.h "lldb/Target/JITLoader.h"
/// A plug-in interface definition class for JIT loaders.
///
/// Plugins of this kind listen for code generated at runtime in the target.
/// Scans the installed DynamicLoader plug-ins and tries to find all
/// applicable instances for the current process.
///
- /// @param[in] process
+ /// \param[in] process
/// The process for which to try and locate a JIT loader
/// plug-in instance.
///
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class JITLoaderList JITLoaderList.h "lldb/Target/JITLoaderList.h"
+/// \class JITLoaderList JITLoaderList.h "lldb/Target/JITLoaderList.h"
///
/// Class used by the Process to hold a list of its JITLoaders.
//----------------------------------------------------------------------
class UUID;
//----------------------------------------------------------------------
-/// @class ModuleCache ModuleCache.h "lldb/Target/ModuleCache.h"
+/// \class ModuleCache ModuleCache.h "lldb/Target/ModuleCache.h"
/// A module cache class.
///
/// Caches locally modules that are downloaded from remote targets. Each
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class OperatingSystem OperatingSystem.h "lldb/Target/OperatingSystem.h"
+/// \class OperatingSystem OperatingSystem.h "lldb/Target/OperatingSystem.h"
/// A plug-in interface definition class for halted OS helpers.
///
/// Halted OS plug-ins can be used by any process to locate and create
/// Scans the installed OperatingSystem plug-ins and tries to find an
/// instance that matches the current target triple and executable.
///
- /// @param[in] process
+ /// \param[in] process
/// The process for which to try and locate a halted OS
/// plug-in instance.
///
- /// @param[in] plugin_name
+ /// \param[in] plugin_name
/// An optional name of a specific halted OS plug-in that
/// should be used. If NULL, pick the best plug-in.
//------------------------------------------------------------------
/// does NOT stat the file system so it can be used in tight loops
/// where debug info is being parsed.
///
- /// @param[in] path
+ /// \param[in] path
/// The original source file path to try and remap.
///
- /// @param[out] new_path
+ /// \param[out] new_path
/// The newly remapped filespec that is may or may not exist.
///
- /// @return
+ /// \return
/// /b true if \a path was successfully located and \a new_path
/// is filled in with a new source path, \b false otherwise.
//------------------------------------------------------------------
/// or are even on the local file system, so use this function
/// sparingly (not in a tight debug info parsing loop).
///
- /// @param[in] orig_spec
+ /// \param[in] orig_spec
/// The original source file path to try and remap.
///
- /// @param[out] new_spec
+ /// \param[out] new_spec
/// The newly remapped filespec that is guaranteed to exist.
///
- /// @return
+ /// \return
/// /b true if \a orig_spec was successfully located and
/// \a new_spec is filled in with an existing file spec,
/// \b false otherwise.
typedef llvm::SmallVector<lldb::addr_t, 6> MmapArgList;
//----------------------------------------------------------------------
-/// @class Platform Platform.h "lldb/Target/Platform.h"
+/// \class Platform Platform.h "lldb/Target/Platform.h"
/// A plug-in interface definition class for debug platform that
/// includes many platform abilities such as:
-/// @li getting platform information such as supported architectures,
+/// \li getting platform information such as supported architectures,
/// supported binary file formats and more
-/// @li launching new processes
-/// @li attaching to existing processes
-/// @li download/upload files
-/// @li execute shell commands
-/// @li listing and getting info for existing processes
-/// @li attaching and possibly debugging the platform's kernel
+/// \li launching new processes
+/// \li attaching to existing processes
+/// \li download/upload files
+/// \li execute shell commands
+/// \li listing and getting info for existing processes
+/// \li attaching and possibly debugging the platform's kernel
//----------------------------------------------------------------------
class Platform : public PluginInterface {
public:
/// Scans the installed Platform plug-ins and tries to find an instance that
/// can be used for \a process
///
- /// @param[in] process
+ /// \param[in] process
/// The process for which to try and locate a platform
/// plug-in instance.
///
- /// @param[in] plugin_name
+ /// \param[in] plugin_name
/// An optional name of a specific platform plug-in that
/// should be used. If nullptr, pick the best plug-in.
//------------------------------------------------------------------
/// application bundles or executable wrappers can also be inspected for the
/// actual application binary within the bundle that should be used.
///
- /// @return
+ /// \return
/// Returns \b true if this Platform plug-in was able to find
/// a suitable executable, \b false otherwise.
//------------------------------------------------------------------
/// support symbol files that are bundles and know how to extract the right
/// symbol file given a bundle.
///
- /// @param[in] target
+ /// \param[in] target
/// The target in which we are trying to resolve the symbol file.
/// The target has a list of modules that we might be able to
/// use in order to help find the right symbol file. If the
/// is specified, we can use a variety of tricks to locate the
/// symbols in an SDK, PDK, or other development kit location.
///
- /// @param[in] sym_spec
+ /// \param[in] sym_spec
/// A module spec that describes some information about the
/// symbol file we are trying to resolve. The ModuleSpec might
/// contain the following:
/// a symbol file, or resolve an symbol file in a
/// symbol file bundle.
///
- /// @param[out] sym_file
+ /// \param[out] sym_file
/// The resolved symbol file spec if the returned error
/// indicates success.
///
- /// @return
+ /// \return
/// Returns an error that describes success or failure.
//------------------------------------------------------------------
virtual Status ResolveSymbolFile(Target &target, const ModuleSpec &sym_spec,
/// The default implementation of this function will return the same file
/// patch in \a local_file as was in \a platform_file.
///
- /// @param[in] platform_file
+ /// \param[in] platform_file
/// The platform file path to locate and cache locally.
///
- /// @param[in] uuid_ptr
+ /// \param[in] uuid_ptr
/// If we know the exact UUID of the file we are looking for, it
/// can be specified. If it is not specified, we might now know
/// the exact file. The UUID is usually some sort of MD5 checksum
/// file queries to ensure we are finding the correct file, not
/// just a file at the correct path.
///
- /// @param[out] local_file
+ /// \param[out] local_file
/// A locally cached version of the platform file. For platforms
/// that describe the current host computer, this will just be
/// the same file. For remote platforms, this file might come from
/// and SDK directory, or might need to be sync'ed over to the
/// current machine for efficient debugging access.
///
- /// @return
+ /// \return
/// An error object.
//------------------------------------------------------------------
virtual Status GetFileWithUUID(const FileSpec &platform_file,
/// Get the platform's supported architectures in the order in which they
/// should be searched.
///
- /// @param[in] idx
+ /// \param[in] idx
/// A zero based architecture index
///
- /// @param[out] arch
+ /// \param[out] arch
/// A copy of the architecture at index if the return value is
/// \b true.
///
- /// @return
+ /// \return
/// \b true if \a arch was filled in and is valid, \b false
/// otherwise.
//------------------------------------------------------------------
/// attached to the process, or an empty shared pointer with an appropriate
/// error.
///
- /// @param[in] pid
+ /// \param[in] pid
/// The process ID that we should attempt to attach to.
///
- /// @return
+ /// \return
/// An appropriate ProcessSP containing a valid shared pointer
/// to the default Process subclass for the platform that is
/// attached to the process, or an empty shared pointer with an
/// the attach. If DoAttach returns \b true, then Process::DidAttach() will
/// be called.
///
- /// @param[in] process_name
+ /// \param[in] process_name
/// A process name to match against the current process list.
///
- /// @return
+ /// \return
/// Returns \a pid if attaching was successful, or
/// LLDB_INVALID_PROCESS_ID if attaching fails.
//------------------------------------------------------------------
/// application/framework/shared library, then this extra registration can
/// be done.
///
- /// @param[in] src
+ /// \param[in] src
/// The source file/directory to install on the remote system.
///
- /// @param[in] dst
+ /// \param[in] dst
/// The destination file/directory where \a src will be installed.
/// If \a dst has no filename specified, then its filename will
/// be set from \a src. It \a dst has no directory specified, it
/// platform working directory will be prepended to the relative
/// directory.
///
- /// @return
+ /// \return
/// An error object that describes anything that went wrong.
//----------------------------------------------------------------------
virtual Status Install(const FileSpec &src, const FileSpec &dst);
/// dispatch_qaddr this Platform method will locate the queue name and
/// provide that.
///
- /// @param[in] process
+ /// \param[in] process
/// A process is required for reading memory.
///
- /// @param[in] dispatch_qaddr
+ /// \param[in] dispatch_qaddr
/// The dispatch_qaddr for this thread.
///
- /// @return
+ /// \return
/// The name of the queue, if there is one. An empty string
/// means that this thread is not associated with a dispatch
/// queue.
/// dispatch_qaddr this Platform method will locate the queue ID and provide
/// that.
///
- /// @param[in] process
+ /// \param[in] process
/// A process is required for reading memory.
///
- /// @param[in] dispatch_qaddr
+ /// \param[in] dispatch_qaddr
/// The dispatch_qaddr for this thread.
///
- /// @return
+ /// \return
/// The queue_id for this thread, if this thread is associated
/// with a dispatch queue. Else LLDB_INVALID_QUEUE_ID is returned.
//------------------------------------------------------------------
/// signal handler routines as needed. For most Unix platforms, add
/// _sigtramp.
///
- /// @return
+ /// \return
/// A list of symbol names. The list may be empty.
//------------------------------------------------------------------
virtual const std::vector<ConstString> &GetTrapHandlerSymbolNames();
/// Executable might exist within the Platform SDK directories, or in
/// standard tool directories within the current IDE that is running LLDB.
///
- /// @param[in] basename
+ /// \param[in] basename
/// The basename of the executable to locate in the current
/// platform.
///
- /// @return
+ /// \return
/// A FileSpec pointing to the executable on disk, or an invalid
/// FileSpec if the executable cannot be found.
//------------------------------------------------------------------
/// fail in the dynamic loader plug-in says it isn't safe to try and load
/// shared libraries at the moment.
///
- /// @param[in] process
+ /// \param[in] process
/// The process to load the image.
///
- /// @param[in] local_file
+ /// \param[in] local_file
/// The file spec that points to the shared library that you want
/// to load if the library is located on the host. The library will
/// be copied over to the location specified by remote_file or into
/// the current working directory with the same filename if the
/// remote_file isn't specified.
///
- /// @param[in] remote_file
+ /// \param[in] remote_file
/// If local_file is specified then the location where the library
/// should be copied over from the host. If local_file isn't
/// specified, then the path for the shared library on the target
/// what you want to load.
///
- /// @param[out] error
+ /// \param[out] error
/// An error object that gets filled in with any errors that
/// might occur when trying to load the shared library.
///
- /// @return
+ /// \return
/// A token that represents the shared library that can be
/// later used to unload the shared library. A value of
/// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
/// Load a shared library specified by base name into this process,
/// looking by hand along a set of paths.
///
- /// @param[in] process
+ /// \param[in] process
/// The process to load the image.
///
- /// @param[in] library_name
+ /// \param[in] library_name
/// The name of the library to look for. If library_name is an
/// absolute path, the basename will be extracted and searched for
/// along the paths. This emulates the behavior of the loader when
/// given an install name and a set (e.g. DYLD_LIBRARY_PATH provided) of
/// alternate paths.
///
- /// @param[in] path_list
+ /// \param[in] path_list
/// The list of paths to use to search for the library. First
/// match wins.
///
- /// @param[out] error
+ /// \param[out] error
/// An error object that gets filled in with any errors that
/// might occur when trying to load the shared library.
///
- /// @param[out] loaded_path
+ /// \param[out] loaded_path
/// If non-null, the path to the dylib that was successfully loaded
/// is stored in this path.
///
- /// @return
+ /// \return
/// A token that represents the shared library which can be
/// passed to UnloadImage. A value of
/// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
/// If the platform have a list of processes waiting for a debugger to
/// connect to them then connect to all of these pending processes.
///
- /// @param[in] debugger
+ /// \param[in] debugger
/// The debugger used for the connect.
///
- /// @param[out] error
+ /// \param[out] error
/// If an error occurred during the connect then this object will
/// contain the error message.
///
- /// @return
+ /// \return
/// The number of processes we are successfully connected to.
//------------------------------------------------------------------
virtual size_t ConnectToWaitingProcesses(lldb_private::Debugger &debugger,
}
//----------------------------------------------------------------------
-/// @class Process Process.h "lldb/Target/Process.h"
+/// \class Process Process.h "lldb/Target/Process.h"
/// A plug-in interface definition class for debugging a process.
//----------------------------------------------------------------------
class Process : public std::enable_shared_from_this<Process>,
/// A notification structure that can be used by clients to listen
/// for changes in a process's lifetime.
///
-/// @see RegisterNotificationCallbacks (const Notifications&) @see
+/// \see RegisterNotificationCallbacks (const Notifications&) @see
/// UnregisterNotificationCallbacks (const Notifications&)
//------------------------------------------------------------------
#ifndef SWIG
/// Process plug-in interface and returns the first instance that can debug
/// the file.
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// The module shared pointer that this process will debug.
///
- /// @param[in] plugin_name
+ /// \param[in] plugin_name
/// If nullptr, select the best plug-in for the binary. If non-nullptr
/// then look for a plugin whose PluginInfo's name matches
/// this string.
///
- /// @see Process::CanDebug ()
+ /// \see Process::CanDebug ()
//------------------------------------------------------------------
static lldb::ProcessSP FindPlugin(lldb::TargetSP target_sp,
llvm::StringRef plugin_name,
/// \a module. If the Process plug-in instance can debug a file on the
/// current system, it should return \b true.
///
- /// @return
+ /// \return
/// Returns \b true if this Process plug-in instance can
/// debug the executable, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return whether this object is valid (i.e. has not been finalized.)
///
- /// @return
+ /// \return
/// Returns \b true if this Process has not been finalized
/// and \b false otherwise.
//------------------------------------------------------------------
///
/// (lldb) process command <args>
///
- /// @return
+ /// \return
/// A CommandObject which can be one of the concrete subclasses
/// of CommandObject like CommandObjectRaw, CommandObjectParsed,
/// or CommandObjectMultiword.
/// launching. If DoLaunch returns \b true, then Process::DidLaunch() will
/// be called.
///
- /// @param[in] launch_info
+ /// \param[in] launch_info
/// Details regarding the environment, STDIN/STDOUT/STDERR
/// redirection, working path, etc. related to the requested launch.
///
- /// @return
+ /// \return
/// An error object. Call GetID() to get the process ID if
/// the error object is success.
//------------------------------------------------------------------
/// Get the cached UtilityFunction that assists in loading binary images
/// into the process.
///
- /// @param[in] platform
+ /// \param[in] platform
/// The platform fetching the UtilityFunction.
- /// @param[in] factory
+ /// \param[in] factory
/// A function that will be called only once per-process in a
/// thread-safe way to create the UtilityFunction if it has not
/// been initialized yet.
///
- /// @return
+ /// \return
/// The cached utility function or null if the platform is not the
/// same as the target's platform.
//------------------------------------------------------------------
//
// The default action is to return an empty data buffer.
//
- // @return
+ // \return
// A data buffer containing the contents of the AUXV data.
//------------------------------------------------------------------
virtual const lldb::DataBufferSP GetAuxvData();
/// plug-ins can use this function if they can't determine the current
/// shared library load state.
///
- /// @return
+ /// \return
/// The number of shared libraries that were loaded
//------------------------------------------------------------------
virtual size_t LoadModules() { return 0; }
//------------------------------------------------------------------
/// Get the system runtime plug-in for this process.
///
- /// @return
+ /// \return
/// Returns a pointer to the SystemRuntime plugin for this Process
/// if one is available. Else returns nullptr.
//------------------------------------------------------------------
/// char *) will be called to actually do the attach. If DoAttach returns \b
/// true, then Process::DidAttach() will be called.
///
- /// @param[in] pid
+ /// \param[in] pid
/// The process ID that we should attempt to attach to.
///
- /// @return
+ /// \return
/// Returns \a pid if attaching was successful, or
/// LLDB_INVALID_PROCESS_ID if attaching fails.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Attach to a remote system via a URL
///
- /// @param[in] strm
+ /// \param[in] strm
/// A stream where output intended for the user
/// (if the driver has a way to display that) generated during
/// the connection. This may be nullptr if no output is needed.A
///
- /// @param[in] remote_url
+ /// \param[in] remote_url
/// The URL format that we are connecting to.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status ConnectRemote(Stream *strm, llvm::StringRef remote_url);
/// opposed to the DynamicLoader interface) to ensure that remote debugging
/// can take advantage of this functionality.
///
- /// @return
+ /// \return
/// The address of the dynamic loader information, or
/// LLDB_INVALID_ADDRESS if this is not supported by this
/// interface.
/// Clients can register notification callbacks by filling out a
/// Process::Notifications structure and calling this function.
///
-/// @param[in] callbacks
+/// \param[in] callbacks
/// A structure that contains the notification baton and
/// callback functions.
///
-/// @see Process::Notifications
+/// \see Process::Notifications
//------------------------------------------------------------------
#ifndef SWIG
void RegisterNotificationCallbacks(const Process::Notifications &callbacks);
/// Clients can unregister notification callbacks by passing a copy of the
/// original baton and callbacks in \a callbacks.
///
-/// @param[in] callbacks
+/// \param[in] callbacks
/// A structure that contains the notification baton and
/// callback functions.
///
-/// @return
+/// \return
/// Returns \b true if the notification callbacks were
/// successfully removed from the process, \b false otherwise.
///
-/// @see Process::Notifications
+/// \see Process::Notifications
//------------------------------------------------------------------
#ifndef SWIG
bool UnregisterNotificationCallbacks(const Process::Notifications &callbacks);
/// use PrivateResume (though you should only do that from inside the
/// Process class.
///
- /// @return
+ /// \return
/// Returns an error object.
///
- /// @see Thread:Resume()
- /// @see Thread:Step()
- /// @see Thread:Suspend()
+ /// \see Thread:Resume()
+ /// \see Thread:Step()
+ /// \see Thread:Suspend()
//------------------------------------------------------------------
Status Resume();
/// GetInterrupted will be broadcast. If false, we will halt the process
/// with no events generated by the halt.
///
- /// @param[in] clear_thread_plans
+ /// \param[in] clear_thread_plans
/// If true, when the process stops, clear all thread plans.
///
- /// @param[in] use_run_lock
+ /// \param[in] use_run_lock
/// Whether to release the run lock after the stop.
///
- /// @return
+ /// \return
/// Returns an error object. If the error is empty, the process is
/// halted.
/// otherwise the halt has failed.
///
/// This function is not meant to be overridden by Process subclasses.
///
- /// @param[in] keep_stopped
+ /// \param[in] keep_stopped
/// If true, don't resume the process on detach.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
Status Detach(bool keep_stopped);
///
/// This function is not meant to be overridden by Process subclasses.
///
- /// @param[in] force_kill
+ /// \param[in] force_kill
/// Whether lldb should force a kill (instead of a detach) from
/// the inferior process. Normally if lldb launched a binary and
/// Destory is called, lldb kills it. If lldb attached to a
/// this behavior needs to be over-ridden, this is the bool that
/// can be used.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
Status Destroy(bool force_kill);
///
/// This function is not meant to be overridden by Process subclasses.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
Status Signal(int signal);
///
/// Allow Process plug-ins to execute some code before attaching a process.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status WillAttachToProcessWithID(lldb::pid_t pid) { return Status(); }
///
/// Allow Process plug-ins to execute some code before attaching a process.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status WillAttachToProcessWithName(const char *process_name,
//------------------------------------------------------------------
/// Attach to a remote system via a URL
///
- /// @param[in] strm
+ /// \param[in] strm
/// A stream where output intended for the user
/// (if the driver has a way to display that) generated during
/// the connection. This may be nullptr if no output is needed.A
///
- /// @param[in] remote_url
+ /// \param[in] remote_url
/// The URL format that we are connecting to.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status DoConnectRemote(Stream *strm, llvm::StringRef remote_url) {
//------------------------------------------------------------------
/// Attach to an existing process using a process ID.
///
- /// @param[in] pid
+ /// \param[in] pid
/// The process ID that we should attempt to attach to.
///
- /// @param[in] attach_info
+ /// \param[in] attach_info
/// Information on how to do the attach. For example, GetUserID()
/// will return the uid to attach as.
///
- /// @return
+ /// \return
/// Returns a successful Status attaching was successful, or
/// an appropriate (possibly platform-specific) error code if
/// attaching fails.
//------------------------------------------------------------------
/// Attach to an existing process using a partial process name.
///
- /// @param[in] process_name
+ /// \param[in] process_name
/// The name of the process to attach to.
///
- /// @param[in] attach_info
+ /// \param[in] attach_info
/// Information on how to do the attach. For example, GetUserID()
/// will return the uid to attach as.
///
- /// @return
+ /// \return
/// Returns a successful Status attaching was successful, or
/// an appropriate (possibly platform-specific) error code if
/// attaching fails.
//------------------------------------------------------------------
/// Called after attaching a process.
///
- /// @param[in] process_arch
+ /// \param[in] process_arch
/// If you can figure out the process architecture after attach, fill it
/// in here.
///
///
/// Allow Process plug-ins to execute some code before launching a process.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status WillLaunch(Module *module) { return Status(); }
/// file as the file to launch. Launch details are provided in \a
/// launch_info.
///
- /// @param[in] exe_module
+ /// \param[in] exe_module
/// The module from which to extract the file specification and
/// launch.
///
- /// @param[in] launch_info
+ /// \param[in] launch_info
/// Details (e.g. arguments, stdio redirection, etc.) for the
/// requested launch.
///
- /// @return
+ /// \return
/// An Status instance indicating success or failure of the
/// operation.
//------------------------------------------------------------------
///
/// Allow Process plug-ins to execute some code before resuming a process.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status WillResume() { return Status(); }
/// process is resumed. If no run control action is given to a thread it
/// will be resumed by default.
///
- /// @return
+ /// \return
/// Returns \b true if the process successfully resumes using
/// the thread run control actions, \b false otherwise.
///
- /// @see Thread:Resume()
- /// @see Thread:Step()
- /// @see Thread:Suspend()
+ /// \see Thread:Resume()
+ /// \see Thread:Step()
+ /// \see Thread:Suspend()
//------------------------------------------------------------------
virtual Status DoResume() {
Status error;
///
/// Allow Process plug-ins to execute some code before halting a process.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status WillHalt() { return Status(); }
/// Otherwise, you must generate the event manually. This function is called
/// from the context of the private state thread.
///
- /// @param[out] caused_stop
+ /// \param[out] caused_stop
/// If true, then this Halt caused the stop, otherwise, the
/// process was already stopped.
///
- /// @return
+ /// \return
/// Returns \b true if the process successfully halts, \b false
/// otherwise.
//------------------------------------------------------------------
/// Allow Process plug-ins to execute some code before detaching from a
/// process.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status WillDetach() { return Status(); }
//------------------------------------------------------------------
/// Detaches from a running or stopped process.
///
- /// @return
+ /// \return
/// Returns \b true if the process successfully detaches, \b
/// false otherwise.
//------------------------------------------------------------------
/// Allow Process plug-ins to execute some code before sending a signal to a
/// process.
///
- /// @return
+ /// \return
/// Returns no error if it is safe to proceed with a call to
/// Process::DoSignal(int), otherwise an error describing what
/// prevents the signal from being sent.
//------------------------------------------------------------------
/// Sends a process a UNIX signal \a signal.
///
- /// @return
+ /// \return
/// Returns an error object.
//------------------------------------------------------------------
virtual Status DoSignal(int signal) {
/// platform that might itself be running natively, but have different
/// heuristics for figuring out which OS is is emulating.
///
- /// @return
+ /// \return
/// Returns the version tuple of the host OS. In case of failure an empty
/// VersionTuple is returner.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the target object pointer for this module.
///
- /// @return
+ /// \return
/// A Target object pointer to the target that owns this
/// module.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the const target object pointer for this module.
///
- /// @return
+ /// \return
/// A const Target object pointer to the target that owns this
/// module.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get accessor for the current process state.
///
- /// @return
+ /// \return
/// The current state of the process.
///
- /// @see lldb::StateType
+ /// \see lldb::StateType
//------------------------------------------------------------------
lldb::StateType GetState();
/// memory and return a concise summary sufficient for the DynamicLoader
/// plugin.
///
- /// @param [in] image_list_address
+ /// \param [in] image_list_address
/// The address where the table of shared libraries is stored in memory,
/// if that is appropriate for this platform. Else this may be
/// passed as LLDB_INVALID_ADDRESS.
///
- /// @param [in] image_count
+ /// \param [in] image_count
/// The number of shared libraries that are present in this process, if
/// that is appropriate for this platofrm Else this may be passed as
/// LLDB_INVALID_ADDRESS.
///
- /// @return
+ /// \return
/// A StructureDataSP object which, if non-empty, will contain the
/// information the DynamicLoader needs to get the initial scan of
/// solibs resolved.
/// Prints a async warning message to the user one time per Module where a
/// function is found that was compiled with optimization, per Process.
///
- /// @param [in] sc
+ /// \param [in] sc
/// A SymbolContext with eSymbolContextFunction and eSymbolContextModule
/// pre-computed.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the exit status for a process.
///
- /// @return
+ /// \return
/// The process's return code, or -1 if the current process
/// state is not eStateExited.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get a textual description of what the process exited.
///
- /// @return
+ /// \return
/// The textual description of why the process exited, or nullptr
/// if there is no description available.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the Modification ID of the process.
///
- /// @return
+ /// \return
/// The modification ID of the process.
//------------------------------------------------------------------
ProcessModID GetModID() const { return m_mod_id; }
/// Setting this will cause a eStateExited event to be posted to the process
/// event queue.
///
- /// @param[in] exit_status
+ /// \param[in] exit_status
/// The value for the process's return code.
///
- /// @see lldb::StateType
+ /// \see lldb::StateType
//------------------------------------------------------------------
virtual bool SetExitStatus(int exit_status, const char *cstr);
//------------------------------------------------------------------
/// Check if a process is still alive.
///
- /// @return
+ /// \return
/// Returns \b true if the process is still valid, \b false
/// otherwise.
//------------------------------------------------------------------
/// user can reconstruct the "state" by simply re-running the debugger on
/// the core file.
///
- /// @return
+ /// \return
// true if the user should be warned about detaching from this process.
//------------------------------------------------------------------
virtual bool WarnBeforeDetach() const { return true; }
/// requested when memory requests are too large. This class will break up
/// the memory requests and keep advancing the arguments along as needed.
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// A virtual load address that indicates where to start reading
/// memory from.
///
- /// @param[in] size
+ /// \param[in] size
/// The number of bytes to read.
///
- /// @param[out] buf
+ /// \param[out] buf
/// A byte buffer that is at least \a size bytes long that
/// will receive the memory bytes.
///
- /// @param[out] error
+ /// \param[out] error
/// An error that indicates the success or failure of this
/// operation. If error indicates success (error.Success()),
/// then the value returned can be trusted, otherwise zero
/// will be returned.
///
- /// @return
+ /// \return
/// The number of bytes that were actually read into \a buf.
/// Zero is returned in the case of an error.
//------------------------------------------------------------------
/// subclasses should implement Process::DoReadMemory (lldb::addr_t, size_t,
/// void *).
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// A virtual load address that indicates where to start reading
/// memory from.
///
- /// @param[out] buf
+ /// \param[out] buf
/// A byte buffer that is at least \a size bytes long that
/// will receive the memory bytes.
///
- /// @param[in] size
+ /// \param[in] size
/// The number of bytes to read.
///
- /// @param[out] error
+ /// \param[out] error
/// An error that indicates the success or failure of this
/// operation. If error indicates success (error.Success()),
/// then the value returned can be trusted, otherwise zero
/// will be returned.
///
- /// @return
+ /// \return
/// The number of bytes that were actually read into \a buf. If
/// the returned number is greater than zero, yet less than \a
/// size, then this function will get called again with \a
/// terminated, and that no more than (max_bytes - type_width) bytes will be
/// read.
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// The virtual load address to start the memory read.
///
- /// @param[in] str
+ /// \param[in] str
/// A character buffer containing at least max_bytes.
///
- /// @param[in] max_bytes
+ /// \param[in] max_bytes
/// The maximum number of bytes to read.
///
- /// @param[in] error
+ /// \param[in] error
/// The error status of the read operation.
///
- /// @param[in] type_width
+ /// \param[in] type_width
/// The size of the null terminator (1 to 4 bytes per
/// character). Defaults to 1.
///
- /// @return
+ /// \return
/// The error status or the number of bytes prior to the null terminator.
//------------------------------------------------------------------
size_t ReadStringFromMemory(lldb::addr_t vm_addr, char *str, size_t max_bytes,
/// Reads an unsigned integer of the specified byte size from process
/// memory.
///
- /// @param[in] load_addr
+ /// \param[in] load_addr
/// A load address of the integer to read.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in byte of the integer to read.
///
- /// @param[in] fail_value
+ /// \param[in] fail_value
/// The value to return if we fail to read an integer.
///
- /// @param[out] error
+ /// \param[out] error
/// An error that indicates the success or failure of this
/// operation. If error indicates success (error.Success()),
/// then the value returned can be trusted, otherwise zero
/// will be returned.
///
- /// @return
+ /// \return
/// The unsigned integer that was read from the process memory
/// space. If the integer was smaller than a uint64_t, any
/// unused upper bytes will be zero filled. If the process
//------------------------------------------------------------------
/// Actually do the writing of memory to a process.
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// A virtual load address that indicates where to start writing
/// memory to.
///
- /// @param[in] buf
+ /// \param[in] buf
/// A byte buffer that is at least \a size bytes long that
/// contains the data to write.
///
- /// @param[in] size
+ /// \param[in] size
/// The number of bytes to write.
///
- /// @param[out] error
+ /// \param[out] error
/// An error value in case the memory write fails.
///
- /// @return
+ /// \return
/// The number of bytes that were actually written.
//------------------------------------------------------------------
virtual size_t DoWriteMemory(lldb::addr_t vm_addr, const void *buf,
/// extra space will be padded with zeros and the scalar value will be
/// placed in the least significant bytes in memory.
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// A virtual load address that indicates where to start writing
/// memory to.
///
- /// @param[in] scalar
+ /// \param[in] scalar
/// The scalar to write to the debugged process.
///
- /// @param[in] size
+ /// \param[in] size
/// This value can be smaller or larger than the scalar value
/// itself. If \a size is smaller than the size of \a scalar,
/// the least significant bytes in \a scalar will be used. If
/// the extra space will be padded with zeros. If \a size is
/// set to UINT32_MAX, then the size of \a scalar will be used.
///
- /// @param[out] error
+ /// \param[out] error
/// An error value in case the memory write fails.
///
- /// @return
+ /// \return
/// The number of bytes that were actually written.
//------------------------------------------------------------------
size_t WriteScalarToMemory(lldb::addr_t vm_addr, const Scalar &scalar,
/// subclasses should implement Process::DoWriteMemory (lldb::addr_t,
/// size_t, void *).
///
- /// @param[in] vm_addr
+ /// \param[in] vm_addr
/// A virtual load address that indicates where to start writing
/// memory to.
///
- /// @param[in] buf
+ /// \param[in] buf
/// A byte buffer that is at least \a size bytes long that
/// contains the data to write.
///
- /// @param[in] size
+ /// \param[in] size
/// The number of bytes to write.
///
- /// @return
+ /// \return
/// The number of bytes that were actually written.
//------------------------------------------------------------------
// TODO: change this to take an ArrayRef<uint8_t>
/// can't rely on the generic function calling mechanism, since that
/// requires this function.
///
- /// @param[in] size
+ /// \param[in] size
/// The size of the allocation requested.
///
- /// @return
+ /// \return
/// The address of the allocated buffer in the process, or
/// LLDB_INVALID_ADDRESS if the allocation failed.
//------------------------------------------------------------------
/// can't rely on the generic function calling mechanism, since that
/// requires this function.
///
- /// @param[in] size
+ /// \param[in] size
/// The size of the allocation requested.
///
- /// @param[in] permissions
+ /// \param[in] permissions
/// Or together any of the lldb::Permissions bits. The permissions on
/// a given memory allocation can't be changed after allocation. Note
/// that a block that isn't set writable can still be written on from
/// lldb,
/// just not by the process itself.
///
- /// @param[in,out] error
+ /// \param[in,out] error
/// An error object to fill in if things go wrong.
- /// @return
+ /// \return
/// The address of the allocated buffer in the process, or
/// LLDB_INVALID_ADDRESS if the allocation failed.
//------------------------------------------------------------------
/// can't rely on the generic function calling mechanism, since that
/// requires this function.
///
- /// @param[in] size
+ /// \param[in] size
/// The size of the allocation requested.
///
- /// @param[in] permissions
+ /// \param[in] permissions
/// Or together any of the lldb::Permissions bits. The permissions on
/// a given memory allocation can't be changed after allocation. Note
/// that a block that isn't set writable can still be written on from
/// lldb,
/// just not by the process itself.
///
- /// @param[in/out] error
+ /// \param[in/out] error
/// An error object to fill in if things go wrong.
- /// @return
+ /// \return
/// The address of the allocated buffer in the process, or
/// LLDB_INVALID_ADDRESS if the allocation failed.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Resolve dynamically loaded indirect functions.
///
- /// @param[in] address
+ /// \param[in] address
/// The load address of the indirect function to resolve.
///
- /// @param[out] error
+ /// \param[out] error
/// An error value in case the resolve fails.
///
- /// @return
+ /// \return
/// The address of the resolved function.
/// LLDB_INVALID_ADDRESS if the resolution failed.
//------------------------------------------------------------------
/// GetMemoryRegionInfo will only return an error if it is unimplemented for
/// the current process.
///
- /// @param[in] load_addr
+ /// \param[in] load_addr
/// The load address to query the range_info for.
///
- /// @param[out] range_info
+ /// \param[out] range_info
/// An range_info value containing the details of the range.
///
- /// @return
+ /// \return
/// An error value.
//------------------------------------------------------------------
virtual Status GetMemoryRegionInfo(lldb::addr_t load_addr,
//------------------------------------------------------------------
/// Obtain all the mapped memory regions within this process.
///
- /// @param[out] region_list
+ /// \param[out] region_list
/// A vector to contain MemoryRegionInfo objects for all mapped
/// ranges.
///
- /// @return
+ /// \return
/// An error value.
//------------------------------------------------------------------
virtual Status
/// of memory at a given address or whether that page is
/// readable/writable/executable by the process.
///
- /// @param[in] load_addr
+ /// \param[in] load_addr
/// The address of interest in the process.
///
- /// @param[out] permissions
+ /// \param[out] permissions
/// If this call returns successfully, this bitmask will have
/// its Permissions bits set to indicate whether the region is
/// readable/writable/executable. If this call fails, the
/// bitmask values are undefined.
///
- /// @return
+ /// \return
/// Returns true if it was able to determine the attributes of the
/// memory region. False if not.
//------------------------------------------------------------------
/// Determines whether executing JIT-compiled code in this process is
/// possible.
///
- /// @return
+ /// \return
/// True if execution of JIT code is possible; false otherwise.
//------------------------------------------------------------------
bool CanJIT();
//------------------------------------------------------------------
/// Sets whether executing JIT-compiled code in this process is possible.
///
- /// @param[in] can_jit
+ /// \param[in] can_jit
/// True if execution of JIT code is possible; false otherwise.
//------------------------------------------------------------------
void SetCanJIT(bool can_jit);
/// Determines whether executing function calls using the interpreter is
/// possible for this process.
///
- /// @return
+ /// \return
/// True if possible; false otherwise.
//------------------------------------------------------------------
bool CanInterpretFunctionCalls() { return m_can_interpret_function_calls; }
/// Sets whether executing function calls using the interpreter is possible
/// for this process.
///
- /// @param[in] can_interpret_function_calls
+ /// \param[in] can_interpret_function_calls
/// True if possible; false otherwise.
//------------------------------------------------------------------
void SetCanInterpretFunctionCalls(bool can_interpret_function_calls) {
/// Sets whether executing code in this process is possible. This could be
/// either through JIT or interpreting.
///
- /// @param[in] can_run_code
+ /// \param[in] can_run_code
/// True if execution of code is possible; false otherwise.
//------------------------------------------------------------------
void SetCanRunCode(bool can_run_code);
/// This function will deallocate memory in the process's address space that
/// was allocated with AllocateMemory.
///
- /// @param[in] ptr
+ /// \param[in] ptr
/// A return value from AllocateMemory, pointing to the memory you
/// want to deallocate.
///
- /// @return
+ /// \return
/// \btrue if the memory was deallocated, \bfalse otherwise.
//------------------------------------------------------------------
virtual Status DoDeallocateMemory(lldb::addr_t ptr) {
/// This function will deallocate memory in the process's address space that
/// was allocated with AllocateMemory.
///
- /// @param[in] ptr
+ /// \param[in] ptr
/// A return value from AllocateMemory, pointing to the memory you
/// want to deallocate.
///
- /// @return
+ /// \return
/// \btrue if the memory was deallocated, \bfalse otherwise.
//------------------------------------------------------------------
Status DeallocateMemory(lldb::addr_t ptr);
/// Events will be queued indicating that there is STDOUT available that can
/// be retrieved using this function.
///
- /// @param[out] buf
+ /// \param[out] buf
/// A buffer that will receive any STDOUT bytes that are
/// currently available.
///
- /// @param[in] buf_size
+ /// \param[in] buf_size
/// The size in bytes for the buffer \a buf.
///
- /// @return
+ /// \return
/// The number of bytes written into \a buf. If this value is
/// equal to \a buf_size, another call to this function should
/// be made to retrieve more STDOUT data.
/// Events will be queued indicating that there is STDERR available that can
/// be retrieved using this function.
///
- /// @param[in] buf
+ /// \param[in] buf
/// A buffer that will receive any STDERR bytes that are
/// currently available.
///
- /// @param[out] buf_size
+ /// \param[out] buf_size
/// The size in bytes for the buffer \a buf.
///
- /// @return
+ /// \return
/// The number of bytes written into \a buf. If this value is
/// equal to \a buf_size, another call to this function should
/// be made to retrieve more STDERR data.
/// process was launched without supplying a valid file path
/// for STDIN.
///
- /// @param[in] buf
+ /// \param[in] buf
/// A buffer that contains the data to write to the process's STDIN.
///
- /// @param[in] buf_size
+ /// \param[in] buf_size
/// The size in bytes for the buffer \a buf.
///
- /// @return
+ /// \return
/// The number of bytes written into \a buf. If this value is
/// less than \a buf_size, another call to this function should
/// be made to write the rest of the data.
//------------------------------------------------------------------
/// Get any available profile data.
///
- /// @param[out] buf
+ /// \param[out] buf
/// A buffer that will receive any profile data bytes that are
/// currently available.
///
- /// @param[out] buf_size
+ /// \param[out] buf_size
/// The size in bytes for the buffer \a buf.
///
- /// @return
+ /// \return
/// The number of bytes written into \a buf. If this value is
/// equal to \a buf_size, another call to this function should
/// be made to retrieve more profile data.
/// The main purpose of this is to implement an interlock waiting for
/// HandlePrivateEvent to push an IOHandler.
///
- /// @param[in] timeout
+ /// \param[in] timeout
/// The maximum time length to wait for the process to transition to the
/// eStateRunning state.
//--------------------------------------------------------------------------------------
/// Centralize the code that handles and prints descriptions for process
/// state changes.
///
- /// @param[in] event_sp
+ /// \param[in] event_sp
/// The process state changed event
///
- /// @param[in] stream
+ /// \param[in] stream
/// The output stream to get the state change description
///
- /// @param[in,out] pop_process_io_handler
+ /// \param[in,out] pop_process_io_handler
/// If this value comes in set to \b true, then pop the Process IOHandler
/// if needed.
/// Else this variable will be set to \b true or \b false to indicate if
/// the process
/// needs to have its process IOHandler popped.
///
- /// @return
+ /// \return
/// \b true if the event describes a process state changed event, \b false
/// otherwise.
//--------------------------------------------------------------------------------------
/// WaitFor* calls above. Be sure to call RestoreProcessEvents when you are
/// done.
///
- /// @param[in] listener
+ /// \param[in] listener
/// This is the new listener to whom all process events will be delivered.
///
- /// @return
+ /// \return
/// Returns \b true if the new listener could be installed,
/// \b false otherwise.
//------------------------------------------------------------------
/// can immediately suspend it, and keep executing only the one thread you
/// intend.
///
- /// @return
+ /// \return
/// Returns \b true if we were able to start up the notification
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Call this to turn off the stop & notice new threads mode.
///
- /// @return
+ /// \return
/// Returns \b true if we were able to start up the notification
/// \b false otherwise.
//------------------------------------------------------------------
/// if they support platforms where the Platform object can't get the module
/// spec for all module.
///
- /// @param[in] module_file_spec
+ /// \param[in] module_file_spec
/// The file name of the module to get specification for.
///
- /// @param[in] arch
+ /// \param[in] arch
/// The architecture of the module to get specification for.
///
- /// @param[out] module_spec
+ /// \param[out] module_spec
/// The fetched module specification if the return value is
/// \b true, unchanged otherwise.
///
- /// @return
+ /// \return
/// Returns \b true if the module spec fetched successfully,
/// \b false otherwise.
//------------------------------------------------------------------
/// The load address is defined as the address of the first memory region
/// what contains data mapped from the specified file.
///
- /// @param[in] file
+ /// \param[in] file
/// The name of the file whose load address we are looking for
///
- /// @param[out] is_loaded
+ /// \param[out] is_loaded
/// \b True if the file is loaded into the memory and false
/// otherwise.
///
- /// @param[out] load_addr
+ /// \param[out] load_addr
/// The load address of the file if it is loaded into the
/// processes address space, LLDB_INVALID_ADDRESS otherwise.
//------------------------------------------------------------------
/// and continue the process to there, yielding significant performance
/// benefits over instruction stepping.
///
- /// @param[in] default_stop_addr
+ /// \param[in] default_stop_addr
/// The address of the instruction where lldb would put a
/// breakpoint normally.
///
- /// @param[in] range_bounds
+ /// \param[in] range_bounds
/// The range which the breakpoint must be contained within.
/// Typically a source line.
///
- /// @return
+ /// \return
/// The address of the next branch instruction, or the end of
/// the range provided in range_bounds. If there are any
/// problems with the disassembly or getting the instructions,
/// StructuredDataPlugin implementations will call this to configure a
/// feature that has been reported as being supported.
///
- /// @param[in] type_name
+ /// \param[in] type_name
/// The StructuredData type name as previously discovered by
/// the Process-derived instance.
///
- /// @param[in] config
+ /// \param[in] config
/// Configuration data for the feature being enabled. This config
/// data, which may be null, will be passed along to the feature
/// to process. The feature will dictate whether this is a dictionary,
/// set up properly before it can be enabled, then the config should
/// also take an enable/disable flag.
///
- /// @return
+ /// \return
/// Returns the result of attempting to configure the feature.
//------------------------------------------------------------------
virtual Status
/// will come in on the structured data event bit
/// (eBroadcastBitStructuredData).
///
- /// @param[in] object_sp
+ /// \param[in] object_sp
/// The structured data object to broadcast.
///
- /// @param[in] plugin_sp
+ /// \param[in] plugin_sp
/// The plugin that will be reported in the event's plugin
/// parameter.
//------------------------------------------------------------------
/// debugged process monitor claims that the feature is supported. This is
/// one way to tell whether a feature is available.
///
- /// @return
+ /// \return
/// The plugin if one is available for the specified feature;
/// otherwise, returns an empty shared pointer.
//------------------------------------------------------------------
/// The "private" side of resuming a process. This doesn't alter the state
/// of m_run_lock, but just causes the process to resume.
///
- /// @return
+ /// \return
/// An Status object describing the success or failure of the resume.
//------------------------------------------------------------------
Status PrivateResume();
/// that the warning strings are all centralized in Process, instead of
/// calling PrintWarning() directly.
///
- /// @param [in] warning_type
+ /// \param [in] warning_type
/// One of the types defined in Process::Warnings.
///
- /// @param [in] repeat_key
+ /// \param [in] repeat_key
/// A pointer value used to ensure that the warning is only printed once.
/// May be nullptr, indicating that the warning is printed unconditionally
/// every time.
///
- /// @param [in] fmt
+ /// \param [in] fmt
/// printf style format string
//------------------------------------------------------------------
void PrintWarning(uint64_t warning_type, const void *repeat_key,
/// named 'type', with a value that equals the relevant type name string
/// (one of the values in \b supported_type_names).
///
- /// @param[in] supported_type_names
+ /// \param[in] supported_type_names
/// An array of zero or more type names. Each must be unique.
/// For each entry in the list, a StructuredDataPlugin will be
/// searched for that supports the structured data type name.
/// key named 'type' that stores a string value. The string value must be
/// the name of the structured data feature that knows how to handle it.
///
- /// @param[in] object_sp
+ /// \param[in] object_sp
/// When non-null and pointing to a dictionary, the 'type'
/// key's string value is used to look up the plugin that
/// was registered for that structured data type. It then
/// const StructuredData::ObjectSP
/// &object_sp)
///
- /// @return
+ /// \return
/// True if the structured data was routed to a plugin; otherwise,
/// false.
//------------------------------------------------------------------
/// again. There is only one place where this call should be called,
/// HandlePrivateEvent. Don't call it from anywhere else...
///
- /// @param[in] event_ptr
+ /// \param[in] event_ptr
/// This is the event we are handling.
///
- /// @return
+ /// \return
/// Returns \b true if the event should be reported to the
/// user, \b false otherwise.
//------------------------------------------------------------------
/// each queue. A serialnum is not reused for a different queue in the
/// lifetime of that process execution.
///
- /// @return
+ /// \return
/// The QueueID for this Queue.
//------------------------------------------------------------------
lldb::queue_id_t GetID();
//------------------------------------------------------------------
/// Get the name of this Queue
///
- /// @return
+ /// \return
/// The name of the queue, if one is available.
/// A NULL pointer is returned if none is available.
//------------------------------------------------------------------
/// maintain similar API to the Thread class, and allow for the
/// possibility of GetID changing to a different source in the future.
///
- /// @return
+ /// \return
/// The IndexID for this queue.
//------------------------------------------------------------------
uint32_t GetIndexID();
/// a given point in time. This call returns the list of threads
/// that are currently executing work for this queue.
///
- /// @return
+ /// \return
/// The threads currently performing work for this queue
//------------------------------------------------------------------
std::vector<lldb::ThreadSP> GetThreads();
/// be done, but has not yet been done. When the item is going to
/// be processed it is "dequeued".
///
- /// @return
+ /// \return
/// The vector of enqueued items for this queue
//------------------------------------------------------------------
const std::vector<lldb::QueueItemSP> &GetPendingItems();
//------------------------------------------------------------------
/// Get the number of work items that this queue is currently running
///
- /// @return
+ /// \return
/// The number of work items currently executing. For a serial
/// queue, this will be 0 or 1. For a concurrent queue, this
/// may be any number.
//------------------------------------------------------------------
/// Get the number of work items enqueued on this queue
///
- /// @return
+ /// \return
/// The number of work items currently enqueued, waiting to
/// execute.
//------------------------------------------------------------------
/// Get the address in the inferior process' memory of this Queue's
/// dispatch_queue_t structure.
///
- /// @return
+ /// \return
/// The address of the dispatch_queue_t structure, if known.
/// LLDB_INVALID_ADDRESS will be returned if it is unavailable.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return the kind (serial, concurrent) of this queue
///
- /// @return
+ /// \return
// Whether this is a serial or a concurrent queue
//------------------------------------------------------------------
lldb::QueueKind GetKind();
//------------------------------------------------------------------
/// Get the kind of work item this is
///
- /// @return
+ /// \return
/// The type of work item that this QueueItem object
/// represents. eQueueItemKindUnknown may be returned.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the type of work item this is
///
- /// @param [in] item_kind
+ /// \param [in] item_kind
/// Set the kind of this work item object.
//------------------------------------------------------------------
void SetKind(lldb::QueueItemKind item_kind);
/// Get the code address that will be executed when this work item
/// is executed.
///
- /// @return
+ /// \return
/// The address that will be invoked when this work item is
/// executed. Not all types of QueueItems will have an
/// address associated with them; check that the returned
//------------------------------------------------------------------
/// Set the work item address for this object
///
- /// @param [in] addr
+ /// \param [in] addr
/// The address that will be invoked when this work item
/// is executed.
//------------------------------------------------------------------
/// If the weak pointer to the parent Queue cannot be revivified,
/// it is invalid.
///
- /// @return
+ /// \return
/// True if this object is valid.
//------------------------------------------------------------------
bool IsValid() { return m_queue_wp.lock() != nullptr; }
/// If the backtrace/thread information was collected when this item
/// was enqueued, this call will provide it.
///
- /// @param [in] type
+ /// \param [in] type
/// The type of extended backtrace being requested, e.g. "libdispatch"
/// or "pthread".
///
- /// @return
+ /// \return
/// A thread shared pointer which will have a reference to an extended
/// thread if one was available.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the number of libdispatch queues that are available
///
- /// @return
+ /// \return
/// The number of queues that are stored in the QueueList.
//------------------------------------------------------------------
uint32_t GetSize();
//------------------------------------------------------------------
/// Get the Queue at a given index number
///
- /// @param [in] idx
+ /// \param [in] idx
/// The index number (0-based) of the queue.
- /// @return
+ /// \return
/// The Queue at that index number.
//------------------------------------------------------------------
lldb::QueueSP GetQueueAtIndex(uint32_t idx);
//------------------------------------------------------------------
/// Iterate over the list of queues
///
- /// @return
+ /// \return
/// An Iterable object which can be used to loop over the queues
/// that exist.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Add a Queue to the QueueList
///
- /// @param [in] queue
+ /// \param [in] queue
/// Used by the SystemRuntime to populate the QueueList
//------------------------------------------------------------------
void AddQueue(lldb::QueueSP queue);
//------------------------------------------------------------------
/// Find a queue in the QueueList by QueueID
///
- /// @param [in] qid
+ /// \param [in] qid
/// The QueueID (same as returned by Thread::GetQueueID()) to find.
///
- /// @return
+ /// \return
/// A QueueSP to the queue requested, if it is present in the QueueList.
/// An empty QueueSP will be returned if this queue was not found.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find a queue in the QueueList by IndexID
///
- /// @param [in] index_id
+ /// \param [in] index_id
/// Find a queue by IndexID. This is an integer associated with each
/// unique queue seen during a debug session and will not be reused
/// for a different queue. Unlike the QueueID, a 64-bit value, this
/// will tend to be an integral value like 1 or 7.
///
- /// @return
+ /// \return
/// A QueueSP to the queue requested, if it is present in the QueueList.
/// An empty QueueSP will be returned if this queue was not found.
//------------------------------------------------------------------
/// This method translates a given register kind + register number into
/// the eRegisterKindLLDB register numbering.
///
- /// @param [in] kind
+ /// \param [in] kind
/// The register numbering scheme (RegisterKind) that the following
/// register number is in.
///
- /// @param [in] num
+ /// \param [in] num
/// A register number in the 'kind' register numbering scheme.
///
- /// @return
+ /// \return
/// The equivalent register number in the eRegisterKindLLDB
/// numbering scheme, if possible, else LLDB_INVALID_REGNUM.
//------------------------------------------------------------------
namespace lldb_private {
-/// @class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
+/// \class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
///
/// This base class provides an interface to stack frames.
///
/// point in the past. We may only have pc values. We may have a CFA,
/// or more likely, we won't.
///
- /// @param [in] thread_sp
+ /// \param [in] thread_sp
/// The Thread that this frame belongs to.
///
- /// @param [in] frame_idx
+ /// \param [in] frame_idx
/// This StackFrame's frame index number in the Thread. If inlined stack
/// frames are being created, this may differ from the concrete_frame_idx
/// which is the frame index without any inlined stack frames.
///
- /// @param [in] concrete_frame_idx
+ /// \param [in] concrete_frame_idx
/// The StackFrame's frame index number in the Thread without any inlined
/// stack frames being included in the index.
///
- /// @param [in] cfa
+ /// \param [in] cfa
/// The Canonical Frame Address (this terminology from DWARF) for this
/// stack frame. The CFA for a stack frame does not change over the
/// span of the stack frame's existence. It is often the value of the
/// function. It is usually not the same as the frame pointer register's
/// value.
///
- /// @param [in] cfa_is_valid
+ /// \param [in] cfa_is_valid
/// A history stack frame may not have a CFA value collected. We want to
/// distinguish between "no CFA available" and a CFA of
/// LLDB_INVALID_ADDRESS.
///
- /// @param [in] pc
+ /// \param [in] pc
/// The current pc value of this stack frame.
///
- /// @param [in] frame_kind
+ /// \param [in] frame_kind
///
- /// @param [in] sc_ptr
+ /// \param [in] sc_ptr
/// Optionally seed the StackFrame with the SymbolContext information that
/// has
/// already been discovered.
///
/// May not be the same as the actual PC value for inlined stack frames.
///
- /// @return
+ /// \return
/// The Address object set to the current PC value.
//------------------------------------------------------------------
const Address &GetFrameCodeAddress();
///
/// Change the current pc value for the frame on this thread.
///
- /// @param[in] pc
+ /// \param[in] pc
/// The load address that the pc will be set to.
///
- /// @return
+ /// \return
/// true if the pc was changed. false if this failed -- possibly
/// because this frame is not a live StackFrame.
//------------------------------------------------------------------
/// functions looking up symbolic information for a given pc value multiple
/// times.
///
- /// @params [in] resolve_scope
+ /// \params [in] resolve_scope
/// Flags from the SymbolContextItem enumerated type which specify what
/// type of symbol context is needed by this caller.
///
- /// @return
+ /// \return
/// A SymbolContext reference which includes the types of information
/// requested by resolve_scope, if they are available.
//------------------------------------------------------------------
/// Live StackFrames will always have a CFA but other types of frames may
/// not be able to supply one.
///
- /// @param [out] value
+ /// \param [out] value
/// The address of the CFA for this frame, if available.
///
- /// @param [out] error_ptr
+ /// \param [out] error_ptr
/// If there is an error determining the CFA address, this may contain a
/// string explaining the failure.
///
- /// @return
+ /// \return
/// Returns true if the CFA value was successfully set in value. Some
/// frames may be unable to provide this value; they will return false.
//------------------------------------------------------------------
///
/// Often a register (bp), but sometimes a register + offset.
///
- /// @param [out] error_ptr
+ /// \param [out] error_ptr
/// If there is an error determining the CFA address, this may contain a
/// string explaining the failure.
///
- /// @return
+ /// \return
/// Returns the corresponding DWARF expression, or NULL.
//------------------------------------------------------------------
DWARFExpression *GetFrameBaseExpression(Status *error_ptr);
/// If debug information is available for this stack frame, return a pointer
/// to the innermost lexical Block that the frame is currently executing.
///
- /// @return
+ /// \return
/// A pointer to the current Block. nullptr is returned if this can
/// not be provided.
//------------------------------------------------------------------
/// registers. Only the currently executing frame (frame 0) can reliably
/// provide every register in the register context.
///
- /// @return
+ /// \return
/// The RegisterContext shared point for this frame.
//------------------------------------------------------------------
lldb::RegisterContextSP GetRegisterContext();
/// pc value even though variables would be available at this point if it
/// were a live stack frame.
///
- /// @param[in] get_file_globals
+ /// \param[in] get_file_globals
/// Whether to also retrieve compilation-unit scoped variables
/// that are visible to the entire compilation unit (e.g. file
/// static in C, globals that are homed in this CU).
///
- /// @return
+ /// \return
/// A pointer to a list of variables.
//------------------------------------------------------------------
VariableList *GetVariableList(bool get_file_globals);
/// given pc value even though variables would be available at this point if
/// it were a live stack frame.
///
- /// @param[in] get_file_globals
+ /// \param[in] get_file_globals
/// Whether to also retrieve compilation-unit scoped variables
/// that are visible to the entire compilation unit (e.g. file
/// static in C, globals that are homed in this CU).
///
- /// @return
+ /// \return
/// A pointer to a list of variables.
//------------------------------------------------------------------
lldb::VariableListSP
/// Create a ValueObject for a variable name / pathname, possibly including
/// simple dereference/child selection syntax.
///
- /// @param[in] var_expr
+ /// \param[in] var_expr
/// The string specifying a variable to base the VariableObject off
/// of.
///
- /// @param[in] use_dynamic
+ /// \param[in] use_dynamic
/// Whether the correct dynamic type of an object pointer should be
/// determined before creating the object, or if the static type is
/// sufficient. One of the DynamicValueType enumerated values.
///
- /// @param[in] options
+ /// \param[in] options
/// An unsigned integer of flags, values from
/// StackFrame::ExpressionPathOption
/// enum.
- /// @param[in] var_sp
+ /// \param[in] var_sp
/// A VariableSP that will be set to the variable described in the
/// var_expr path.
///
- /// @param[in] error
+ /// \param[in] error
/// Record any errors encountered while evaluating var_expr.
///
- /// @return
+ /// \return
/// A shared pointer to the ValueObject described by var_expr.
//------------------------------------------------------------------
lldb::ValueObjectSP GetValueForVariableExpressionPath(
//------------------------------------------------------------------
/// Determine whether this StackFrame has debug information available or not
///
- /// @return
+ /// \return
// true if debug information is available for this frame (function,
// compilation unit, block, etc.)
//------------------------------------------------------------------
/// Return the disassembly for the instructions of this StackFrame's
/// function as a single C string.
///
- /// @return
+ /// \return
// C string with the assembly instructions for this function.
//------------------------------------------------------------------
const char *Disassemble();
/// Print a description for this frame using the frame-format formatter
/// settings.
///
- /// @param [in] strm
+ /// \param [in] strm
/// The Stream to print the description to.
///
- /// @param [in] show_unique
+ /// \param [in] show_unique
/// Whether to print the function arguments or not for backtrace unique.
///
- /// @param [in] frame_marker
+ /// \param [in] frame_marker
/// Optional string that will be prepended to the frame output description.
//------------------------------------------------------------------
void DumpUsingSettingsFormat(Stream *strm, bool show_unique = false,
//------------------------------------------------------------------
/// Print a description for this frame using a default format.
///
- /// @param [in] strm
+ /// \param [in] strm
/// The Stream to print the description to.
///
- /// @param [in] show_frame_index
+ /// \param [in] show_frame_index
/// Whether to print the frame number or not.
///
- /// @param [in] show_fullpaths
+ /// \param [in] show_fullpaths
/// Whether to print the full source paths or just the file base name.
//------------------------------------------------------------------
void Dump(Stream *strm, bool show_frame_index, bool show_fullpaths);
/// Print a description of this stack frame and/or the source
/// context/assembly for this stack frame.
///
- /// @param[in] strm
+ /// \param[in] strm
/// The Stream to send the output to.
///
- /// @param[in] show_frame_info
+ /// \param[in] show_frame_info
/// If true, print the frame info by calling DumpUsingSettingsFormat().
///
- /// @param[in] show_source
+ /// \param[in] show_source
/// If true, print source or disassembly as per the user's settings.
///
- /// @param[in] show_unique
+ /// \param[in] show_unique
/// If true, print using backtrace unique style, without function
/// arguments as per the user's settings.
///
- /// @param[in] frame_marker
+ /// \param[in] frame_marker
/// Passed to DumpUsingSettingsFormat() for the frame info printing.
///
- /// @return
+ /// \return
/// Returns true if successful.
//------------------------------------------------------------------
bool GetStatus(Stream &strm, bool show_frame_info, bool show_source,
/// is an inlined frame derived from the debug information and presented by
/// the debugger.
///
- /// @return
+ /// \return
/// true if this is an inlined frame.
//------------------------------------------------------------------
bool IsInlined();
/// Query this frame to find what frame it is in this Thread's
/// StackFrameList.
///
- /// @return
+ /// \return
/// StackFrame index 0 indicates the currently-executing function. Inline
/// frames are included in this frame index count.
//------------------------------------------------------------------
/// Query this frame to find what frame it is in this Thread's
/// StackFrameList, not counting inlined frames.
///
- /// @return
+ /// \return
/// StackFrame index 0 indicates the currently-executing function. Inline
/// frames are not included in this frame index count; their concrete
/// frame index will be the same as the concrete frame that they are
//------------------------------------------------------------------
/// Create a ValueObject for a given Variable in this StackFrame.
///
- /// @params [in] variable_sp
+ /// \params [in] variable_sp
/// The Variable to base this ValueObject on
///
- /// @params [in] use_dynamic
+ /// \params [in] use_dynamic
/// Whether the correct dynamic type of the variable should be
/// determined before creating the ValueObject, or if the static type
/// is sufficient. One of the DynamicValueType enumerated values.
///
- /// @return
+ /// \return
// A ValueObject for this variable.
//------------------------------------------------------------------
lldb::ValueObjectSP
/// Add an arbitrary Variable object (e.g. one that specifics a global or
/// static) to a StackFrame's list of ValueObjects.
///
- /// @params [in] variable_sp
+ /// \params [in] variable_sp
/// The Variable to base this ValueObject on
///
- /// @params [in] use_dynamic
+ /// \params [in] use_dynamic
/// Whether the correct dynamic type of the variable should be
/// determined before creating the ValueObject, or if the static type
/// is sufficient. One of the DynamicValueType enumerated values.
///
- /// @return
+ /// \return
// A ValueObject for this variable.
//------------------------------------------------------------------
lldb::ValueObjectSP TrackGlobalVariable(const lldb::VariableSP &variable_sp,
/// Query this frame to determine what the default language should be when
/// parsing expressions given the execution context.
///
- /// @return
+ /// \return
/// The language of the frame if known, else lldb::eLanguageTypeUnknown.
//------------------------------------------------------------------
lldb::LanguageType GetLanguage();
/// the current instruction. The ExpressionPath should indicate how to get
/// to this value using "frame variable."
///
- /// @params [in] addr
+ /// \params [in] addr
/// The raw address.
///
- /// @return
+ /// \return
/// The ValueObject if found. If valid, it has a valid ExpressionPath.
//------------------------------------------------------------------
lldb::ValueObjectSP GuessValueForAddress(lldb::addr_t addr);
/// given register plus an offset. The ExpressionPath should indicate how
/// to get to this value using "frame variable."
///
- /// @params [in] reg
+ /// \params [in] reg
/// The name of the register.
///
- /// @params [in] offset
+ /// \params [in] offset
/// The offset from the register. Particularly important for sp...
///
- /// @return
+ /// \return
/// The ValueObject if found. If valid, it has a valid ExpressionPath.
//------------------------------------------------------------------
lldb::ValueObjectSP GuessValueForRegisterAndOffset(ConstString reg,
/// PC in the stack frame and traverse through all parent blocks stopping at
/// inlined function boundaries.
///
- /// @params [in] name
+ /// \params [in] name
/// The name of the variable.
///
- /// @return
+ /// \return
/// The ValueObject if found.
//------------------------------------------------------------------
lldb::ValueObjectSP FindVariable(ConstString name);
namespace lldb_private {
-/// @class RecognizedStackFrame
+/// \class RecognizedStackFrame
///
/// This class provides extra information about a stack frame that was
/// provided by a specific stack frame recognizer. Right now, this class only
lldb::ValueObjectListSP m_arguments;
};
-/// @class StackFrameRecognizer
+/// \class StackFrameRecognizer
///
/// A base class for frame recognizers. Subclasses (actual frame recognizers)
/// should implement RecognizeFrame to provide a RecognizedStackFrame for a
#ifndef LLDB_DISABLE_PYTHON
-/// @class ScriptedStackFrameRecognizer
+/// \class ScriptedStackFrameRecognizer
///
/// Python implementation for frame recognizers. An instance of this class
/// tracks a particular Python classobject, which will be asked to recognize
#endif
-/// @class StackFrameRecognizerManager
+/// \class StackFrameRecognizerManager
///
/// Static class that provides a registry of known stack frame recognizers.
/// Has static methods to add, enumerate, remove, query and invoke recognizers.
static lldb::RecognizedStackFrameSP RecognizeFrame(lldb::StackFrameSP frame);
};
-/// @class ValueObjectRecognizerSynthesizedValue
+/// \class ValueObjectRecognizerSynthesizedValue
///
/// ValueObject subclass that presents the passed ValueObject as a recognized
/// value with the specified ValueType. Frame recognizers should return
/// features, and if that happens, there is a single plugin instance
/// created covering all of the mapped features for a given process.
///
- /// @param[in] type_name
+ /// \param[in] type_name
/// The name of the feature tag supported by a process.
/// e.g. "darwin-log".
///
- /// @return
+ /// \return
/// true if the plugin supports the feature; otherwise, false.
// -------------------------------------------------------------------------
virtual bool SupportsStructuredDataType(ConstString type_name) = 0;
/// value. This is the manner in which the data is routed to the proper
/// plugin instance.
///
- /// @param[in] process
+ /// \param[in] process
/// The process instance that just received the structured data.
/// This will always be the same process for a given instance of
/// a plugin.
///
- /// @param[in] type_name
+ /// \param[in] type_name
/// The name of the feature tag for the asynchronous structured data.
/// Note this data will also be present in the \b object_sp dictionary
/// under the string value with key "type".
///
- /// @param[in] object_sp
+ /// \param[in] object_sp
/// A shared pointer to the structured data that arrived. This must
/// be a dictionary. The only key required is the aforementioned
/// key named "type" that must be a string value containing the
/// nothing will be printed; otherwise, a newline will be added to the end
/// when displayed.
///
- /// @param[in] object_sp
+ /// \param[in] object_sp
/// A shared pointer to the structured data to format.
///
- /// @param[in] stream
+ /// \param[in] stream
/// The stream where the structured data should be pretty printed.
///
- /// @return
+ /// \return
/// The error if formatting the object contents failed; otherwise,
/// success.
// -------------------------------------------------------------------------
/// their functionality. It allows retrieval of this state without
/// requiring a cast.
///
- /// @param[in] type_name
+ /// \param[in] type_name
/// The name of the feature tag for the asynchronous structured data.
/// This is needed for plugins that support more than one feature.
// -------------------------------------------------------------------------
/// if they have any behavior they want to enable/modify based on loaded
/// modules.
///
- /// @param[in] process
+ /// \param[in] process
/// The process that just was notified of modules having been loaded.
/// This will always be the same process for a given instance of
/// a plugin.
///
- /// @param[in] module_list
+ /// \param[in] module_list
/// The list of modules that the process registered as having just
/// loaded. See \b Process::ModulesDidLoad(...).
// -------------------------------------------------------------------------
/// StructuredDataPlugin derived classes are available for this debugger.
/// If this has already happened, this call is a no-op.
///
- /// @param[in] debugger
+ /// \param[in] debugger
/// The Debugger instance for which we're creating the required shared
/// components for the StructuredDataPlugin derived classes.
// -------------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h"
+/// \class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h"
/// A plug-in interface definition class for system runtimes.
///
/// The system runtime plugins can collect information from the system
/// Scans the installed SystemRuntime plugins and tries to find an instance
/// that can be used to track image changes in \a process.
///
- /// @param[in] process
+ /// \param[in] process
/// The process for which to try and locate a system runtime
/// plugin instance.
//------------------------------------------------------------------
/// libdispatch queue origin. If there is none, then request the pthread
/// origin.
///
- /// @return
+ /// \return
/// A vector of ConstStrings with names like "pthread" or "libdispatch".
/// An empty vector may be returned if no thread origin extended
/// backtrace capabilities are available.
/// There may be a chain of thread-origins; it may be informative to the end
/// user to query the returned ThreadSP for its origins as well.
///
- /// @param [in] thread
+ /// \param [in] thread
/// The thread to examine.
///
- /// @param [in] type
+ /// \param [in] type
/// The type of thread origin being requested. The types supported
/// are returned from SystemRuntime::GetExtendedBacktraceTypes.
///
- /// @return
+ /// \return
/// A ThreadSP which will have a StackList of frames. This Thread will
/// not appear in the Process' list of current threads. Normal thread
/// operations like stepping will not be available. This is a historical
/// This method will report a thread backtrace of the function that enqueued
/// it originally, if possible.
///
- /// @param [in] queue_item_sp
+ /// \param [in] queue_item_sp
/// The QueueItem that we are getting an extended backtrace for.
///
- /// @param [in] type
+ /// \param [in] type
/// The type of extended backtrace to fetch. The types supported
/// are returned from SystemRuntime::GetExtendedBacktraceTypes.
///
- /// @return
+ /// \return
/// If an extended backtrace is available, it is returned. Else
/// an empty ThreadSP is returned.
//------------------------------------------------------------------
/// When process execution is paused, the SystemRuntime may be called to
/// fill in the list of Queues that currently exist.
///
- /// @param [out] queue_list
+ /// \param [out] queue_list
/// This QueueList will be cleared, and any queues that currently exist
/// will be added. An empty QueueList will be returned if no queues
/// exist or if this Systemruntime does not support libdispatch queues.
/// dispatch_queue_t structure. Given the address of the dispatch_queue_t
/// structure for a thread, get the queue name and return it.
///
- /// @param [in] dispatch_qaddr
+ /// \param [in] dispatch_qaddr
/// The address of the dispatch_qaddr pointer for this thread.
///
- /// @return
+ /// \return
/// The string of this queue's name. An empty string is returned if the
/// name could not be found.
//------------------------------------------------------------------
/// dispatch_queue_t structure. Given the address of the dispatch_queue_t
/// structure for a thread, get the queue ID and return it.
///
- /// @param [in] dispatch_qaddr
+ /// \param [in] dispatch_qaddr
/// The address of the dispatch_qaddr pointer for this thread.
///
- /// @return
+ /// \return
/// The queue ID, or if it could not be retrieved, LLDB_INVALID_QUEUE_ID.
//------------------------------------------------------------------
virtual lldb::queue_id_t
/// the thread's dispatch_qaddr, find the libdispatch_queue_t address and
/// return it.
///
- /// @param [in] dispatch_qaddr
+ /// \param [in] dispatch_qaddr
/// The address of the dispatch_qaddr pointer for this thread.
///
- /// @return
+ /// \return
/// The libdispatch_queue_t address, or LLDB_INVALID_ADDRESS if
/// unavailable/not found.
//------------------------------------------------------------------
/// eQueueKindConcurrent, indicating that this queue processes work items
/// serially or concurrently.
///
- /// @return
+ /// \return
/// The Queue kind, if it could be read, else eQueueKindUnknown.
//------------------------------------------------------------------
virtual lldb::QueueKind GetQueueKind(lldb::addr_t dispatch_qaddr) {
/// retrieve the list of pending work items for the specified Queue and add
/// it to the Queue.
///
- /// @param [in] queue
+ /// \param [in] queue
/// The queue of interest.
//------------------------------------------------------------------
virtual void PopulatePendingItemsForQueue(lldb_private::Queue *queue) {}
/// details; when the remaining fields are needed, they will be fetched by
/// call this method.
///
- /// @param [in] queue_item
+ /// \param [in] queue_item
/// The QueueItem that we will be completing.
///
- /// @param [in] item_ref
+ /// \param [in] item_ref
/// The item_ref token that is needed to retrieve the rest of the
/// information about the QueueItem.
//------------------------------------------------------------------
/// information debugserver may need when constructing the
/// jThreadExtendedInfo packet.
///
- /// @param [out] dict
+ /// \param [out] dict
/// Dictionary to which key-value pairs should be added; they will
/// be sent to the remote gdb server stub as arguments in the
/// jThreadExtendedInfo request.
/// this method gives a way for it to flag that the expression should not be
/// run.
///
- /// @param [in] thread_sp
+ /// \param [in] thread_sp
/// The thread we want to run the expression on.
///
- /// @return
+ /// \return
/// True will be returned if there are no known problems with running an
/// expression on this thread. False means that the inferior function
/// call should not be made on this thread.
/// is called, so this is a good way to see what has been parsed
/// in a target.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s, lldb::DescriptionLevel description_level);
/// dependent modules that are discovered from the object files, or
/// discovered at runtime as things are dynamically loaded.
///
- /// @return
+ /// \return
/// The shared pointer to the executable module which can
/// contains a nullptr Module object if no executable has been
/// set.
///
- /// @see DynamicLoader
- /// @see ObjectFile::GetDependentModules (FileSpecList&)
- /// @see Process::SetExecutableModule(lldb::ModuleSP&)
+ /// \see DynamicLoader
+ /// \see ObjectFile::GetDependentModules (FileSpecList&)
+ /// \see Process::SetExecutableModule(lldb::ModuleSP&)
//------------------------------------------------------------------
lldb::ModuleSP GetExecutableModule();
/// Process::GetImages() will return the newly found images that
/// were obtained from all of the object files.
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// A shared pointer reference to the module that will become
/// the main executable for this process.
///
- /// @param[in] load_dependent_files
+ /// \param[in] load_dependent_files
/// If \b true then ask the object files to track down any
/// known dependent files.
///
- /// @see ObjectFile::GetDependentModules (FileSpecList&)
- /// @see Process::GetImages()
+ /// \see ObjectFile::GetDependentModules (FileSpecList&)
+ /// \see Process::GetImages()
//------------------------------------------------------------------
void SetExecutableModule(
lldb::ModuleSP &module_sp,
/// addresses is each image, and also in images that are loaded by
/// code.
///
- /// @return
+ /// \return
/// A list of Module objects in a module list.
//------------------------------------------------------------------
const ModuleList &GetImages() const { return m_images; }
/// The target call at present just consults the Platform's call of the
/// same name.
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// A shared pointer reference to the module that checked.
///
- /// @return \b true if the module should be excluded, \b false otherwise.
+ /// \return \b true if the module should be excluded, \b false otherwise.
//------------------------------------------------------------------
bool ModuleIsExcludedForUnconstrainedSearches(const FileSpec &module_spec);
/// that they
/// don't want searched, in addition to or instead of the platform ones.
///
- /// @param[in] module_sp
+ /// \param[in] module_sp
/// A shared pointer reference to the module that checked.
///
- /// @return \b true if the module should be excluded, \b false otherwise.
+ /// \return \b true if the module should be excluded, \b false otherwise.
//------------------------------------------------------------------
bool
ModuleIsExcludedForUnconstrainedSearches(const lldb::ModuleSP &module_sp);
/// won't be changed. If the input arch_spec is the same as the already set
/// architecture, this is a no-op.
///
- /// @param[in] arch_spec
+ /// \param[in] arch_spec
/// The new architecture.
///
- /// @param[in] set_platform
+ /// \param[in] set_platform
/// If \b true, then the platform will be adjusted if the currently
/// selected platform is not compatible with the archicture being set.
/// If \b false, then just the architecture will be set even if the
/// currently selected platform isn't compatible (in case it might be
/// manually set following this function call).
///
- /// @return
+ /// \return
/// \b true if the architecture was successfully set, \bfalse otherwise.
//------------------------------------------------------------------
bool SetArchitecture(const ArchSpec &arch_spec, bool set_platform = false);
/// TargetList::CreateTarget(const FileSpec*, const ArchSpec*)
/// so all targets can be tracked from the central target list.
///
- /// @see TargetList::CreateTarget(const FileSpec*, const ArchSpec*)
+ /// \see TargetList::CreateTarget(const FileSpec*, const ArchSpec*)
//------------------------------------------------------------------
Target(Debugger &debugger, const ArchSpec &target_arch,
const lldb::PlatformSP &platform_sp, bool is_dummy_target);
/// get ahold of of the one and only target list through the
/// lldb_private::Debugger::GetSharedInstance().GetTargetList().
///
- /// @see static TargetList& lldb_private::Debugger::GetTargetList().
+ /// \see static TargetList& lldb_private::Debugger::GetTargetList().
//------------------------------------------------------------------
TargetList(Debugger &debugger);
/// locate an appropriate target to deliver asynchronous information
/// to.
///
- /// @param[in] debugger
+ /// \param[in] debugger
/// The debugger to associate this target with
///
- /// @param[in] file_spec
+ /// \param[in] file_spec
/// The main executable file for a debug target. This value
/// can be nullptr and the file can be set later using:
/// Target::SetExecutableModule (ModuleSP&)
///
- /// @param[in] triple_cstr
+ /// \param[in] triple_cstr
/// A target triple string to be used for the target. This can
/// be nullptr if the triple is not known or when attaching to a
/// process.
///
- /// @param[in] get_dependent_modules
+ /// \param[in] get_dependent_modules
/// Track down the dependent modules for an executable and
/// load those into the module list.
///
- /// @param[in] platform_options
+ /// \param[in] platform_options
/// A pointer to the platform options to use when creating this
/// target. If this value is nullptr, then the currently selected
/// platform will be used.
///
- /// @param[out] target_sp
+ /// \param[out] target_sp
/// A shared pointer to a target that will be filled in if
/// this call is successful.
///
- /// @return
+ /// \return
/// An error object that indicates success or failure
//------------------------------------------------------------------
Status CreateTarget(Debugger &debugger, llvm::StringRef user_exe_path,
/// should be called to release the memory associated with a target
/// object.
///
- /// @param[in] target_sp
+ /// \param[in] target_sp
/// The shared pointer to a target.
///
- /// @return
+ /// \return
/// Returns \b true if the target was successfully removed from
/// from this target list, \b false otherwise. The client will
/// be left with the last remaining shared pointer to the target
/// matches \a exe_file_spec, and whose architecture matches
/// \a arch_ptr if arch_ptr is not nullptr.
///
- /// @param[in] exe_file_spec
+ /// \param[in] exe_file_spec
/// A file spec containing a basename, or a full path (directory
/// and basename). If \a exe_file_spec contains only a filename
/// (empty GetDirectory() value) then matching will be done
/// compared. If \a exe_file_spec contains a filename and a
/// directory, then both must match.
///
- /// @param[in] exe_arch_ptr
+ /// \param[in] exe_arch_ptr
/// If not nullptr then the architecture also needs to match, else
/// the architectures will be compared.
///
- /// @return
+ /// \return
/// A shared pointer to a target object. The returned shared
/// pointer will contain nullptr if no target objects have a
/// executable whose full or partial path matches
/// Find the target that contains a process with process ID \a
/// pid.
///
- /// @param[in] pid
+ /// \param[in] pid
/// The process ID to search our target list for.
///
- /// @return
+ /// \return
/// A shared pointer to a target object. The returned shared
/// pointer will contain nullptr if no target objects own a process
/// with a matching process ID.
/// pid and send a LLDB_EVENT_ASYNC_INTERRUPT event to the process's
/// event queue.
///
- /// @param[in] pid
+ /// \param[in] pid
/// The process ID to search our target list for, if \a pid is
/// LLDB_INVALID_PROCESS_ID, then the interrupt will be sent to
/// all processes.
///
- /// @return
+ /// \return
/// The number of async interrupts sent.
//------------------------------------------------------------------
uint32_t SendAsyncInterrupt(lldb::pid_t pid = LLDB_INVALID_PROCESS_ID);
/// The regular expression returned determines symbols that this
/// thread won't stop in during "step-in" operations.
///
- /// @return
+ /// \return
/// A pointer to a regular expression to compare against symbols,
/// or nullptr if all symbols are allowed.
///
//------------------------------------------------------------------
/// Constructor
///
- /// @param [in] process
+ /// \param [in] process
///
- /// @param [in] tid
+ /// \param [in] tid
///
- /// @param [in] use_invalid_index_id
+ /// \param [in] use_invalid_index_id
/// Optional parameter, defaults to false. The only subclass that
/// is likely to set use_invalid_index_id == true is the HistoryThread
/// class. In that case, the Thread we are constructing represents
/// to force the thread to run (e.g. the "thread continue" command, or are
/// resetting the state
/// (e.g. in SBThread::Resume()), then pass true to override_suspend.
- /// @return
+ /// \return
/// The User resume state for this thread.
//------------------------------------------------------------------
void SetResumeState(lldb::StateType state, bool override_suspend = false) {
/// this
/// thread to run.
///
- /// @return
+ /// \return
/// The User resume state for this thread.
//------------------------------------------------------------------
lldb::StateType GetResumeState() const { return m_resume_state; }
/// queue, or it may be unknown whether it is associated with a libdispatch
/// queue.
///
- /// @return
+ /// \return
/// eLazyBoolNo if this thread is definitely not associated with a
/// libdispatch queue (e.g. on a non-Darwin system where GCD aka
/// libdispatch is not available).
/// queues and incrementing, a QueueID will not be reused for a
/// different queue during the lifetime of a process.
///
- /// @return
+ /// \return
/// A QueueID if the Thread subclass implements this, else
/// LLDB_INVALID_QUEUE_ID.
//------------------------------------------------------------------
/// If this Thread is doing work on behalf of a libdispatch/GCD queue,
/// retrieve the Queue name.
///
- /// @return
+ /// \return
/// The Queue name, if the Thread subclass implements this, else
/// nullptr.
//------------------------------------------------------------------
/// eQueueKindConcurrent, indicating that this queue processes work
/// items serially or concurrently.
///
- /// @return
+ /// \return
/// The Queue kind, if the Thread subclass implements this, else
/// eQueueKindUnknown.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Retrieve the Queue for this thread, if any.
///
- /// @return
+ /// \return
/// A QueueSP for the queue that is currently associated with this
/// thread.
/// An empty shared pointer indicates that this thread is not
/// lifetime and should not be used to identify a queue uniquely. Use
/// the GetQueueID() call for that.
///
- /// @return
+ /// \return
/// The Queue's libdispatch_queue_t address if the Thread subclass
/// implements this, else LLDB_INVALID_ADDRESS.
//------------------------------------------------------------------
/// This function is designed to be used by commands where the
/// process is publicly stopped.
///
- /// @param[in] source_step
+ /// \param[in] source_step
/// If true and the frame has debug info, then do a source level
/// step in, else do a single instruction step in.
///
- /// @param[in] step_in_avoids_code_without_debug_info
+ /// \param[in] step_in_avoids_code_without_debug_info
/// If \a true, then avoid stepping into code that doesn't have
/// debug info, else step into any code regardless of whether it
/// has debug info.
///
- /// @param[in] step_out_avoids_code_without_debug_info
+ /// \param[in] step_out_avoids_code_without_debug_info
/// If \a true, then if you step out to code with no debug info, keep
/// stepping out till you get to code with debug info.
///
- /// @return
+ /// \return
/// An error that describes anything that went wrong
//------------------------------------------------------------------
virtual Status
/// This function is designed to be used by commands where the
/// process is publicly stopped.
///
- /// @param[in] source_step
+ /// \param[in] source_step
/// If true and the frame has debug info, then do a source level
/// step over, else do a single instruction step over.
///
- /// @return
+ /// \return
/// An error that describes anything that went wrong
//------------------------------------------------------------------
virtual Status StepOver(
/// This function is designed to be used by commands where the
/// process is publicly stopped.
///
- /// @return
+ /// \return
/// An error that describes anything that went wrong
//------------------------------------------------------------------
virtual Status StepOut();
/// Most OSs maintain a per-thread pointer (e.g. the FS register on
/// x64), which we return the value of here.
///
- /// @return
+ /// \return
/// LLDB_INVALID_ADDRESS if not supported, otherwise the thread
/// pointer value.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Retrieves the per-module TLS block for a thread.
///
- /// @param[in] module
+ /// \param[in] module
/// The module to query TLS data for.
///
- /// @param[in] tls_file_addr
+ /// \param[in] tls_file_addr
/// The thread local address in module
- /// @return
+ /// \return
/// If the thread has TLS data allocated for the
/// module, the address of the TLS block. Otherwise
/// LLDB_INVALID_ADDRESS is returned.
/// process of execution, for instance) which can make it unsafe for
/// functions to be called.
///
- /// @return
+ /// \return
/// True if it is safe to call functions on this thread.
/// False if function calls should be avoided on this thread.
//------------------------------------------------------------------
/// one you probably want to call through to the Process one for anything
/// your plugin doesn't explicitly handle.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
/// Queues the plan used to step one instruction from the current PC of \a
/// thread.
///
- /// @param[in] step_over
+ /// \param[in] step_over
/// \b true if we step over calls to functions, false if we step in.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @param[in] stop_other_threads
+ /// \param[in] stop_other_threads
/// \b true if we will stop other threads while we single step this one.
///
- /// @param[out] status
+ /// \param[out] status
/// A status with an error if queuing failed.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
/// Queues the plan used to step through an address range, stepping over
/// function calls.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @param[in] type
+ /// \param[in] type
/// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
/// by this plan.
///
- /// @param[in] range
+ /// \param[in] range
/// The address range to step through.
///
- /// @param[in] addr_context
+ /// \param[in] addr_context
/// When dealing with stepping through inlined functions the current PC is
/// not enough information to know
/// what "step" means. For instance a series of nested inline functions
/// is supposed to be out of.
// FIXME: Currently unused.
///
- /// @param[in] stop_other_threads
+ /// \param[in] stop_other_threads
/// \b true if we will stop other threads while we single step this one.
///
- /// @param[out] status
+ /// \param[out] status
/// A status with an error if queuing failed.
///
- /// @param[in] step_out_avoids_code_without_debug_info
+ /// \param[in] step_out_avoids_code_without_debug_info
/// If eLazyBoolYes, if the step over steps out it will continue to step
/// out till it comes to a frame with debug info.
/// If eLazyBoolCalculate, we will consult the default set in the thread.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
/// Queues the plan used to step through an address range, stepping into
/// functions.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @param[in] type
+ /// \param[in] type
/// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
/// by this plan.
///
- /// @param[in] range
+ /// \param[in] range
/// The address range to step through.
///
- /// @param[in] addr_context
+ /// \param[in] addr_context
/// When dealing with stepping through inlined functions the current PC is
/// not enough information to know
/// what "step" means. For instance a series of nested inline functions
/// is supposed to be out of.
// FIXME: Currently unused.
///
- /// @param[in] step_in_target
+ /// \param[in] step_in_target
/// Name if function we are trying to step into. We will step out if we
/// don't land in that function.
///
- /// @param[in] stop_other_threads
+ /// \param[in] stop_other_threads
/// \b true if we will stop other threads while we single step this one.
///
- /// @param[out] status
+ /// \param[out] status
/// A status with an error if queuing failed.
///
- /// @param[in] step_in_avoids_code_without_debug_info
+ /// \param[in] step_in_avoids_code_without_debug_info
/// If eLazyBoolYes we will step out if we step into code with no debug
/// info.
/// If eLazyBoolCalculate we will consult the default set in the thread.
///
- /// @param[in] step_out_avoids_code_without_debug_info
+ /// \param[in] step_out_avoids_code_without_debug_info
/// If eLazyBoolYes, if the step over steps out it will continue to step
/// out till it comes to a frame with debug info.
/// If eLazyBoolCalculate, it will consult the default set in the thread.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
/// Queue the plan used to step out of the function at the current PC of
/// \a thread.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @param[in] addr_context
+ /// \param[in] addr_context
/// When dealing with stepping through inlined functions the current PC is
/// not enough information to know
/// what "step" means. For instance a series of nested inline functions
/// is supposed to be out of.
// FIXME: Currently unused.
///
- /// @param[in] first_insn
+ /// \param[in] first_insn
/// \b true if this is the first instruction of a function.
///
- /// @param[in] stop_other_threads
+ /// \param[in] stop_other_threads
/// \b true if we will stop other threads while we single step this one.
///
- /// @param[in] stop_vote
- /// @param[in] run_vote
+ /// \param[in] stop_vote
+ /// \param[in] run_vote
/// See standard meanings for the stop & run votes in ThreadPlan.h.
///
- /// @param[out] status
+ /// \param[out] status
/// A status with an error if queuing failed.
///
- /// @param[in] step_out_avoids_code_without_debug_info
+ /// \param[in] step_out_avoids_code_without_debug_info
/// If eLazyBoolYes, if the step over steps out it will continue to step
/// out till it comes to a frame with debug info.
/// If eLazyBoolCalculate, it will consult the default set in the thread.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
/// be used by other thread plans when they need to retain control of the step
/// out.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @param[in] addr_context
+ /// \param[in] addr_context
/// When dealing with stepping through inlined functions the current PC is
/// not enough information to know
/// what "step" means. For instance a series of nested inline functions
/// is supposed to be out of.
// FIXME: Currently unused.
///
- /// @param[in] first_insn
+ /// \param[in] first_insn
/// \b true if this is the first instruction of a function.
///
- /// @param[in] stop_other_threads
+ /// \param[in] stop_other_threads
/// \b true if we will stop other threads while we single step this one.
///
- /// @param[in] stop_vote
+ /// \param[in] stop_vote
///
- /// @param[in] run_vote
+ /// \param[in] run_vote
/// See standard meanings for the stop & run votes in ThreadPlan.h.
///
- /// @param[in] frame_idx
+ /// \param[in] frame_idx
///
- /// @param[out] status
+ /// \param[out] status
/// A status with an error if queuing failed.
///
- /// @param[in] continue_to_next_branch
+ /// \param[in] continue_to_next_branch
/// Normally this will enqueue a plan that will put a breakpoint on the
/// return address and continue
/// to there. If continue_to_next_branch is true, this is an operation not
/// registers which are overwritten
/// before the next branch instruction.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
/// Gets the plan used to step through the code that steps from a function
/// call site at the current PC into the actual function call.
///
- /// @param[in] return_stack_id
+ /// \param[in] return_stack_id
/// The stack id that we will return to (by setting backstop breakpoints on
/// the return
/// address to that frame) if we fail to step through.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @param[in] stop_other_threads
+ /// \param[in] stop_other_threads
/// \b true if we will stop other threads while we single step this one.
///
- /// @param[out] status
+ /// \param[out] status
/// A status with an error if queuing failed.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
/// This is a simple plan, mostly useful as a backstop when you are continuing
/// for some particular purpose.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @param[in] target_addr
+ /// \param[in] target_addr
/// The address to which we're running.
///
- /// @param[in] stop_other_threads
+ /// \param[in] stop_other_threads
/// \b true if we will stop other threads while we single step this one.
///
- /// @param[out] status
+ /// \param[out] status
/// A status with an error if queuing failed.
///
- /// @return
+ /// \return
/// A shared pointer to the newly queued thread plan, or nullptr if the
/// plan could not be queued.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Gets the plan which will execute next on the plan stack.
///
- /// @return
+ /// \return
/// A pointer to the next executed plan.
//------------------------------------------------------------------
ThreadPlan *GetCurrentPlan();
/// Unwinds the thread stack for the innermost expression plan currently
/// on the thread plan stack.
///
- /// @return
+ /// \return
/// An error if the thread plan could not be unwound.
//------------------------------------------------------------------
/// Gets the outer-most plan that was popped off the plan stack in the
/// most recent stop. Useful for printing the stop reason accurately.
///
- /// @return
+ /// \return
/// A pointer to the last completed plan.
//------------------------------------------------------------------
lldb::ThreadPlanSP GetCompletedPlan();
//------------------------------------------------------------------
/// Gets the outer-most return value from the completed plans
///
- /// @return
+ /// \return
/// A ValueObjectSP, either empty if there is no return value,
/// or containing the return value.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Gets the outer-most expression variable from the completed plans
///
- /// @return
+ /// \return
/// A ExpressionVariableSP, either empty if there is no
/// plan completed an expression during the current stop
/// or the expression variable that was made for the completed expression.
/// Checks whether the given plan is in the completed plans for this
/// stop.
///
- /// @param[in] plan
+ /// \param[in] plan
/// Pointer to the plan you're checking.
///
- /// @return
+ /// \return
/// Returns true if the input plan is in the completed plan stack,
/// false otherwise.
//------------------------------------------------------------------
/// Checks whether the given plan is in the discarded plans for this
/// stop.
///
- /// @param[in] plan
+ /// \param[in] plan
/// Pointer to the plan you're checking.
///
- /// @return
+ /// \return
/// Returns true if the input plan is in the discarded plan stack,
/// false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Check if we have completed plan to override breakpoint stop reason
///
- /// @return
+ /// \return
/// Returns true if completed plan stack is not empty
/// false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Queues a generic thread plan.
///
- /// @param[in] plan_sp
+ /// \param[in] plan_sp
/// The plan to queue.
///
- /// @param[in] abort_other_plans
+ /// \param[in] abort_other_plans
/// \b true if we discard the currently queued plans and replace them with
/// this one.
/// Otherwise this plan will go on the end of the plan stack.
///
- /// @return
+ /// \return
/// A pointer to the last completed plan.
//------------------------------------------------------------------
Status QueueThreadPlan(lldb::ThreadPlanSP &plan_sp, bool abort_other_plans);
/// and
/// including up_to_plan_sp.
//
- // @param[in] up_to_plan_sp
+ // \param[in] up_to_plan_sp
// Discard all plans up to and including this one.
//------------------------------------------------------------------
void DiscardThreadPlansUpToPlan(lldb::ThreadPlanSP &up_to_plan_sp);
/// including the plan in that matches \a thread_index counting only
/// the non-Private plans.
///
- /// @param[in] up_to_plan_sp
+ /// \param[in] up_to_plan_sp
/// Discard all plans up to and including this user plan given by this
/// index.
///
- /// @return
+ /// \return
/// \b true if there was a thread plan with that user index, \b false
/// otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Prints the current plan stack.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the plan stack info.
///
//------------------------------------------------------------------
// Thread subclasses should call Thread::SetStopInfo(...) with the reason the
// thread stopped.
//
- // @return
+ // \return
// True if Thread::SetStopInfo(...) was called, false otherwise.
//----------------------------------------------------------------------
virtual bool CalculateStopInfo() = 0;
/// Some Thread subclasses may maintain a token to help with providing
/// an extended backtrace. The SystemRuntime plugin will set/request this.
///
- /// @param [in] token
+ /// \param [in] token
//----------------------------------------------------------------------
virtual void SetExtendedBacktraceToken(uint64_t token) {}
/// Some Thread subclasses may maintain a token to help with providing
/// an extended backtrace. The SystemRuntime plugin will set/request this.
///
- /// @return
+ /// \return
/// The token needed by the SystemRuntime to create an extended backtrace.
/// LLDB_INVALID_ADDRESS is returned if no token is available.
//----------------------------------------------------------------------
/// will return false for WillResume, and then the process will not be
/// restarted.
///
- /// @return
+ /// \return
/// \b true instructs the process to resume normally,
/// \b false means start & stopped events will be generated, but
/// the process will not actually run. The thread must then return
//------------------------------------------------------------------
/// Returns the name of this thread plan.
///
- /// @return
+ /// \return
/// A const char * pointer to the thread plan's name.
//------------------------------------------------------------------
const char *GetName() const { return m_name.c_str(); }
//------------------------------------------------------------------
/// Returns the Thread that is using this thread plan.
///
- /// @return
+ /// \return
/// A pointer to the thread plan's owning thread.
//------------------------------------------------------------------
Thread &GetThread() { return m_thread; }
/// Print a description of this thread to the stream \a s.
/// \a thread.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to print the description.
///
- /// @param[in] level
+ /// \param[in] level
/// The level of description desired. Note that eDescriptionLevelBrief
/// will be used in the stop message printed when the plan is complete.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns whether this plan could be successfully created.
///
- /// @param[in] error
+ /// \param[in] error
/// A stream to which to print some reason why the plan could not be
/// created.
/// Can be NULL.
///
- /// @return
+ /// \return
/// \b true if the plan should be queued, \b false otherwise.
//------------------------------------------------------------------
virtual bool ValidatePlan(Stream *error) = 0;
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ArchSpec ArchSpec.h "lldb/Utility/ArchSpec.h" An architecture
+/// \class ArchSpec ArchSpec.h "lldb/Utility/ArchSpec.h" An architecture
/// specification class.
///
/// A class designed to be created from a cpu type and subtype, a
//------------------------------------------------------------------
/// Assignment operator.
///
- /// @param[in] rhs another ArchSpec object to copy.
+ /// \param[in] rhs another ArchSpec object to copy.
///
- /// @return A const reference to this object.
+ /// \return A const reference to this object.
//------------------------------------------------------------------
const ArchSpec &operator=(const ArchSpec &rhs);
//------------------------------------------------------------------
/// Returns a static string representing the current architecture.
///
- /// @return A static string corresponding to the current
+ /// \return A static string corresponding to the current
/// architecture.
//------------------------------------------------------------------
const char *GetArchitectureName() const;
//-----------------------------------------------------------------
/// if MIPS architecture return true.
///
- /// @return a boolean value.
+ /// \return a boolean value.
//-----------------------------------------------------------------
bool IsMIPS() const;
/// Returns a string representing current architecture as a target CPU for
/// tools like compiler, disassembler etc.
///
- /// @return A string representing target CPU for the current
+ /// \return A string representing target CPU for the current
/// architecture.
//------------------------------------------------------------------
std::string GetClangTargetCPU() const;
//------------------------------------------------------------------
/// Return a string representing target application ABI.
///
- /// @return A string representing target application ABI.
+ /// \return A string representing target application ABI.
//------------------------------------------------------------------
std::string GetTargetABI() const;
//------------------------------------------------------------------
/// Returns the size in bytes of an address of the current architecture.
///
- /// @return The byte size of an address of the current architecture.
+ /// \return The byte size of an address of the current architecture.
//------------------------------------------------------------------
uint32_t GetAddressByteSize() const;
//------------------------------------------------------------------
/// Returns a machine family for the current architecture.
///
- /// @return An LLVM arch type.
+ /// \return An LLVM arch type.
//------------------------------------------------------------------
llvm::Triple::ArchType GetMachine() const;
///
/// This will be something like "ubuntu", "fedora", etc. on Linux.
///
- /// @return A ConstString ref containing the distribution id,
+ /// \return A ConstString ref containing the distribution id,
/// potentially empty.
//------------------------------------------------------------------
ConstString GetDistributionId() const;
//------------------------------------------------------------------
/// Tests if this ArchSpec is valid.
///
- /// @return True if the current architecture is valid, false
+ /// \return True if the current architecture is valid, false
/// otherwise.
//------------------------------------------------------------------
bool IsValid() const {
//------------------------------------------------------------------
/// Change the architecture object type, CPU type and OS type.
///
- /// @param[in] arch_type The object type of this ArchSpec.
+ /// \param[in] arch_type The object type of this ArchSpec.
///
- /// @param[in] cpu The required CPU type.
+ /// \param[in] cpu The required CPU type.
///
- /// @param[in] os The optional OS type
+ /// \param[in] os The optional OS type
/// The default value of 0 was chosen to from the ELF spec value
/// ELFOSABI_NONE. ELF is the only one using this parameter. If another
/// format uses this parameter and 0 does not work, use a value over
/// 255 because in the ELF header this is value is only a byte.
///
- /// @return True if the object, and CPU were successfully set.
+ /// \return True if the object, and CPU were successfully set.
///
/// As a side effect, the vendor value is usually set to unknown. The
/// exceptions are
//------------------------------------------------------------------
/// Returns the byte order for the architecture specification.
///
- /// @return The endian enumeration for the current endianness of
+ /// \return The endian enumeration for the current endianness of
/// the architecture specification
//------------------------------------------------------------------
lldb::ByteOrder GetByteOrder() const;
//------------------------------------------------------------------
/// Architecture data byte width accessor
///
- /// @return the size in 8-bit (host) bytes of a minimum addressable unit
+ /// \return the size in 8-bit (host) bytes of a minimum addressable unit
/// from the Architecture's data bus
//------------------------------------------------------------------
uint32_t GetDataByteSize() const;
//------------------------------------------------------------------
/// Architecture code byte width accessor
///
- /// @return the size in 8-bit (host) bytes of a minimum addressable unit
+ /// \return the size in 8-bit (host) bytes of a minimum addressable unit
/// from the Architecture's code bus
//------------------------------------------------------------------
uint32_t GetCodeByteSize() const;
//------------------------------------------------------------------
/// Architecture triple accessor.
///
- /// @return A triple describing this ArchSpec.
+ /// \return A triple describing this ArchSpec.
//------------------------------------------------------------------
llvm::Triple &GetTriple() { return m_triple; }
//------------------------------------------------------------------
/// Architecture triple accessor.
///
- /// @return A triple describing this ArchSpec.
+ /// \return A triple describing this ArchSpec.
//------------------------------------------------------------------
const llvm::Triple &GetTriple() const { return m_triple; }
/// to further resolve the CPU type and subtype, endian characteristics,
/// etc.
///
- /// @return A triple describing this ArchSpec.
+ /// \return A triple describing this ArchSpec.
//------------------------------------------------------------------
bool SetTriple(const llvm::Triple &triple);
//------------------------------------------------------------------
/// Returns the default endianness of the architecture.
///
- /// @return The endian enumeration for the default endianness of
+ /// \return The endian enumeration for the default endianness of
/// the architecture.
//------------------------------------------------------------------
lldb::ByteOrder GetDefaultEndian() const;
/// Returns true if 'char' is a signed type by default in the architecture
/// false otherwise
///
- /// @return True if 'char' is a signed type by default on the
+ /// \return True if 'char' is a signed type by default on the
/// architecture and false otherwise.
//------------------------------------------------------------------
bool CharIsSignedByDefault() const;
/// match between them. e.g. armv7s is not an exact match with armv7 - this
/// would return false
///
- /// @return true if the two ArchSpecs match.
+ /// \return true if the two ArchSpecs match.
//------------------------------------------------------------------
bool IsExactMatch(const ArchSpec &rhs) const;
/// match between them. e.g. armv7s is compatible with armv7 - this method
/// would return true
///
- /// @return true if the two ArchSpecs are compatible
+ /// \return true if the two ArchSpecs are compatible
//------------------------------------------------------------------
bool IsCompatibleMatch(const ArchSpec &rhs) const;
/// (especially common with these embedded processors), we may not have
/// those things easily accessible.
///
- /// @return true if this is an arm ArchSpec which can only execute Thumb
+ /// \return true if this is an arm ArchSpec which can only execute Thumb
/// instructions
//------------------------------------------------------------------
bool IsAlwaysThumbInstructions() const;
};
//------------------------------------------------------------------
-/// @fn bool operator< (const ArchSpec& lhs, const ArchSpec& rhs) Less than
+/// \fn bool operator< (const ArchSpec& lhs, const ArchSpec& rhs) Less than
/// operator.
///
/// Tests two ArchSpec objects to see if \a lhs is less than \a rhs.
///
-/// @param[in] lhs The Left Hand Side ArchSpec object to compare. @param[in]
+/// \param[in] lhs The Left Hand Side ArchSpec object to compare. \param[in]
/// rhs The Left Hand Side ArchSpec object to compare.
///
-/// @return true if \a lhs is less than \a rhs
+/// \return true if \a lhs is less than \a rhs
//------------------------------------------------------------------
bool operator<(const ArchSpec &lhs, const ArchSpec &rhs);
bool operator==(const ArchSpec &lhs, const ArchSpec &rhs);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Args Args.h "lldb/Utility/Args.h"
+/// \class Args Args.h "lldb/Utility/Args.h"
/// A command line argument class.
///
/// The Args class is designed to be fed a command line. The command line is
//------------------------------------------------------------------
/// Construct with an option command string.
///
- /// @param[in] command
+ /// \param[in] command
/// A NULL terminated command that will be copied and split up
/// into arguments.
///
- /// @see Args::SetCommandString(llvm::StringRef)
+ /// \see Args::SetCommandString(llvm::StringRef)
//------------------------------------------------------------------
Args(llvm::StringRef command = llvm::StringRef());
///
/// If label_name is nullptr, the dump operation is skipped.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump all arguments in the argument
/// vector.
- /// @param[in] label_name
+ /// \param[in] label_name
/// The label_name to use as the label printed for each
/// entry of the args like so:
/// {label_name}[{index}]={value}
/// The command string will be copied and split up into arguments that can
/// be accessed via the accessor functions.
///
- /// @param[in] command
+ /// \param[in] command
/// A command StringRef that will be copied and split up
/// into arguments.
///
- /// @see Args::GetArgumentCount() const
- /// @see Args::GetArgumentAtIndex (size_t) const @see
- /// Args::GetArgumentVector () @see Args::Shift () @see Args::Unshift (const
+ /// \see Args::GetArgumentCount() const
+ /// \see Args::GetArgumentAtIndex (size_t) const @see
+ /// Args::GetArgumentVector () \see Args::Shift () \see Args::Unshift (const
/// char *)
//------------------------------------------------------------------
void SetCommandString(llvm::StringRef command);
//------------------------------------------------------------------
/// Gets the number of arguments left in this command object.
///
- /// @return
+ /// \return
/// The number or arguments in this object.
//------------------------------------------------------------------
size_t GetArgumentCount() const;
/// Gets the NULL terminated C string argument pointer for the argument at
/// index \a idx.
///
- /// @return
+ /// \return
/// The NULL terminated C string argument pointer if \a idx is a
/// valid argument index, NULL otherwise.
//------------------------------------------------------------------
/// int main (int argc, const char **argv);
/// \endcode
///
- /// @return
+ /// \return
/// An array of NULL terminated C string argument pointers that
/// also has a terminating NULL C string pointer
//------------------------------------------------------------------
/// int main (int argc, const char **argv);
/// \endcode
///
- /// @return
+ /// \return
/// An array of NULL terminate C string argument pointers that
/// also has a terminating NULL C string pointer
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Appends a new argument to the end of the list argument list.
///
- /// @param[in] arg_cstr
+ /// \param[in] arg_cstr
/// The new argument as a NULL terminated C string.
///
- /// @param[in] quote_char
+ /// \param[in] quote_char
/// If the argument was originally quoted, put in the quote char here.
//------------------------------------------------------------------
void AppendArgument(llvm::StringRef arg_str, char quote_char = '\0');
//------------------------------------------------------------------
/// Insert the argument value at index \a idx to \a arg_cstr.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The index of where to insert the argument.
///
- /// @param[in] arg_cstr
+ /// \param[in] arg_cstr
/// The new argument as a NULL terminated C string.
///
- /// @param[in] quote_char
+ /// \param[in] quote_char
/// If the argument was originally quoted, put in the quote char here.
///
- /// @return
+ /// \return
/// The NULL terminated C string of the copy of \a arg_cstr.
//------------------------------------------------------------------
void InsertArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
/// Replaces the argument value at index \a idx to \a arg_cstr if \a idx is
/// a valid argument index.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The index of the argument that will have its value replaced.
///
- /// @param[in] arg_cstr
+ /// \param[in] arg_cstr
/// The new argument as a NULL terminated C string.
///
- /// @param[in] quote_char
+ /// \param[in] quote_char
/// If the argument was originally quoted, put in the quote char here.
//------------------------------------------------------------------
void ReplaceArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
/// Deletes the argument value at index
/// if \a idx is a valid argument index.
///
- /// @param[in] idx
+ /// \param[in] idx
/// The index of the argument that will have its value replaced.
///
//------------------------------------------------------------------
/// by calling Args::GetArgumentAtIndex (size_t) const first and copying the
/// returned value before calling Args::Shift().
///
- /// @see Args::GetArgumentAtIndex (size_t) const
+ /// \see Args::GetArgumentAtIndex (size_t) const
//------------------------------------------------------------------
void Shift();
///
/// A copy \a arg_cstr will be made.
///
- /// @param[in] arg_cstr
+ /// \param[in] arg_cstr
/// The argument to push on the front of the argument stack.
///
- /// @param[in] quote_char
+ /// \param[in] quote_char
/// If the argument was originally quoted, put in the quote char here.
//------------------------------------------------------------------
void Unshift(llvm::StringRef arg_str, char quote_char = '\0');
};
//----------------------------------------------------------------------
-/// @class OptionsWithRaw Args.h "lldb/Utility/Args.h"
+/// \class OptionsWithRaw Args.h "lldb/Utility/Args.h"
/// A pair of an option list with a 'raw' string as a suffix.
///
/// This class works similar to Args, but handles the case where we have a
/// All strings not matching the above format as considered to be just a raw
/// string without any options.
///
-/// @see Args
+/// \see Args
//----------------------------------------------------------------------
class OptionsWithRaw {
public:
///
/// See the class description for a description of the input format.
///
- /// @param[in] argument_string
+ /// \param[in] argument_string
/// The string that should be parsed.
//------------------------------------------------------------------
explicit OptionsWithRaw(llvm::StringRef argument_string);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Baton Baton.h "lldb/Core/Baton.h"
+/// \class Baton Baton.h "lldb/Core/Baton.h"
/// A class designed to wrap callback batons so they can cleanup
/// any acquired resources
///
};
//----------------------------------------------------------------------
-/// @class Broadcaster Broadcaster.h "lldb/Utility/Broadcaster.h" An event
+/// \class Broadcaster Broadcaster.h "lldb/Utility/Broadcaster.h" An event
/// broadcasting class.
///
/// The Broadcaster class is designed to be subclassed by objects that wish to
/// vend events in a multi-threaded environment. Broadcaster objects can each
/// vend 32 events. Each event is represented by a bit in a 32 bit value and
/// these bits can be set:
-/// @see Broadcaster::SetEventBits(uint32_t)
+/// \see Broadcaster::SetEventBits(uint32_t)
/// or cleared:
-/// @see Broadcaster::ResetEventBits(uint32_t)
+/// \see Broadcaster::ResetEventBits(uint32_t)
/// When an event gets set the Broadcaster object will notify the Listener
/// object that is listening for the event (if there is one).
///
//------------------------------------------------------------------
/// Construct with a broadcaster with a name.
///
- /// @param[in] name
+ /// \param[in] name
/// A NULL terminated C string that contains the name of the
/// broadcaster object.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Broadcast an event which has no associated data.
///
- /// @param[in] event_type
+ /// \param[in] event_type
/// The element from the enum defining this broadcaster's events
/// that is being broadcast.
///
- /// @param[in] event_data
+ /// \param[in] event_data
/// User event data that will be owned by the lldb::Event that
/// is created internally.
///
- /// @param[in] unique
+ /// \param[in] unique
/// If true, then only add an event of this type if there isn't
/// one already in the queue.
///
/// different from what is requested in \a event_mask, and to track this the
/// actual event bits that are acquired get returned.
///
- /// @param[in] listener
+ /// \param[in] listener
/// The Listener object that wants to monitor the events that
/// get broadcast by this object.
///
- /// @param[in] event_mask
+ /// \param[in] event_mask
/// A bit mask that indicates which events the listener is
/// asking to monitor.
///
- /// @return
+ /// \return
/// The actual event bits that were acquired by \a listener.
//------------------------------------------------------------------
uint32_t AddListener(const lldb::ListenerSP &listener_sp,
//------------------------------------------------------------------
/// Get the NULL terminated C string name of this Broadcaster object.
///
- /// @return
+ /// \return
/// The NULL terminated C string name of this Broadcaster.
//------------------------------------------------------------------
ConstString GetBroadcasterName() { return m_broadcaster_name; }
//------------------------------------------------------------------
/// Get the event name(s) for one or more event bits.
///
- /// @param[in] event_mask
+ /// \param[in] event_mask
/// A bit mask that indicates which events to get names for.
///
- /// @return
+ /// \return
/// The NULL terminated C string name of this Broadcaster.
//------------------------------------------------------------------
bool GetEventNames(Stream &s, const uint32_t event_mask,
//------------------------------------------------------------------
/// Set the name for an event bit.
///
- /// @param[in] event_mask
+ /// \param[in] event_mask
/// A bit mask that indicates which events the listener is
/// asking to monitor.
///
- /// @return
+ /// \return
/// The NULL terminated C string name of this Broadcaster.
//------------------------------------------------------------------
void SetEventName(uint32_t event_mask, const char *name) {
/// (assuming \a listener was listening to this object) for other listener
/// objects to use.
///
- /// @param[in] listener
+ /// \param[in] listener
/// A Listener object that previously called AddListener.
///
- /// @param[in] event_mask
+ /// \param[in] event_mask
/// The event bits \a listener wishes to relinquish.
///
- /// @return
+ /// \return
/// \b True if the listener was listening to this broadcaster
/// and was removed, \b false otherwise.
///
- /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
+ /// \see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
//------------------------------------------------------------------
bool RemoveListener(const lldb::ListenerSP &listener_sp,
uint32_t event_mask = UINT32_MAX) {
/// now go to the hijacking listener. Only one hijack can occur at a time.
/// If we need more than this we will have to implement a Listener stack.
///
- /// @param[in] listener
+ /// \param[in] listener
/// A Listener object. You do not need to call StartListeningForEvents
/// for this broadcaster (that would fail anyway since the event bits
/// would most likely be taken by the listener(s) you are usurping.
///
- /// @param[in] event_mask
+ /// \param[in] event_mask
/// The event bits \a listener wishes to hijack.
///
- /// @return
+ /// \return
/// \b True if the event mask could be hijacked, \b false otherwise.
///
- /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
+ /// \see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
//------------------------------------------------------------------
bool HijackBroadcaster(const lldb::ListenerSP &listener_sp,
uint32_t event_mask = UINT32_MAX) {
};
//----------------------------------------------------------------------
-/// @class CompletionRequest CompletionRequest.h
+/// \class CompletionRequest CompletionRequest.h
/// "lldb/Utility/ArgCompletionRequest.h"
///
/// Contains all information necessary to complete an incomplete command
//----------------------------------------------------------
/// Constructs a completion request.
///
- /// @param [in] command_line
+ /// \param [in] command_line
/// The command line the user has typed at this point.
///
- /// @param [in] raw_cursor_pos
+ /// \param [in] raw_cursor_pos
/// The position of the cursor in the command line string. Index 0 means
/// the cursor is at the start of the line. The completion starts from
/// this cursor position.
///
- /// @param [in] match_start_point
- /// @param [in] max_return_elements
+ /// \param [in] match_start_point
+ /// \param [in] max_return_elements
/// If there is a match that is expensive to compute, these are here to
/// allow you to compute the completions in batches. Start the
/// completion from match_start_point, and return match_return_elements
/// elements.
///
- /// @param [out] result
+ /// \param [out] result
/// The CompletionResult that will be filled with the results after this
/// request has been handled.
//----------------------------------------------------------
/// the suggested completion is stored, so the given string can be free'd
/// afterwards.
///
- /// @param match The suggested completion.
- /// @param match An optional description of the completion string. The
+ /// \param match The suggested completion.
+ /// \param match An optional description of the completion string. The
/// description will be displayed to the user alongside the completion.
void AddCompletion(llvm::StringRef completion,
llvm::StringRef description = "") {
///
/// \param completions The list of completions.
///
- /// @see AddCompletion
+ /// \see AddCompletion
void AddCompletions(const StringList &completions) {
for (std::size_t i = 0; i < completions.GetSize(); ++i)
AddCompletion(completions.GetStringAtIndex(i));
/// \param completions The list of completions.
/// \param completions The list of descriptions.
///
- /// @see AddCompletion
+ /// \see AddCompletion
void AddCompletions(const StringList &completions,
const StringList &descriptions) {
lldbassert(completions.GetSize() == descriptions.GetSize());
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Connection Connection.h "lldb/Utility/Connection.h"
+/// \class Connection Connection.h "lldb/Utility/Connection.h"
/// A communication connection class.
///
/// A class that implements that actual communication functions for
//------------------------------------------------------------------
/// Connect using the connect string \a url.
///
- /// @param[in] url
+ /// \param[in] url
/// A string that contains all information needed by the
/// subclass to connect to another client.
///
- /// @param[out] error_ptr
+ /// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns false. This
/// value can be NULL if the error value should be ignored.
///
- /// @return
+ /// \return
/// \b True if the connect succeeded, \b false otherwise. The
/// internal error object should be filled in with an
/// appropriate value based on the result of this function.
///
- /// @see Status& Communication::GetError ();
+ /// \see Status& Communication::GetError ();
//------------------------------------------------------------------
virtual lldb::ConnectionStatus Connect(llvm::StringRef url,
Status *error_ptr) = 0;
//------------------------------------------------------------------
/// Disconnect the communications connection if one is currently connected.
///
- /// @param[out] error_ptr
+ /// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns false. This
/// value can be NULL if the error value should be ignored.
///
- /// @return
+ /// \return
/// \b True if the disconnect succeeded, \b false otherwise. The
/// internal error object should be filled in with an
/// appropriate value based on the result of this function.
///
- /// @see Status& Communication::GetError ();
+ /// \see Status& Communication::GetError ();
//------------------------------------------------------------------
virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0;
//------------------------------------------------------------------
/// Check if the connection is valid.
///
- /// @return
+ /// \return
/// \b True if this object is currently connected, \b false
/// otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// The read function that attempts to read from the connection.
///
- /// @param[in] dst
+ /// \param[in] dst
/// A destination buffer that must be at least \a dst_len bytes
/// long.
///
- /// @param[in] dst_len
+ /// \param[in] dst_len
/// The number of bytes to attempt to read, and also the max
/// number of bytes that can be placed into \a dst.
///
- /// @param[in] timeout
+ /// \param[in] timeout
/// The number of microseconds to wait for the data.
///
- /// @param[out] status
+ /// \param[out] status
/// On return, indicates whether the call was successful or terminated
/// due to some error condition.
///
- /// @param[out] error_ptr
+ /// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns zero. This
/// value can be NULL if the error value should be ignored.
///
- /// @return
+ /// \return
/// The number of bytes actually read.
///
- /// @see size_t Communication::Read (void *, size_t, uint32_t);
+ /// \see size_t Communication::Read (void *, size_t, uint32_t);
//------------------------------------------------------------------
virtual size_t Read(void *dst, size_t dst_len,
const Timeout<std::micro> &timeout,
///
/// Subclasses must override this function.
///
- /// @param[in] dst
+ /// \param[in] dst
/// A desination buffer that must be at least \a dst_len bytes
/// long.
///
- /// @param[in] dst_len
+ /// \param[in] dst_len
/// The number of bytes to attempt to write, and also the
/// number of bytes are currently available in \a dst.
///
- /// @param[out] error_ptr
+ /// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns zero. This
/// value can be NULL if the error value should be ignored.
///
- /// @return
+ /// \return
/// The number of bytes actually Written.
//------------------------------------------------------------------
virtual size_t Write(const void *dst, size_t dst_len,
///
/// Subclasses may override this function.
///
- /// @return
+ /// \return
/// Returns URI or an empty string if disconnecteds
//------------------------------------------------------------------
virtual std::string GetURI() = 0;
/// interrupt request (which will remain queued for the next Read()
/// operation).
///
- /// @return
+ /// \return
/// Returns true is the interrupt request was successful.
//------------------------------------------------------------------
virtual bool InterruptRead() = 0;
/// connection. If the Connection does not use IOObjects (and hence does not
/// support waiting) this function should return a null pointer.
///
- /// @return
+ /// \return
/// The underlying IOObject used for reading.
//------------------------------------------------------------------
virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ConstString ConstString.h "lldb/Utility/ConstString.h"
+/// \class ConstString ConstString.h "lldb/Utility/ConstString.h"
/// A uniqued constant string class.
///
/// Provides an efficient way to store strings as uniqued strings. After the
///
/// Copies the string value in \a rhs into this object.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// Another string object to copy.
//------------------------------------------------------------------
ConstString(const ConstString &rhs) : m_string(rhs.m_string) {}
/// C string already exists in the global string pool. If it doesn't
/// exist, it is added to the string pool.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// A NULL terminated C string to add to the string pool.
//------------------------------------------------------------------
explicit ConstString(const char *cstr);
/// be truncated. This allows substrings to be created without the need to
/// NULL terminate the string as it is passed into this function.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// A pointer to the first character in the C string. The C
/// string can be NULL terminated in a buffer that contains
/// more characters than the length of the string, or the
/// string can be part of another string and a new substring
/// can be created.
///
- /// @param[in] max_cstr_len
+ /// \param[in] max_cstr_len
/// The max length of \a cstr. If the string length of \a cstr
/// is less than \a max_cstr_len, then the string will be
/// truncated. If the string length of \a cstr is greater than
/// Two C strings are equal when they are contained in ConstString objects
/// when their pointer values are equal to each other.
///
- /// @return
+ /// \return
/// Returns \b true if the C string in \a lhs is equal to
/// the C string value in \a rhs, \b false otherwise.
//--------------------------------------------------------------
/// This allows code to check a ConstString object to see if it contains a
/// valid string using code such as:
///
- /// @code
+ /// \code
/// ConstString str(...);
/// if (str)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// /b True this object contains a valid non-empty C string, \b
/// false otherwise.
//------------------------------------------------------------------
///
/// Assigns the string in this object with the value from \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// Another string object to copy into this object.
///
- /// @return
+ /// \return
/// A const reference to this object.
//------------------------------------------------------------------
ConstString operator=(ConstString rhs) {
/// operation is very fast as it results in a pointer comparison since all
/// strings are in a uniqued in a global string pool.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// Another string object to compare this object to.
///
- /// @return
- /// @li \b true if this object is equal to \a rhs.
- /// @li \b false if this object is not equal to \a rhs.
+ /// \return
+ /// \li \b true if this object is equal to \a rhs.
+ /// \li \b false if this object is not equal to \a rhs.
//------------------------------------------------------------------
bool operator==(ConstString rhs) const {
// We can do a pointer compare to compare these strings since they must
/// operation is very fast as it results in a pointer comparison since all
/// strings are in a uniqued in a global string pool.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// Another string object to compare this object to.
///
- /// @return
- /// @li \b true if this object is not equal to \a rhs.
- /// @li \b false if this object is equal to \a rhs.
+ /// \return
+ /// \li \b true if this object is not equal to \a rhs.
+ /// \li \b false if this object is equal to \a rhs.
//------------------------------------------------------------------
bool operator!=(ConstString rhs) const {
return m_string != rhs.m_string;
///
/// If \a value_if_empty is nullptr, then nullptr will be returned.
///
- /// @return
+ /// \return
/// Returns \a value_if_empty if the string is empty, otherwise
/// the C string value contained in this object.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the string value as a llvm::StringRef
///
- /// @return
+ /// \return
/// Returns a new llvm::StringRef object filled in with the
/// needed data.
//------------------------------------------------------------------
/// function will always return nullptr if the string is not valid. So this
/// function is a direct accessor to the string pointer value.
///
- /// @return
+ /// \return
/// Returns nullptr the string is invalid, otherwise the C string
/// value contained in this object.
//------------------------------------------------------------------
/// The string pool stores the length of the string, so we can avoid calling
/// strlen() on the pointer value with this function.
///
- /// @return
+ /// \return
/// Returns the number of bytes that this string occupies in
/// memory, not including the NULL termination byte.
//------------------------------------------------------------------
/// in a pointer comparison since all strings are in a uniqued in a global
/// string pool.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Left Hand Side const ConstString object reference.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Right Hand Side const ConstString object reference.
///
- /// @param[in] case_sensitive
+ /// \param[in] case_sensitive
/// Case sensitivity. If true, case sensitive equality
/// will be tested, otherwise character case will be ignored
///
- /// @return
- /// @li \b true if this object is equal to \a rhs.
- /// @li \b false if this object is not equal to \a rhs.
+ /// \return
+ /// \li \b true if this object is equal to \a rhs.
+ /// \li \b false if this object is not equal to \a rhs.
//------------------------------------------------------------------
static bool Equals(ConstString lhs, ConstString rhs,
const bool case_sensitive = true);
/// it is much more efficient. Also if you want string inequality, use the
/// != operator for the same reasons.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// The Left Hand Side const ConstString object reference.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// The Right Hand Side const ConstString object reference.
///
- /// @param[in] case_sensitive
+ /// \param[in] case_sensitive
/// Case sensitivity of compare. If true, case sensitive compare
/// will be performed, otherwise character case will be ignored
///
- /// @return
- /// @li -1 if lhs < rhs
- /// @li 0 if lhs == rhs
- /// @li 1 if lhs > rhs
+ /// \return
+ /// \li -1 if lhs < rhs
+ /// \li 0 if lhs == rhs
+ /// \li 1 if lhs > rhs
//------------------------------------------------------------------
static int Compare(ConstString lhs, ConstString rhs,
const bool case_sensitive = true);
/// empty, print \a value_if_empty to the stream instead. If \a
/// value_if_empty is nullptr, then nothing will be dumped to the stream.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream that will be used to dump the object description.
///
- /// @param[in] value_if_empty
+ /// \param[in] value_if_empty
/// The value to dump if the string is empty. If nullptr, nothing
/// will be output to the stream.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Dump the object debug description to a stream.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream that will be used to dump the object description.
//------------------------------------------------------------------
void DumpDebug(Stream *s) const;
//------------------------------------------------------------------
/// Test for empty string.
///
- /// @return
- /// @li \b true if the contained string is empty.
- /// @li \b false if the contained string is not empty.
+ /// \return
+ /// \li \b true if the contained string is empty.
+ /// \li \b false if the contained string is not empty.
//------------------------------------------------------------------
bool IsEmpty() const { return m_string == nullptr || m_string[0] == '\0'; }
//------------------------------------------------------------------
/// Test for null string.
///
- /// @return
- /// @li \b true if there is no string associated with this instance.
- /// @li \b false if there is a string associated with this instance.
+ /// \return
+ /// \li \b true if there is no string associated with this instance.
+ /// \li \b false if there is a string associated with this instance.
//------------------------------------------------------------------
bool IsNull() const { return m_string == nullptr; }
/// current entry and returns the existing value. If it doesn't exist, it is
/// added to the string pool.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// A NULL terminated C string to add to the string pool.
//------------------------------------------------------------------
void SetCString(const char *cstr);
/// demangler over and over on the same strings and then trying to unique
/// them.
///
- /// @param[in] demangled
+ /// \param[in] demangled
/// The demangled string to correlate with the \a mangled name.
///
- /// @param[in] mangled
+ /// \param[in] mangled
/// The already uniqued mangled ConstString to correlate the
/// soon to be uniqued version of \a demangled.
//------------------------------------------------------------------
/// demangler over and over on the same strings and then trying to unique
/// them.
///
- /// @param[in] counterpart
+ /// \param[in] counterpart
/// A reference to a ConstString object that might get filled in
/// with the demangled/mangled counterpart.
///
- /// @return
+ /// \return
/// /b True if \a counterpart was filled in with the counterpart
/// /b false otherwise.
//------------------------------------------------------------------
/// current entry and returns the existing value. If it doesn't exist, it is
/// added to the string pool.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// A NULL terminated C string to add to the string pool.
///
- /// @param[in] cstr_len
+ /// \param[in] cstr_len
/// The maximum length of the C string.
//------------------------------------------------------------------
void SetCStringWithLength(const char *cstr, size_t cstr_len);
/// the size in bytes of this object, which does not include any the shared
/// string values it may refer to.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//------------------------------------------------------------------
size_t MemorySize() const { return sizeof(ConstString); }
/// Reports the size in bytes of all shared C string values, containers and
/// any other values as a byte size for the entire string pool.
///
- /// @return
+ /// \return
/// The number of bytes that the global string pool occupies
/// in memory.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DataBuffer DataBuffer.h "lldb/Core/DataBuffer.h"
+/// \class DataBuffer DataBuffer.h "lldb/Core/DataBuffer.h"
/// A pure virtual protocol class for abstracted data buffers.
///
/// DataBuffer is an abstract class that gets packaged into a shared pointer
//------------------------------------------------------------------
/// Get a pointer to the data.
///
- /// @return
+ /// \return
/// A pointer to the bytes owned by this object, or NULL if the
/// object contains no bytes.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get a const pointer to the data.
///
- /// @return
+ /// \return
/// A const pointer to the bytes owned by this object, or NULL
/// if the object contains no bytes.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the number of bytes in the data buffer.
///
- /// @return
+ /// \return
/// The number of bytes this object currently contains.
//------------------------------------------------------------------
virtual lldb::offset_t GetByteSize() const = 0;
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DataBufferHeap DataBufferHeap.h "lldb/Core/DataBufferHeap.h"
+/// \class DataBufferHeap DataBufferHeap.h "lldb/Core/DataBufferHeap.h"
/// A subclass of DataBuffer that stores a data buffer on the heap.
///
/// This class keeps its data in a heap based buffer that is owned by the
///
/// Initialize this class with \a n bytes and fills the buffer with \a ch.
///
- /// @param[in] n
+ /// \param[in] n
/// The number of bytes that heap based buffer should contain.
///
- /// @param[in] ch
+ /// \param[in] ch
/// The character to use when filling the buffer initially.
//------------------------------------------------------------------
DataBufferHeap(lldb::offset_t n, uint8_t ch);
//------------------------------------------------------------------
/// Construct by making a copy of \a src_len bytes from \a src.
///
- /// @param[in] src
+ /// \param[in] src
/// A pointer to the data to copy.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// The number of bytes in \a src to copy.
//------------------------------------------------------------------
DataBufferHeap(const void *src, lldb::offset_t src_len);
~DataBufferHeap() override;
//------------------------------------------------------------------
- /// @copydoc DataBuffer::GetBytes()
+ /// \copydoc DataBuffer::GetBytes()
//------------------------------------------------------------------
uint8_t *GetBytes() override;
//------------------------------------------------------------------
- /// @copydoc DataBuffer::GetBytes() const
+ /// \copydoc DataBuffer::GetBytes() const
//------------------------------------------------------------------
const uint8_t *GetBytes() const override;
//------------------------------------------------------------------
- /// @copydoc DataBuffer::GetByteSize() const
+ /// \copydoc DataBuffer::GetByteSize() const
//------------------------------------------------------------------
lldb::offset_t GetByteSize() const override;
/// This can be used prior to copying data into the buffer. Note that this
/// zero-initializes up to \p byte_size bytes.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The new size in bytes that this data buffer should attempt
/// to resize itself to.
///
- /// @return
+ /// \return
/// The size in bytes after that this heap buffer was
/// successfully resized to.
//------------------------------------------------------------------
///
/// Copies the data in \a src into an internal buffer.
///
- /// @param[in] src
+ /// \param[in] src
/// A pointer to the data to copy.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// The number of bytes in \a src to copy.
//------------------------------------------------------------------
void CopyData(const void *src, lldb::offset_t src_len);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h" An binary data
+/// \class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h" An binary data
/// encoding class.
///
/// DataEncoder is a class that can encode binary data (swapping if needed) to
/// a data buffer. The data buffer can be caller owned, or can be shared data
/// that can be shared between multiple DataEncoder or DataEncoder instances.
///
-/// @see DataBuffer
+/// \see DataBuffer
//----------------------------------------------------------------------
class DataEncoder {
public:
/// This constructor allows us to use data that is owned by the caller. The
/// data must stay around as long as this object is valid.
///
- /// @param[in] data
+ /// \param[in] data
/// A pointer to caller owned data.
///
- /// @param[in] data_length
+ /// \param[in] data_length
/// The length in bytes of \a data.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// A byte order of the data that we are extracting from.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// A new address byte size value.
//------------------------------------------------------------------
DataEncoder(void *data, uint32_t data_length, lldb::ByteOrder byte_order,
/// the data lives as long as anyone still has a valid shared pointer to the
/// data in \a data_sp.
///
- /// @param[in] data_sp
+ /// \param[in] data_sp
/// A shared pointer to data.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// A byte order of the data that we are extracting from.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// A new address byte size value.
//------------------------------------------------------------------
DataEncoder(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order,
///
/// Return the size in bytes of any address values this object will extract.
///
- /// @return
+ /// \return
/// The size in bytes of address values that will be extracted.
//------------------------------------------------------------------
uint8_t GetAddressByteSize() const { return m_addr_size; }
//------------------------------------------------------------------
/// Get the number of bytes contained in this object.
///
- /// @return
+ /// \return
/// The total number of bytes of data this object refers to.
//------------------------------------------------------------------
size_t GetByteSize() const { return m_end - m_start; }
//------------------------------------------------------------------
/// Get the data end pointer.
///
- /// @return
+ /// \return
/// Returns a pointer to the next byte contained in this
/// object's data, or NULL of there is no data in this object.
//------------------------------------------------------------------
///
/// Get the offset of the first byte of data in the shared data (if any).
///
- /// @return
+ /// \return
/// If this object contains shared data, this function returns
/// the offset in bytes into that shared data, zero otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the current byte order value.
///
- /// @return
+ /// \return
/// The current byte order value from this object's internal
/// state.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the data start pointer.
///
- /// @return
+ /// \return
/// Returns a pointer to the first byte contained in this
/// object's data, or NULL of there is no data in this object.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Encode unsigned integer values into the data at \a offset.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset within the contained data at which to put the
/// data.
///
- /// @param[in] value
+ /// \param[in] value
/// The value to encode into the data.
///
- /// @return
+ /// \return
/// The next offset in the bytes of this data if the data
/// was successfully encoded, UINT32_MAX if the encoding failed.
//------------------------------------------------------------------
/// into the existing data. There must be enough room in the data, else
/// UINT32_MAX will be returned to indicate that encoding failed.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset within the contained data at which to put the
/// encoded integer.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in byte of the integer to encode.
///
- /// @param[in] value
+ /// \param[in] value
/// The integer value to write. The least significant bytes of
/// the integer value will be written if the size is less than
/// 8 bytes.
///
- /// @return
+ /// \return
/// The next offset in the bytes of this data if the integer
/// was successfully encoded, UINT32_MAX if the encoding failed.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Encode an arbitrary number of bytes.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset in bytes into the contained data at which to
/// start encoding.
///
- /// @param[in] src
+ /// \param[in] src
/// The buffer that contains the bytes to encode.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// The number of bytes to encode.
///
- /// @return
+ /// \return
/// The next valid offset within data if the put operation
/// was successful, else UINT32_MAX to indicate the put failed.
//------------------------------------------------------------------
/// m_addr_size member variable and should be set correctly prior to
/// extracting any address values.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The next valid offset within data if the put operation
/// was successful, else UINT32_MAX to indicate the put failed.
//------------------------------------------------------------------
///
/// Encodes a C string into the existing data including the terminating
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// A pointer to the C string value in the data. If the offset
/// pointed to by \a offset_ptr is out of bounds, or if the
/// offset plus the length of the C string is out of bounds,
/// Set the size in bytes that will be used when extracting any address and
/// pointer values from data contained in this object.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// The size in bytes to use when extracting addresses.
//------------------------------------------------------------------
void SetAddressByteSize(uint8_t addr_size) { m_addr_size = addr_size; }
/// subset of this object's data, is valid. If \a bytes is NULL, or \a
/// length is zero, this object will contain no data.
///
- /// @param[in] bytes
+ /// \param[in] bytes
/// A pointer to caller owned data.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of \a bytes.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// A byte order of the data that we are extracting from.
///
- /// @return
+ /// \return
/// The number of bytes that this object now contains.
//------------------------------------------------------------------
uint32_t SetData(void *bytes, uint32_t length, lldb::ByteOrder byte_order);
/// bytes available in \a data starting at \a offset, the length will be
/// truncated to contains as many bytes as possible.
///
- /// @param[in] data_sp
+ /// \param[in] data_sp
/// A shared pointer to data.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset into \a data_sp at which the subset starts.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of the subset of \a data_sp.
///
- /// @return
+ /// \return
/// The number of bytes that this object now contains.
//------------------------------------------------------------------
uint32_t SetData(const lldb::DataBufferSP &data_sp, uint32_t offset = 0,
/// Sets the byte order of the data to extract. Extracted values will be
/// swapped if necessary when decoding.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// The byte order value to use when extracting data.
//------------------------------------------------------------------
void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; }
//------------------------------------------------------------------
/// Test the validity of \a offset.
///
- /// @return
+ /// \return
/// \b true if \a offset is a valid offset into the data in this
/// object, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Test the availability of \a length bytes of data from \a offset.
///
- /// @return
+ /// \return
/// \b true if \a offset is a valid offset and there are \a
/// length bytes available at that offset, \b false otherwise.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h" An data
+/// \class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h" An data
/// extractor class.
///
/// DataExtractor is a class that can extract data (swapping if needed) from a
/// unique position in the shared data and extract data from different
/// offsets.
///
-/// @see DataBuffer
+/// \see DataBuffer
//----------------------------------------------------------------------
class DataExtractor {
public:
//------------------------------------------------------------------
- /// @typedef DataExtractor::Type
+ /// \typedef DataExtractor::Type
/// Type enumerations used in the dump routines.
//------------------------------------------------------------------
typedef enum {
/// This constructor allows us to use data that is owned by the caller. The
/// data must stay around as long as this object is valid.
///
- /// @param[in] data
+ /// \param[in] data
/// A pointer to caller owned data.
///
- /// @param[in] data_length
+ /// \param[in] data_length
/// The length in bytes of \a data.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// A byte order of the data that we are extracting from.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// A new address byte size value.
///
- /// @param[in] target_byte_size
+ /// \param[in] target_byte_size
/// A size of a target byte in 8-bit host bytes
//------------------------------------------------------------------
DataExtractor(const void *data, lldb::offset_t data_length,
/// the data lives as long as anyone still has a valid shared pointer to the
/// data in \a data_sp.
///
- /// @param[in] data_sp
+ /// \param[in] data_sp
/// A shared pointer to data.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// A byte order of the data that we are extracting from.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// A new address byte size value.
///
- /// @param[in] target_byte_size
+ /// \param[in] target_byte_size
/// A size of a target byte in 8-bit host bytes
//------------------------------------------------------------------
DataExtractor(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order,
/// are not \a length bytes available in \a data starting at \a offset, the
/// length will be truncated to contain as many bytes as possible.
///
- /// @param[in] data
+ /// \param[in] data
/// Another DataExtractor object that contains data.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset into \a data at which the subset starts.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of the subset of data.
///
- /// @param[in] target_byte_size
+ /// \param[in] target_byte_size
/// A size of a target byte in 8-bit host bytes
//------------------------------------------------------------------
DataExtractor(const DataExtractor &data, lldb::offset_t offset,
/// this object. If \a rhs contains shared data, a reference to that shared
/// data will be added.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// Another DataExtractor object to copy.
///
- /// @return
+ /// \return
/// A const reference to this object.
//------------------------------------------------------------------
const DataExtractor &operator=(const DataExtractor &rhs);
/// the beginning of each line and can be offset by base address \a
/// base_addr. \a num_per_line objects will be displayed on each line.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to dump the output to. If nullptr the output will
/// be dumped to Log().
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset into the data at which to start dumping.
///
- /// @param[in] length
+ /// \param[in] length
/// The number of bytes to dump.
///
- /// @param[in] base_addr
+ /// \param[in] base_addr
/// The base address that gets added to the offset displayed on
/// each line.
///
- /// @param[in] num_per_line
+ /// \param[in] num_per_line
/// The number of \a type objects to display on each line.
///
- /// @param[in] type
+ /// \param[in] type
/// The type of objects to use when dumping data from this
/// object. See DataExtractor::Type.
///
- /// @param[in] type_format
+ /// \param[in] type_format
/// The optional format to use for the \a type objects. If this
/// is nullptr, the default format for the \a type will be used.
///
- /// @return
+ /// \return
/// The offset at which dumping ended.
//------------------------------------------------------------------
lldb::offset_t PutToLog(Log *log, lldb::offset_t offset,
/// data in the requested byte order (\a dst_byte_order) and place the
/// results in \a dst. \a dst must be at least \a length bytes long.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset in bytes into the contained data at which to
/// start extracting.
///
- /// @param[in] length
+ /// \param[in] length
/// The number of bytes to extract.
///
- /// @param[in] dst_byte_order
+ /// \param[in] dst_byte_order
/// A byte order of the data that we want when the value in
/// copied to \a dst.
///
- /// @param[out] dst
+ /// \param[out] dst
/// The buffer that will receive the extracted value if there
/// are enough bytes available in the current data.
///
- /// @return
+ /// \return
/// The number of bytes that were extracted which will be \a
/// length when the value is successfully extracted, or zero
/// if there aren't enough bytes at the specified offset.
/// m_addr_size member variable and should be set correctly prior to
/// extracting any address values.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted address value.
//------------------------------------------------------------------
uint64_t GetAddress(lldb::offset_t *offset_ptr) const;
///
/// Return the size in bytes of any address values this object will extract.
///
- /// @return
+ /// \return
/// The size in bytes of address values that will be extracted.
//------------------------------------------------------------------
uint32_t GetAddressByteSize() const { return m_addr_size; }
//------------------------------------------------------------------
/// Get the number of bytes contained in this object.
///
- /// @return
+ /// \return
/// The total number of bytes of data this object refers to.
//------------------------------------------------------------------
uint64_t GetByteSize() const { return m_end - m_start; }
/// extracted and the \a offset_ptr will be updated with the offset of the
/// byte that follows the NULL terminator byte.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// A pointer to the C string value in the data. If the offset
/// pointed to by \a offset_ptr is out of bounds, or if the
/// offset plus the length of the C string is out of bounds,
/// will be updated with the offset of the byte that follows the fixed
/// length field.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// A pointer to the C string value in the data. If the offset
/// pointed to by \a offset_ptr is out of bounds, or if the
/// offset plus the length of the field is out of bounds, or if
/// pointed to by \a offset_ptr will not be updated and nullptr will be
/// returned.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[in] length
+ /// \param[in] length
/// The optional length of a string to extract. If the value is
/// zero, a NULL terminated C string will be extracted.
///
- /// @return
+ /// \return
/// A pointer to the bytes in this object's data if the offset
/// and length are valid, or nullptr otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Copy \a length bytes from \a *offset, without swapping bytes.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset into this data from which to start copying
///
- /// @param[in] length
+ /// \param[in] length
/// The length of the data to copy from this object
///
- /// @param[out] dst
+ /// \param[out] dst
/// The buffer to place the output data.
///
- /// @return
+ /// \return
/// Returns the number of bytes that were copied, or zero if
/// anything goes wrong.
//------------------------------------------------------------------
/// order of this object and the \a dst_byte_order. This can be very handy
/// when say copying a partial data value into a register.
///
- /// @param[in] src_offset
+ /// \param[in] src_offset
/// The offset into this data from which to start copying an
/// endian entity
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// The length of the endian data to copy from this object
/// into the \a dst object
///
- /// @param[out] dst
+ /// \param[out] dst
/// The buffer where to place the endian data. The data might
/// need to be byte swapped (and appropriately padded with
/// zeroes if \a src_len != \a dst_len) if \a dst_byte_order
/// does not match the byte order in this object.
///
- /// @param[in] dst_len
+ /// \param[in] dst_len
/// The length number of bytes that the endian value will
/// occupy is \a dst.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// The byte order that the endian value should be in the \a dst
/// buffer.
///
- /// @return
+ /// \return
/// Returns the number of bytes that were copied, or zero if
/// anything goes wrong.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the data end pointer.
///
- /// @return
+ /// \return
/// Returns a pointer to the next byte contained in this
/// object's data, or nullptr of there is no data in this object.
//------------------------------------------------------------------
///
/// Get the offset of the first byte of data in the shared data (if any).
///
- /// @return
+ /// \return
/// If this object contains shared data, this function returns
/// the offset in bytes into that shared data, zero otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the data start pointer.
///
- /// @return
+ /// \return
/// Returns a pointer to the first byte contained in this
/// object's data, or nullptr of there is no data in this object.
//------------------------------------------------------------------
///
/// Extract a single float value.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The floating value that was extracted, or zero on failure.
//------------------------------------------------------------------
float GetFloat(lldb::offset_t *offset_ptr) const;
/// byte_size argument. \a byte_size must have a value >= 1 and <= 4 since
/// the return value is only 32 bits wide.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in byte of the integer to extract.
///
- /// @return
+ /// \return
/// The integer value that was extracted, or zero on failure.
//------------------------------------------------------------------
uint32_t GetMaxU32(lldb::offset_t *offset_ptr, size_t byte_size) const;
/// equal to one and less than or equal to eight since the return value is
/// 64 bits wide.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in byte of the integer to extract.
///
- /// @return
+ /// \return
/// The unsigned integer value that was extracted, or zero on
/// failure.
//------------------------------------------------------------------
/// have a value greater than or equal to one and less than or equal to
/// eight since the return value is 64 bits wide.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in byte of the integer to extract.
///
- /// @return
+ /// \return
/// The sign extended signed integer value that was extracted,
/// or zero on failure.
//------------------------------------------------------------------
/// equal to one and less than or equal to 8 since the return value is 64
/// bits wide.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in byte of the integer to extract.
///
- /// @param[in] bitfield_bit_size
+ /// \param[in] bitfield_bit_size
/// The size in bits of the bitfield value to extract, or zero
/// to just extract the entire integer value.
///
- /// @param[in] bitfield_bit_offset
+ /// \param[in] bitfield_bit_offset
/// The bit offset of the bitfield value in the extracted
/// integer. For little-endian data, this is the offset of
/// the LSB of the bitfield from the LSB of the integer.
/// For big-endian data, this is the offset of the MSB of the
/// bitfield from the MSB of the integer.
///
- /// @return
+ /// \return
/// The unsigned bitfield integer value that was extracted, or
/// zero on failure.
//------------------------------------------------------------------
/// have a value greater than or equal to one and less than or equal to
/// eight since the return value is 64 bits wide.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[in] byte_size
+ /// \param[in] byte_size
/// The size in bytes of the integer to extract.
///
- /// @param[in] bitfield_bit_size
+ /// \param[in] bitfield_bit_size
/// The size in bits of the bitfield value to extract, or zero
/// to just extract the entire integer value.
///
- /// @param[in] bitfield_bit_offset
+ /// \param[in] bitfield_bit_offset
/// The bit offset of the bitfield value in the extracted
/// integer. For little-endian data, this is the offset of
/// the LSB of the bitfield from the LSB of the integer.
/// For big-endian data, this is the offset of the MSB of the
/// bitfield from the MSB of the integer.
///
- /// @return
+ /// \return
/// The signed bitfield integer value that was extracted, or
/// zero on failure.
//------------------------------------------------------------------
/// m_addr_size member variable and should be set correctly prior to
/// extracting any pointer values.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted pointer value as a 64 integer.
//------------------------------------------------------------------
uint64_t GetPointer(lldb::offset_t *offset_ptr) const;
//------------------------------------------------------------------
/// Get the current byte order value.
///
- /// @return
+ /// \return
/// The current byte order value from this object's internal
/// state.
//------------------------------------------------------------------
/// Extract a single uint8_t from the binary data at the offset pointed to
/// by \a offset_ptr, and advance the offset on success.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted uint8_t value.
//------------------------------------------------------------------
uint8_t GetU8(lldb::offset_t *offset_ptr) const;
/// pointed to by \a offset_ptr, and advance the offset on success. The
/// extracted values are copied into \a dst.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[out] dst
+ /// \param[out] dst
/// A buffer to copy \a count uint8_t values into. \a dst must
/// be large enough to hold all requested data.
///
- /// @param[in] count
+ /// \param[in] count
/// The number of uint8_t values to extract.
///
- /// @return
+ /// \return
/// \a dst if all values were properly extracted and copied,
/// nullptr otherwise.
//------------------------------------------------------------------
/// Extract a single uint16_t from the binary data at the offset pointed to
/// by \a offset_ptr, and update the offset on success.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted uint16_t value.
//------------------------------------------------------------------
uint16_t GetU16(lldb::offset_t *offset_ptr) const;
/// pointed to by \a offset_ptr, and advance the offset on success. The
/// extracted values are copied into \a dst.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[out] dst
+ /// \param[out] dst
/// A buffer to copy \a count uint16_t values into. \a dst must
/// be large enough to hold all requested data.
///
- /// @param[in] count
+ /// \param[in] count
/// The number of uint16_t values to extract.
///
- /// @return
+ /// \return
/// \a dst if all values were properly extracted and copied,
/// nullptr otherwise.
//------------------------------------------------------------------
/// Extract a single uint32_t from the binary data at the offset pointed to
/// by \a offset_ptr, and update the offset on success.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted uint32_t value.
//------------------------------------------------------------------
uint32_t GetU32(lldb::offset_t *offset_ptr) const;
/// pointed to by \a offset_ptr, and advance the offset on success. The
/// extracted values are copied into \a dst.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[out] dst
+ /// \param[out] dst
/// A buffer to copy \a count uint32_t values into. \a dst must
/// be large enough to hold all requested data.
///
- /// @param[in] count
+ /// \param[in] count
/// The number of uint32_t values to extract.
///
- /// @return
+ /// \return
/// \a dst if all values were properly extracted and copied,
/// nullptr otherwise.
//------------------------------------------------------------------
/// Extract a single uint64_t from the binary data at the offset pointed to
/// by \a offset_ptr, and update the offset on success.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted uint64_t value.
//------------------------------------------------------------------
uint64_t GetU64(lldb::offset_t *offset_ptr) const;
/// pointed to by \a offset_ptr, and advance the offset on success. The
/// extracted values are copied into \a dst.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @param[out] dst
+ /// \param[out] dst
/// A buffer to copy \a count uint64_t values into. \a dst must
/// be large enough to hold all requested data.
///
- /// @param[in] count
+ /// \param[in] count
/// The number of uint64_t values to extract.
///
- /// @return
+ /// \return
/// \a dst if all values were properly extracted and copied,
/// nullptr otherwise.
//------------------------------------------------------------------
/// offset_ptr will be updated with the offset of the byte following the
/// last extracted byte.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted signed integer value.
//------------------------------------------------------------------
int64_t GetSLEB128(lldb::offset_t *offset_ptr) const;
/// offset_ptr will be updated with the offset of the byte following the
/// last extracted byte.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
/// The extracted unsigned integer value.
//------------------------------------------------------------------
uint64_t GetULEB128(lldb::offset_t *offset_ptr) const;
/// sure the entire string lies within the bounds of this object's data,
/// only \a offset is verified to be a valid offset.
///
- /// @param[in] offset
+ /// \param[in] offset
/// An offset into the data.
///
- /// @return
+ /// \return
/// A non-nullptr C string pointer if \a offset is a valid offset,
/// nullptr otherwise.
//------------------------------------------------------------------
/// Returns a pointer to \a length bytes at \a offset as long as there are
/// \a length bytes available starting at \a offset.
///
- /// @return
+ /// \return
/// A non-nullptr data pointer if \a offset is a valid offset and
/// there are \a length bytes available at that offset, nullptr
/// otherwise.
/// Set the size in bytes that will be used when extracting any address and
/// pointer values from data contained in this object.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// The size in bytes to use when extracting addresses.
//------------------------------------------------------------------
void SetAddressByteSize(uint32_t addr_size) {
/// subset of this object's data, is valid. If \a bytes is nullptr, or \a
/// length is zero, this object will contain no data.
///
- /// @param[in] bytes
+ /// \param[in] bytes
/// A pointer to caller owned data.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of \a bytes.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// A byte order of the data that we are extracting from.
///
- /// @return
+ /// \return
/// The number of bytes that this object now contains.
//------------------------------------------------------------------
lldb::offset_t SetData(const void *bytes, lldb::offset_t length,
/// are not \a length bytes available in \a data starting at \a offset, the
/// length will be truncated to contains as many bytes as possible.
///
- /// @param[in] data
+ /// \param[in] data
/// Another DataExtractor object that contains data.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset into \a data at which the subset starts.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of the subset of \a data.
///
- /// @return
+ /// \return
/// The number of bytes that this object now contains.
//------------------------------------------------------------------
lldb::offset_t SetData(const DataExtractor &data, lldb::offset_t offset,
/// bytes available in \a data starting at \a offset, the length will be
/// truncated to contains as many bytes as possible.
///
- /// @param[in] data_sp
+ /// \param[in] data_sp
/// A shared pointer to data.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset into \a data_sp at which the subset starts.
///
- /// @param[in] length
+ /// \param[in] length
/// The length in bytes of the subset of \a data_sp.
///
- /// @return
+ /// \return
/// The number of bytes that this object now contains.
//------------------------------------------------------------------
lldb::offset_t SetData(const lldb::DataBufferSP &data_sp,
/// Sets the byte order of the data to extract. Extracted values will be
/// swapped if necessary when decoding.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// The byte order value to use when extracting data.
//------------------------------------------------------------------
void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; }
/// to by \a offset_ptr will be updated with the offset of the byte
/// following the last extracted byte.
///
- /// @param[in,out] offset_ptr
+ /// \param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
/// by the appropriate number of bytes if the value is extracted
/// correctly. If the offset is out of bounds or there are not
/// enough bytes to extract this value, the offset will be left
/// unmodified.
///
- /// @return
+ /// \return
// The number of bytes consumed during the extraction.
//------------------------------------------------------------------
uint32_t Skip_LEB128(lldb::offset_t *offset_ptr) const;
//------------------------------------------------------------------
/// Test the validity of \a offset.
///
- /// @return
+ /// \return
/// \b true if \a offset is a valid offset into the data in this
/// object, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Test the availability of \a length bytes of data from \a offset.
///
- /// @return
+ /// \return
/// \b true if \a offset is a valid offset and there are \a
/// length bytes available at that offset, \b false otherwise.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class FileSpec FileSpec.h "lldb/Host/FileSpec.h"
+/// \class FileSpec FileSpec.h "lldb/Host/FileSpec.h"
/// A file utility class.
///
/// A file specification class that divides paths up into a directory
/// \a path is not nullptr or empty, this function will call
/// FileSpec::SetFile (const char *path).
///
- /// @param[in] path
+ /// \param[in] path
/// The full or partial path to a file.
///
- /// @param[in] style
+ /// \param[in] style
/// The style of the path
///
- /// @see FileSpec::SetFile (const char *path)
+ /// \see FileSpec::SetFile (const char *path)
//------------------------------------------------------------------
explicit FileSpec(llvm::StringRef path, Style style = Style::native);
///
/// Makes a copy of the uniqued directory and filename strings from \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const FileSpec object reference to copy.
//------------------------------------------------------------------
FileSpec(const FileSpec &rhs);
/// Makes a copy of the uniqued directory and filename strings from \a rhs
/// if it is not nullptr.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const FileSpec object pointer to copy if non-nullptr.
//------------------------------------------------------------------
FileSpec(const FileSpec *rhs);
///
/// Makes a copy of the uniqued directory and filename strings from \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const FileSpec object reference to assign to this object.
///
- /// @return
+ /// \return
/// A const reference to this object.
//------------------------------------------------------------------
const FileSpec &operator=(const FileSpec &rhs);
///
/// Tests if this object is equal to \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const FileSpec object reference to compare this object
/// to.
///
- /// @return
+ /// \return
/// \b true if this object is equal to \a rhs, \b false
/// otherwise.
//------------------------------------------------------------------
///
/// Tests if this object is not equal to \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const FileSpec object reference to compare this object
/// to.
///
- /// @return
+ /// \return
/// \b true if this object is equal to \a rhs, \b false
/// otherwise.
//------------------------------------------------------------------
///
/// Tests if this object is less than \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const FileSpec object reference to compare this object
/// to.
///
- /// @return
+ /// \return
/// \b true if this object is less than \a rhs, \b false
/// otherwise.
//------------------------------------------------------------------
/// This allows code to check a FileSpec object to see if it contains
/// anything valid using code such as:
///
- /// @code
+ /// \code
/// FileSpec file_spec(...);
/// if (file_spec)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// A pointer to this object if either the directory or filename
/// is valid, nullptr otherwise.
//------------------------------------------------------------------
/// This allows code to check a FileSpec object to see if it is invalid
/// using code such as:
///
- /// @code
+ /// \code
/// FileSpec file_spec(...);
/// if (!file_spec)
/// { ...
- /// @endcode
+ /// \endcode
///
- /// @return
+ /// \return
/// Returns \b true if the object has an empty directory and
/// filename, \b false otherwise.
//------------------------------------------------------------------
/// to only contain a filename and it can match FileSpec objects that have
/// matching filenames with different paths.
///
- /// @param[in] lhs
+ /// \param[in] lhs
/// A const reference to the Left Hand Side object to compare.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const reference to the Right Hand Side object to compare.
///
- /// @param[in] full
+ /// \param[in] full
/// If true, then both the directory and filenames will have to
/// match for a compare to return zero (equal to). If false
/// and either directory from \a lhs or \a rhs is empty, then
/// only the filename will be compared, else a full comparison
/// is done.
///
- /// @return
- /// @li -1 if \a lhs is less than \a rhs
- /// @li 0 if \a lhs is equal to \a rhs
- /// @li 1 if \a lhs is greater than \a rhs
+ /// \return
+ /// \li -1 if \a lhs is less than \a rhs
+ /// \li 0 if \a lhs is equal to \a rhs
+ /// \li 1 if \a lhs is greater than \a rhs
//------------------------------------------------------------------
static int Compare(const FileSpec &lhs, const FileSpec &rhs, bool full);
//------------------------------------------------------------------
/// Case sensitivity of path.
///
- /// @return
+ /// \return
/// \b true if the file path is case sensitive (POSIX), false
/// if case insensitive (Windows).
//------------------------------------------------------------------
/// valid directory name, it will be displayed followed by a directory
/// delimiter, and the filename.
///
- /// @param[in] s
+ /// \param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
void Dump(Stream *s) const;
//------------------------------------------------------------------
/// Directory string get accessor.
///
- /// @return
+ /// \return
/// A reference to the directory string object.
//------------------------------------------------------------------
ConstString &GetDirectory();
//------------------------------------------------------------------
/// Directory string const get accessor.
///
- /// @return
+ /// \return
/// A const reference to the directory string object.
//------------------------------------------------------------------
ConstString GetDirectory() const;
//------------------------------------------------------------------
/// Filename string get accessor.
///
- /// @return
+ /// \return
/// A reference to the filename string object.
//------------------------------------------------------------------
ConstString &GetFilename();
//------------------------------------------------------------------
/// Filename string const get accessor.
///
- /// @return
+ /// \return
/// A const reference to the filename string object.
//------------------------------------------------------------------
ConstString GetFilename() const;
/// Returns true if the filespec represents an implementation source file
/// (files with a ".c", ".cpp", ".m", ".mm" (many more) extension).
///
- /// @return
+ /// \return
/// \b true if the filespec represents an implementation source
/// file, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns true if the filespec represents a relative path.
///
- /// @return
+ /// \return
/// \b true if the filespec represents a relative path,
/// \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Returns true if the filespec represents an absolute path.
///
- /// @return
+ /// \return
/// \b true if the filespec represents an absolute path,
/// \b false otherwise.
//------------------------------------------------------------------
/// Extract the directory and path into a fixed buffer. This is needed as
/// the directory and path are stored in separate string values.
///
- /// @param[out] path
+ /// \param[out] path
/// The buffer in which to place the extracted full path.
///
- /// @param[in] max_path_length
+ /// \param[in] max_path_length
/// The maximum length of \a path.
///
- /// @return
+ /// \return
/// Returns the number of characters that would be needed to
/// properly copy the full path into \a path. If the returned
/// number is less than \a max_path_length, then the path is
///
/// Extract the directory and path into a std::string, which is returned.
///
- /// @return
+ /// \return
/// Returns a std::string with the directory and filename
/// concatenated.
//------------------------------------------------------------------
///
/// Extract the directory and path into an llvm::SmallVectorImpl<>
///
- /// @return
+ /// \return
/// Returns a std::string with the directory and filename
/// concatenated.
//------------------------------------------------------------------
/// filename has no extension, ConstString(nullptr) is returned. The dot
/// ('.') character is not returned as part of the extension
///
- /// @return
+ /// \return
/// Returns the extension of the file as a ConstString object.
//------------------------------------------------------------------
ConstString GetFileNameExtension() const;
/// without the extension part (e.g. for a file named "foo.bar", "foo" is
/// returned)
///
- /// @return
+ /// \return
/// Returns the filename without extension
/// as a ConstString object.
//------------------------------------------------------------------
/// the size in bytes of this object, not any shared string values it may
/// refer to.
///
- /// @return
+ /// \return
/// The number of bytes that this object occupies in memory.
///
- /// @see ConstString::StaticMemorySize ()
+ /// \see ConstString::StaticMemorySize ()
//------------------------------------------------------------------
size_t MemorySize() const;
/// split up into a directory and filename and stored as uniqued string
/// values for quick comparison and efficient memory usage.
///
- /// @param[in] path
+ /// \param[in] path
/// A full, partial, or relative path to a file.
///
- /// @param[in] resolve_path
+ /// \param[in] resolve_path
/// If \b true, then we will try to resolve links the path using
/// the static FileSpec::Resolve.
//------------------------------------------------------------------
/// we don't try and resolve it later, or try and resolve a path that has
/// already been resolved.
///
- /// @param[in] is_resolved
+ /// \param[in] is_resolved
/// A boolean value that will replace the current value that
/// indicates if the paths in this object have been resolved.
//------------------------------------------------------------------
/// Removes the last path component by replacing the current path with its
/// parent. When the current path has no parent, this is a no-op.
///
- /// @return
+ /// \return
/// A boolean value indicating whether the path was updated.
//------------------------------------------------------------------
bool RemoveLastPathComponent();
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Flags Flags.h "lldb/Utility/Flags.h"
+/// \class Flags Flags.h "lldb/Utility/Flags.h"
/// A class to manage flags.
///
/// The Flags class managed flag bits and allows testing and modification of
/// Constructs this object with \a mask as the initial value for all of the
/// flags.
///
- /// @param[in] mask
+ /// \param[in] mask
/// The initial value for all flags.
//----------------------------------------------------------------------
Flags(ValueType flags = 0) : m_flags(flags) {}
///
/// Construct and copy the flags from \a rhs.
///
- /// @param[in] rhs
+ /// \param[in] rhs
/// A const Flags object reference to copy.
//----------------------------------------------------------------------
Flags(const Flags &rhs) : m_flags(rhs.m_flags) {}
//----------------------------------------------------------------------
/// Get accessor for all flags.
///
- /// @return
+ /// \return
/// Returns all of the flags as a Flags::ValueType.
//----------------------------------------------------------------------
ValueType Get() const { return m_flags; }
//----------------------------------------------------------------------
/// Return the number of flags that can be represented in this object.
///
- /// @return
+ /// \return
/// The maximum number bits in this flag object.
//----------------------------------------------------------------------
size_t GetBitSize() const { return sizeof(ValueType) * 8; }
//----------------------------------------------------------------------
/// Set accessor for all flags.
///
- /// @param[in] flags
+ /// \param[in] flags
/// The bits with which to replace all of the current flags.
//----------------------------------------------------------------------
void Reset(ValueType flags) { m_flags = flags; }
//----------------------------------------------------------------------
/// Clear one or more flags.
///
- /// @param[in] mask
+ /// \param[in] mask
/// A bitfield containing one or more flags.
///
- /// @return
+ /// \return
/// The new flags after clearing all bits from \a mask.
//----------------------------------------------------------------------
ValueType Clear(ValueType mask = ~(ValueType)0) {
//----------------------------------------------------------------------
/// Set one or more flags by logical OR'ing \a mask with the current flags.
///
- /// @param[in] mask
+ /// \param[in] mask
/// A bitfield containing one or more flags.
///
- /// @return
+ /// \return
/// The new flags after setting all bits from \a mask.
//----------------------------------------------------------------------
ValueType Set(ValueType mask) {
//----------------------------------------------------------------------
/// Test if all bits in \a mask are 1 in the current flags
///
- /// @return
+ /// \return
/// \b true if all flags in \a mask are 1, \b false
/// otherwise.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// Test one or more flags.
///
- /// @return
+ /// \return
/// \b true if any flags in \a mask are 1, \b false
/// otherwise.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// Test a single flag bit.
///
- /// @return
+ /// \return
/// \b true if \a bit is set, \b false otherwise.
//----------------------------------------------------------------------
bool Test(ValueType bit) const { return (m_flags & bit) != 0; }
//----------------------------------------------------------------------
/// Test if all bits in \a mask are clear.
///
- /// @return
+ /// \return
/// \b true if \b all flags in \a mask are clear, \b false
/// otherwise.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// Test a single flag bit to see if it is clear (zero).
///
- /// @return
+ /// \return
/// \b true if \a bit is 0, \b false otherwise.
//----------------------------------------------------------------------
bool IsClear(ValueType bit) const { return (m_flags & bit) == 0; }
//----------------------------------------------------------------------
/// Get the number of zero bits in \a m_flags.
///
- /// @return
+ /// \return
/// The number of bits that are set to 0 in the current flags.
//----------------------------------------------------------------------
size_t ClearCount() const {
//----------------------------------------------------------------------
/// Get the number of one bits in \a m_flags.
///
- /// @return
+ /// \return
/// The number of bits that are set to 1 in the current flags.
//----------------------------------------------------------------------
size_t SetCount() const {
} PredicateBroadcastType;
//----------------------------------------------------------------------
-/// @class Predicate Predicate.h "lldb/Utility/Predicate.h"
+/// \class Predicate Predicate.h "lldb/Utility/Predicate.h"
/// A C++ wrapper class for providing threaded access to a value of
/// type T.
///
/// Initializes the mutex and condition with their default
/// constructors, and initializes the value with \a initial_value.
///
- /// @param[in] initial_value
+ /// \param[in] initial_value
/// The initial value for our T object.
//------------------------------------------------------------------
Predicate(T initial_value)
/// Copies the current \a m_value in a thread safe manor and returns
/// the copied value.
///
- /// @return
+ /// \return
/// A copy of the current value.
//------------------------------------------------------------------
T GetValue() const {
/// Set the contained \a m_value to \a new_value in a thread safe
/// way and broadcast if needed.
///
- /// @param[in] value
+ /// \param[in] value
/// The new value to set.
///
- /// @param[in] broadcast_type
+ /// \param[in] broadcast_type
/// A value indicating when and if to broadcast. See the
/// PredicateBroadcastType enumeration for details.
///
- /// @see Predicate::Broadcast()
+ /// \see Predicate::Broadcast()
//------------------------------------------------------------------
void SetValue(T value, PredicateBroadcastType broadcast_type) {
std::lock_guard<std::mutex> guard(m_mutex);
/// into a wait state. It may be necessary for the calling code to use
/// additional thread synchronization methods to detect transitory states.
///
- /// @param[in] Cond
+ /// \param[in] Cond
/// The condition we want \a m_value satisfy.
///
- /// @param[in] timeout
+ /// \param[in] timeout
/// How long to wait for the condition to hold.
///
- /// @return
- /// @li m_value if Cond(m_value) is true.
- /// @li None otherwise (timeout occurred).
+ /// \return
+ /// \li m_value if Cond(m_value) is true.
+ /// \li None otherwise (timeout occurred).
//------------------------------------------------------------------
template <typename C>
llvm::Optional<T> WaitFor(C Cond, const Timeout<std::micro> &timeout) {
/// may be necessary for the calling code to use additional thread
/// synchronization methods to detect transitory states.
///
- /// @param[in] value
+ /// \param[in] value
/// The value we want \a m_value to be equal to.
///
- /// @param[in] timeout
+ /// \param[in] timeout
/// How long to wait for the condition to hold.
///
- /// @return
- /// @li \b true if the \a m_value is equal to \a value
- /// @li \b false otherwise (timeout occurred)
+ /// \return
+ /// \li \b true if the \a m_value is equal to \a value
+ /// \li \b false otherwise (timeout occurred)
//------------------------------------------------------------------
bool WaitForValueEqualTo(T value,
const Timeout<std::micro> &timeout = llvm::None) {
/// necessary for the calling code to use additional thread
/// synchronization methods to detect transitory states.
///
- /// @param[in] value
+ /// \param[in] value
/// The value we want \a m_value to not be equal to.
///
- /// @param[in] timeout
+ /// \param[in] timeout
/// How long to wait for the condition to hold.
///
- /// @return
- /// @li m_value if m_value != value
- /// @li None otherwise (timeout occurred).
+ /// \return
+ /// \li m_value if m_value != value
+ /// \li None otherwise (timeout occurred).
//------------------------------------------------------------------
llvm::Optional<T>
WaitForValueNotEqualTo(T value,
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class RegularExpression RegularExpression.h
+/// \class RegularExpression RegularExpression.h
/// "lldb/Utility/RegularExpression.h"
/// A C++ wrapper class for regex.
///
/// after the regular expression is compiled. Any previously compiled
/// regular expression contained in this object will be freed.
///
- /// @param[in] re
+ /// \param[in] re
/// A NULL terminated C string that represents the regular
/// expression to compile.
///
- /// @return
+ /// \return
/// \b true if the regular expression compiles successfully,
/// \b false otherwise.
//------------------------------------------------------------------
/// indicate the number of regmatch_t values that are present in \a
/// match_ptr.
///
- /// @param[in] string
+ /// \param[in] string
/// The string to match against the compile regular expression.
///
- /// @param[in] match
+ /// \param[in] match
/// A pointer to a RegularExpression::Match structure that was
/// properly initialized with the desired number of maximum
/// matches, or nullptr if no parenthesized matching is needed.
///
- /// @return
+ /// \return
/// \b true if \a string matches the compiled regular
/// expression, \b false otherwise.
//------------------------------------------------------------------
/// Returns the text that was used to compile the current regular
/// expression.
///
- /// @return
+ /// \return
/// The NULL terminated C string that was used to compile the
/// current regular expression
//------------------------------------------------------------------
///
/// Test if this object contains a valid regular expression.
///
- /// @return
+ /// \return
/// \b true if the regular expression compiled and is ready
/// for execution, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Converts a StateType to a C string.
///
-/// @param[in] state
+/// \param[in] state
/// The StateType object to convert.
///
-/// @return
+/// \return
/// A NULL terminated C string that describes \a state. The
/// returned string comes from constant string buffers and does
/// not need to be freed.
/// Check if a state represents a state where the process or thread
/// is running.
///
-/// @param[in] state
+/// \param[in] state
/// The StateType enumeration value
///
-/// @return
+/// \return
/// \b true if the state represents a process or thread state
/// where the process or thread is running, \b false otherwise.
//------------------------------------------------------------------
/// yet. The \a must_exist argument tells us which of these cases is
/// desired.
///
-/// @param[in] state
+/// \param[in] state
/// The StateType enumeration value
///
-/// @param[in] must_exist
+/// \param[in] must_exist
/// A boolean that indicates the thread must also be alive
/// so states like unloaded or exited won't return true.
///
-/// @return
+/// \return
/// \b true if the state represents a process or thread state
/// where the process or thread is stopped. If \a must_exist is
/// \b true, then the process can't be exited or unloaded,
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Status Status.h "lldb/Utility/Status.h" An error handling class.
+/// \class Status Status.h "lldb/Utility/Status.h" An error handling class.
///
/// This class is designed to be able to hold any error code that can be
/// encountered on a given platform. The errors are stored as a value of type
///
/// Initialize the error object with a generic success value.
///
- /// @param[in] err
+ /// \param[in] err
/// An error code.
///
- /// @param[in] type
+ /// \param[in] type
/// The type for \a err.
//------------------------------------------------------------------
Status();
//------------------------------------------------------------------
/// Assignment operator.
///
- /// @param[in] err
+ /// \param[in] err
/// An error code.
///
- /// @return
+ /// \return
/// A const reference to this object.
//------------------------------------------------------------------
const Status &operator=(const Status &rhs);
/// from a callback that is appropriate for the type of the error and will
/// be cached until the error value is changed or cleared.
///
- /// @return
+ /// \return
/// The error as a NULL terminated C string value if the error
/// is valid and is able to be converted to a string value,
/// NULL otherwise.
//------------------------------------------------------------------
/// Test for error condition.
///
- /// @return
+ /// \return
/// \b true if this object contains an error, \b false
/// otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Access the error value.
///
- /// @return
+ /// \return
/// The error value.
//------------------------------------------------------------------
ValueType GetError() const;
//------------------------------------------------------------------
/// Access the error type.
///
- /// @return
+ /// \return
/// The error type enumeration value.
//------------------------------------------------------------------
lldb::ErrorType GetType() const;
/// Set accesssor for the error value to \a err and the error type to \c
/// MachKernel.
///
- /// @param[in] err
+ /// \param[in] err
/// A mach error code.
//------------------------------------------------------------------
void SetMachError(uint32_t err);
/// Set accesssor for the error value to \a err and the error type to \a
/// type.
///
- /// @param[in] err
+ /// \param[in] err
/// A mach error code.
///
- /// @param[in] type
+ /// \param[in] type
/// The type for \a err.
//------------------------------------------------------------------
void SetError(ValueType err, lldb::ErrorType type);
/// will remain until the error value is cleared or a new error value/type
/// is assigned.
///
- /// @param err_str
+ /// \param err_str
/// The new custom error string to copy and cache.
//------------------------------------------------------------------
void SetErrorString(llvm::StringRef err_str);
//------------------------------------------------------------------
/// Set the current error string to a formatted error string.
///
- /// @param format
+ /// \param format
/// A printf style format string
//------------------------------------------------------------------
int SetErrorStringWithFormat(const char *format, ...)
/// Returns true if the error code in this object is considered a successful
/// return value.
///
- /// @return
+ /// \return
/// \b true if this object contains an value that describes
/// success (non-erro), \b false otherwise.
//------------------------------------------------------------------
/// Returns true if the error code in this object was caused by an
/// interrupt. At present only supports Posix EINTR.
///
- /// @return
+ /// \return
/// \b true if this object contains an value that describes
/// failure due to interrupt, \b false otherwise.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Stream Stream.h "lldb/Utility/Stream.h"
+/// \class Stream Stream.h "lldb/Utility/Stream.h"
/// A stream class that can stream formatted output to a file.
//----------------------------------------------------------------------
class Stream {
/// Utility class for counting the bytes that were written to a stream in a
/// certain time span.
- /// @example
+ /// \example
/// ByteDelta delta(*this);
/// WriteDataToStream("foo");
/// return *delta;
- /// @endcode
+ /// \endcode
class ByteDelta {
Stream *m_stream;
/// Bytes we have written so far when ByteDelta was created.
///
/// Appends \a src_len characters from the buffer \a src to the stream.
///
- /// @param[in] src
+ /// \param[in] src
/// A buffer containing at least \a src_len bytes of data.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// A number of bytes to append to the stream.
///
- /// @return
+ /// \return
/// The number of bytes that were appended to the stream.
//------------------------------------------------------------------
size_t Write(const void *src, size_t src_len) {
/// Sets the byte order of the data to extract. Extracted values will be
/// swapped if necessary when decoding.
///
- /// @param[in] byte_order
+ /// \param[in] byte_order
/// The byte order value to use when extracting data.
///
- /// @return
+ /// \return
/// The old byte order value.
//------------------------------------------------------------------
lldb::ByteOrder SetByteOrder(lldb::ByteOrder byte_order);
/// Format a C string from a printf style format and variable arguments and
/// encode and append the resulting C string as hex bytes.
///
- /// @param[in] format
+ /// \param[in] format
/// A printf style format string.
///
- /// @param[in] ...
+ /// \param[in] ...
/// Any additional arguments needed for the printf format string.
///
- /// @return
+ /// \return
/// The number of bytes that were appended to the stream.
//------------------------------------------------------------------
size_t PrintfAsRawHex8(const char *format, ...)
//------------------------------------------------------------------
/// Append an uint8_t value in the hexadecimal format to the stream.
///
- /// @param[in] uvalue
+ /// \param[in] uvalue
/// The value to append.
///
- /// @return
+ /// \return
/// The number of bytes that were appended to the stream.
//------------------------------------------------------------------
size_t PutHex8(uint8_t uvalue);
//------------------------------------------------------------------
/// Output a NULL terminated C string \a cstr to the stream \a s.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// A NULL terminated C string.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a pointer value \a p to the stream \a s.
///
- /// @param[in] p
+ /// \param[in] p
/// A void pointer.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a character \a ch to the stream \a s.
///
- /// @param[in] ch
+ /// \param[in] ch
/// A printable character value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a uint8_t \a uval to the stream \a s.
///
- /// @param[in] uval
+ /// \param[in] uval
/// A uint8_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a uint16_t \a uval to the stream \a s.
///
- /// @param[in] uval
+ /// \param[in] uval
/// A uint16_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a uint32_t \a uval to the stream \a s.
///
- /// @param[in] uval
+ /// \param[in] uval
/// A uint32_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a uint64_t \a uval to the stream \a s.
///
- /// @param[in] uval
+ /// \param[in] uval
/// A uint64_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a int8_t \a sval to the stream \a s.
///
- /// @param[in] sval
+ /// \param[in] sval
/// A int8_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a int16_t \a sval to the stream \a s.
///
- /// @param[in] sval
+ /// \param[in] sval
/// A int16_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a int32_t \a sval to the stream \a s.
///
- /// @param[in] sval
+ /// \param[in] sval
/// A int32_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Output a int64_t \a sval to the stream \a s.
///
- /// @param[in] sval
+ /// \param[in] sval
/// A int64_t value.
///
- /// @return
+ /// \return
/// A reference to this class so multiple things can be streamed
/// in one statement.
//------------------------------------------------------------------
/// Put an address \a addr out to the stream with optional \a prefix and \a
/// suffix strings.
///
- /// @param[in] addr
+ /// \param[in] addr
/// An address value.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// Size in bytes of the address, used for formatting.
///
- /// @param[in] prefix
+ /// \param[in] prefix
/// A prefix C string. If nullptr, no prefix will be output.
///
- /// @param[in] suffix
+ /// \param[in] suffix
/// A suffix C string. If nullptr, no suffix will be output.
//------------------------------------------------------------------
void Address(uint64_t addr, uint32_t addr_size, const char *prefix = nullptr,
/// Put an address range \a lo_addr - \a hi_addr out to the stream with
/// optional \a prefix and \a suffix strings.
///
- /// @param[in] lo_addr
+ /// \param[in] lo_addr
/// The start address of the address range.
///
- /// @param[in] hi_addr
+ /// \param[in] hi_addr
/// The end address of the address range.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// Size in bytes of the address, used for formatting.
///
- /// @param[in] prefix
+ /// \param[in] prefix
/// A prefix C string. If nullptr, no prefix will be output.
///
- /// @param[in] suffix
+ /// \param[in] suffix
/// A suffix C string. If nullptr, no suffix will be output.
//------------------------------------------------------------------
void AddressRange(uint64_t lo_addr, uint64_t hi_addr, uint32_t addr_size,
///
/// Print a C string \a cstr to the stream.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// The string to be output to the stream.
//------------------------------------------------------------------
size_t PutCString(llvm::StringRef cstr);
//------------------------------------------------------------------
/// Get the address size in bytes.
///
- /// @return
+ /// \return
/// The size of an address in bytes that is used when outputting
/// address and pointer values to the stream.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// The flags accessor.
///
- /// @return
+ /// \return
/// A reference to the Flags member variable.
//------------------------------------------------------------------
Flags &GetFlags();
//------------------------------------------------------------------
/// The flags const accessor.
///
- /// @return
+ /// \return
/// A const reference to the Flags member variable.
//------------------------------------------------------------------
const Flags &GetFlags() const;
//------------------------------------------------------------------
//// The byte order accessor.
////
- //// @return
+ //// \return
//// The byte order.
//------------------------------------------------------------------
lldb::ByteOrder GetByteOrder() const;
//------------------------------------------------------------------
/// Get the current indentation level.
///
- /// @return
+ /// \return
/// The current indentation level as an integer.
//------------------------------------------------------------------
int GetIndentLevel() const;
/// Indent the current line using the current indentation level and print an
/// optional string following the indentation spaces.
///
- /// @param[in] s
+ /// \param[in] s
/// A C string to print following the indentation. If nullptr, just
/// output the indentation characters.
//------------------------------------------------------------------
/// Put an offset \a uval out to the stream using the printf format in \a
/// format.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset value.
///
- /// @param[in] format
+ /// \param[in] format
/// The printf style format to use when outputting the offset.
//------------------------------------------------------------------
void Offset(uint32_t offset, const char *format = "0x%8.8x: ");
///
/// Print some formatted output to the stream.
///
- /// @param[in] format
+ /// \param[in] format
/// A printf style format string.
///
- /// @param[in] ...
+ /// \param[in] ...
/// Variable arguments that are needed for the printf style
/// format string \a format.
//------------------------------------------------------------------
/// Print a double quoted NULL terminated C string to the stream using the
/// printf format in \a format.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// A NULL terminated C string value.
///
- /// @param[in] format
+ /// \param[in] format
/// The optional C string format that can be overridden.
//------------------------------------------------------------------
void QuotedCString(const char *cstr, const char *format = "\"%s\"");
//------------------------------------------------------------------
/// Set the address size in bytes.
///
- /// @param[in] addr_size
+ /// \param[in] addr_size
/// The new size in bytes of an address to use when outputting
/// address and pointer values.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the current indentation level.
///
- /// @param[in] level
+ /// \param[in] level
/// The new indentation level.
//------------------------------------------------------------------
void SetIndentLevel(int level);
/// Put an SLEB128 \a uval out to the stream using the printf format in \a
/// format.
///
- /// @param[in] uval
+ /// \param[in] uval
/// A uint64_t value that was extracted as a SLEB128 value.
//------------------------------------------------------------------
size_t PutSLEB128(int64_t uval);
/// Put an ULEB128 \a uval out to the stream using the printf format in \a
/// format.
///
- /// @param[in] uval
+ /// \param[in] uval
/// A uint64_t value that was extracted as a ULEB128 value.
//------------------------------------------------------------------
size_t PutULEB128(uint64_t uval);
///
/// Appends \a src_len characters from the buffer \a src to the stream.
///
- /// @param[in] src
+ /// \param[in] src
/// A buffer containing at least \a src_len bytes of data.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// A number of bytes to append to the stream.
///
- /// @return
+ /// \return
/// The number of bytes that were appended to the stream.
//------------------------------------------------------------------
virtual size_t WriteImpl(const void *src, size_t src_len) = 0;
//----------------------------------------------------------------------
- /// @class RawOstreamForward Stream.h "lldb/Utility/Stream.h"
+ /// \class RawOstreamForward Stream.h "lldb/Utility/Stream.h"
/// This is a wrapper class that exposes a raw_ostream interface that just
/// forwards to an LLDB stream, allowing to reuse LLVM algorithms that take
/// a raw_ostream within the LLDB code base.
//------------------------------------------------------------------
/// Output a block of data to the stream performing GDB-remote escaping.
///
- /// @param[in] s
+ /// \param[in] s
/// A block of data.
///
- /// @param[in] src_len
+ /// \param[in] src_len
/// The amount of data to write.
///
- /// @return
+ /// \return
/// Number of bytes written.
//------------------------------------------------------------------
// TODO: Convert this function to take ArrayRef<uint8_t>
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class StructuredData StructuredData.h "lldb/Utility/StructuredData.h"
+/// \class StructuredData StructuredData.h "lldb/Utility/StructuredData.h"
/// A class which can hold structured data
///
/// The StructuredData class is designed to hold the data from a JSON or plist
class Stream;
//----------------------------------------------------------------------
-/// @class Timer Timer.h "lldb/Utility/Timer.h"
+/// \class Timer Timer.h "lldb/Utility/Timer.h"
/// A timer class that simplifies common timing metrics.
//----------------------------------------------------------------------
/// Decode as many UUID bytes (up to 16) as possible from the C
/// string \a cstr.
///
- /// @param[in] cstr
+ /// \param[in] cstr
/// A NULL terminate C string that points at a UUID string value
/// (no leading spaces). The string must contain only hex
/// characters and optionally can contain the '-' sepearators.
///
- /// @param[in] uuid_bytes
+ /// \param[in] uuid_bytes
/// A buffer of bytes that will contain a full or patially
/// decoded UUID.
///
- /// @return
+ /// \return
/// The original string, with all decoded bytes removed.
//------------------------------------------------------------------
static llvm::StringRef
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class UserID UserID.h "lldb/Core/UserID.h"
+/// \class UserID UserID.h "lldb/Core/UserID.h"
/// A mix in class that contains a generic user ID.
///
/// UserID is designed as a mix in class that can contain an integer based
//------------------------------------------------------------------
/// Get accessor for the user ID.
///
- /// @return
+ /// \return
/// The user ID.
//------------------------------------------------------------------
lldb::user_id_t GetID() const { return m_uid; }
//------------------------------------------------------------------
/// Set accessor for the user ID.
///
- /// @param[in] uid
+ /// \param[in] uid
/// The new user ID.
//------------------------------------------------------------------
void SetID(lldb::user_id_t uid) { m_uid = uid; }
#if defined(__cplusplus)
//----------------------------------------------------------------------
-/// @def DISALLOW_COPY_AND_ASSIGN(TypeName)
+/// \def DISALLOW_COPY_AND_ASSIGN(TypeName)
/// Macro definition for easily disallowing copy constructor and
/// assignment operators in C++ classes.
//----------------------------------------------------------------------
}
@end
-
\ No newline at end of file
+
Clients of the class should stick to the methods provided in this
base class.
- @see ProcessHelper.process_helper()
+ \see ProcessHelper.process_helper()
"""
def __init__(self):
}
//----------------------------------------------------------------------
-/// @class Instrumenter IRDynamicChecks.cpp
+/// \class Instrumenter IRDynamicChecks.cpp
/// Finds and instruments individual LLVM IR instructions
///
/// When instrumenting LLVM IR, it is frequently desirable to first search for
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] module
+ /// \param[in] module
/// The module being instrumented.
//------------------------------------------------------------------
Instrumenter(llvm::Module &module, DynamicCheckerFunctions &checker_functions)
//------------------------------------------------------------------
/// Inspect a function to find instructions to instrument
///
- /// @param[in] function
+ /// \param[in] function
/// The function to inspect.
///
- /// @return
+ /// \return
/// True on success; false on error.
//------------------------------------------------------------------
bool Inspect(llvm::Function &function) { return InspectFunction(function); }
//------------------------------------------------------------------
/// Instrument all the instructions found by Inspect()
///
- /// @return
+ /// \return
/// True on success; false on error.
//------------------------------------------------------------------
bool Instrument() {
//------------------------------------------------------------------
/// Add instrumentation to a single instruction
///
- /// @param[in] inst
+ /// \param[in] inst
/// The instruction to be instrumented.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
virtual bool InstrumentInstruction(llvm::Instruction *inst) = 0;
//------------------------------------------------------------------
/// Register a single instruction to be instrumented
///
- /// @param[in] inst
+ /// \param[in] inst
/// The instruction to be instrumented.
//------------------------------------------------------------------
void RegisterInstruction(llvm::Instruction &i) {
/// Determine whether a single instruction is interesting to instrument,
/// and, if so, call RegisterInstruction
///
- /// @param[in] i
+ /// \param[in] i
/// The instruction to be inspected.
///
- /// @return
+ /// \return
/// False if there was an error scanning; true otherwise.
//------------------------------------------------------------------
virtual bool InspectInstruction(llvm::Instruction &i) { return true; }
//------------------------------------------------------------------
/// Scan a basic block to see if any instructions are interesting
///
- /// @param[in] bb
+ /// \param[in] bb
/// The basic block to be inspected.
///
- /// @return
+ /// \return
/// False if there was an error scanning; true otherwise.
//------------------------------------------------------------------
virtual bool InspectBasicBlock(llvm::BasicBlock &bb) {
//------------------------------------------------------------------
/// Scan a function to see if any instructions are interesting
///
- /// @param[in] f
+ /// \param[in] f
/// The function to be inspected.
///
- /// @return
+ /// \return
/// False if there was an error scanning; true otherwise.
//------------------------------------------------------------------
virtual bool InspectFunction(llvm::Function &f) {
/// Build a function pointer for a function with signature void
/// (*)(uint8_t*) with a given address
///
- /// @param[in] start_address
+ /// \param[in] start_address
/// The address of the function.
///
- /// @return
+ /// \return
/// The function pointer, for use in a CallInst.
//------------------------------------------------------------------
llvm::FunctionCallee BuildPointerValidatorFunc(lldb::addr_t start_address) {
/// Build a function pointer for a function with signature void
/// (*)(uint8_t*, uint8_t*) with a given address
///
- /// @param[in] start_address
+ /// \param[in] start_address
/// The address of the function.
///
- /// @return
+ /// \return
/// The function pointer, for use in a CallInst.
//------------------------------------------------------------------
llvm::FunctionCallee BuildObjectCheckerFunc(lldb::addr_t start_address) {
//------------------------------------------------------------------
/// Constructor
///
-/// @param[in] text
+/// \param[in] text
/// The text of the function. Must be a full translation unit.
///
-/// @param[in] name
+/// \param[in] name
/// The name of the function, as used in the text.
//------------------------------------------------------------------
UtilityFunction::UtilityFunction(ExecutionContextScope &exe_scope,
}
}
-/// Removes the loaded sections from the target in @p module.
+/// Removes the loaded sections from the target in \p module.
///
-/// @param module The module to traverse.
+/// \param module The module to traverse.
void DynamicLoaderHexagonDYLD::UnloadSections(const ModuleSP module) {
Target &target = m_process->GetTarget();
const SectionList *sections = GetSectionListFromModule(module);
/// of loaded modules.
void RefreshModules();
- /// Updates the load address of every allocatable section in @p module.
+ /// Updates the load address of every allocatable section in \p module.
///
- /// @param module The module to traverse.
+ /// \param module The module to traverse.
///
- /// @param link_map_addr The virtual address of the link map for the @p
+ /// \param link_map_addr The virtual address of the link map for the @p
/// module.
///
- /// @param base_addr The virtual base address @p module is loaded at.
+ /// \param base_addr The virtual base address \p module is loaded at.
void UpdateLoadedSections(lldb::ModuleSP module, lldb::addr_t link_map_addr,
lldb::addr_t base_addr,
bool base_addr_is_offset) override;
- /// Removes the loaded sections from the target in @p module.
+ /// Removes the loaded sections from the target in \p module.
///
- /// @param module The module to traverse.
+ /// \param module The module to traverse.
void UnloadSections(const lldb::ModuleSP module) override;
/// Callback routine invoked when we hit the breakpoint on process entry.
class Process;
}
-/// @class HexagonDYLDRendezvous
+/// \class HexagonDYLDRendezvous
/// Interface to the runtime linker.
///
/// A structure is present in a processes memory space which is updated by the
/// This method should be called once one start up, then once each time the
/// runtime linker enters the function given by GetBreakAddress().
///
- /// @returns true on success and false on failure.
+ /// \returns true on success and false on failure.
///
- /// @see GetBreakAddress().
+ /// \see GetBreakAddress().
bool Resolve();
- /// @returns true if this rendezvous has been located in the inferiors
+ /// \returns true if this rendezvous has been located in the inferiors
/// address space and false otherwise.
bool IsValid();
- /// @returns the address of the rendezvous structure in the inferiors
+ /// \returns the address of the rendezvous structure in the inferiors
/// address space.
lldb::addr_t GetRendezvousAddress() const { return m_rendezvous_addr; }
/// Provide the dyld structure address
void SetRendezvousAddress(lldb::addr_t);
- /// @returns the version of the rendezvous protocol being used.
+ /// \returns the version of the rendezvous protocol being used.
uint64_t GetVersion() const { return m_current.version; }
- /// @returns address in the inferiors address space containing the linked
+ /// \returns address in the inferiors address space containing the linked
/// list of shared object descriptors.
lldb::addr_t GetLinkMapAddress() const { return m_current.map_addr; }
/// A breakpoint should be set at this address and Resolve called on each
/// hit.
///
- /// @returns the address of a function called by the runtime linker each
+ /// \returns the address of a function called by the runtime linker each
/// time a module is loaded/unloaded, or about to be loaded/unloaded.
///
- /// @see Resolve()
+ /// \see Resolve()
lldb::addr_t GetBreakAddress() const { return m_current.brk; }
/// In hexagon it is possible that we can know the dyld breakpoint without
/// Returns the current state of the rendezvous structure.
uint64_t GetState() const { return m_current.state; }
- /// @returns the base address of the runtime linker in the inferiors address
+ /// \returns the base address of the runtime linker in the inferiors address
/// space.
lldb::addr_t GetLDBase() const { return m_current.ldbase; }
- /// @returns the thread layout metadata from the inferiors thread library.
+ /// \returns the thread layout metadata from the inferiors thread library.
const ThreadInfo &GetThreadInfo();
- /// @returns true if modules have been loaded into the inferior since the
+ /// \returns true if modules have been loaded into the inferior since the
/// last call to Resolve().
bool ModulesDidLoad() const { return !m_added_soentries.empty(); }
- /// @returns true if modules have been unloaded from the inferior since the
+ /// \returns true if modules have been unloaded from the inferior since the
/// last call to Resolve().
bool ModulesDidUnload() const { return !m_removed_soentries.empty(); }
/// Constants describing the state of the rendezvous.
///
- /// @see GetState().
+ /// \see GetState().
enum RendezvousState {
eConsistent = 0,
eAdd,
/// Threading metadata read from the inferior.
ThreadInfo m_thread_info;
- /// Reads an unsigned integer of @p size bytes from the inferior's address
- /// space starting at @p addr.
+ /// Reads an unsigned integer of \p size bytes from the inferior's address
+ /// space starting at \p addr.
///
- /// @returns addr + size if the read was successful and false otherwise.
+ /// \returns addr + size if the read was successful and false otherwise.
lldb::addr_t ReadWord(lldb::addr_t addr, uint64_t *dst, size_t size);
- /// Reads an address from the inferior's address space starting at @p addr.
+ /// Reads an address from the inferior's address space starting at \p addr.
///
- /// @returns addr + target address size if the read was successful and
+ /// \returns addr + target address size if the read was successful and
/// 0 otherwise.
lldb::addr_t ReadPointer(lldb::addr_t addr, lldb::addr_t *dst);
/// addr.
std::string ReadStringFromMemory(lldb::addr_t addr);
- /// Reads an SOEntry starting at @p addr.
+ /// Reads an SOEntry starting at \p addr.
bool ReadSOEntryFromMemory(lldb::addr_t addr, SOEntry &entry);
/// Updates the current set of SOEntries, the set of added entries, and the
class DataExtractor;
}
-/// @class AuxVector
+/// \class AuxVector
/// Represents a processes auxiliary vector.
///
/// When a process is loaded on Linux a vector of values is placed onto the
class Process;
}
-/// @class DYLDRendezvous
+/// \class DYLDRendezvous
/// Interface to the runtime linker.
///
/// A structure is present in a processes memory space which is updated by the
/// This method should be called once one start up, then once each time the
/// runtime linker enters the function given by GetBreakAddress().
///
- /// @returns true on success and false on failure.
+ /// \returns true on success and false on failure.
///
- /// @see GetBreakAddress().
+ /// \see GetBreakAddress().
bool Resolve();
- /// @returns true if this rendezvous has been located in the inferiors
+ /// \returns true if this rendezvous has been located in the inferiors
/// address space and false otherwise.
bool IsValid();
- /// @returns the address of the rendezvous structure in the inferiors
+ /// \returns the address of the rendezvous structure in the inferiors
/// address space.
lldb::addr_t GetRendezvousAddress() const { return m_rendezvous_addr; }
- /// @returns the version of the rendezvous protocol being used.
+ /// \returns the version of the rendezvous protocol being used.
uint64_t GetVersion() const { return m_current.version; }
- /// @returns address in the inferiors address space containing the linked
+ /// \returns address in the inferiors address space containing the linked
/// list of shared object descriptors.
lldb::addr_t GetLinkMapAddress() const { return m_current.map_addr; }
/// A breakpoint should be set at this address and Resolve called on each
/// hit.
///
- /// @returns the address of a function called by the runtime linker each
+ /// \returns the address of a function called by the runtime linker each
/// time a module is loaded/unloaded, or about to be loaded/unloaded.
///
- /// @see Resolve()
+ /// \see Resolve()
lldb::addr_t GetBreakAddress() const { return m_current.brk; }
/// Returns the current state of the rendezvous structure.
uint64_t GetState() const { return m_current.state; }
- /// @returns the base address of the runtime linker in the inferiors address
+ /// \returns the base address of the runtime linker in the inferiors address
/// space.
lldb::addr_t GetLDBase() const { return m_current.ldbase; }
- /// @returns the thread layout metadata from the inferiors thread library.
+ /// \returns the thread layout metadata from the inferiors thread library.
const ThreadInfo &GetThreadInfo();
- /// @returns true if modules have been loaded into the inferior since the
+ /// \returns true if modules have been loaded into the inferior since the
/// last call to Resolve().
bool ModulesDidLoad() const { return !m_added_soentries.empty(); }
- /// @returns true if modules have been unloaded from the inferior since the
+ /// \returns true if modules have been unloaded from the inferior since the
/// last call to Resolve().
bool ModulesDidUnload() const { return !m_removed_soentries.empty(); }
/// Constants describing the state of the rendezvous.
///
- /// @see GetState().
+ /// \see GetState().
enum RendezvousState { eConsistent, eAdd, eDelete };
/// Structure representing the shared objects currently loaded into the
/// Threading metadata read from the inferior.
ThreadInfo m_thread_info;
- /// Reads an unsigned integer of @p size bytes from the inferior's address
- /// space starting at @p addr.
+ /// Reads an unsigned integer of \p size bytes from the inferior's address
+ /// space starting at \p addr.
///
- /// @returns addr + size if the read was successful and false otherwise.
+ /// \returns addr + size if the read was successful and false otherwise.
lldb::addr_t ReadWord(lldb::addr_t addr, uint64_t *dst, size_t size);
- /// Reads an address from the inferior's address space starting at @p addr.
+ /// Reads an address from the inferior's address space starting at \p addr.
///
- /// @returns addr + target address size if the read was successful and
+ /// \returns addr + target address size if the read was successful and
/// 0 otherwise.
lldb::addr_t ReadPointer(lldb::addr_t addr, lldb::addr_t *dst);
/// addr.
std::string ReadStringFromMemory(lldb::addr_t addr);
- /// Reads an SOEntry starting at @p addr.
+ /// Reads an SOEntry starting at \p addr.
bool ReadSOEntryFromMemory(lldb::addr_t addr, SOEntry &entry);
/// Updates the current set of SOEntries, the set of added entries, and the
/// of loaded modules.
void RefreshModules();
- /// Updates the load address of every allocatable section in @p module.
+ /// Updates the load address of every allocatable section in \p module.
///
- /// @param module The module to traverse.
+ /// \param module The module to traverse.
///
- /// @param link_map_addr The virtual address of the link map for the @p
+ /// \param link_map_addr The virtual address of the link map for the @p
/// module.
///
- /// @param base_addr The virtual base address @p module is loaded at.
+ /// \param base_addr The virtual base address \p module is loaded at.
void UpdateLoadedSections(lldb::ModuleSP module, lldb::addr_t link_map_addr,
lldb::addr_t base_addr,
bool base_addr_is_offset) override;
- /// Removes the loaded sections from the target in @p module.
+ /// Removes the loaded sections from the target in \p module.
///
- /// @param module The module to traverse.
+ /// \param module The module to traverse.
void UnloadSections(const lldb::ModuleSP module) override;
/// Resolves the entry point for the current inferior process and sets a
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ASTResultSynthesizer ASTResultSynthesizer.h
+/// \class ASTResultSynthesizer ASTResultSynthesizer.h
/// "lldb/Expression/ASTResultSynthesizer.h" Adds a result variable
/// declaration to the ASTs for an expression.
///
//----------------------------------------------------------------------
/// Constructor
///
- /// @param[in] passthrough
+ /// \param[in] passthrough
/// Since the ASTs must typically go through to the Clang code generator
/// in order to produce LLVM IR, this SemaConsumer must allow them to
/// pass to the next step in the chain after processing. Passthrough is
/// the next ASTConsumer, or NULL if none is required.
///
- /// @param[in] top_level
+ /// \param[in] top_level
/// If true, register all top-level Decls and don't try to handle the
/// main function.
///
- /// @param[in] target
+ /// \param[in] target
/// The target, which contains the persistent variable store and the
/// AST importer.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// Link this consumer with a particular AST context
///
- /// @param[in] Context
+ /// \param[in] Context
/// This AST context will be used for types and identifiers, and also
/// forwarded to the passthrough consumer, if one exists.
//----------------------------------------------------------------------
/// Examine a list of Decls to find the function $__lldb_expr and transform
/// its code
///
- /// @param[in] D
+ /// \param[in] D
/// The list of Decls to search. These may contain LinkageSpecDecls,
/// which need to be searched recursively. That job falls to
/// TransformTopLevelDecl.
//----------------------------------------------------------------------
/// Set the Sema object to use when performing transforms, and pass it on
///
- /// @param[in] S
+ /// \param[in] S
/// The Sema to use. Because Sema isn't externally visible, this class
/// casts it to an Action for actual use.
//----------------------------------------------------------------------
/// necessary through LinkageSpecDecls, and calling SynthesizeResult on
/// anything that was found
///
- /// @param[in] D
+ /// \param[in] D
/// The Decl to hunt.
//----------------------------------------------------------------------
void TransformTopLevelDecl(clang::Decl *D);
/// Process an Objective-C method and produce the result variable and
/// initialization
///
- /// @param[in] MethodDecl
+ /// \param[in] MethodDecl
/// The method to process.
//----------------------------------------------------------------------
bool SynthesizeObjCMethodResult(clang::ObjCMethodDecl *MethodDecl);
//----------------------------------------------------------------------
/// Process a function and produce the result variable and initialization
///
- /// @param[in] FunDecl
+ /// \param[in] FunDecl
/// The function to process.
//----------------------------------------------------------------------
bool SynthesizeFunctionResult(clang::FunctionDecl *FunDecl);
/// Process a function body and produce the result variable and
/// initialization
///
- /// @param[in] Body
+ /// \param[in] Body
/// The body of the function.
///
- /// @param[in] DC
+ /// \param[in] DC
/// The DeclContext of the function, into which the result variable
/// is inserted.
//----------------------------------------------------------------------
/// Given a DeclContext for a function or method, find all types declared in
/// the context and record any persistent types found.
///
- /// @param[in] FunDeclCtx
+ /// \param[in] FunDeclCtx
/// The context for the function to process.
//----------------------------------------------------------------------
void RecordPersistentTypes(clang::DeclContext *FunDeclCtx);
/// sign, register it as a pointer type in the target's scratch
/// AST context.
///
- /// @param[in] Body
+ /// \param[in] Body
/// The body of the function.
//----------------------------------------------------------------------
void MaybeRecordPersistentType(clang::TypeDecl *D);
/// Given a NamedDecl, register it as a pointer type in the target's scratch
/// AST context.
///
- /// @param[in] Body
+ /// \param[in] Body
/// The body of the function.
//----------------------------------------------------------------------
void RecordPersistentDecl(clang::NamedDecl *D);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ASTStructExtractor ASTStructExtractor.h
+/// \class ASTStructExtractor ASTStructExtractor.h
/// "lldb/Expression/ASTStructExtractor.h" Extracts and describes the argument
/// structure for a wrapped function.
///
//----------------------------------------------------------------------
/// Constructor
///
- /// @param[in] passthrough
+ /// \param[in] passthrough
/// Since the ASTs must typically go through to the Clang code generator
/// in order to produce LLVM IR, this SemaConsumer must allow them to
/// pass to the next step in the chain after processing. Passthrough is
/// the next ASTConsumer, or NULL if none is required.
///
- /// @param[in] struct_name
+ /// \param[in] struct_name
/// The name of the structure to extract from the wrapper function.
///
- /// @param[in] function
+ /// \param[in] function
/// The caller object whose members should be populated with information
/// about the argument struct. ClangFunctionCaller friends
/// ASTStructExtractor
//----------------------------------------------------------------------
/// Link this consumer with a particular AST context
///
- /// @param[in] Context
+ /// \param[in] Context
/// This AST context will be used for types and identifiers, and also
/// forwarded to the passthrough consumer, if one exists.
//----------------------------------------------------------------------
/// Examine a list of Decls to find the function $__lldb_expr and transform
/// its code
///
- /// @param[in] D
+ /// \param[in] D
/// The list of Decls to search. These may contain LinkageSpecDecls,
/// which need to be searched recursively. That job falls to
/// TransformTopLevelDecl.
//----------------------------------------------------------------------
/// Set the Sema object to use when performing transforms, and pass it on
///
- /// @param[in] S
+ /// \param[in] S
/// The Sema to use. Because Sema isn't externally visible, this class
/// casts it to an Action for actual use.
//----------------------------------------------------------------------
/// Hunt the given FunctionDecl for the argument struct and place
/// information about it into m_function
///
- /// @param[in] F
+ /// \param[in] F
/// The FunctionDecl to hunt.
//----------------------------------------------------------------------
void ExtractFromFunctionDecl(clang::FunctionDecl *F);
/// function name, recursing as necessary through LinkageSpecDecls, and
/// calling ExtractFromFunctionDecl on anything that was found
///
- /// @param[in] D
+ /// \param[in] D
/// The Decl to hunt.
//----------------------------------------------------------------------
void ExtractFromTopLevelDecl(clang::Decl *D);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ClangASTSource ClangASTSource.h "lldb/Expression/ClangASTSource.h"
+/// \class ClangASTSource ClangASTSource.h "lldb/Expression/ClangASTSource.h"
/// Provider for named objects defined in the debug info for Clang
///
/// As Clang parses an expression, it may encounter names that are not defined
///
/// Initializes class variables.
///
- /// @param[in] target
+ /// \param[in] target
/// A reference to the target containing debug information to use.
//------------------------------------------------------------------
ClangASTSource(const lldb::TargetSP &target);
/// The work for this function is done by
/// void FindExternalVisibleDecls (NameSearchContext &);
///
- /// @param[in] DC
+ /// \param[in] DC
/// The DeclContext to register the found Decls in.
///
- /// @param[in] Name
+ /// \param[in] Name
/// The name to find entries for.
///
- /// @return
+ /// \return
/// Whatever SetExternalVisibleDeclsForName returns.
//------------------------------------------------------------------
bool FindExternalVisibleDeclsByName(const clang::DeclContext *DC,
//------------------------------------------------------------------
/// Enumerate all Decls in a given lexical context.
///
- /// @param[in] DC
+ /// \param[in] DC
/// The DeclContext being searched.
///
- /// @param[in] isKindWeWant
+ /// \param[in] isKindWeWant
/// A callback function that returns true given the
/// DeclKinds of desired Decls, and false otherwise.
///
- /// @param[in] Decls
+ /// \param[in] Decls
/// A vector that is filled in with matching Decls.
//------------------------------------------------------------------
void FindExternalLexicalDecls(
//------------------------------------------------------------------
/// Specify the layout of the contents of a RecordDecl.
///
- /// @param[in] Record
+ /// \param[in] Record
/// The record (in the parser's AST context) that needs to be
/// laid out.
///
- /// @param[out] Size
+ /// \param[out] Size
/// The total size of the record in bits.
///
- /// @param[out] Alignment
+ /// \param[out] Alignment
/// The alignment of the record in bits.
///
- /// @param[in] FieldOffsets
+ /// \param[in] FieldOffsets
/// A map that must be populated with pairs of the record's
/// fields (in the parser's AST context) and their offsets
/// (measured in bits).
///
- /// @param[in] BaseOffsets
+ /// \param[in] BaseOffsets
/// A map that must be populated with pairs of the record's
/// C++ concrete base classes (in the parser's AST context,
/// and only if the record is a CXXRecordDecl and has base
/// classes) and their offsets (measured in bytes).
///
- /// @param[in] VirtualBaseOffsets
+ /// \param[in] VirtualBaseOffsets
/// A map that must be populated with pairs of the record's
/// C++ virtual base classes (in the parser's AST context,
/// and only if the record is a CXXRecordDecl and has base
/// classes) and their offsets (measured in bytes).
///
- /// @return
+ /// \return
/// True <=> the layout is valid.
//-----------------------------------------------------------------
bool layoutRecordType(
//------------------------------------------------------------------
/// Complete a TagDecl.
///
- /// @param[in] Tag
+ /// \param[in] Tag
/// The Decl to be completed in place.
//------------------------------------------------------------------
void CompleteType(clang::TagDecl *Tag) override;
//------------------------------------------------------------------
/// Complete an ObjCInterfaceDecl.
///
- /// @param[in] Class
+ /// \param[in] Class
/// The Decl to be completed in place.
//------------------------------------------------------------------
void CompleteType(clang::ObjCInterfaceDecl *Class) override;
/// setHasExternalVisibleStorage() and setHasExternalLexicalStorage() that
/// this object has something to say about undefined names.
///
- /// @param[in] ASTConsumer
+ /// \param[in] ASTConsumer
/// Unused.
//------------------------------------------------------------------
void StartTranslationUnit(clang::ASTConsumer *Consumer) override;
/// Look up the modules containing a given namespace and put the appropriate
/// entries in the namespace map.
///
- /// @param[in] namespace_map
+ /// \param[in] namespace_map
/// The map to be completed.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the namespace to be found.
///
- /// @param[in] parent_map
+ /// \param[in] parent_map
/// The map for the namespace's parent namespace, if there is
/// one.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// The worker function for FindExternalVisibleDeclsByName.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when filing results.
//------------------------------------------------------------------
virtual void FindExternalVisibleDecls(NameSearchContext &context);
bool GetLookupsEnabled() { return m_lookups_enabled; }
//----------------------------------------------------------------------
- /// @class ClangASTSourceProxy ClangASTSource.h
+ /// \class ClangASTSourceProxy ClangASTSource.h
/// "lldb/Expression/ClangASTSource.h" Proxy for ClangASTSource
///
/// Clang AST contexts like to own their AST sources, so this is a state-
/// Look for the complete version of an Objective-C interface, and return it
/// if found.
///
- /// @param[in] interface_decl
+ /// \param[in] interface_decl
/// An ObjCInterfaceDecl that may not be the complete one.
///
- /// @return
+ /// \return
/// NULL if the complete interface couldn't be found;
/// the complete interface otherwise.
//------------------------------------------------------------------
/// Find all entities matching a given name in a given module, using a
/// NameSearchContext to make Decls for them.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext that can construct Decls for this name.
///
- /// @param[in] module
+ /// \param[in] module
/// If non-NULL, the module to query.
///
- /// @param[in] namespace_decl
+ /// \param[in] namespace_decl
/// If valid and module is non-NULL, the parent namespace.
///
- /// @param[in] current_id
+ /// \param[in] current_id
/// The ID for the current FindExternalVisibleDecls invocation,
/// for logging purposes.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Find all Objective-C methods matching a given selector.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext that can construct Decls for this name.
/// Its m_decl_name contains the selector and its m_decl_context
/// is the containing object.
//------------------------------------------------------------------
/// Find all Objective-C properties and ivars with a given name.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext that can construct Decls for this name.
/// Its m_decl_name contains the name and its m_decl_context
/// is the containing object.
/// A wrapper for ClangASTContext::CopyType that sets a flag that
/// indicates that we should not respond to queries during import.
///
- /// @param[in] dest_context
+ /// \param[in] dest_context
/// The target AST context, typically the parser's AST context.
///
- /// @param[in] source_context
+ /// \param[in] source_context
/// The source AST context, typically the AST context of whatever
/// symbol file the type was found in.
///
- /// @param[in] src_type
+ /// \param[in] src_type
/// The source type.
///
- /// @return
+ /// \return
/// The imported type.
//------------------------------------------------------------------
CompilerType GuardedCopyType(const CompilerType &src_type);
//------------------------------------------------------------------
/// Returns true if a name should be ignored by name lookup.
///
- /// @param[in] name
+ /// \param[in] name
/// The name to be considered.
///
- /// @param[in] ignore_all_dollar_nmmes
+ /// \param[in] ignore_all_dollar_nmmes
/// True if $-names of all sorts should be ignored.
///
- /// @return
+ /// \return
/// True if the name is one of a class of names that are ignored by
/// global lookup for performance reasons.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Copies a single Decl into the parser's AST context.
///
- /// @param[in] src_decl
+ /// \param[in] src_decl
/// The Decl to copy.
///
- /// @return
+ /// \return
/// A copy of the Decl in m_ast_context, or NULL if the copy failed.
//------------------------------------------------------------------
clang::Decl *CopyDecl(clang::Decl *src_decl);
//------------------------------------------------------------------
/// Copies a single Type to the target of the given ExternalASTMerger.
///
- /// @param[in] src_context
+ /// \param[in] src_context
/// The ASTContext containing the type.
///
- /// @param[in] merger
+ /// \param[in] merger
/// The merger to use. This isn't just *m_merger_up because it might be
/// the persistent AST context's merger.
///
- /// @param[in] type
+ /// \param[in] type
/// The type to copy.
///
- /// @return
+ /// \return
/// A copy of the Type in the merger's target context.
//------------------------------------------------------------------
clang::QualType CopyTypeWithMerger(clang::ASTContext &src_context,
//------------------------------------------------------------------
/// Determined the origin of a single Decl, if it can be found.
///
- /// @param[in] decl
+ /// \param[in] decl
/// The Decl whose origin is to be found.
///
- /// @param[out] original_decl
+ /// \param[out] original_decl
/// A pointer whose target is filled in with the original Decl.
///
- /// @param[in] original_ctx
+ /// \param[in] original_ctx
/// A pointer whose target is filled in with the original's ASTContext.
///
- /// @return
+ /// \return
/// True if lookup succeeded; false otherwise.
//------------------------------------------------------------------
bool ResolveDeclOrigin(const clang::Decl *decl, clang::Decl **original_decl,
};
//----------------------------------------------------------------------
-/// @class NameSearchContext ClangASTSource.h
+/// \class NameSearchContext ClangASTSource.h
/// "lldb/Expression/ClangASTSource.h" Container for all objects relevant to a
/// single name lookup
///
///
/// Initializes class variables.
///
- /// @param[in] astSource
+ /// \param[in] astSource
/// A reference to the AST source making a request.
///
- /// @param[in] decls
+ /// \param[in] decls
/// A reference to a list into which new Decls will be placed. This
/// list is typically empty when the function is called.
///
- /// @param[in] name
+ /// \param[in] name
/// The name being searched for (always an Identifier).
///
- /// @param[in] dc
+ /// \param[in] dc
/// The DeclContext to register Decls in.
//------------------------------------------------------------------
NameSearchContext(ClangASTSource &astSource,
/// Create a VarDecl with the name being searched for and the provided type
/// and register it in the right places.
///
- /// @param[in] type
+ /// \param[in] type
/// The opaque QualType for the VarDecl being registered.
//------------------------------------------------------------------
clang::NamedDecl *AddVarDecl(const CompilerType &type);
/// Create a FunDecl with the name being searched for and the provided type
/// and register it in the right places.
///
- /// @param[in] type
+ /// \param[in] type
/// The opaque QualType for the FunDecl being registered.
///
- /// @param[in] extern_c
+ /// \param[in] extern_c
/// If true, build an extern "C" linkage specification for this.
//------------------------------------------------------------------
clang::NamedDecl *AddFunDecl(const CompilerType &type, bool extern_c = false);
/// Create a TypeDecl with the name being searched for and the provided type
/// and register it in the right places.
///
- /// @param[in] compiler_type
+ /// \param[in] compiler_type
/// The opaque QualType for the TypeDecl being registered.
//------------------------------------------------------------------
clang::NamedDecl *AddTypeDecl(const CompilerType &compiler_type);
/// Add Decls from the provided DeclContextLookupResult to the list of
/// results.
///
- /// @param[in] result
+ /// \param[in] result
/// The DeclContextLookupResult, usually returned as the result
/// of querying a DeclContext.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Add a NamedDecl to the list of results.
///
- /// @param[in] decl
+ /// \param[in] decl
/// The NamedDecl, usually returned as the result
/// of querying a DeclContext.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ClangExpressionDeclMap ClangExpressionDeclMap.h
+/// \class ClangExpressionDeclMap ClangExpressionDeclMap.h
/// "lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are
/// defined in LLDB's debug information.
///
///
/// Initializes class variables.
///
- /// @param[in] keep_result_in_memory
+ /// \param[in] keep_result_in_memory
/// If true, inhibits the normal deallocation of the memory for
/// the result persistent variable, and instead marks the variable
/// as persisting.
///
- /// @param[in] delegate
+ /// \param[in] delegate
/// If non-NULL, use this delegate to report result values. This
/// allows the client ClangUserExpression to report a result.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when parsing.
///
- /// @param[in] ctx_obj
+ /// \param[in] ctx_obj
/// If not empty, then expression is evaluated in context of this object.
/// See the comment to `UserExpression::Evaluate` for details.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Enable the state needed for parsing and IR transformation.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when finding types for variables.
/// Also used to find a "scratch" AST context to store result types.
///
- /// @param[in] materializer
+ /// \param[in] materializer
/// If non-NULL, the materializer to populate with information about
/// the variables to use
///
- /// @return
+ /// \return
/// True if parsing is possible; false if it is unsafe to continue.
//------------------------------------------------------------------
bool WillParse(ExecutionContext &exe_ctx, Materializer *materializer);
/// [Used by ClangExpressionParser] For each variable that had an unknown
/// type at the beginning of parsing, determine its final type now.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool ResolveUnknownTypes();
/// [Used by IRForTarget] Add a variable to the list of persistent
/// variables for the process.
///
- /// @param[in] decl
+ /// \param[in] decl
/// The Clang declaration for the persistent variable, used for
/// lookup during parsing.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the persistent variable, usually $something.
///
- /// @param[in] type
+ /// \param[in] type
/// The type of the variable, in the Clang parser's context.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool AddPersistentVariable(const clang::NamedDecl *decl,
/// [Used by IRForTarget] Add a variable to the struct that needs to
/// be materialized each time the expression runs.
///
- /// @param[in] decl
+ /// \param[in] decl
/// The Clang declaration for the variable.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the variable.
///
- /// @param[in] value
+ /// \param[in] value
/// The LLVM IR value for this variable.
///
- /// @param[in] size
+ /// \param[in] size
/// The size of the variable in bytes.
///
- /// @param[in] alignment
+ /// \param[in] alignment
/// The required alignment of the variable in bytes.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool AddValueToStruct(const clang::NamedDecl *decl, ConstString name,
/// [Used by IRForTarget] Finalize the struct, laying out the position of
/// each object in it.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool DoStructLayout();
/// [Used by IRForTarget] Get general information about the laid-out struct
/// after DoStructLayout() has been called.
///
- /// @param[out] num_elements
+ /// \param[out] num_elements
/// The number of elements in the struct.
///
- /// @param[out] size
+ /// \param[out] size
/// The size of the struct, in bytes.
///
- /// @param[out] alignment
+ /// \param[out] alignment
/// The alignment of the struct, in bytes.
///
- /// @return
+ /// \return
/// True if the information could be retrieved; false otherwise.
//------------------------------------------------------------------
bool GetStructInfo(uint32_t &num_elements, size_t &size,
/// [Used by IRForTarget] Get specific information about one field of the
/// laid-out struct after DoStructLayout() has been called.
///
- /// @param[out] decl
+ /// \param[out] decl
/// The parsed Decl for the field, as generated by ClangASTSource
/// on ClangExpressionDeclMap's behalf. In the case of the result
/// value, this will have the name $__lldb_result even if the
/// result value ends up having the name $1. This is an
/// implementation detail of IRForTarget.
///
- /// @param[out] value
+ /// \param[out] value
/// The IR value for the field (usually a GlobalVariable). In
/// the case of the result value, this will have the correct
/// name ($1, for instance). This is an implementation detail
/// of IRForTarget.
///
- /// @param[out] offset
+ /// \param[out] offset
/// The offset of the field from the beginning of the struct.
/// As long as the struct is aligned according to its required
/// alignment, this offset will align the field correctly.
///
- /// @param[out] name
+ /// \param[out] name
/// The name of the field as used in materialization.
///
- /// @param[in] index
+ /// \param[in] index
/// The index of the field about which information is requested.
///
- /// @return
+ /// \return
/// True if the information could be retrieved; false otherwise.
//------------------------------------------------------------------
bool GetStructElement(const clang::NamedDecl *&decl, llvm::Value *&value,
//------------------------------------------------------------------
/// [Used by IRForTarget] Get information about a function given its Decl.
///
- /// @param[in] decl
+ /// \param[in] decl
/// The parsed Decl for the Function, as generated by ClangASTSource
/// on ClangExpressionDeclMap's behalf.
///
- /// @param[out] ptr
+ /// \param[out] ptr
/// The absolute address of the function in the target.
///
- /// @return
+ /// \return
/// True if the information could be retrieved; false otherwise.
//------------------------------------------------------------------
bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr);
/// [Used by IRForTarget] Get the address of a symbol given nothing but its
/// name.
///
- /// @param[in] target
+ /// \param[in] target
/// The target to find the symbol in. If not provided,
/// then the current parsing context's Target.
///
- /// @param[in] process
+ /// \param[in] process
/// The process to use. For Objective-C symbols, the process's
/// Objective-C language runtime may be queried if the process
/// is non-NULL.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the symbol.
///
- /// @param[in] module
+ /// \param[in] module
/// The module to limit the search to. This can be NULL
///
- /// @return
+ /// \return
/// Valid load address for the symbol
//------------------------------------------------------------------
lldb::addr_t GetSymbolAddress(Target &target, Process *process,
//------------------------------------------------------------------
/// [Used by IRInterpreter] Get basic target information.
///
- /// @param[out] byte_order
+ /// \param[out] byte_order
/// The byte order of the target.
///
- /// @param[out] address_byte_size
+ /// \param[out] address_byte_size
/// The size of a pointer in bytes.
///
- /// @return
+ /// \return
/// True if the information could be determined; false
/// otherwise.
//------------------------------------------------------------------
/// [Used by ClangASTSource] Find all entities matching a given name, using
/// a NameSearchContext to make Decls for them.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext that can construct Decls for this name.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
void FindExternalVisibleDecls(NameSearchContext &context) override;
/// Find all entities matching a given name in a given module/namespace,
/// using a NameSearchContext to make Decls for them.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext that can construct Decls for this name.
///
- /// @param[in] module
+ /// \param[in] module
/// If non-NULL, the module to query.
///
- /// @param[in] namespace_decl
+ /// \param[in] namespace_decl
/// If valid and module is non-NULL, the parent namespace.
///
- /// @param[in] current_id
+ /// \param[in] current_id
/// The ID for the current FindExternalVisibleDecls invocation,
/// for logging purposes.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
void FindExternalVisibleDecls(NameSearchContext &context,
//------------------------------------------------------------------
/// Given a target, find a variable that matches the given name and type.
///
- /// @param[in] target
+ /// \param[in] target
/// The target to use as a basis for finding the variable.
///
- /// @param[in] module
+ /// \param[in] module
/// If non-NULL, the module to search.
///
- /// @param[in] name
+ /// \param[in] name
/// The name as a plain C string.
///
- /// @param[in] namespace_decl
+ /// \param[in] namespace_decl
/// If non-NULL and module is non-NULL, the parent namespace.
///
- /// @param[in] type
+ /// \param[in] type
/// The required type for the variable. This function may be called
/// during parsing, in which case we don't know its type; hence the
/// default.
///
- /// @return
+ /// \return
/// The LLDB Variable found, or NULL if none was found.
//------------------------------------------------------------------
lldb::VariableSP FindGlobalVariable(Target &target, lldb::ModuleSP &module,
/// Get the value of a variable in a given execution context and return the
/// associated Types if needed.
///
- /// @param[in] var
+ /// \param[in] var
/// The variable to evaluate.
///
- /// @param[out] var_location
+ /// \param[out] var_location
/// The variable location value to fill in
///
- /// @param[out] found_type
+ /// \param[out] found_type
/// The type of the found value, as it was found in the user process.
/// This is only useful when the variable is being inspected on behalf
/// of the parser, hence the default.
///
- /// @param[out] parser_type
+ /// \param[out] parser_type
/// The type of the found value, as it was copied into the parser's
/// AST context. This is only useful when the variable is being
/// inspected on behalf of the parser, hence the default.
///
- /// @param[in] decl
+ /// \param[in] decl
/// The Decl to be looked up.
///
- /// @return
+ /// \return
/// Return true if the value was successfully filled in.
//------------------------------------------------------------------
bool GetVariableValue(lldb::VariableSP &var,
/// Use the NameSearchContext to generate a Decl for the given LLDB
/// Variable, and put it in the Tuple list.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when constructing the Decl.
///
- /// @param[in] var
+ /// \param[in] var
/// The LLDB Variable that needs a Decl.
///
- /// @param[in] valobj
+ /// \param[in] valobj
/// The LLDB ValueObject for that variable.
//------------------------------------------------------------------
void AddOneVariable(NameSearchContext &context, lldb::VariableSP var,
/// Use the NameSearchContext to generate a Decl for the given persistent
/// variable, and put it in the list of found entities.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when constructing the Decl.
///
- /// @param[in] pvar
+ /// \param[in] pvar
/// The persistent variable that needs a Decl.
///
- /// @param[in] current_id
+ /// \param[in] current_id
/// The ID of the current invocation of FindExternalVisibleDecls
/// for logging purposes.
//------------------------------------------------------------------
/// Use the NameSearchContext to generate a Decl for the given LLDB symbol
/// (treated as a variable), and put it in the list of found entities.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when constructing the Decl.
///
- /// @param[in] var
+ /// \param[in] var
/// The LLDB Variable that needs a Decl.
//------------------------------------------------------------------
void AddOneGenericVariable(NameSearchContext &context, const Symbol &symbol,
/// (Functions are not placed in the Tuple list.) Can handle both fully
/// typed functions and generic functions.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when constructing the Decl.
///
- /// @param[in] fun
+ /// \param[in] fun
/// The Function that needs to be created. If non-NULL, this is
/// a fully-typed function.
///
- /// @param[in] sym
+ /// \param[in] sym
/// The Symbol that corresponds to a function that needs to be
/// created with generic type (unitptr_t foo(...)).
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Use the NameSearchContext to generate a Decl for the given register.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when constructing the Decl.
///
- /// @param[in] reg_info
+ /// \param[in] reg_info
/// The information corresponding to that register.
//------------------------------------------------------------------
void AddOneRegister(NameSearchContext &context, const RegisterInfo *reg_info,
/// Use the NameSearchContext to generate a Decl for the given type. (Types
/// are not placed in the Tuple list.)
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when constructing the Decl.
///
- /// @param[in] type
+ /// \param[in] type
/// The type that needs to be created.
//------------------------------------------------------------------
void AddOneType(NameSearchContext &context, const TypeFromUser &type,
/// Generate a Decl for "*this" and add a member function declaration to it
/// for the expression, then report it.
///
- /// @param[in] context
+ /// \param[in] context
/// The NameSearchContext to use when constructing the Decl.
///
- /// @param[in] type
+ /// \param[in] type
/// The type for *this.
//------------------------------------------------------------------
void AddThisType(NameSearchContext &context, const TypeFromUser &type,
/// Move a type out of the current ASTContext into another, but make sure to
/// export all components of the type also.
///
- /// @param[in] target
+ /// \param[in] target
/// The ClangASTContext to move to.
- /// @param[in] source
+ /// \param[in] source
/// The ClangASTContext to move from. This is assumed to be going away.
- /// @param[in] parser_type
+ /// \param[in] parser_type
/// The type as it appears in the source context.
///
- /// @return
+ /// \return
/// Returns the moved type, or an empty type if there was a problem.
//------------------------------------------------------------------
TypeFromUser DeportType(ClangASTContext &target, ClangASTContext &source,
/// Return the object that the parser should allow to access ASTs.
/// May be NULL if the ASTs do not need to be transformed.
///
- /// @param[in] passthrough
+ /// \param[in] passthrough
/// The ASTConsumer that the returned transformer should send
/// the ASTs to after transformation.
//------------------------------------------------------------------
namespace {
//----------------------------------------------------------------------
-/// @class CodeComplete
+/// \class CodeComplete
///
/// A code completion consumer for the clang Sema that is responsible for
/// creating the completion suggestions when a user requests completion
public:
/// Constructs a CodeComplete consumer that can be attached to a Sema.
- /// @param[out] matches
+ /// \param[out] matches
/// The list of matches that the lldb completion API expects as a result.
/// This may already contain matches, so it's only allowed to append
/// to this variable.
- /// @param[out] expr
+ /// \param[out] expr
/// The whole expression string that we are currently parsing. This
/// string needs to be equal to the input the user typed, and NOT the
/// final code that Clang is parsing.
- /// @param[out] position
+ /// \param[out] position
/// The character position of the user cursor in the `expr` parameter.
///
CodeComplete(CompletionRequest &request, clang::LangOptions ops,
class IRExecutionUnit;
//----------------------------------------------------------------------
-/// @class ClangExpressionParser ClangExpressionParser.h
+/// \class ClangExpressionParser ClangExpressionParser.h
/// "lldb/Expression/ClangExpressionParser.h" Encapsulates an instance of
/// Clang that can parse expressions.
///
///
/// Initializes class variables.
///
- /// @param[in] exe_scope,
+ /// \param[in] exe_scope,
/// If non-NULL, an execution context scope that can help to
/// correctly create an expression with a valid process for
/// optional tuning Objective-C runtime support. Can be NULL.
///
- /// @param[in] expr
+ /// \param[in] expr
/// The expression to be parsed.
//------------------------------------------------------------------
ClangExpressionParser(ExecutionContextScope *exe_scope, Expression &expr,
/// Parse a single expression and convert it to IR using Clang. Don't wrap
/// the expression in anything at all.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
///
- /// @return
+ /// \return
/// The number of errors encountered during parsing. 0 means
/// success.
//------------------------------------------------------------------
/// Ready an already-parsed expression for execution, possibly evaluating it
/// statically.
///
- /// @param[out] func_addr
+ /// \param[out] func_addr
/// The address to which the function has been written.
///
- /// @param[out] func_end
+ /// \param[out] func_end
/// The end of the function's allocated memory region. (func_addr
/// and func_end do not delimit an allocated region; the allocated
/// region may begin before func_addr.)
///
- /// @param[in] execution_unit_sp
+ /// \param[in] execution_unit_sp
/// After parsing, ownership of the execution unit for
/// for the expression is handed to this shared pointer.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to write the function into.
///
- /// @param[out] evaluated_statically
+ /// \param[out] evaluated_statically
/// Set to true if the expression could be interpreted statically;
/// untouched otherwise.
///
- /// @param[out] const_result
+ /// \param[out] const_result
/// If the result of the expression is constant, and the
/// expression has no side effects, this is set to the result of the
/// expression.
///
- /// @param[in] execution_policy
+ /// \param[in] execution_policy
/// Determines whether the expression must be JIT-compiled, must be
/// evaluated statically, or whether this decision may be made
/// opportunistically.
///
- /// @return
+ /// \return
/// An error code indicating the success or failure of the operation.
/// Test with Success().
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Run all static initializers for an execution unit.
///
- /// @param[in] execution_unit_sp
+ /// \param[in] execution_unit_sp
/// The execution unit.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when running them. Thread can't be null.
///
- /// @return
+ /// \return
/// The error code indicating the
//------------------------------------------------------------------
Status RunStaticInitializers(lldb::IRExecutionUnitSP &execution_unit_sp,
//------------------------------------------------------------------
/// Returns a string representing current ABI.
///
- /// @param[in] target_arch
+ /// \param[in] target_arch
/// The target architecture.
///
- /// @return
+ /// \return
/// A string representing target ABI for the current architecture.
//-------------------------------------------------------------------
std::string GetClangTargetABI(const ArchSpec &target_arch);
//------------------------------------------------------------------
/// Parses the expression.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager that should receive the diagnostics
/// from the parsing process.
///
- /// @param[in] completion
+ /// \param[in] completion
/// The completion consumer that should be used during parsing
/// (or a nullptr if no consumer should be attached).
///
- /// @param[in] completion_line
+ /// \param[in] completion_line
/// The line in which the completion marker should be placed.
/// The first line is represented by the value 0.
///
- /// @param[in] completion_column
+ /// \param[in] completion_column
/// The column in which the completion marker should be placed.
/// The first column is represented by the value 0.
///
- /// @return
+ /// \return
/// The number of parsing errors.
//-------------------------------------------------------------------
unsigned ParseInternal(DiagnosticManager &diagnostic_manager,
class ValueObjectConstResult;
//----------------------------------------------------------------------
-/// @class ClangExpressionVariable ClangExpressionVariable.h
+/// \class ClangExpressionVariable ClangExpressionVariable.h
/// "lldb/Expression/ClangExpressionVariable.h" Encapsulates one variable for
/// the expression parser.
///
//----------------------------------------------------------------------
/// Finds a variable by NamedDecl in the list.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the requested variable.
///
- /// @return
+ /// \return
/// The variable requested, or NULL if that variable is not in the list.
//----------------------------------------------------------------------
static ClangExpressionVariable *
/// exe_ctx in not NULL, the value will be resolved in with that execution
/// context.
///
- /// @param[in] value
+ /// \param[in] value
/// The value to point at the data.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use to resolve \a value.
///
- /// @return
+ /// \return
/// True on success; false otherwise (in particular, if this variable
/// does not contain its own data).
//----------------------------------------------------------------------
class ClangExpressionParser;
//----------------------------------------------------------------------
-/// @class ClangFunctionCaller ClangFunctionCaller.h
+/// \class ClangFunctionCaller ClangFunctionCaller.h
/// "lldb/Expression/ClangFunctionCaller.h" Encapsulates a function that can
/// be called.
///
/// Return the object that the parser should allow to access ASTs. May be
/// NULL if the ASTs do not need to be transformed.
///
- /// @param[in] passthrough
+ /// \param[in] passthrough
/// The ASTConsumer that the returned transformer should send
/// the ASTs to after transformation.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] exe_scope
+ /// \param[in] exe_scope
/// An execution context scope that gets us at least a target and
/// process.
///
- /// @param[in] ast_context
+ /// \param[in] ast_context
/// The AST context to evaluate argument types in.
///
- /// @param[in] return_qualtype
+ /// \param[in] return_qualtype
/// An opaque Clang QualType for the function result. Should be
/// defined in ast_context.
///
- /// @param[in] function_address
+ /// \param[in] function_address
/// The address of the function to call.
///
- /// @param[in] arg_value_list
+ /// \param[in] arg_value_list
/// The default values to use when calling this function. Can
/// be overridden using WriteFunctionArguments().
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Compile the wrapper function
///
- /// @param[in] thread_to_use_sp
+ /// \param[in] thread_to_use_sp
/// Compilation might end up calling functions. Pass in the thread you
/// want the compilation to use. If you pass in an empty ThreadSP it will
/// use the currently selected thread.
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// The diagnostic manager to report parser errors to.
///
- /// @return
+ /// \return
/// The number of errors.
//------------------------------------------------------------------
unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp,
//------------------------------------------------------------------
/// Add a module to the list of modules to search.
///
- /// @param[in] module
+ /// \param[in] module
/// The path to the exact module to be loaded. E.g., if the desired
/// module is std.io, then this should be { "std", "io" }.
///
- /// @param[in] exported_modules
+ /// \param[in] exported_modules
/// If non-NULL, a pointer to a vector to populate with the ID of every
/// module that is re-exported by the specified module.
///
- /// @param[in] error_stream
+ /// \param[in] error_stream
/// A stream to populate with the output of the Clang parser when
/// it tries to load the module.
///
- /// @return
+ /// \return
/// True if the module could be loaded; false if not. If the
/// compiler encountered a fatal error during a previous module
/// load, then this will always return false for this ModuleImporter.
/// Add all modules referred to in a given compilation unit to the list
/// of modules to search.
///
- /// @param[in] cu
+ /// \param[in] cu
/// The compilation unit to scan for imported modules.
///
- /// @param[in] exported_modules
+ /// \param[in] exported_modules
/// A vector to populate with the ID of each module loaded (directly
/// and via re-exports) in this way.
///
- /// @param[in] error_stream
+ /// \param[in] error_stream
/// A stream to populate with the output of the Clang parser when
/// it tries to load the modules.
///
- /// @return
+ /// \return
/// True if all modules referred to by the compilation unit could be
/// loaded; false if one could not be loaded. If the compiler
/// encountered a fatal error during a previous module
/// Enumerate all the macros that are defined by a given set of modules
/// that are already imported.
///
- /// @param[in] modules
+ /// \param[in] modules
/// The unique IDs for all modules to query. Later modules have higher
/// priority, just as if you @imported them in that order. This matters
/// if module A #defines a macro and module B #undefs it.
///
- /// @param[in] handler
+ /// \param[in] handler
/// A function to call with the text of each #define (including the
/// #define directive). #undef directives are not included; we simply
/// elide any corresponding #define. If this function returns true,
/// LLDB uses this to decide whether to try to find the modules loaded
/// by a given compile unit.
///
- /// @param[in] language
+ /// \param[in] language
/// The language to query for.
///
- /// @return
+ /// \return
/// True if Clang has modules for the given language.
//------------------------------------------------------------------
static bool LanguageSupportsClangModules(lldb::LanguageType language);
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ClangPersistentVariables ClangPersistentVariables.h
+/// \class ClangPersistentVariables ClangPersistentVariables.h
/// "lldb/Expression/ClangPersistentVariables.h" Manages persistent values
/// that need to be preserved between expression invocations.
///
/// Converts an absolute position inside a given code string into
/// a column/line pair.
///
-/// @param[in] abs_pos
+/// \param[in] abs_pos
/// A absolute position in the code string that we want to convert
/// to a column/line pair.
///
-/// @param[in] code
+/// \param[in] code
/// A multi-line string usually representing source code.
///
-/// @param[out] line
+/// \param[out] line
/// The line in the code that contains the given absolute position.
/// The first line in the string is indexed as 1.
///
-/// @param[out] column
+/// \param[out] column
/// The column in the line that contains the absolute position.
/// The first character in a line is indexed as 0.
//------------------------------------------------------------------
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ClangUserExpression ClangUserExpression.h
+/// \class ClangUserExpression ClangUserExpression.h
/// "lldb/Expression/ClangUserExpression.h" Encapsulates a single expression
/// for use with Clang
///
/// Return the object that the parser should allow to access ASTs. May be
/// NULL if the ASTs do not need to be transformed.
///
- /// @param[in] passthrough
+ /// \param[in] passthrough
/// The ASTConsumer that the returned transformer should send
/// the ASTs to after transformation.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] expr
+ /// \param[in] expr
/// The expression to parse.
///
- /// @param[in] expr_prefix
+ /// \param[in] expr_prefix
/// If non-NULL, a C string containing translation-unit level
/// definitions to be included when the expression is parsed.
///
- /// @param[in] language
+ /// \param[in] language
/// If not eLanguageTypeUnknown, a language to use when parsing
/// the expression. Currently restricted to those languages
/// supported by Clang.
///
- /// @param[in] desired_type
+ /// \param[in] desired_type
/// If not eResultTypeAny, the type to use for the expression
/// result.
///
- /// @param[in] ctx_obj
+ /// \param[in] ctx_obj
/// The object (if any) in which context the expression
/// must be evaluated. For details see the comment to
/// `UserExpression::Evaluate`.
//------------------------------------------------------------------
/// Parse the expression
///
- /// @param[in] diagnostic_manager
+ /// \param[in] diagnostic_manager
/// A diagnostic manager to report parse errors and warnings to.
///
- /// @param[in] exe_ctx
+ /// \param[in] exe_ctx
/// The execution context to use when looking up entities that
/// are needed for parsing (locations of functions, types of
/// variables, persistent variables, etc.)
///
- /// @param[in] execution_policy
+ /// \param[in] execution_policy
/// Determines whether interpretation is possible or mandatory.
///
- /// @param[in] keep_result_in_memory
+ /// \param[in] keep_result_in_memory
/// True if the resulting persistent variable should reside in
/// target memory, if applicable.
///
- /// @return
+ /// \return
/// True on success (no errors); false otherwise.
//------------------------------------------------------------------
bool Parse(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
//------------------------------------------------------------------
/// Constructor
///
-/// @param[in] text
+/// \param[in] text
/// The text of the function. Must be a full translation unit.
///
-/// @param[in] name
+/// \param[in] name
/// The name of the function, as used in the text.
//------------------------------------------------------------------
ClangUtilityFunction::ClangUtilityFunction(ExecutionContextScope &exe_scope,
//------------------------------------------------------------------
/// Install the utility function into a process
///
-/// @param[in] diagnostic_manager
+/// \param[in] diagnostic_manager
/// A diagnostic manager to report errors and warnings to.
///
-/// @param[in] exe_ctx
+/// \param[in] exe_ctx
/// The execution context to install the utility function to.
///
-/// @return
+/// \return
/// True on success (no errors); false otherwise.
//------------------------------------------------------------------
bool ClangUtilityFunction::Install(DiagnosticManager &diagnostic_manager,
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ClangUtilityFunction ClangUtilityFunction.h
+/// \class ClangUtilityFunction ClangUtilityFunction.h
/// "lldb/Expression/ClangUtilityFunction.h" Encapsulates a single expression
/// for use with Clang
///
/// Return the object that the parser should allow to access ASTs. May be
/// NULL if the ASTs do not need to be transformed.
///
- /// @param[in] passthrough
+ /// \param[in] passthrough
/// The ASTConsumer that the returned transformer should send
/// the ASTs to after transformation.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] text
+ /// \param[in] text
/// The text of the function. Must be a full translation unit.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the function, as used in the text.
//------------------------------------------------------------------
ClangUtilityFunction(ExecutionContextScope &exe_scope, const char *text,
}
//----------------------------------------------------------------------
-/// @class IRForTarget IRForTarget.h "lldb/Expression/IRForTarget.h"
+/// \class IRForTarget IRForTarget.h "lldb/Expression/IRForTarget.h"
/// Transforms the IR for a function to run in the target
///
/// Once an expression has been parsed and converted to IR, it can run in two
//------------------------------------------------------------------
/// Constructor
///
- /// @param[in] decl_map
+ /// \param[in] decl_map
/// The list of externally-referenced variables for the expression,
/// for use in looking up globals and allocating the argument
/// struct. See the documentation for ClangExpressionDeclMap.
///
- /// @param[in] resolve_vars
+ /// \param[in] resolve_vars
/// True if the external variable references (including persistent
/// variables) should be resolved. If not, only external functions
/// are resolved.
///
- /// @param[in] execution_policy
+ /// \param[in] execution_policy
/// Determines whether an IR interpreter can be used to statically
/// evaluate the expression.
///
- /// @param[in] const_result
+ /// \param[in] const_result
/// This variable is populated with the statically-computed result
/// of the function, if it has no side-effects and the result can
/// be computed statically.
///
- /// @param[in] execution_unit
+ /// \param[in] execution_unit
/// The holder for raw data associated with the expression.
///
- /// @param[in] error_stream
+ /// \param[in] error_stream
/// If non-NULL, a stream on which errors can be printed.
///
- /// @param[in] func_name
+ /// \param[in] func_name
/// The name of the function to prepare for execution in the target.
//------------------------------------------------------------------
IRForTarget(lldb_private::ClangExpressionDeclMap *decl_map, bool resolve_vars,
///
/// Implementation of the llvm::ModulePass::runOnModule() function.
///
- /// @param[in] llvm_module
+ /// \param[in] llvm_module
/// The module to run on. This module is searched for the function
/// $__lldb_expr, and that function is passed to the passes one by
/// one.
///
- /// @param[in] interpreter_error
+ /// \param[in] interpreter_error
/// An error. If the expression fails to be interpreted, this error
/// is set to a reason why.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool runOnModule(llvm::Module &llvm_module) override;
/// Ensures that the current function's linkage is set to external.
/// Otherwise the JIT may not return an address for it.
///
- /// @param[in] llvm_function
+ /// \param[in] llvm_function
/// The function whose linkage is to be fixed.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool FixFunctionLinkage(llvm::Function &llvm_function);
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] llvm_module
+ /// \param[in] llvm_module
/// The module currently being processed.
///
- /// @param[in] llvm_function
+ /// \param[in] llvm_function
/// The function currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise.
//------------------------------------------------------------------
bool HasSideEffects(llvm::Function &llvm_function);
/// Get the address of a function, and a location to put the complete Value
/// of the function if one is available.
///
- /// @param[in] function
+ /// \param[in] function
/// The function to find the location of.
///
- /// @param[out] ptr
+ /// \param[out] ptr
/// The location of the function in the target.
///
- /// @param[out] name
+ /// \param[out] name
/// The resolved name of the function (matters for intrinsics).
///
- /// @param[out] value_ptr
+ /// \param[out] value_ptr
/// A variable to put the function's completed Value* in, or NULL
/// if the Value* shouldn't be stored anywhere.
///
- /// @return
+ /// \return
/// The pointer.
//------------------------------------------------------------------
LookupResult GetFunctionAddress(llvm::Function *function, uint64_t &ptr,
/// Find the NamedDecl corresponding to a Value. This interface is exposed
/// for the IR interpreter.
///
- /// @param[in] module
+ /// \param[in] module
/// The module containing metadata to search
///
- /// @param[in] global
+ /// \param[in] global
/// The global entity to search for
///
- /// @return
+ /// \return
/// The corresponding variable declaration
//------------------------------------------------------------------
public:
/// constant, assuming it can be evaluated. The result variable will be
/// reset to NULL later if the expression has side effects.
///
- /// @param[in] initializer
+ /// \param[in] initializer
/// The constant initializer for the variable.
///
- /// @param[in] name
+ /// \param[in] name
/// The name of the result variable.
///
- /// @param[in] type
+ /// \param[in] type
/// The Clang type of the result variable.
//------------------------------------------------------------------
void MaybeSetConstantResult(llvm::Constant *initializer,
/// result of the cast. The result variable will be reset to
/// NULL latger if the expression has side effects.
///
- /// @param[in] type
+ /// \param[in] type
/// The Clang type of the result variable.
//------------------------------------------------------------------
void MaybeSetCastResult(lldb_private::TypeFromParser type);
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] llvm_function
+ /// \param[in] llvm_function
/// The function currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool CreateResultVariable(llvm::Function &llvm_function);
//------------------------------------------------------------------
/// Rewrite a single Objective-C constant string.
///
- /// @param[in] NSStr
+ /// \param[in] NSStr
/// The constant NSString to be transformed
///
- /// @param[in] CStr
+ /// \param[in] CStr
/// The constant C string inside the NSString. This will be
/// passed as the bytes argument to CFStringCreateWithBytes.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RewriteObjCConstString(llvm::GlobalVariable *NSStr,
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RewriteObjCConstStrings();
//------------------------------------------------------------------
/// Replace a single selector reference
///
- /// @param[in] selector_load
+ /// \param[in] selector_load
/// The load of the statically-allocated selector.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RewriteObjCSelector(llvm::Instruction *selector_load);
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] basic_block
+ /// \param[in] basic_block
/// The basic block currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RewriteObjCSelectors(llvm::BasicBlock &basic_block);
//------------------------------------------------------------------
/// Replace a single old-style class reference
///
- /// @param[in] selector_load
+ /// \param[in] selector_load
/// The load of the statically-allocated selector.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RewriteObjCClassReference(llvm::Instruction *class_load);
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] basic_block
+ /// \param[in] basic_block
/// The basic block currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RewriteObjCClassReferences(llvm::BasicBlock &basic_block);
//------------------------------------------------------------------
/// Handle a single allocation of a persistent variable
///
- /// @param[in] persistent_alloc
+ /// \param[in] persistent_alloc
/// The allocation of the persistent variable.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RewritePersistentAlloc(llvm::Instruction *persistent_alloc);
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] basic_block
+ /// \param[in] basic_block
/// The basic block currently being processed.
//------------------------------------------------------------------
bool RewritePersistentAllocs(llvm::BasicBlock &basic_block);
//------------------------------------------------------------------
/// Write an initializer to a memory array of assumed sufficient size.
///
- /// @param[in] data
+ /// \param[in] data
/// A pointer to the data to write to.
///
- /// @param[in] initializer
+ /// \param[in] initializer
/// The initializer itself.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool MaterializeInitializer(uint8_t *data, llvm::Constant *initializer);
//------------------------------------------------------------------
/// Move an internal variable into the static allocation section.
///
- /// @param[in] global_variable
+ /// \param[in] global_variable
/// The variable.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool MaterializeInternalVariable(llvm::GlobalVariable *global_variable);
//------------------------------------------------------------------
/// Handle a single externally-defined variable
///
- /// @param[in] value
+ /// \param[in] value
/// The variable.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool MaybeHandleVariable(llvm::Value *value);
//------------------------------------------------------------------
/// Handle a single externally-defined symbol
///
- /// @param[in] symbol
+ /// \param[in] symbol
/// The symbol.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool HandleSymbol(llvm::Value *symbol);
//------------------------------------------------------------------
/// Handle a single externally-defined Objective-C class
///
- /// @param[in] classlist_reference
+ /// \param[in] classlist_reference
/// The reference, usually "01L_OBJC_CLASSLIST_REFERENCES_$_n"
/// where n (if present) is an index.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool HandleObjCClass(llvm::Value *classlist_reference);
//------------------------------------------------------------------
/// Handle all the arguments to a function call
///
- /// @param[in] C
+ /// \param[in] C
/// The call instruction.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool MaybeHandleCallArguments(llvm::CallInst *call_inst);
//------------------------------------------------------------------
/// Resolve variable references in calls to external functions
///
- /// @param[in] basic_block
+ /// \param[in] basic_block
/// The basic block currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool ResolveCalls(llvm::BasicBlock &basic_block);
/// Remove calls to __cxa_atexit, which should never be generated by
/// expressions.
///
- /// @param[in] call_inst
+ /// \param[in] call_inst
/// The call instruction.
///
- /// @return
+ /// \return
/// True if the scan was successful; false if some operation
/// failed
//------------------------------------------------------------------
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] basic_block
+ /// \param[in] basic_block
/// The function currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool ResolveExternals(llvm::Function &llvm_function);
//------------------------------------------------------------------
/// Rewrite a load to a guard variable to return constant 0.
///
- /// @param[in] guard_load
+ /// \param[in] guard_load
/// The load instruction to zero out.
//------------------------------------------------------------------
void TurnGuardLoadIntoZero(llvm::Instruction *guard_load);
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] basic_block
+ /// \param[in] basic_block
/// The basic block currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool RemoveGuards(llvm::BasicBlock &basic_block);
//------------------------------------------------------------------
/// The top-level pass implementation
///
- /// @param[in] llvm_function
+ /// \param[in] llvm_function
/// The function currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool ReplaceVariables(llvm::Function &llvm_function);
/// instructions replace the constant uses, so UnfoldConstant calls itself
/// recursively for those.
///
- /// @param[in] llvm_function
+ /// \param[in] llvm_function
/// The function currently being processed.
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
/// offset. This typically happens after inserting data into
/// m_data_allocator.
///
- /// @param[in] type
+ /// \param[in] type
/// The type of the value being loaded.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset of the value from the base of m_data_allocator.
///
- /// @return
+ /// \return
/// The Constant for the reference, usually a ConstantExpr.
//------------------------------------------------------------------
llvm::Constant *BuildRelocation(llvm::Type *type, uint64_t offset);
/// Commit the allocation in m_data_allocator and use its final location to
/// replace m_reloc_placeholder.
///
- /// @param[in] module
+ /// \param[in] module
/// The module that m_data_allocator resides in
///
- /// @return
+ /// \return
/// True on success; false otherwise
//------------------------------------------------------------------
bool CompleteDataAllocation();
//
//===----------------------------------------------------------------------===//
//
-/// @file
+/// \file
/// Generic structures and typedefs for ELF files.
///
/// This file provides definitions for the various entities comprising an ELF
namespace elf {
//------------------------------------------------------------------------------
-/// @name ELF type definitions.
+/// \name ELF type definitions.
///
/// Types used to represent the various components of ELF structures. All
/// types are signed or unsigned integral types wide enough to hold values
//@}
//------------------------------------------------------------------------------
-/// @class ELFHeader
+/// \class ELFHeader
/// Generic representation of an ELF file header.
///
/// This object is used to identify the general attributes on an ELF file and
//--------------------------------------------------------------------------
/// Returns true if this is a 32 bit ELF file header.
///
- /// @return
+ /// \return
/// True if this is a 32 bit ELF file header.
bool Is32Bit() const {
return e_ident[llvm::ELF::EI_CLASS] == llvm::ELF::ELFCLASS32;
//--------------------------------------------------------------------------
/// Returns true if this is a 64 bit ELF file header.
///
- /// @return
+ /// \return
/// True if this is a 64 bit ELF file header.
bool Is64Bit() const {
return e_ident[llvm::ELF::EI_CLASS] == llvm::ELF::ELFCLASS64;
//--------------------------------------------------------------------------
/// The byte order of this ELF file header.
///
- /// @return
+ /// \return
/// The byte order of this ELF file as described by the header.
lldb::ByteOrder GetByteOrder() const;
//--------------------------------------------------------------------------
/// Check if there should be header extension in section header #0
///
- /// @return
+ /// \return
/// True if parsing the ELFHeader requires reading header extension
/// and false otherwise.
bool HasHeaderExtension() const;
/// data extractor with the address size and byte order attributes as
/// defined by the header.
///
- /// @param[in,out] data
+ /// \param[in,out] data
/// The DataExtractor to read from. Updated with the address size and
/// byte order attributes appropriate to this header.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFHeader was successfully read and false
/// otherwise.
bool Parse(lldb_private::DataExtractor &data, lldb::offset_t *offset);
/// Examines at most EI_NIDENT bytes starting from the given pointer and
/// determines if the magic ELF identification exists.
///
- /// @return
+ /// \return
/// True if the given sequence of bytes identifies an ELF file.
static bool MagicBytesMatch(const uint8_t *magic);
/// should only be called on an pointer for which MagicBytesMatch returns
/// true.
///
- /// @return
+ /// \return
/// The number of bytes forming an address in the ELF file (either 4 or
/// 8), else zero if the address size could not be determined.
static unsigned AddressSizeInBytes(const uint8_t *magic);
/// Parse an ELFHeader header extension entry. This method is called by
/// Parse().
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from.
void ParseHeaderExtension(lldb_private::DataExtractor &data);
};
//------------------------------------------------------------------------------
-/// @class ELFSectionHeader
+/// \class ELFSectionHeader
/// Generic representation of an ELF section header.
struct ELFSectionHeader {
elf_word sh_name; ///< Section name string index.
/// Parse an ELFSectionHeader entry from the given DataExtracter starting at
/// position \p offset.
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from. The address size of the extractor
/// determines if a 32 or 64 bit object should be read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFSectionHeader was successfully read and false
/// otherwise.
bool Parse(const lldb_private::DataExtractor &data, lldb::offset_t *offset);
};
//------------------------------------------------------------------------------
-/// @class ELFProgramHeader
+/// \class ELFProgramHeader
/// Generic representation of an ELF program header.
struct ELFProgramHeader {
elf_word p_type; ///< Type of program segment.
/// position \p offset. The address size of the DataExtractor determines if
/// a 32 or 64 bit object is to be parsed.
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from. The address size of the extractor
/// determines if a 32 or 64 bit object should be read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFProgramHeader was successfully read and false
/// otherwise.
bool Parse(const lldb_private::DataExtractor &data, lldb::offset_t *offset);
};
//------------------------------------------------------------------------------
-/// @class ELFSymbol
+/// \class ELFSymbol
/// Represents a symbol within an ELF symbol table.
struct ELFSymbol {
elf_addr st_value; ///< Absolute or relocatable address.
/// position \p offset. The address size of the DataExtractor determines if
/// a 32 or 64 bit object is to be parsed.
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from. The address size of the extractor
/// determines if a 32 or 64 bit object should be read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFSymbol was successfully read and false otherwise.
bool Parse(const lldb_private::DataExtractor &data, lldb::offset_t *offset);
};
//------------------------------------------------------------------------------
-/// @class ELFDynamic
+/// \class ELFDynamic
/// Represents an entry in an ELF dynamic table.
struct ELFDynamic {
elf_sxword d_tag; ///< Type of dynamic table entry.
/// position \p offset. The address size of the DataExtractor determines if
/// a 32 or 64 bit object is to be parsed.
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from. The address size of the extractor
/// determines if a 32 or 64 bit object should be read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFDynamic entry was successfully read and false
/// otherwise.
bool Parse(const lldb_private::DataExtractor &data, lldb::offset_t *offset);
};
//------------------------------------------------------------------------------
-/// @class ELFRel
+/// \class ELFRel
/// Represents a relocation entry with an implicit addend.
struct ELFRel {
elf_addr r_offset; ///< Address of reference.
/// \p offset. The address size of the DataExtractor determines if a 32 or
/// 64 bit object is to be parsed.
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from. The address size of the extractor
/// determines if a 32 or 64 bit object should be read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFRel entry was successfully read and false otherwise.
bool Parse(const lldb_private::DataExtractor &data, lldb::offset_t *offset);
};
//------------------------------------------------------------------------------
-/// @class ELFRela
+/// \class ELFRela
/// Represents a relocation entry with an explicit addend.
struct ELFRela {
elf_addr r_offset; ///< Address of reference.
/// \p offset. The address size of the DataExtractor determines if a 32 or
/// 64 bit object is to be parsed.
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from. The address size of the extractor
/// determines if a 32 or 64 bit object should be read.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFRela entry was successfully read and false otherwise.
bool Parse(const lldb_private::DataExtractor &data, lldb::offset_t *offset);
#define NT_METAG_TLS 0x502
//===----------------------------------------------------------------------===//
-/// @class ELFRelocation
+/// \class ELFRelocation
/// Generic wrapper for ELFRel and ELFRela.
///
/// This helper class allows us to parse both ELFRel and ELFRela relocation
/// Constructs an ELFRelocation entry with a personality as given by @p
/// type.
///
- /// @param type Either DT_REL or DT_RELA. Any other value is invalid.
+ /// \param type Either DT_REL or DT_RELA. Any other value is invalid.
ELFRelocation(unsigned type);
~ELFRelocation();
/// Parse an ELFNote entry from the given DataExtractor starting at position
/// \p offset.
///
- /// @param[in] data
+ /// \param[in] data
/// The DataExtractor to read from.
///
- /// @param[in,out] offset
+ /// \param[in,out] offset
/// Pointer to an offset in the data. On return the offset will be
/// advanced by the number of bytes read.
///
- /// @return
+ /// \return
/// True if the ELFRel entry was successfully read and false otherwise.
bool Parse(const lldb_private::DataExtractor &data, lldb::offset_t *offset);
};
//------------------------------------------------------------------------------
-/// @class ObjectFileELF
+/// \class ObjectFileELF
/// Generic ELF object file reader.
///
/// This class provides a generic ELF (32/64 bit) reader plugin implementing
/// Returns the section header with the given id or NULL.
const ELFSectionHeaderInfo *GetSectionHeaderByIndex(lldb::user_id_t id);
- /// @name ELF header dump routines
+ /// \name ELF header dump routines
//@{
static void DumpELFHeader(lldb_private::Stream *s,
const elf::ELFHeader &header);
elf::elf_half e_type);
//@}
- /// @name ELF program header dump routines
+ /// \name ELF program header dump routines
//@{
void DumpELFProgramHeaders(lldb_private::Stream *s);
elf::elf_word p_flags);
//@}
- /// @name ELF section header dump routines
+ /// \name ELF section header dump routines
//@{
void DumpELFSectionHeaders(lldb_private::Stream *s);
// =============================================================================
/// Launches a process for debugging.
///
-/// @param[inout] launch_info
+/// \param[inout] launch_info
/// Specifies details about the process to launch (e.g. path, architecture,
/// etc.). On output, includes the launched ProcessID (pid).
///
-/// @param[out] pty_master_fd
+/// \param[out] pty_master_fd
/// Returns the master side of the pseudo-terminal used to communicate
/// with stdin/stdout from the launched process. May be nullptr.
///
-/// @param[out] launch_flavor
+/// \param[out] launch_flavor
/// Contains the launch flavor used when launching the process.
// =============================================================================
Status
namespace process_darwin {
-/// @class NativeProcessDarwin
+/// \class NativeProcessDarwin
/// Manages communication with the inferior (debugee) process.
///
/// Upon construction, this class prepares and launches an inferior process
/// listener to the inferior exception port, ptracing the process, and the
/// like.
///
- /// @param[in] launch_flavor
+ /// \param[in] launch_flavor
/// The launch flavor that was used to launch the process.
///
- /// @param[in] main_loop
+ /// \param[in] main_loop
/// The main loop that will run the process monitor. Work
/// that needs to be done (e.g. reading files) gets registered
/// here along with callbacks to process the work.
///
- /// @return
+ /// \return
/// Any error that occurred during the aforementioned
/// operations. Failure here will force termination of the
/// launched process and debugging session.
Status FixupBreakpointPCAsNeeded(NativeThreadDarwin &thread);
/// Writes a siginfo_t structure corresponding to the given thread
- /// ID to the memory region pointed to by @p siginfo.
+ /// ID to the memory region pointed to by \p siginfo.
Status GetSignalInfo(lldb::tid_t tid, void *siginfo);
/// Writes the raw event message code (vis-a-vis PTRACE_GETEVENTMSG)
// Interface for friend classes
// -----------------------------------------------------------------
- /// Resumes the thread. If @p signo is anything but
+ /// Resumes the thread. If \p signo is anything but
/// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the thread.
Status Resume(uint32_t signo);
- /// Single steps the thread. If @p signo is anything but
+ /// Single steps the thread. If \p signo is anything but
/// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the thread.
Status SingleStep(uint32_t signo);
// -------------------------------------------------------------------------
/// Return the mach thread port number for this thread.
///
- /// @return
+ /// \return
/// The mach port number for this thread. Returns NULL_THREAD
/// when the thread is invalid.
// -------------------------------------------------------------------------
#include <string>
//===----------------------------------------------------------------------===//
-/// @class POSIXStopInfo
+/// \class POSIXStopInfo
/// Simple base class for all POSIX-specific StopInfo objects.
///
class POSIXStopInfo : public lldb_private::StopInfo {
};
//===----------------------------------------------------------------------===//
-/// @class POSIXLimboStopInfo
+/// \class POSIXLimboStopInfo
/// Represents the stop state of a process ready to exit.
///
class POSIXLimboStopInfo : public POSIXStopInfo {
};
//===----------------------------------------------------------------------===//
-/// @class POSIXNewThreadStopInfo
+/// \class POSIXNewThreadStopInfo
/// Represents the stop state of process when a new thread is spawned.
///
}
//------------------------------------------------------------------------------
-/// @class Operation
+/// \class Operation
/// Represents a ProcessMonitor operation.
///
/// Under FreeBSD, it is not possible to ptrace() from any other thread but
};
//------------------------------------------------------------------------------
-/// @class ReadOperation
+/// \class ReadOperation
/// Implements ProcessMonitor::ReadMemory.
class ReadOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class WriteOperation
+/// \class WriteOperation
/// Implements ProcessMonitor::WriteMemory.
class WriteOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class ReadRegOperation
+/// \class ReadRegOperation
/// Implements ProcessMonitor::ReadRegisterValue.
class ReadRegOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class WriteRegOperation
+/// \class WriteRegOperation
/// Implements ProcessMonitor::WriteRegisterValue.
class WriteRegOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class ReadDebugRegOperation
+/// \class ReadDebugRegOperation
/// Implements ProcessMonitor::ReadDebugRegisterValue.
class ReadDebugRegOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class WriteDebugRegOperation
+/// \class WriteDebugRegOperation
/// Implements ProcessMonitor::WriteDebugRegisterValue.
class WriteDebugRegOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class ReadGPROperation
+/// \class ReadGPROperation
/// Implements ProcessMonitor::ReadGPR.
class ReadGPROperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class ReadFPROperation
+/// \class ReadFPROperation
/// Implements ProcessMonitor::ReadFPR.
class ReadFPROperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class WriteGPROperation
+/// \class WriteGPROperation
/// Implements ProcessMonitor::WriteGPR.
class WriteGPROperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class WriteFPROperation
+/// \class WriteFPROperation
/// Implements ProcessMonitor::WriteFPR.
class WriteFPROperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class ResumeOperation
+/// \class ResumeOperation
/// Implements ProcessMonitor::Resume.
class ResumeOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class SingleStepOperation
+/// \class SingleStepOperation
/// Implements ProcessMonitor::SingleStep.
class SingleStepOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class LwpInfoOperation
+/// \class LwpInfoOperation
/// Implements ProcessMonitor::GetLwpInfo.
class LwpInfoOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class ThreadSuspendOperation
+/// \class ThreadSuspendOperation
/// Implements ProcessMonitor::ThreadSuspend.
class ThreadSuspendOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class EventMessageOperation
+/// \class EventMessageOperation
/// Implements ProcessMonitor::GetEventMessage.
class EventMessageOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class KillOperation
+/// \class KillOperation
/// Implements ProcessMonitor::Kill.
class KillOperation : public Operation {
public:
}
//------------------------------------------------------------------------------
-/// @class DetachOperation
+/// \class DetachOperation
/// Implements ProcessMonitor::Detach.
class DetachOperation : public Operation {
public:
class ProcessFreeBSD;
class Operation;
-/// @class ProcessMonitor
+/// \class ProcessMonitor
/// Manages communication with the inferior (debugee) process.
///
/// Upon construction, this class prepares and launches an inferior process
/// -1.
int GetTerminalFD() const { return m_terminal_fd; }
- /// Reads @p size bytes from address @vm_adder in the inferior process
+ /// Reads \p size bytes from address @vm_adder in the inferior process
/// address space.
///
/// This method is provided to implement Process::DoReadMemory.
size_t ReadMemory(lldb::addr_t vm_addr, void *buf, size_t size,
lldb_private::Status &error);
- /// Writes @p size bytes from address @p vm_adder in the inferior process
+ /// Writes \p size bytes from address \p vm_adder in the inferior process
/// address space.
///
/// This method is provided to implement Process::DoWriteMemory.
size_t GetCurrentThreadIDs(std::vector<lldb::tid_t> &thread_ids);
/// Writes a ptrace_lwpinfo structure corresponding to the given thread ID
- /// to the memory region pointed to by @p lwpinfo.
+ /// to the memory region pointed to by \p lwpinfo.
bool GetLwpInfo(lldb::tid_t tid, void *lwpinfo, int &error_no);
/// Suspends or unsuspends a thread prior to process resume or step.
/// message.
bool GetEventMessage(lldb::tid_t tid, unsigned long *message);
- /// Resumes the process. If @p signo is anything but
+ /// Resumes the process. If \p signo is anything but
/// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the process.
bool Resume(lldb::tid_t unused, uint32_t signo);
- /// Single steps the process. If @p signo is anything but
+ /// Single steps the process. If \p signo is anything but
/// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the process.
bool SingleStep(lldb::tid_t unused, uint32_t signo);
lldb_private::Status m_error; // Set if process operation failed.
};
- /// @class LauchArgs
+ /// \class LauchArgs
///
/// Simple structure to pass data to the thread responsible for launching a
/// child process.
#include "lldb/Utility/ArchSpec.h"
//------------------------------------------------------------------------------
-/// @class POSIXBreakpointProtocol
+/// \class POSIXBreakpointProtocol
///
/// Extends RegisterClass with a few virtual operations useful on POSIX.
class POSIXBreakpointProtocol {
/// implementation simply returns true for architectures which do not
/// require any update.
///
- /// @return
+ /// \return
/// True if the operation succeeded and false otherwise.
virtual bool UpdateAfterBreakpoint() = 0;
class Scalar;
namespace process_linux {
-/// @class NativeProcessLinux
+/// \class NativeProcessLinux
/// Manages communication with the inferior (debugee) process.
///
/// Upon construction, this class prepares and launches an inferior process
NativeThreadLinux &AddThread(lldb::tid_t thread_id);
/// Writes a siginfo_t structure corresponding to the given thread ID to the
- /// memory region pointed to by @p siginfo.
+ /// memory region pointed to by \p siginfo.
Status GetSignalInfo(lldb::tid_t tid, void *siginfo);
/// Writes the raw event message code (vis-a-vis PTRACE_GETEVENTMSG)
// Interface for friend classes
// ---------------------------------------------------------------------
- /// Resumes the thread. If @p signo is anything but
+ /// Resumes the thread. If \p signo is anything but
/// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the thread.
Status Resume(uint32_t signo);
- /// Single steps the thread. If @p signo is anything but
+ /// Single steps the thread. If \p signo is anything but
/// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the thread.
Status SingleStep(uint32_t signo);
// ---------------------------------------------------------------------
/// Read data from a cyclic buffer
///
- /// @param[in] [out] buf
+ /// \param[in] [out] buf
/// Destination buffer, the buffer will be truncated to written size.
///
- /// @param[in] src
+ /// \param[in] src
/// Source buffer which must be a cyclic buffer.
///
- /// @param[in] src_cyc_index
+ /// \param[in] src_cyc_index
/// The index pointer (start of the valid data in the cyclic
/// buffer).
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset to begin reading the data in the cyclic buffer.
// ---------------------------------------------------------------------
static void ReadCyclicBuffer(llvm::MutableArrayRef<uint8_t> &dst,
namespace lldb_private {
namespace process_netbsd {
-/// @class NativeProcessNetBSD
+/// \class NativeProcessNetBSD
/// Manages communication with the inferior (debugee) process.
///
/// Upon construction, this class prepares and launches an inferior process
lldb::tid_t GetTID() const { return m_tid; }
- /// Indicates that the process @p pid has successfully attached.
+ /// Indicates that the process \p pid has successfully attached.
static ProcessMessage Attach(lldb::pid_t pid) {
return ProcessMessage(pid, eAttachMessage);
}
- /// Indicates that the thread @p tid is about to exit with status @p status.
+ /// Indicates that the thread \p tid is about to exit with status \p status.
static ProcessMessage Limbo(lldb::tid_t tid, int status) {
return ProcessMessage(tid, eLimboMessage, status);
}
- /// Indicates that the thread @p tid had the signal @p signum delivered.
+ /// Indicates that the thread \p tid had the signal \p signum delivered.
static ProcessMessage Signal(lldb::tid_t tid, int signum) {
return ProcessMessage(tid, eSignalMessage, signum);
}
- /// Indicates that a signal @p signum generated by the debugging process was
- /// delivered to the thread @p tid.
+ /// Indicates that a signal \p signum generated by the debugging process was
+ /// delivered to the thread \p tid.
static ProcessMessage SignalDelivered(lldb::tid_t tid, int signum) {
return ProcessMessage(tid, eSignalDeliveredMessage, signum);
}
- /// Indicates that the thread @p tid encountered a trace point.
+ /// Indicates that the thread \p tid encountered a trace point.
static ProcessMessage Trace(lldb::tid_t tid) {
return ProcessMessage(tid, eTraceMessage);
}
- /// Indicates that the thread @p tid encountered a break point.
+ /// Indicates that the thread \p tid encountered a break point.
static ProcessMessage Break(lldb::tid_t tid) {
return ProcessMessage(tid, eBreakpointMessage);
}
return ProcessMessage(tid, eWatchpointMessage, 0, wp_addr);
}
- /// Indicates that the thread @p tid crashed.
+ /// Indicates that the thread \p tid crashed.
static ProcessMessage Crash(lldb::pid_t pid, CrashReason reason, int signo,
lldb::addr_t fault_addr) {
ProcessMessage message(pid, eCrashMessage, signo, fault_addr);
return message;
}
- /// Indicates that the thread @p child_tid was spawned.
+ /// Indicates that the thread \p child_tid was spawned.
static ProcessMessage NewThread(lldb::tid_t parent_tid,
lldb::tid_t child_tid) {
return ProcessMessage(parent_tid, eNewThreadMessage, child_tid);
}
- /// Indicates that the thread @p tid is about to exit with status @p status.
+ /// Indicates that the thread \p tid is about to exit with status \p status.
static ProcessMessage Exit(lldb::tid_t tid, int status) {
return ProcessMessage(tid, eExitMessage, status);
}
- /// Indicates that the thread @p pid has exec'd.
+ /// Indicates that the thread \p pid has exec'd.
static ProcessMessage Exec(lldb::tid_t tid) {
return ProcessMessage(tid, eExecMessage);
}
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class HistoryThread HistoryThread.h "HistoryThread.h"
+/// \class HistoryThread HistoryThread.h "HistoryThread.h"
/// A thread object representing a backtrace from a previous point in the
/// process execution
///
/// Given a SymbolContext, determines if this is a trap handler function
/// aka asynchronous signal handler.
///
- /// @return
+ /// \return
/// Returns true if the SymbolContext is a trap handler.
//------------------------------------------------------------------
bool IsTrapHandlerSymbol(lldb_private::Process *process,
/// better. This is mostly helping to work around problems where the
/// assembly language inspection fails on hand-written assembly code.
///
- /// @return
+ /// \return
/// Returns true if a fallback unwindplan was found & was installed.
//------------------------------------------------------------------
bool TryFallbackUnwindPlan();
namespace lldb_private {
///------------------------------------------------------------------------------
-/// @class RegisterInfoInterface
+/// \class RegisterInfoInterface
///
/// RegisterInfo interface to patch RegisterInfo structure for archs.
///------------------------------------------------------------------------------
/// into an array of ConstStrings before it can be used - we only want
/// to do that once per thread so it's here in the UnwindLLDB object.
///
- /// @return
+ /// \return
/// Vector of ConstStrings of trap handler function names. May be
/// empty.
//------------------------------------------------------------------
// =========================================================================
/// Process asynchronously-received structured data.
///
- /// @param[in] data
+ /// \param[in] data
/// The complete data packet, expected to start with JSON-async.
// =========================================================================
virtual void HandleAsyncStructuredDataPacket(llvm::StringRef data) = 0;
/// Sends a GDB remote protocol 'A' packet that delivers program
/// arguments to the remote server.
///
- /// @param[in] argv
+ /// \param[in] argv
/// A NULL terminated array of const C strings to use as the
/// arguments.
///
- /// @return
+ /// \return
/// Zero if the response was "OK", a positive value if the
/// the response was "Exx" where xx are two hex digits, or
/// -1 if the call is unsupported or any other unexpected
/// multiple times in a row in order to pass on the desired
/// environment that the inferior should be launched with.
///
- /// @param[in] name_equal_value
+ /// \param[in] name_equal_value
/// A NULL terminated C string that contains a single environment
/// in the format "NAME=VALUE".
///
- /// @return
+ /// \return
/// Zero if the response was "OK", a positive value if the
/// the response was "Exx" where xx are two hex digits, or
/// -1 if the call is unsupported or any other unexpected
//------------------------------------------------------------------
/// Sends a "vAttach:PID" where PID is in hex.
///
- /// @param[in] pid
+ /// \param[in] pid
/// A process ID for the remote gdb server to attach to.
///
- /// @param[out] response
+ /// \param[out] response
/// The response received from the gdb server. If the return
/// value is zero, \a response will contain a stop reply
/// packet.
///
- /// @return
+ /// \return
/// Zero if the attach was successful, or an error indicating
/// an error code.
//------------------------------------------------------------------
/// Sends a GDB remote protocol 'I' packet that delivers stdin
/// data to the remote process.
///
- /// @param[in] data
+ /// \param[in] data
/// A pointer to stdin data.
///
- /// @param[in] data_len
+ /// \param[in] data_len
/// The number of bytes available at \a data.
///
- /// @return
+ /// \return
/// Zero if the attach was successful, or an error indicating
/// an error code.
//------------------------------------------------------------------
/// Sets the path to use for stdin/out/err for a process
/// that will be launched with the 'A' packet.
///
- /// @param[in] path
+ /// \param[in] path
/// The path to use for stdin/out/err
///
- /// @return
+ /// \return
/// Zero if the for success, or an error code for failure.
//------------------------------------------------------------------
int SetSTDIN(const FileSpec &file_spec);
/// Sets the disable ASLR flag to \a enable for a process that will
/// be launched with the 'A' packet.
///
- /// @param[in] enable
+ /// \param[in] enable
/// A boolean value indicating whether to disable ASLR or not.
///
- /// @return
+ /// \return
/// Zero if the for success, or an error code for failure.
//------------------------------------------------------------------
int SetDisableASLR(bool enable);
/// Sets the DetachOnError flag to \a enable for the process controlled by the
/// stub.
///
- /// @param[in] enable
+ /// \param[in] enable
/// A boolean value indicating whether to detach on error or not.
///
- /// @return
+ /// \return
/// Zero if the for success, or an error code for failure.
//------------------------------------------------------------------
int SetDetachOnError(bool enable);
/// implements the platform, it will change the current working
/// directory for the platform process.
///
- /// @param[in] working_dir
+ /// \param[in] working_dir
/// The path to a directory to use when launching our process
///
- /// @return
+ /// \return
/// Zero if the for success, or an error code for failure.
//------------------------------------------------------------------
int SetWorkingDir(const FileSpec &working_dir);
/// Gets the current working directory of a remote platform GDB
/// server.
///
- /// @param[out] working_dir
+ /// \param[out] working_dir
/// The current working directory on the remote platform.
///
- /// @return
+ /// \return
/// Boolean for success
//------------------------------------------------------------------
bool GetWorkingDir(FileSpec &working_dir);
/// packet. The response is the complete string payload returned
/// to the client.
///
- /// @return
+ /// \return
/// The string returned by the server to the qSupported query.
//------------------------------------------------------------------
const std::string &GetServerSupportedFeatures() const {
/// A plugin indicates whether it knows how to handle a type_name.
/// If so, it can be used to process the async JSON packet.
///
- /// @return
+ /// \return
/// The string returned by the server to the qSupported query.
//------------------------------------------------------------------
lldb_private::StructuredData::Array *GetSupportedStructuredDataPlugins();
//------------------------------------------------------------------
/// Configure a StructuredData feature on the remote end.
///
- /// @see \b Process::ConfigureStructuredData(...) for details.
+ /// \see \b Process::ConfigureStructuredData(...) for details.
//------------------------------------------------------------------
Status
ConfigureRemoteStructuredData(ConstString type_name,
/// server in a situation where the startup code has been provided
/// with all the information for a child process to be launched.
///
- /// @return
+ /// \return
/// An Status object indicating the success or failure of the
/// launch.
//------------------------------------------------------------------
/// server in a situation where the startup code has been provided
/// with all the information for a child process to be launched.
///
- /// @return
+ /// \return
/// An Status object indicating the success or failure of the
/// launch.
//------------------------------------------------------------------
/// This method supports attaching llgs to a process accessible via the
/// configured Platform.
///
- /// @return
+ /// \return
/// An Status object indicating the success or failure of the
/// attach operation.
//------------------------------------------------------------------
/// that controls if we always enable it for newly created/attached
/// processes.
///
- /// @return
+ /// \return
/// True if DarwinLog support is/will be enabled for existing or
/// newly launched/attached processes.
// -------------------------------------------------------------------------
//------------------------------------------------------------------
/// Get the data that contains the DIE information for this unit.
///
- /// @return
+ /// \return
/// The correct data (.debug_types for DWARF 4 and earlier, and
/// .debug_info for DWARF 5 and later) for the DIE information in
/// this unit.
//------------------------------------------------------------------
/// Get the size in bytes of the header.
///
- /// @return
+ /// \return
/// Byte size of the compile unit header
//------------------------------------------------------------------
uint32_t GetHeaderByteSize() const override;
/// this DWARFUnit. It could be .debug_info or .debug_types
/// depending on where the data for this unit originates.
///
- /// @return
+ /// \return
/// The correct data for the DIE information in this unit.
//------------------------------------------------------------------
virtual const lldb_private::DWARFDataExtractor &GetData() const = 0;
//------------------------------------------------------------------
/// Get the size in bytes of the compile unit header.
///
- /// @return
+ /// \return
/// Byte size of the compile unit header
//------------------------------------------------------------------
virtual uint32_t GetHeaderByteSize() const = 0;
/// In DWARF32 this is just 4 bytes, and DWARF64 it is 12 where 4
/// are 0xFFFFFFFF followed by the actual 64 bit length.
///
- /// @return
+ /// \return
/// Byte size of the compile unit header length field
//------------------------------------------------------------------
size_t GetLengthByteSize() const { return IsDWARF64() ? 12 : 4; }
//------------------------------------------------------------------
/// Convert \a addr from a .o file address, to an executable address.
///
- /// @param[in] addr
+ /// \param[in] addr
/// A section offset address from a .o file
///
- /// @return
+ /// \return
/// Returns true if \a addr was converted to be an executable
/// section/offset address, false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Convert a .o file "file address" to an executable "file address".
///
- /// @param[in] oso_symfile
+ /// \param[in] oso_symfile
/// The DWARF symbol file that contains \a oso_file_addr
///
- /// @param[in] oso_file_addr
+ /// \param[in] oso_file_addr
/// A .o file "file address" to convert.
///
- /// @return
+ /// \return
/// LLDB_INVALID_ADDRESS if \a oso_file_addr is not in the
/// linked executable, otherwise a valid "file address" from the
/// linked executable that contains the debug map.
/// for a .o file represented by \a oso_symfile, link a new line table
/// and return it.
///
- /// @param[in] oso_symfile
+ /// \param[in] oso_symfile
/// The DWARF symbol file that produced the \a line_table
///
- /// @param[in] addr
+ /// \param[in] addr
/// A section offset address from a .o file
///
- /// @return
+ /// \return
/// Returns a valid line table full of linked addresses, or NULL
/// if none of the line table addresses exist in the main
/// executable.
//------------------------------------------------------------------------------
/// Converts a location information from a PDB symbol to a DWARF expression
///
-/// @param[in] module
+/// \param[in] module
/// The module \a symbol belongs to.
///
-/// @param[in] symbol
+/// \param[in] symbol
/// The symbol with a location information to convert.
///
-/// @param[in] ranges
+/// \param[in] ranges
/// Ranges where this variable is valid.
///
-/// @param[out] is_constant
+/// \param[out] is_constant
/// Set to \b true if the result expression is a constant value data,
/// and \b false if it is a DWARF bytecode.
///
-/// @return
+/// \return
/// The DWARF expression corresponding to the location data of \a symbol.
//------------------------------------------------------------------------------
lldb_private::DWARFExpression
/// memory that needs to be freed, pass in the address and size and it will
/// be freed before getting the list of queues.
///
- /// @param [in] thread
+ /// \param [in] thread
/// The thread to run this plan on.
///
- /// @param [in] item
+ /// \param [in] item
/// The introspection_dispatch_item_info_ref value for the item of
/// interest.
///
- /// @param [in] page_to_free
+ /// \param [in] page_to_free
/// An address of an inferior process vm page that needs to be
/// deallocated,
/// LLDB_INVALID_ADDRESS if this is not needed.
///
- /// @param [in] page_to_free_size
+ /// \param [in] page_to_free_size
/// The size of the vm page that needs to be deallocated if an address was
/// passed in to page_to_free.
///
- /// @param [out] error
+ /// \param [out] error
/// This object will be updated with the error status / error string from
/// any failures encountered.
///
- /// @returns
+ /// \returns
/// The result of the inferior function call execution. If there was a
/// failure of any kind while getting
/// the information, the item_buffer_ptr value will be
/// memory that needs to be freed, pass in the address and size and it will
/// be freed before getting the list of queues.
///
- /// @param [in] thread
+ /// \param [in] thread
/// The thread to run this plan on.
///
- /// @param [in] queue
+ /// \param [in] queue
/// The dispatch_queue_t value for the queue of interest.
///
- /// @param [in] page_to_free
+ /// \param [in] page_to_free
/// An address of an inferior process vm page that needs to be
/// deallocated,
/// LLDB_INVALID_ADDRESS if this is not needed.
///
- /// @param [in] page_to_free_size
+ /// \param [in] page_to_free_size
/// The size of the vm page that needs to be deallocated if an address was
/// passed in to page_to_free.
///
- /// @param [out] error
+ /// \param [out] error
/// This object will be updated with the error status / error string from
/// any failures encountered.
///
- /// @returns
+ /// \returns
/// The result of the inferior function call execution. If there was a
/// failure of any kind while getting
/// the information, the items_buffer_ptr value will be
/// memory that needs to be freed, pass in the address and size and it will
/// be freed before getting the list of queues.
///
- /// @param [in] thread
+ /// \param [in] thread
/// The thread to run this plan on.
///
- /// @param [in] page_to_free
+ /// \param [in] page_to_free
/// An address of an inferior process vm page that needs to be
/// deallocated,
/// LLDB_INVALID_ADDRESS if this is not needed.
///
- /// @param [in] page_to_free_size
+ /// \param [in] page_to_free_size
/// The size of the vm page that needs to be deallocated if an address was
/// passed in to page_to_free.
///
- /// @param [out] error
+ /// \param [out] error
/// This object will be updated with the error status / error string from
/// any failures encountered.
///
- /// @returns
+ /// \returns
/// The result of the inferior function call execution. If there was a
/// failure of any kind while getting
/// the information, the queues_buffer_ptr value will be
/// memory that needs to be freed, pass in the address and size and it will
/// be freed before getting the list of queues.
///
- /// @param [in] thread_id
+ /// \param [in] thread_id
/// The thread to get the extended backtrace for.
///
- /// @param [in] page_to_free
+ /// \param [in] page_to_free
/// An address of an inferior process vm page that needs to be
/// deallocated,
/// LLDB_INVALID_ADDRESS if this is not needed.
///
- /// @param [in] page_to_free_size
+ /// \param [in] page_to_free_size
/// The size of the vm page that needs to be deallocated if an address was
/// passed in to page_to_free.
///
- /// @param [out] error
+ /// \param [out] error
/// This object will be updated with the error status / error string from
/// any failures encountered.
///
- /// @returns
+ /// \returns
/// The result of the inferior function call execution. If there was a
/// failure of any kind while getting
/// the information, the item_buffer_ptr value will be
/// Attempt to reconstruct the ValueObject for the address contained in a
/// given register plus an offset.
///
-/// @params [in] frame
+/// \params [in] frame
/// The current stack frame.
///
-/// @params [in] reg
+/// \params [in] reg
/// The register.
///
-/// @params [in] offset
+/// \params [in] offset
/// The offset from the register.
///
-/// @param [in] disassembler
+/// \param [in] disassembler
/// A disassembler containing instructions valid up to the current PC.
///
-/// @param [in] variables
+/// \param [in] variables
/// The variable list from the current frame,
///
-/// @param [in] pc
+/// \param [in] pc
/// The program counter for the instruction considered the 'user'.
///
-/// @return
+/// \return
/// A string describing the base for the ExpressionPath. This could be a
/// variable, a register value, an argument, or a function return value.
/// The ValueObject if found. If valid, it has a valid ExpressionPath.
//------------------------------------------------------------------
/// Safely get a character at the specified index.
///
-/// @param[in] path
+/// \param[in] path
/// A full, partial, or relative path to a file.
///
-/// @param[in] i
+/// \param[in] i
/// An index into path which may or may not be valid.
///
-/// @return
+/// \return
/// The character at index \a i if the index is valid, or 0 if
/// the index is not valid.
//------------------------------------------------------------------
/// need normalization since we aren't trying to resolve the path,
/// we are just trying to remove redundant things from the path.
///
-/// @param[in] path
+/// \param[in] path
/// A full, partial, or relative path to a file.
///
-/// @return
+/// \return
/// Returns \b true if the path needs to be normalized.
//------------------------------------------------------------------
bool needsNormalization(const llvm::StringRef &path) {
/// file (files with a ".c", ".cpp", ".m", ".mm" (many more)
/// extension).
///
-/// @return
+/// \return
/// \b true if the filespec represents an implementation source
/// file, \b false otherwise.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the current error string to a formatted error string.
///
-/// @param format
+/// \param format
/// A printf style format string
//------------------------------------------------------------------
int Status::SetErrorStringWithFormat(const char *format, ...) {
// -------------------------------------------------------------------------
/// Return keyed value as bool
///
- /// @param[in] key
+ /// \param[in] key
/// The value of the key to lookup
///
- /// @param[out] value
+ /// \param[out] value
/// The value of the key as a bool. Undefined if the key doesn't
/// exist or if the key is not either true or false.
///
- /// @return
+ /// \return
/// true if the key existed as was a bool value; false otherwise.
/// Note the return value is *not* the value of the bool, use
/// \b value for that.
#include <vector>
//----------------------------------------------------------------------
-/// @class JSONGenerator JSONGenerator.h
+/// \class JSONGenerator JSONGenerator.h
/// A class which can construct structured data for the sole purpose
/// of printing it in JSON format.
///
//------------------------------------------------------------------
/// Return whether the os_log and activity tracing SPI is available.
///
- /// @return \b true if the activity stream support is available,
+ /// \return \b true if the activity stream support is available,
/// \b false otherwise.
//------------------------------------------------------------------
static bool IsSupported();
/// Return a log function suitable for DNBLog to use as the internal
/// logging function.
///
- /// @return a DNBLog-style logging function if IsSupported() returns
+ /// \return a DNBLog-style logging function if IsSupported() returns
/// true; otherwise, returns nullptr.
//------------------------------------------------------------------
static DNBCallbackLog GetLogFunction();
/// Runs the main loop.
///
- /// @return The exit code that the process should return.
+ /// \return The exit code that the process should return.
int MainLoop();
lldb::SBError ProcessArgs(const llvm::opt::InputArgList &args, bool &exiting);
namespace ptdecoder_private {
//----------------------------------------------------------------------
-/// @class Instruction
+/// \class Instruction
/// Represents an assembly instruction containing raw
/// instruction bytes, instruction address along with information
/// regarding execution flow context and Intel(R) Processor Trace
};
//---------------------------------------------------------------------------
-/// @class InstructionList
+/// \class InstructionList
/// Represents a list of assembly instructions. Each instruction is of
/// type Instruction.
//---------------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class TraceOptions
+/// \class TraceOptions
/// Provides Intel(R) Processor Trace specific configuration options and
/// other information obtained by decoding and post-processing the trace
/// data. Currently, this information comprises of the total number of
/// Get total number of assembly instructions obtained after decoding the
/// complete Intel(R) Processor Trace data obtained from LLDB.
///
- /// @return
+ /// \return
/// Total number of instructions.
//------------------------------------------------------------------
uint32_t getInstructionLogSize() const { return m_insn_log_size; }
//------------------------------------------------------------------
/// Set total number of assembly instructions.
///
- /// @param[in] size
+ /// \param[in] size
/// Value to be set.
//------------------------------------------------------------------
void setInstructionLogSize(uint32_t size) { m_insn_log_size = size; }
};
//----------------------------------------------------------------------
-/// @class Decoder
+/// \class Decoder
/// This class makes use of Intel(R) Processor Trace hardware feature
/// (implememted inside LLDB) to gather trace data for an inferior (being
/// debugged with LLDB) to provide meaningful information out of it.
namespace ptdecoder {
//----------------------------------------------------------------------
-/// @class PTInstruction
+/// \class PTInstruction
/// Represents an assembly instruction containing raw
/// instruction bytes, instruction address along with information
/// regarding execution flow context and Intel(R) Processor Trace
//------------------------------------------------------------------
/// Get raw bytes of the instruction in the buffer.
///
- /// @param[out] buf
+ /// \param[out] buf
/// The buffer where the raw bytes will be written. This buffer should be
/// allocated by the caller of this API. Providing an unallocated buffer
/// is an error. In case of errors, the content of the buffer is not
/// valid.
///
- /// @param[in] size
+ /// \param[in] size
/// Number of raw bytes to be written to @buf. Atleast @size bytes of
/// memory should be allocated to @buf otherwise the behaviour of the API
/// is undefined. Providing 0 for this argument is an error.
///
- /// @return
+ /// \return
/// Number of bytes of the instruction actually written to @buf if API
/// succeeds. In case of errors, total number of raw bytes of the
/// instruction is returned.
};
//---------------------------------------------------------------------------
-/// @class PTInstructionList
+/// \class PTInstructionList
/// Represents a list of assembly instructions. Each instruction is of
/// type PTInstruction.
//---------------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class PTTraceOptions
+/// \class PTTraceOptions
/// Provides configuration options like trace type, trace buffer size,
/// meta data buffer size along with other Intel(R) Processor Trace
/// specific options.
/// 64-bit unsigned integer in hex format. For "Name", please refer to
/// SBProcess::StartTrace API description for setting SBTraceOptions.
///
- /// @return
+ /// \return
/// A string formatted as json text {"Name":Value,"Name":Value}
//------------------------------------------------------------------
lldb::SBStructuredData GetTraceParams(lldb::SBError &error);
};
//----------------------------------------------------------------------
-/// @class PTDecoder
+/// \class PTDecoder
/// This class makes use of Intel(R) Processor Trace hardware feature
/// (implememted inside LLDB) to gather trace data for an inferior (being
/// debugged with LLDB) to provide meaningful information out of it.
/// Start Intel(R) Processor Trace on a thread or complete process with
/// Intel(R) Processor Trace specific configuration options
///
- /// @param[in] sbprocess
+ /// \param[in] sbprocess
/// A valid process on which this operation will be performed. An error is
/// returned in case of an invalid process.
///
- /// @param[in] sbtraceoptions
+ /// \param[in] sbtraceoptions
/// Contains thread id information and configuration options:
///
/// For tracing a single thread, provide a valid thread id. If sbprocess
/// be started by user. The actual used configuration options can be
/// obtained from GetProcessorTraceInfo() API.
///
- /// @param[out] sberror
+ /// \param[out] sberror
/// An error with the failure reason if API fails. Else success.
//------------------------------------------------------------------
void StartProcessorTrace(lldb::SBProcess &sbprocess,
//------------------------------------------------------------------
/// Stop Intel(R) Processor Trace on a thread or complete process.
///
- /// @param[in] sbprocess
+ /// \param[in] sbprocess
/// A valid process on which this operation will be performed. An error is
/// returned in case of an invalid process.
///
- /// @param[in] tid
+ /// \param[in] tid
/// Case 1: To stop tracing a single thread, provide a valid thread id. If
/// sbprocess doesn't contain the thread tid, error will be returned.
/// Case 2: To stop tracing complete process, use
/// lldb::LLDB_INVALID_THREAD_ID.
///
- /// @param[out] sberror
+ /// \param[out] sberror
/// An error with the failure reason if API fails. Else success.
//------------------------------------------------------------------
void StopProcessorTrace(lldb::SBProcess &sbprocess, lldb::SBError &sberror,
/// Get instruction log containing the execution flow for a thread of a
/// process in terms of assembly instructions executed.
///
- /// @param[in] sbprocess
+ /// \param[in] sbprocess
/// A valid process on which this operation will be performed. An error is
/// returned in case of an invalid process.
///
- /// @param[in] tid
+ /// \param[in] tid
/// A valid thread id of the thread for which instruction log is desired.
/// If sbprocess doesn't contain the thread tid, error will be returned.
///
- /// @param[in] count
+ /// \param[in] count
/// The number of instructions requested by the user to be returned from
/// the complete instruction log. Complete instruction log refers to all
/// the assembly instructions obtained after decoding the complete raw
/// The number of instructions actually returned are dependent on 'count'
/// and 'offset' parameters of this API.
///
- /// @param[in] offset
+ /// \param[in] offset
/// The offset in the complete instruction log from where 'count' number
/// of instructions are requested by the user. offset is counted from the
/// end of of this complete instruction log (which means the last executed
/// instruction is at offset 0 (zero)).
///
- /// @param[out] result_list
+ /// \param[out] result_list
/// Depending upon 'count' and 'offset' values, list will be overwritten
/// with the new instructions.
///
- /// @param[out] sberror
+ /// \param[out] sberror
/// An error with the failure reason if API fails. Else success.
//------------------------------------------------------------------
void GetInstructionLogAtOffset(lldb::SBProcess &sbprocess, lldb::tid_t tid,
/// process. The information contains the actual configuration options with
/// which the trace was started for this thread.
///
- /// @param[in] sbprocess
+ /// \param[in] sbprocess
/// A valid process on which this operation will be performed. An error is
/// returned in case of an invalid process.
///
- /// @param[in] tid
+ /// \param[in] tid
/// A valid thread id of the thread for which the trace specific
/// information is required. If sbprocess doesn't contain the thread tid,
/// an error will be returned.
///
- /// @param[out] options
+ /// \param[out] options
/// Contains actual configuration options (they may be different to the
/// ones with which tracing was asked to be started for this thread during
/// StartProcessorTrace() API call).
///
- /// @param[out] sberror
+ /// \param[out] sberror
/// An error with the failure reason if API fails. Else success.
//------------------------------------------------------------------
void GetProcessorTraceInfo(lldb::SBProcess &sbprocess, lldb::tid_t tid,
/// string is valid UTF8. If not, first call llvm::json::fixUTF8
/// before emplacing.
///
-/// @param[in] obj
+/// \param[in] obj
/// A JSON object that we will attempt to emplace the value in
///
-/// @param[in] key
+/// \param[in] key
/// The key to use when emplacing the value
///
-/// @param[in] str
+/// \param[in] str
/// The string to emplace
//------------------------------------------------------------------
void EmplaceSafeString(llvm::json::Object &obj, llvm::StringRef key,
//------------------------------------------------------------------
/// Extract simple values as a string.
///
-/// @param[in] value
+/// \param[in] value
/// A JSON value to extract the string from.
///
-/// @return
+/// \return
/// A llvm::StringRef that contains the string value, or an empty
/// string if \a value isn't a string.
//------------------------------------------------------------------
/// Extract the string value for the specified key from the
/// specified object.
///
-/// @param[in] obj
+/// \param[in] obj
/// A JSON object that we will attempt to extract the value from
///
-/// @param[in] key
+/// \param[in] key
/// The key to use when extracting the value
///
-/// @return
+/// \return
/// A llvm::StringRef that contains the string value for the
/// specified \a key, or an empty string if there is no key that
/// matches or if the value is not a string.
/// Extract the unsigned integer value for the specified key from
/// the specified object.
///
-/// @param[in] obj
+/// \param[in] obj
/// A JSON object that we will attempt to extract the value from
///
-/// @param[in] key
+/// \param[in] key
/// The key to use when extracting the value
///
-/// @return
+/// \return
/// The unsigned integer value for the specified \a key, or
/// \a fail_value if there is no key that matches or if the
/// value is not an integer.
/// Extract the boolean value for the specified key from the
/// specified object.
///
-/// @param[in] obj
+/// \param[in] obj
/// A JSON object that we will attempt to extract the value from
///
-/// @param[in] key
+/// \param[in] key
/// The key to use when extracting the value
///
-/// @return
+/// \return
/// The boolean value for the specified \a key, or \a fail_value
/// if there is no key that matches or if the value is not a
/// boolean value of an integer.
/// Extract the signed integer for the specified key from the
/// specified object.
///
-/// @param[in] obj
+/// \param[in] obj
/// A JSON object that we will attempt to extract the value from
///
-/// @param[in] key
+/// \param[in] key
/// The key to use when extracting the value
///
-/// @return
+/// \return
/// The signed integer value for the specified \a key, or
/// \a fail_value if there is no key that matches or if the
/// value is not an integer.
//------------------------------------------------------------------
/// Check if the specified key exists in the specified object.
///
-/// @param[in] obj
+/// \param[in] obj
/// A JSON object that we will attempt to extract the value from
///
-/// @param[in] key
+/// \param[in] key
/// The key to check for
///
-/// @return
+/// \return
/// \b True if the key exists in the \a obj, \b False otherwise.
//------------------------------------------------------------------
bool ObjectContainsKey(const llvm::json::Object &obj, llvm::StringRef key);
/// strings. Any NULL, array or objects values in the array will be
/// ignored.
///
-/// @param[in] obj
+/// \param[in] obj
/// A JSON object that we will attempt to extract the array from
///
-/// @param[in] key
+/// \param[in] key
/// The key to use when extracting the value
///
-/// @return
+/// \return
/// An array of string values for the specified \a key, or
/// \a fail_value if there is no key that matches or if the
/// value is not an array or all items in the array are not
/// \a request, "command" set to the "command" from \a request,
/// and "success" set to true.
///
-/// @param[in] request
+/// \param[in] request
/// The request object received from a call to VSCode::ReadJSON().
///
-/// @param[in,out] response
+/// \param[in,out] response
/// An empty llvm::json::Object object that will be filled
/// in as noted in description.
//------------------------------------------------------------------
/// the address of the type if it has an address.
///
///
-/// @param[in] v
+/// \param[in] v
/// A lldb::SBValue object to extract the string value from
///
///
-/// @param[in] object
+/// \param[in] object
/// The object to place the value object into
///
///
-/// @param[in] key
+/// \param[in] key
/// The key name to use when inserting the value object we create
//----------------------------------------------------------------------
void SetValueForKey(lldb::SBValue &v, llvm::json::Object &object,
/// Converts \a bp to a JSON value and appends all locations to the
/// \a breakpoints array.
///
-/// @param[in] bp
+/// \param[in] bp
/// A LLDB breakpoint object which will get all locations extracted
/// and converted into a JSON objects in the \a breakpoints array
///
-/// @param[in] breakpoints
+/// \param[in] breakpoints
/// A JSON array that will get a llvm::json::Value for \a bp
/// appended to it.
//----------------------------------------------------------------------
/// Converts breakpoint location to a Visual Studio Code "Breakpoint"
/// JSON object and appends it to the \a breakpoints array.
///
-/// @param[in] bp_loc
+/// \param[in] bp_loc
/// A LLDB breakpoint location object to convert into a JSON value
///
-/// @return
+/// \return
/// A "Breakpoint" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// Create a "Event" JSON object using \a event_name as the event name
///
-/// @param[in] event_name
+/// \param[in] event_name
/// The string value to use for the "event" key in the JSON object.
///
-/// @return
+/// \return
/// A "Event" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// Create a "ExceptionBreakpointsFilter" JSON object as described in
/// the Visual Studio Code debug adaptor definition.
///
-/// @param[in] bp
+/// \param[in] bp
/// The exception breakppoint object to use
///
-/// @return
+/// \return
/// A "ExceptionBreakpointsFilter" JSON object with that follows
/// the formal JSON definition outlined by Microsoft.
//----------------------------------------------------------------------
/// Create a "Scope" JSON object as described in the Visual Studio Code
/// debug adaptor definition.
///
-/// @param[in] name
+/// \param[in] name
/// The value to place into the "name" key
//
-/// @param[in] variablesReference
+/// \param[in] variablesReference
/// The value to place into the "variablesReference" key
//
-/// @param[in] namedVariables
+/// \param[in] namedVariables
/// The value to place into the "namedVariables" key
//
-/// @param[in] expensive
+/// \param[in] expensive
/// The value to place into the "expensive" key
///
-/// @return
+/// \return
/// A "Scope" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// Create a "Source" JSON object as described in the Visual Studio Code
/// debug adaptor definition.
///
-/// @param[in] line_entry
+/// \param[in] line_entry
/// The LLDB line table to use when populating out the "Source"
/// object
///
-/// @return
+/// \return
/// A "Source" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// within the source referred to by "sourceReference" will be filled
/// in.
///
-/// @param[in] frame
+/// \param[in] frame
/// The LLDB stack frame to use when populating out the "Source"
/// object.
///
-/// @param[out] disasm_line
+/// \param[out] disasm_line
/// The line within the "sourceReference" file that the PC from
/// \a frame matches.
///
-/// @return
+/// \return
/// A "Source" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// "line" - the source file line number as an integer
/// "column" - the source file column number as an integer
///
-/// @param[in] frame
+/// \param[in] frame
/// The LLDB stack frame to use when populating out the "StackFrame"
/// object.
///
-/// @return
+/// \return
/// A "StackFrame" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// thread index ID along with the string name of the thread
/// from the OS if it has a name.
///
-/// @param[in] thread
+/// \param[in] thread
/// The LLDB thread to use when populating out the "Thread"
/// object.
///
-/// @return
+/// \return
/// A "Thread" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// "allThreadsStopped" - set to True to indicate that all threads
/// stop when any thread stops.
///
-/// @param[in] thread
+/// \param[in] thread
/// The LLDB thread to use when populating out the "StoppedEvent"
/// object.
///
-/// @return
+/// \return
/// A "StoppedEvent" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// "evaluateName" - The name of the variable to use in expressions
/// as a string.
///
-/// @param[in] v
+/// \param[in] v
/// The LLDB value to use when populating out the "Variable"
/// object.
///
-/// @param[in] variablesReference
+/// \param[in] variablesReference
/// The variable reference. Zero if this value isn't structured
/// and has no children, non-zero if it does have children and
/// might be asked to expand itself.
///
-/// @param[in] varID
+/// \param[in] varID
/// A unique variable identifier to help in properly identifying
/// variables with the same name. This is an extension to the
/// VS protocol.
///
-/// @param[in] format_hex
+/// \param[in] format_hex
/// It set to true the variable will be formatted as hex in
/// the "value" key value pair for the value of the variable.
///
-/// @return
+/// \return
/// A "Variable" JSON object with that follows the formal JSON
/// definition outlined by Microsoft.
//----------------------------------------------------------------------
/// All output from every command, including the prompt + the command
/// is placed into the "strm" argument.
///
-/// @param[in] prefix
+/// \param[in] prefix
/// A string that will be printed into \a strm prior to emitting
/// the prompt + command and command output. Can be NULL.
///
-/// @param[in] commands
+/// \param[in] commands
/// An array of LLDB commands to execute.
///
-/// @param[in] strm
+/// \param[in] strm
/// The stream that will receive the prefix, prompt + command and
/// all command output.
//----------------------------------------------------------------------
/// All output from every command, including the prompt + the command
/// is returned in the std::string return value.
///
-/// @param[in] prefix
+/// \param[in] prefix
/// A string that will be printed into \a strm prior to emitting
/// the prompt + command and command output. Can be NULL.
///
-/// @param[in] commands
+/// \param[in] commands
/// An array of LLDB commands to execute.
///
-/// @return
+/// \return
/// A std::string that contains the prefix and all commands and
/// command output
//----------------------------------------------------------------------
///----------------------------------------------------------------------
/// Check if a thread has a stop reason.
///
-/// @param[in] thread
+/// \param[in] thread
/// The LLDB thread object to check
///
-/// @return
+/// \return
/// \b True if the thread has a valid stop reason, \b false
/// otherwise.
//----------------------------------------------------------------------
/// index in the lower 32 bits and the thread index ID in the upper 32
/// bits.
///
-/// @param[in] frame
+/// \param[in] frame
/// The LLDB stack frame object generate the ID for
///
-/// @return
+/// \return
/// A unique integer that allows us to easily find the right
/// stack frame within a thread on subsequent VS code requests.
//----------------------------------------------------------------------
/// index in the lower THREAD_INDEX_SHIFT bits and the thread index ID in
/// the upper 32 - THREAD_INDEX_SHIFT bits.
///
-/// @param[in] dap_frame_id
+/// \param[in] dap_frame_id
/// The VSCode frame ID to convert to a thread index ID.
///
-/// @return
+/// \return
/// The LLDB thread index ID.
//----------------------------------------------------------------------
uint32_t GetLLDBThreadIndexID(uint64_t dap_frame_id);
/// index in the lower THREAD_INDEX_SHIFT bits and the thread index ID in
/// the upper 32 - THREAD_INDEX_SHIFT bits.
///
-/// @param[in] dap_frame_id
+/// \param[in] dap_frame_id
/// The VSCode frame ID to convert to a frame ID.
///
-/// @return
+/// \return
/// The LLDB frame index ID.
//----------------------------------------------------------------------
uint32_t GetLLDBFrameID(uint64_t dap_frame_id);
/// breakpoint ID in the lower BREAKPOINT_ID_SHIFT bits and the
/// breakpoint location ID in the upper BREAKPOINT_ID_SHIFT bits.
///
-/// @param[in] frame
+/// \param[in] frame
/// The LLDB stack frame object generate the ID for
///
-/// @return
+/// \return
/// A unique integer that allows us to easily find the right
/// stack frame within a thread on subsequent VS code requests.
//----------------------------------------------------------------------
/// breakpoint ID in the lower BREAKPOINT_ID_SHIFT bits and the
/// breakpoint location ID in the upper BREAKPOINT_ID_SHIFT bits.
///
-/// @param[in] dap_breakpoint_id
+/// \param[in] dap_breakpoint_id
/// The VSCode breakpoint ID to convert to an LLDB breakpoint ID.
///
-/// @return
+/// \return
/// The LLDB breakpoint ID.
//----------------------------------------------------------------------
uint32_t GetLLDBBreakpointID(uint64_t dap_breakpoint_id);
/// breakpoint ID in the lower BREAKPOINT_ID_SHIFT bits and the
/// breakpoint location ID in the upper BREAKPOINT_ID_SHIFT bits.
///
-/// @param[in] dap_breakpoint_id
+/// \param[in] dap_breakpoint_id
/// The VSCode frame ID to convert to a breakpoint location ID.
///
-/// @return
+/// \return
/// The LLDB breakpoint location ID.
//----------------------------------------------------------------------
uint32_t GetLLDBBreakpointLocationID(uint64_t dap_breakpoint_id);
projects / platform / upstream / llvm.git / commitdiff