# comments will behave just like regular Qt-style comments
# (thus requiring an explicit @brief command for a brief description.)
-JAVADOC_AUTOBRIEF = NO
+JAVADOC_AUTOBRIEF = YES
# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
# interpret the first line (until the first dot) of a Qt-style
# will behave just like regular Qt-style comments (thus requiring
# an explicit \brief command for a brief description.)
-QT_AUTOBRIEF = NO
+QT_AUTOBRIEF = YES
# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
# treat a multi-line C++ special comment block (i.e. a block of //! or ///
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h"
-/// @brief Class that manages logical breakpoint setting.
+/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" Class that
+/// manages logical breakpoint setting.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// A breakpoint has four main parts, a filter, a resolver, the list of
/// breakpoint
/// locations that have been determined for the filter/resolver pair, and
-/// finally
-/// a set of options for the breakpoint.
+/// finally a set of options for the breakpoint.
///
/// \b Filter:
-/// This is an object derived from SearchFilter. It manages the search
-/// for breakpoint location matches through the symbols in the module list of
-/// the target
-/// that owns it. It also filters out locations based on whatever logic it
-/// wants.
+/// This is an object derived from SearchFilter. It manages the search for
+/// breakpoint location matches through the symbols in the module list of the
+/// target that owns it. It also filters out locations based on whatever
+/// logic it wants.
///
/// \b Resolver:
-/// This is an object derived from BreakpointResolver. It provides a
-/// callback to the filter that will find breakpoint locations. How it does
-/// this is
+/// This is an object derived from BreakpointResolver. It provides a callback
+/// to the filter that will find breakpoint locations. How it does this is
/// determined by what kind of resolver it is.
///
/// The Breakpoint class also provides constructors for the common breakpoint
-/// cases
-/// which make the appropriate filter and resolver for you.
+/// cases which make the appropriate filter and resolver for you.
///
/// \b Location List:
-/// This stores the breakpoint locations that have been determined
-/// to date. For a given breakpoint, there will be only one location with a
-/// given
-/// address. Adding a location at an already taken address will just return the
-/// location
-/// already at that address. Locations can be looked up by ID, or by address.
+/// This stores the breakpoint locations that have been determined to date.
+/// For a given breakpoint, there will be only one location with a given
+/// address. Adding a location at an already taken address will just return
+/// the location already at that address. Locations can be looked up by ID,
+/// or by address.
///
/// \b Options:
/// This includes:
/// \b Callback
/// \b Condition
/// Note, these options can be set on the breakpoint, and they can also be set
-/// on the
-/// individual locations. The options set on the breakpoint take precedence
-/// over the
-/// options set on the individual location.
-/// So for instance disabling the breakpoint will cause NONE of the locations to
-/// get hit.
-/// But if the breakpoint is enabled, then the location's enabled state will be
-/// checked
-/// to determine whether to insert that breakpoint location.
+/// on the individual locations. The options set on the breakpoint take
+/// precedence over the options set on the individual location. So for
+/// instance disabling the breakpoint will cause NONE of the locations to get
+/// hit. But if the breakpoint is enabled, then the location's enabled state
+/// will be checked to determine whether to insert that breakpoint location.
/// Similarly, if the breakpoint condition says "stop", we won't check the
-/// location's condition.
-/// But if the breakpoint condition says "continue", then we will check the
-/// location for whether
-/// to actually stop or not.
-/// One subtle point worth observing here is that you don't actually stop at a
-/// Breakpoint, you
-/// always stop at one of its locations. So the "should stop" tests are done by
-/// the location,
-/// not by the breakpoint.
+/// location's condition. But if the breakpoint condition says "continue",
+/// then we will check the location for whether to actually stop or not. One
+/// subtle point worth observing here is that you don't actually stop at a
+/// Breakpoint, you always stop at one of its locations. So the "should stop"
+/// tests are done by the location, not by the breakpoint.
//----------------------------------------------------------------------
class Breakpoint : public std::enable_shared_from_this<Breakpoint>,
public Stoppoint {
static const ConstString &GetEventIdentifier();
//------------------------------------------------------------------
- /// An enum specifying the match style for breakpoint settings. At
- /// present only used for function name style breakpoints.
+ /// An enum specifying the match style for breakpoint settings. At present
+ /// only used for function name style breakpoints.
//------------------------------------------------------------------
typedef enum { Exact, Regexp, Glob } MatchType;
//------------------------------------------------------------------
/// Destructor.
///
- /// The destructor is not virtual since there should be no reason to subclass
- /// breakpoints. The varieties of breakpoints are specified instead by
- /// providing different resolvers & filters.
+ /// The destructor is not virtual since there should be no reason to
+ /// subclass breakpoints. The varieties of breakpoints are specified
+ /// instead by providing different resolvers & filters.
//------------------------------------------------------------------
~Breakpoint() override;
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// 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 clear all its breakpoint sites. Done
- /// when the process holding the breakpoint sites is destroyed.
+ /// Tell this breakpoint to clear all its breakpoint sites. Done when the
+ /// process holding the breakpoint sites is destroyed.
//------------------------------------------------------------------
void ClearAllBreakpointSites();
void ResolveBreakpoint();
//------------------------------------------------------------------
- /// Tell this breakpoint to scan a given module list and resolve any
- /// new locations that match the breakpoint's specifications.
+ /// Tell this breakpoint to scan a given module list and resolve any new
+ /// locations that match the breakpoint's specifications.
///
/// @param[in] module_list
/// The list of modules to look in for new locations.
bool send_event = true);
//------------------------------------------------------------------
- /// Tell this breakpoint to scan a given module list and resolve any
- /// new locations that match the breakpoint's specifications.
+ /// Tell this breakpoint to scan a given module list and resolve any new
+ /// locations that match the breakpoint's specifications.
///
/// @param[in] changed_modules
/// The list of modules to look in for new locations.
bool delete_locations = false);
//------------------------------------------------------------------
- /// Tells the breakpoint the old module \a old_module_sp has been
- /// replaced by new_module_sp (usually because the underlying file has been
- /// rebuilt, and the old version is gone.)
+ /// Tells the breakpoint the old module \a old_module_sp has been replaced
+ /// by new_module_sp (usually because the underlying file has been rebuilt,
+ /// and the old version is gone.)
///
/// @param[in] old_module_sp
/// The old module that is going away.
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// 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?
+ /// 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
/// The Address specifying the new location.
/// Removes all invalid breakpoint locations.
///
/// Removes all breakpoint locations with architectures that aren't
- /// compatible with \a arch. Also remove any breakpoint locations
- /// with whose locations have address where the section has been
- /// deleted (module and object files no longer exist).
+ /// compatible with \a arch. Also remove any breakpoint locations with whose
+ /// locations have address where the section has been deleted (module and
+ /// object files no longer exist).
///
- /// This is typically used after the process calls exec, or anytime
- /// the architecture of the target changes.
+ /// This is typically used after the process calls exec, or anytime the
+ /// architecture of the target changes.
///
/// @param[in] arch
/// If valid, check the module in each breakpoint to make sure
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;
bool IsOneShot() const;
//------------------------------------------------------------------
- /// If \a auto_continue is \b true, breakpoint will auto-continue when on hit.
+ /// If \a auto_continue is \b true, breakpoint will auto-continue when on
+ /// hit.
//------------------------------------------------------------------
void SetAutoContinue(bool auto_continue);
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// Return the number of breakpoint locations that have resolved to
- /// actual breakpoint sites.
+ /// Return the number of breakpoint locations that have resolved to actual
+ /// breakpoint sites.
///
/// @return
/// The number locations resolved breakpoint sites.
//------------------------------------------------------------------
/// Set the "kind" description for a breakpoint. If the breakpoint is hit
- /// the stop info will show this "kind" description instead of the breakpoint
- /// number. Mostly useful for internal breakpoints, where the breakpoint
- /// number
- /// doesn't have meaning to the user.
+ /// the stop info will show this "kind" description instead of the
+ /// breakpoint number. Mostly useful for internal breakpoints, where the
+ /// breakpoint number doesn't have meaning to the user.
///
/// @param[in] kind
/// New "kind" description.
//------------------------------------------------------------------
/// Find breakpoint locations which match the (filename, line_number)
- /// description.
- /// The breakpoint location collection is to be filled with the matching
- /// locations.
- /// It should be initialized with 0 size by the API client.
+ /// description. The breakpoint location collection is to be filled with the
+ /// matching locations. It should be initialized with 0 size by the API
+ /// client.
///
/// @return
/// True if there is a match
/// Set a pre-condition filter that overrides all user provided
/// filters/callbacks etc.
///
- /// Used to define fancy breakpoints that can do dynamic hit detection without
- /// taking up the condition slot -
- /// which really belongs to the user anyway...
+ /// Used to define fancy breakpoints that can do dynamic hit detection
+ /// without taking up the condition slot - which really belongs to the user
+ /// anyway...
///
- /// The Precondition should not continue the target, it should return true if
- /// the condition says to stop and
- /// false otherwise.
+ /// The Precondition should not continue the target, it should return true
+ /// if the condition says to stop and false otherwise.
///
//------------------------------------------------------------------
void SetPrecondition(BreakpointPreconditionSP precondition_sp) {
//------------------------------------------------------------------
/// Constructors and Destructors
/// Only the Target can make a breakpoint, and it owns the breakpoint
- /// lifespans.
- /// The constructor takes a filter and a resolver. Up in Target there are
- /// convenience
- /// variants that make breakpoints for some common cases.
+ /// lifespans. The constructor takes a filter and a resolver. Up in Target
+ /// there are convenience variants that make breakpoints for some common
+ /// cases.
///
/// @param[in] target
/// The target in which the breakpoint will be set.
//----------------------------------------------------------------------
/// @class BreakpointList BreakpointList.h "lldb/Breakpoint/BreakpointList.h"
-/// @brief This class manages a list of breakpoints.
+/// This class manages a list of breakpoints.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
lldb::BreakpointSP GetBreakpointAtIndex(size_t i);
//------------------------------------------------------------------
- /// Returns a shared pointer to the breakpoint with index \a i, const version
+ /// Returns a shared pointer to the breakpoint with index \a i, const
+ /// version
///
/// @param[in] i
/// The breakpoint index to seek for.
//------------------------------------------------------------------
/// Removes all invalid breakpoint locations.
///
- /// Removes all breakpoint locations in the list with architectures
- /// that aren't compatible with \a arch. Also remove any breakpoint
- /// locations with whose locations have address where the section
- /// has been deleted (module and object files no longer exist).
+ /// Removes all breakpoint locations in the list with architectures that
+ /// aren't compatible with \a arch. Also remove any breakpoint locations
+ /// with whose locations have address where the section has been deleted
+ /// (module and object files no longer exist).
///
- /// This is typically used after the process calls exec, or anytime
- /// the architecture of the target changes.
+ /// This is typically used after the process calls exec, or anytime the
+ /// architecture of the target changes.
///
/// @param[in] arch
/// If valid, check the module in each breakpoint to make sure
//------------------------------------------------------------------
/// Removes all the breakpoints from this list - first checking the
- /// ePermDelete on the breakpoints. This call should be used unless you
- /// are shutting down and need to actually clear them all.
+ /// ePermDelete on the breakpoints. This call should be used unless you are
+ /// shutting down and need to actually clear them all.
//------------------------------------------------------------------
void RemoveAllowed(bool notify);
//----------------------------------------------------------------------
/// @class BreakpointLocation BreakpointLocation.h
-/// "lldb/Breakpoint/BreakpointLocation.h"
-/// @brief Class that manages one unique (by address) instance of a logical
-/// breakpoint.
+/// "lldb/Breakpoint/BreakpointLocation.h" Class that manages one unique (by
+/// address) instance of a logical breakpoint.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// General Outline:
/// A breakpoint location is defined by the breakpoint that produces it,
-/// and the address that resulted in this particular instantiation.
-/// Each breakpoint location also may have a breakpoint site if its
-/// address has been loaded into the program.
-/// Finally it has a settable options object.
+/// and the address that resulted in this particular instantiation. Each
+/// breakpoint location also may have a breakpoint site if its address has
+/// been loaded into the program. Finally it has a settable options object.
///
/// FIXME: Should we also store some fingerprint for the location, so
-/// we can map one location to the "equivalent location" on rerun? This
-/// would be useful if you've set options on the locations.
+/// we can map one location to the "equivalent location" on rerun? This would
+/// be useful if you've set options on the locations.
//----------------------------------------------------------------------
class BreakpointLocation
~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();
Target &GetTarget();
//------------------------------------------------------------------
- /// Determines whether we should stop due to a hit at this
- /// breakpoint location.
+ /// Determines whether we should stop due to a hit at this breakpoint
+ /// location.
///
- /// Side Effects: This may evaluate the breakpoint condition, and
- /// run the callback. So this command may do a considerable amount
- /// of work.
+ /// Side Effects: This may evaluate the breakpoint condition, and run the
+ /// callback. So this command may do a considerable amount of work.
///
/// @return
/// \b true if this breakpoint location thinks we should stop,
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// If \a enable is \b true, enable the breakpoint, if \b false
- /// disable it.
+ /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
//------------------------------------------------------------------
void SetEnabled(bool enabled);
//------------------------------------------------------------------
/// Set the callback action invoked when the breakpoint is hit.
///
- /// The callback will return a bool indicating whether the target
- /// should stop at this breakpoint or not.
+ /// The callback will return a bool indicating whether the target should
+ /// stop at this breakpoint or not.
///
/// @param[in] callback
/// The method that will get called when the breakpoint is hit.
bool ResolveBreakpointSite();
//------------------------------------------------------------------
- /// Clear this breakpoint location's breakpoint site - for instance
- /// when disabling the breakpoint.
+ /// Clear this breakpoint location's breakpoint site - for instance when
+ /// disabling the breakpoint.
///
/// @return
/// \b true if there was a breakpoint site to be cleared, \b false
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.
+ /// Print a description of this breakpoint location to the stream \a s.
///
/// @param[in] s
/// The stream to which to print the description.
//------------------------------------------------------------------
/// Use this to set location specific breakpoint options.
///
- /// It will create a copy of the containing breakpoint's options if
- /// that hasn't been done already
+ /// It will create a copy of the containing breakpoint's options if that
+ /// hasn't been done already
///
/// @return
/// A pointer to the breakpoint options.
//------------------------------------------------------------------
/// Returns whether we should resolve Indirect functions in setting the
- /// breakpoint site
- /// for this location.
+ /// breakpoint site for this location.
///
/// @return
/// \b true if the breakpoint SITE for this location should be set on the
//------------------------------------------------------------------
/// Returns whether the address set in the breakpoint site for this location
- /// was found by resolving
- /// an indirect symbol.
+ /// was found by resolving an indirect symbol.
///
/// @return
/// \b true or \b false as given in the description above.
//------------------------------------------------------------------
/// Returns whether the address set in the breakpoint location was re-routed
- /// to the target of a
- /// re-exported symbol.
+ /// to the target of a re-exported symbol.
///
/// @return
/// \b true or \b false as given in the description above.
//------------------------------------------------------------------
/// Returns whether the two breakpoint locations might represent "equivalent
- /// locations".
- /// This is used when modules changed to determine if a Location in the old
- /// module might
- /// be the "same as" the input location.
+ /// 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
/// The location to compare against.
//----------------------------------------------------------------------
/// @class BreakpointLocationList BreakpointLocationList.h
-/// "lldb/Breakpoint/BreakpointLocationList.h"
-/// @brief 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.
+/// "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.
//----------------------------------------------------------------------
-
class BreakpointLocationList {
// Only Breakpoints can make the location list, or add elements to it. This
// is not just some random collection of locations. Rather, the act of
void Dump(Stream *s) const;
//------------------------------------------------------------------
- /// Returns a shared pointer to the breakpoint location at address
- /// \a addr - const version.
+ /// Returns a shared pointer to the breakpoint location at address \a addr -
+ /// const version.
///
/// @param[in] addr
/// The address to look for.
const lldb::BreakpointLocationSP FindByAddress(const Address &addr) const;
//------------------------------------------------------------------
- /// Returns a shared pointer to the breakpoint location with id
- /// \a breakID, const version.
+ /// Returns a shared pointer to the breakpoint location with id \a breakID,
+ /// const version.
///
/// @param[in] breakID
/// The breakpoint location ID to seek for.
lldb::BreakpointLocationSP FindByID(lldb::break_id_t breakID) const;
//------------------------------------------------------------------
- /// Returns the breakpoint location id to the breakpoint location
- /// at address \a addr.
+ /// Returns the breakpoint location id to the breakpoint location at address
+ /// \a addr.
///
/// @param[in] addr
/// The address to match.
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.
+ /// 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
/// The module to seek in.
BreakpointLocationCollection &bp_loc_list);
//------------------------------------------------------------------
- /// Returns a shared pointer to the breakpoint location with
- /// index \a i.
+ /// Returns a shared pointer to the breakpoint location with index \a i.
///
/// @param[in] i
/// The breakpoint location index to seek for.
lldb::BreakpointLocationSP GetByIndex(size_t i);
//------------------------------------------------------------------
- /// Returns a shared pointer to the breakpoint location with index
- /// \a i, const version.
+ /// Returns a shared pointer to the breakpoint location with index \a i,
+ /// const version.
///
/// @param[in] i
/// The breakpoint location index to seek for.
const lldb::BreakpointLocationSP GetByIndex(size_t i) const;
//------------------------------------------------------------------
- /// Removes all the locations in this list from their breakpoint site
- /// owners list.
+ /// Removes all the locations in this list from their breakpoint site owners
+ /// list.
//------------------------------------------------------------------
void ClearAllBreakpointSites();
//------------------------------------------------------------------
- /// Tells all the breakpoint locations in this list to attempt to
- /// resolve any possible breakpoint sites.
+ /// Tells all the breakpoint locations in this list to attempt to resolve
+ /// any possible breakpoint sites.
//------------------------------------------------------------------
void ResolveAllBreakpointSites();
//------------------------------------------------------------------
- /// Returns the number of breakpoint locations in this list with
- /// resolved breakpoints.
+ /// Returns the number of breakpoint locations in this list with resolved
+ /// breakpoints.
///
/// @result
/// Number of qualifying breakpoint locations.
uint32_t GetHitCount() const;
//------------------------------------------------------------------
- /// Enquires of the breakpoint location in this list with ID \a
- /// breakID whether we should stop.
+ /// Enquires of the breakpoint location in this list with ID \a breakID
+ /// whether we should stop.
///
/// @param[in] context
/// This contains the information about this stop.
size_t GetSize() const { return m_locations.size(); }
//------------------------------------------------------------------
- /// Print a description of the breakpoint locations in this list to
- /// the stream \a s.
+ /// Print a description of the breakpoint locations in this list to the
+ /// stream \a s.
///
/// @param[in] s
/// The stream to which to print the description.
//------------------------------------------------------------------
/// This is the standard constructor.
///
- /// It creates an empty breakpoint location list. It is protected
- /// here because only Breakpoints are allowed to create the
- /// breakpoint location list.
+ /// It creates an empty breakpoint location list. It is protected here
+ /// because only Breakpoints are allowed to create the breakpoint location
+ /// list.
//------------------------------------------------------------------
BreakpointLocationList(Breakpoint &owner);
//----------------------------------------------------------------------
/// @class BreakpointOptions BreakpointOptions.h
-/// "lldb/Breakpoint/BreakpointOptions.h"
-/// @brief Class that manages the options on a breakpoint or breakpoint
-/// location.
+/// "lldb/Breakpoint/BreakpointOptions.h" Class that manages the options on a
+/// breakpoint or breakpoint location.
//----------------------------------------------------------------------
class BreakpointOptions {
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// This constructor allows you to specify all the breakpoint options
- /// except the callback. That one is more complicated, and better
- /// to do by hand.
+ /// 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
/// The expression which if it evaluates to \b true if we are to stop
bool auto_continue = false);
//------------------------------------------------------------------
- /// Breakpoints make options with all flags set. Locations and Names make options
- /// with no flags set.
+ /// Breakpoints make options with all flags set. Locations and Names make
+ /// options with no flags set.
//------------------------------------------------------------------
BreakpointOptions(bool all_flags_set);
BreakpointOptions(const BreakpointOptions &rhs);
//------------------------------------------------------------------
/// Return the current thread spec for this option. This will return nullptr
- /// if the no thread
- /// specifications have been set for this Option yet.
+ /// if the no thread specifications have been set for this Option yet.
/// @return
/// The thread specification pointer for this option, or nullptr if none
/// has
const ThreadSpec *GetThreadSpecNoCreate() const;
//------------------------------------------------------------------
- /// Returns a pointer to the ThreadSpec for this option, creating it.
- /// if it hasn't been created already. This API is used for setting the
+ /// Returns a pointer to the ThreadSpec for this option, creating it. if it
+ /// hasn't been created already. This API is used for setting the
/// ThreadSpec items for this option.
//------------------------------------------------------------------
ThreadSpec *GetThreadSpec();
lldb::user_id_t break_loc_id);
//------------------------------------------------------------------
- /// Set a callback based on BreakpointOptions::CommandData.
- /// @param[in] cmd_data
+ /// 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.
//------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class BreakpointResolver BreakpointResolver.h
-/// "lldb/Breakpoint/BreakpointResolver.h"
-/// @brief This class works with SearchFilter to resolve logical breakpoints to
-/// their
-/// of concrete breakpoint locations.
+/// "lldb/Breakpoint/BreakpointResolver.h" This class works with SearchFilter
+/// to resolve logical breakpoints to their of concrete breakpoint locations.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// General Outline:
-/// The BreakpointResolver is a Searcher. In that protocol,
-/// the SearchFilter asks the question "At what depth of the symbol context
-/// descent do you want your callback to get called?" of the filter. The
-/// resolver
-/// answers this question (in the GetDepth method) and provides the resolution
-/// callback.
+/// The BreakpointResolver is a Searcher. In that protocol, the SearchFilter
+/// asks the question "At what depth of the symbol context descent do you want
+/// your callback to get called?" of the filter. The resolver answers this
+/// question (in the GetDepth method) and provides the resolution callback.
/// Each Breakpoint has a BreakpointResolver, and it calls either
-/// ResolveBreakpoint
-/// or ResolveBreakpointInModules to tell it to look for new breakpoint
-/// locations.
+/// ResolveBreakpoint or ResolveBreakpointInModules to tell it to look for new
+/// breakpoint locations.
//----------------------------------------------------------------------
class BreakpointResolver : public Searcher {
//------------------------------------------------------------------
/// The breakpoint resolver need to have a breakpoint for "ResolveBreakpoint
/// to make sense. It can be constructed without a breakpoint, but you have
- /// to
- /// call SetBreakpoint before ResolveBreakpoint.
+ /// to call SetBreakpoint before ResolveBreakpoint.
///
/// @param[in] bkpt
/// The breakpoint that owns this resolver.
void SetBreakpoint(Breakpoint *bkpt);
//------------------------------------------------------------------
- /// This updates the offset for this breakpoint. All the locations currently
- /// set for this breakpoint will have their offset adjusted when this is
- /// called.
+ /// This updates the offset for this breakpoint. All the locations
+ /// currently set for this breakpoint will have their offset adjusted when
+ /// this is called.
///
/// @param[in] offset
/// The offset to add to all locations.
void SetOffset(lldb::addr_t offset);
//------------------------------------------------------------------
- /// This updates the offset for this breakpoint. All the locations currently
- /// set for this breakpoint will have their offset adjusted when this is
- /// called.
+ /// This updates the offset for this breakpoint. All the locations
+ /// currently set for this breakpoint will have their offset adjusted when
+ /// this is called.
///
/// @param[in] offset
/// The offset to add to all locations.
//------------------------------------------------------------------
/// In response to this method the resolver scans all the modules in the
- /// breakpoint's
- /// target, and adds any new locations it finds.
+ /// breakpoint's target, and adds any new locations it finds.
///
/// @param[in] filter
/// The filter that will manage the search for this resolver.
//------------------------------------------------------------------
/// In response to this method the resolver scans the modules in the module
- /// list
- /// \a modules, and adds any new locations it finds.
+ /// list \a modules, and adds any new locations it finds.
///
/// @param[in] filter
/// The filter that will manage the search for this resolver.
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// An enumeration for keeping track of the concrete subclass that
- /// is actually instantiated. Values of this enumeration are kept in the
+ /// An enumeration for keeping track of the concrete subclass that is
+ /// actually instantiated. Values of this enumeration are kept in the
/// BreakpointResolver's SubclassID field. They are used for concrete type
/// identification.
enum ResolverTy {
protected:
//------------------------------------------------------------------
- /// SetSCMatchesByLine - Takes a symbol context list of matches which
- /// supposedly represent the same file and
- /// line number in a CU, and find the nearest actual line number that matches,
- /// and then filter down the
- /// matching addresses to unique entries, and skip the prologue if asked to do
- /// so, and then set
+ /// Takes a symbol context list of matches which supposedly represent the
+ /// same file and line number in a CU, and find the nearest actual line
+ /// number that matches, and then filter down the matching addresses to
+ /// unique entries, and skip the prologue if asked to do so, and then set
/// breakpoint locations in this breakpoint for all the resultant addresses.
void SetSCMatchesByLine(SearchFilter &filter, SymbolContextList &sc_list,
bool skip_prologue, llvm::StringRef log_ident);
//----------------------------------------------------------------------
/// @class BreakpointResolverAddress BreakpointResolverAddress.h
-/// "lldb/Breakpoint/BreakpointResolverAddress.h"
-/// @brief This class sets breakpoints on a given Address. This breakpoint only
-/// takes
-/// once, and then it won't attempt to reset itself.
+/// "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.
//----------------------------------------------------------------------
class BreakpointResolverAddress : public BreakpointResolver {
//----------------------------------------------------------------------
/// @class BreakpointResolverFileLine BreakpointResolverFileLine.h
-/// "lldb/Breakpoint/BreakpointResolverFileLine.h"
-/// @brief This class sets breakpoints by file and line. Optionally, it will
-/// look for inlined
-/// instances of the file and line specification.
+/// "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.
//----------------------------------------------------------------------
class BreakpointResolverFileLine : public BreakpointResolver {
//----------------------------------------------------------------------
/// @class BreakpointResolverFileRegex BreakpointResolverFileRegex.h
-/// "lldb/Breakpoint/BreakpointResolverFileRegex.h"
-/// @brief This class sets breakpoints by file and line. Optionally, it will
-/// look for inlined
+/// "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.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class BreakpointResolverName BreakpointResolverName.h
-/// "lldb/Breakpoint/BreakpointResolverName.h"
-/// @brief This class sets breakpoints on a given function name, either by exact
-/// match
-/// or by regular expression.
+/// "lldb/Breakpoint/BreakpointResolverName.h" This class sets breakpoints on
+/// a given function name, either by exact match or by regular expression.
//----------------------------------------------------------------------
class BreakpointResolverName : public BreakpointResolver {
//----------------------------------------------------------------------
/// @class BreakpointSite BreakpointSite.h "lldb/Breakpoint/BreakpointSite.h"
-/// @brief Class that manages the actual breakpoint that will be inserted
-/// into the running program.
+/// Class that manages the actual breakpoint that will be inserted into the
+/// running program.
///
-/// The BreakpointSite class handles the physical breakpoint that is
-/// actually inserted in the target program. As such, it is also the
-/// one that gets hit, when the program stops. It keeps a list of all
-/// BreakpointLocations that share this physical site. When the
-/// breakpoint is hit, all the locations are informed by the breakpoint
-/// site. Breakpoint sites are owned by the process.
+/// The BreakpointSite class handles the physical breakpoint that is actually
+/// inserted in the target program. As such, it is also the one that gets
+/// hit, when the program stops. It keeps a list of all BreakpointLocations
+/// that share this physical site. When the breakpoint is hit, all the
+/// locations are informed by the breakpoint site. Breakpoint sites are owned
+/// by the process.
//----------------------------------------------------------------------
class BreakpointSite : public std::enable_shared_from_this<BreakpointSite>,
/// Tells whether the current breakpoint site is enabled or not
///
/// This is a low-level enable bit for the breakpoint sites. If a
- /// breakpoint site has no enabled owners, it should just get
- /// removed. This enable/disable is for the low-level target code
- /// to enable and disable breakpoint sites when single stepping,
- /// etc.
+ /// breakpoint site has no enabled owners, it should just get removed. This
+ /// enable/disable is for the low-level target code to enable and disable
+ /// breakpoint sites when single stepping, etc.
//------------------------------------------------------------------
bool IsEnabled() const;
//------------------------------------------------------------------
/// Enquires of the breakpoint locations that produced this breakpoint site
- /// whether
- /// we should stop at this location.
+ /// whether we should stop at this location.
///
/// @param[in] context
/// This contains the information about this stop.
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.
+ /// 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
/// \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.
+ /// This method returns the number of breakpoint locations currently located
+ /// at this breakpoint site.
///
/// @return
/// The number of owners.
size_t GetNumberOfOwners();
//------------------------------------------------------------------
- /// This method returns the breakpoint location at index \a index
- /// located at this breakpoint site. The owners are listed ordinally
- /// from 0 to GetNumberOfOwners() - 1 so you can use this method to iterate
- /// over the owners
+ /// This method returns the breakpoint location at index \a index located at
+ /// this breakpoint site. The owners are listed ordinally from 0 to
+ /// GetNumberOfOwners() - 1 so you can use this method to iterate over the
+ /// owners
///
/// @param[in] index
/// The index in the list of owners for which you wish the owner location.
size_t CopyOwnersList(BreakpointLocationCollection &out_collection);
//------------------------------------------------------------------
- /// Check whether the owners of this breakpoint site have any
- /// thread specifiers, and if yes, is \a thread contained in any
- /// of these specifiers.
+ /// Check whether the owners of this breakpoint site have any thread
+ /// specifiers, and if yes, is \a thread contained in any of these
+ /// specifiers.
///
/// @param[in] thread
/// The thread against which to test.
//------------------------------------------------------------------
/// Print a description of this breakpoint site to the stream \a s.
- /// GetDescription tells you about the breakpoint site's owners.
- /// Use BreakpointSite::Dump(Stream *) to get information about the
- /// breakpoint site itself.
+ /// GetDescription tells you about the breakpoint site's owners. Use
+ /// BreakpointSite::Dump(Stream *) to get information about the breakpoint
+ /// site itself.
///
/// @param[in] s
/// The stream to which to print the description.
bool IsBreakpointAtThisSite(lldb::break_id_t bp_id);
//------------------------------------------------------------------
- /// Tell whether ALL the breakpoints in the location collection are internal.
+ /// Tell whether ALL the breakpoints in the location collection are
+ /// internal.
///
/// @result
/// \b true if all breakpoint locations are owned by internal breakpoints,
void BumpHitCounts();
//------------------------------------------------------------------
- /// The method removes the owner at \a break_loc_id from this breakpoint list.
+ /// The method removes the owner at \a break_loc_id from this breakpoint
+ /// list.
///
/// @param[in] context
/// \a break_loc_id is the Breakpoint Location to remove.
//----------------------------------------------------------------------
/// @class BreakpointSiteList BreakpointSiteList.h
-/// "lldb/Breakpoint/BreakpointSiteList.h"
-/// @brief Class that manages lists of BreakpointSite shared pointers.
+/// "lldb/Breakpoint/BreakpointSiteList.h" Class that manages lists of
+/// BreakpointSite shared pointers.
//----------------------------------------------------------------------
class BreakpointSiteList {
// At present Process directly accesses the map of BreakpointSites so it can
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.
+ /// Returns a shared pointer to the breakpoint site at address \a addr.
///
/// @param[in] addr
/// The address to look for.
lldb::BreakpointSiteSP FindByID(lldb::break_id_t breakID);
//------------------------------------------------------------------
- /// Returns a shared pointer to the breakpoint site with id \a breakID - const
- /// version.
+ /// Returns a shared pointer to the breakpoint site with id \a breakID -
+ /// const version.
///
/// @param[in] breakID
/// The breakpoint site ID to seek for.
const lldb::BreakpointSiteSP FindByID(lldb::break_id_t breakID) const;
//------------------------------------------------------------------
- /// Returns the breakpoint site id to the breakpoint site at address \a addr.
+ /// Returns the breakpoint site id to the breakpoint site at address \a
+ /// addr.
///
/// @param[in] addr
/// The address to match.
void *baton);
//------------------------------------------------------------------
- /// Enquires of the breakpoint site on in this list with ID \a breakID whether
- /// we should stop for the breakpoint or not.
+ /// 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
/// This contains the information about this stop.
//----------------------------------------------------------------------
/// @class StoppointCallbackContext StoppointCallbackContext.h
-/// "lldb/Breakpoint/StoppointCallbackContext.h"
-/// @brief Class holds the information that a breakpoint callback needs to
-/// evaluate this stop.
+/// "lldb/Breakpoint/StoppointCallbackContext.h" Class holds the information
+/// that a breakpoint callback needs to evaluate this stop.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// General Outline:
/// When we hit a breakpoint we need to package up whatever information is
-/// needed
-/// to evaluate breakpoint commands and conditions. This class is the container
-/// of
-/// that information.
+/// needed to evaluate breakpoint commands and conditions. This class is the
+/// container of that information.
//----------------------------------------------------------------------
class StoppointCallbackContext {
//----------------------------------------------------------------------
/// @class WatchpointList WatchpointList.h "lldb/Breakpoint/WatchpointList.h"
-/// @brief This class is used by Watchpoint to manage a list of watchpoints,
+/// 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.
//----------------------------------------------------------------------
void DumpWithLevel(Stream *s, lldb::DescriptionLevel description_level) const;
//------------------------------------------------------------------
- /// Returns a shared pointer to the watchpoint at address
- /// \a addr -
- /// const version.
+ /// Returns a shared pointer to the watchpoint at address \a addr - const
+ /// version.
///
/// @param[in] addr
/// The address to look for.
const lldb::WatchpointSP FindByAddress(lldb::addr_t addr) const;
//------------------------------------------------------------------
- /// Returns a shared pointer to the watchpoint with watchpoint spec
- /// \a spec -
- /// const version.
+ /// Returns a shared pointer to the watchpoint with watchpoint spec \a spec
+ /// - const version.
///
/// @param[in] spec
/// The watchpoint spec to look for.
const lldb::WatchpointSP FindBySpec(std::string spec) const;
//------------------------------------------------------------------
- /// Returns a shared pointer to the watchpoint with id
- /// \a watchID, const
+ /// Returns a shared pointer to the watchpoint with id \a watchID, const
/// version.
///
/// @param[in] watchID
lldb::WatchpointSP FindByID(lldb::watch_id_t watchID) const;
//------------------------------------------------------------------
- /// Returns the watchpoint id to the watchpoint
- /// at address \a addr.
+ /// Returns the watchpoint id to the watchpoint at address \a addr.
///
/// @param[in] addr
/// The address to match.
lldb::watch_id_t FindIDByAddress(lldb::addr_t addr);
//------------------------------------------------------------------
- /// Returns the watchpoint id to the watchpoint
- /// with watchpoint spec \a spec.
+ /// Returns the watchpoint id to the watchpoint with watchpoint spec \a
+ /// spec.
///
/// @param[in] spec
/// The watchpoint spec to match.
//----------------------------------------------------------------------
/// @class WatchpointOptions WatchpointOptions.h
-/// "lldb/Breakpoint/WatchpointOptions.h"
-/// @brief Class that manages the options on a watchpoint.
+/// "lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a
+/// watchpoint.
//----------------------------------------------------------------------
class WatchpointOptions {
//------------------------------------------------------------------
/// Return the current thread spec for this option. This will return nullptr
- /// if the no thread
- /// specifications have been set for this Option yet.
+ /// if the no thread specifications have been set for this Option yet.
/// @return
/// The thread specification pointer for this option, or nullptr if none
/// has
const ThreadSpec *GetThreadSpecNoCreate() const;
//------------------------------------------------------------------
- /// Returns a pointer to the ThreadSpec for this option, creating it.
- /// if it hasn't been created already. This API is used for setting the
+ /// Returns a pointer to the ThreadSpec for this option, creating it. if it
+ /// hasn't been created already. This API is used for setting the
/// ThreadSpec items for this option.
//------------------------------------------------------------------
ThreadSpec *GetThreadSpec();
//----------------------------------------------------------------------
/// @class Address Address.h "lldb/Core/Address.h"
-/// @brief A section + offset based address class.
+/// A section + offset based address class.
///
-/// The Address class allows addresses to be relative to a section
-/// that can move during runtime due to images (executables, shared
-/// libraries, bundles, 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:
+/// The Address class allows addresses to be relative to a section that can
+/// move during runtime due to images (executables, shared libraries, bundles,
+/// 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
///
-/// File addresses represent the virtual addresses that are in the "on
-/// disk" object files. These virtual addresses are converted to be
-/// relative to unique sections scoped to the object file so that
-/// when/if the addresses slide when the images are loaded/unloaded
-/// in memory, we can easily track these changes without having to
-/// update every object (compile unit ranges, line tables, function
-/// address ranges, lexical block and inlined subroutine address
-/// ranges, global and static variables) each time an image is loaded or
-/// unloaded.
+/// File addresses represent the virtual addresses that are in the "on disk"
+/// object files. These virtual addresses are converted to be relative to
+/// unique sections scoped to the object file so that when/if the addresses
+/// slide when the images are loaded/unloaded in memory, we can easily track
+/// these changes without having to update every object (compile unit ranges,
+/// line tables, function address ranges, lexical block and inlined subroutine
+/// address ranges, global and static variables) each time an image is loaded
+/// or unloaded.
///
-/// Load addresses represent the virtual addresses where each section
-/// ends up getting loaded at runtime. Before executing a program, it
-/// is common for all of the load addresses to be unresolved. When a
-/// DynamicLoader plug-in receives notification that shared libraries
-/// have been loaded/unloaded, the load addresses of the main executable
-/// and any images (shared libraries) will be resolved/unresolved. When
-/// this happens, breakpoints that are in one of these sections can be
-/// set/cleared.
+/// Load addresses represent the virtual addresses where each section ends up
+/// getting loaded at runtime. Before executing a program, it is common for
+/// all of the load addresses to be unresolved. When a DynamicLoader plug-in
+/// receives notification that shared libraries have been loaded/unloaded, the
+/// load addresses of the main executable and any images (shared libraries)
+/// will be resolved/unresolved. When this happens, breakpoints that are in
+/// one of these sections can be set/cleared.
//----------------------------------------------------------------------
class Address {
public:
//------------------------------------------------------------------
- /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const
- /// function to display Address contents in a variety of ways.
+ /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const function
+ /// to display Address contents in a variety of ways.
//------------------------------------------------------------------
typedef enum {
DumpStyleInvalid, ///< Invalid dump style
DumpStyleSectionNameOffset, ///< Display as the section name + offset.
///< \code
/// // address for printf in libSystem.B.dylib as a section name + offset
- /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf
- /// \endcode
+ /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf \endcode
DumpStyleSectionPointerOffset, ///< Display as the section pointer + offset
///(debug output).
///< \code
- /// // address for printf in libSystem.B.dylib as a section pointer + offset
- /// (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode
+ /// // address for printf in libSystem.B.dylib as a section pointer +
+ /// offset (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode
DumpStyleFileAddress, ///< Display as the file address (if any).
///< \code
/// // address for printf in libSystem.B.dylib as a file address
//------------------------------------------------------------------
/// Default constructor.
///
- /// Initialize with a invalid section (NULL) and an invalid
- /// offset (LLDB_INVALID_ADDRESS).
+ /// Initialize with a invalid section (NULL) and an invalid offset
+ /// (LLDB_INVALID_ADDRESS).
//------------------------------------------------------------------
Address() : m_section_wp(), m_offset(LLDB_INVALID_ADDRESS) {}
//------------------------------------------------------------------
/// Construct with a section pointer and offset.
///
- /// Initialize the address with the supplied \a section and \a
- /// offset.
+ /// Initialize the address with the supplied \a section and \a offset.
///
/// @param[in] section
/// A section pointer to a valid lldb::Section, or NULL if the
//------------------------------------------------------------------
/// Construct with a virtual address and section list.
///
- /// Initialize and resolve the address with the supplied virtual
- /// address \a file_addr.
+ /// Initialize and resolve the address with the supplied virtual address \a
+ /// file_addr.
///
/// @param[in] file_addr
/// A virtual file address.
//------------------------------------------------------------------
/// Assignment operator.
///
-/// Copies the address value from another Address object \a rhs
-/// into \a this object.
+/// Copies the address value from another Address object \a rhs into \a this
+/// object.
///
/// @param[in] rhs
/// A const Address object reference to copy.
//------------------------------------------------------------------
/// Clear the object's state.
///
- /// Sets the section to an invalid value (NULL) and an invalid
- /// offset (LLDB_INVALID_ADDRESS).
+ /// Sets the section to an invalid value (NULL) and an invalid offset
+ /// (LLDB_INVALID_ADDRESS).
//------------------------------------------------------------------
void Clear() {
m_section_wp.reset();
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s. There are many ways to display a section
- /// offset based address, and \a style lets the user choose.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s. There are many ways to display a section offset based address, and
+ /// \a style lets the user choose.
///
/// @param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Get the file address.
///
- /// If an address comes from a file on disk that has section
- /// relative addresses, then it has a virtual address that is
- /// relative to unique section in the object file.
+ /// If an address comes from a file on disk that has section relative
+ /// addresses, then it has a virtual address that is relative to unique
+ /// section in the object file.
///
/// @return
/// The valid file virtual address, or LLDB_INVALID_ADDRESS if
//------------------------------------------------------------------
/// Get the load address.
///
- /// If an address comes from a file on disk that has section
- /// relative addresses, then it has a virtual address that is
- /// relative to unique section in the object file. Sections get
- /// resolved at runtime by DynamicLoader plug-ins as images
- /// (executables and shared libraries) get loaded/unloaded. If a
- /// section is loaded, then the load address can be resolved.
+ /// If an address comes from a file on disk that has section relative
+ /// addresses, then it has a virtual address that is relative to unique
+ /// section in the object file. Sections get resolved at runtime by
+ /// DynamicLoader plug-ins as images (executables and shared libraries) get
+ /// loaded/unloaded. If a section is loaded, then the load address can be
+ /// resolved.
///
/// @return
/// The valid load virtual address, or LLDB_INVALID_ADDRESS if
//------------------------------------------------------------------
/// Get the load address as a callable code load address.
///
- /// This function will first resolve its address to a load address.
- /// Then, if the address turns out to be in code address, return the
- /// load address that would be required to call or return to. The
- /// address might have extra bits set (bit zero will be set to Thumb
- /// functions for an ARM target) that are required when changing the
- /// program counter to setting a return address.
+ /// This function will first resolve its address to a load address. Then, if
+ /// the address turns out to be in code address, return the load address
+ /// that would be required to call or return to. The address might have
+ /// extra bits set (bit zero will be set to Thumb functions for an ARM
+ /// target) that are required when changing the program counter to setting a
+ /// return address.
///
/// @return
/// The valid load virtual address, or LLDB_INVALID_ADDRESS if
//------------------------------------------------------------------
/// Get the load address as an opcode load address.
///
- /// This function will first resolve its address to a load address.
- /// Then, if the address turns out to be in code address, return the
- /// load address for an opcode. This address object might have
- /// extra bits set (bit zero will be set to Thumb functions for an
+ /// This function will first resolve its address to a load address. Then, if
+ /// the address turns out to be in code address, return the load address for
+ /// an opcode. This address object might have extra bits set (bit zero will
+ /// be set to Thumb functions for an
/// ARM target) that are required for changing the program counter
- /// and this function will remove any bits that are intended for
- /// these special purposes. The result of this function can be used
- /// to safely write a software breakpoint trap to memory.
+ /// and this function will remove any bits that are intended for these
+ /// special purposes. The result of this function can be used to safely
+ /// write a software breakpoint trap to memory.
///
/// @return
/// The valid load virtual address with extra callable bits
//------------------------------------------------------------------
/// Check if an address is section offset.
///
- /// When converting a virtual file or load address into a section
- /// offset based address, we often need to know if, given a section
- /// list, if the address was able to be converted to section offset.
- /// This function returns true if the current value contained in
- /// this object is section offset based.
+ /// When converting a virtual file or load address into a section offset
+ /// based address, we often need to know if, given a section list, if the
+ /// address was able to be converted to section offset. This function
+ /// returns true if the current value contained in this object is section
+ /// offset based.
///
/// @return
/// Returns \b true if the address has a valid section and
/// Check if the object state is valid.
///
/// A valid Address object contains either a section pointer and
- /// and offset (for section offset based addresses), or just a valid
- /// offset (for absolute addresses that have no section).
+ /// and offset (for section offset based addresses), or just a valid offset
+ /// (for absolute addresses that have no section).
///
/// @return
/// Returns \b true if the offset is valid, \b false
//------------------------------------------------------------------
/// Resolve a file virtual address using a section list.
///
- /// Given a list of sections, attempt to resolve \a addr as a
- /// an offset into one of the file sections.
+ /// Given a list of sections, attempt to resolve \a addr as a an offset into
+ /// one of the file sections.
///
/// @return
/// Returns \b true if \a addr was able to be resolved, \b false
//------------------------------------------------------------------
/// Set the address to represent \a load_addr.
///
- /// The address will attempt to find a loaded section within
- /// \a target that contains \a load_addr. If successful, this
- /// address object will have a valid section and offset. Else this
- /// address object will have no section (NULL) and the offset will
- /// be \a load_addr.
+ /// The address will attempt to find a loaded section within \a target that
+ /// contains \a load_addr. If successful, this address object will have a
+ /// 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
/// A load address from a current process.
//------------------------------------------------------------------
/// Reconstruct a symbol context from an address.
///
- /// This class doesn't inherit from SymbolContextScope because many
- /// address objects have short lifespans. Address objects that are
- /// section offset can reconstruct their symbol context by looking
- /// up the address in the module found in the section.
+ /// This class doesn't inherit from SymbolContextScope because many address
+ /// objects have short lifespans. Address objects that are section offset
+ /// can reconstruct their symbol context by looking up the address in the
+ /// module found in the section.
///
/// @see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
//------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class AddressRange AddressRange.h "lldb/Core/AddressRange.h"
-/// @brief A section + offset based address range class.
+/// A section + offset based address range class.
//----------------------------------------------------------------------
class AddressRange {
public:
//------------------------------------------------------------------
/// Default constructor.
///
- /// Initialize with a invalid section (NULL), an invalid
- /// offset (LLDB_INVALID_ADDRESS), and zero byte size.
+ /// Initialize with a invalid section (NULL), an invalid offset
+ /// (LLDB_INVALID_ADDRESS), and zero byte size.
//------------------------------------------------------------------
AddressRange();
//------------------------------------------------------------------
/// Construct with a section pointer, offset, and byte_size.
///
- /// Initialize the address with the supplied \a section, \a
- /// offset and \a byte_size.
+ /// Initialize the address with the supplied \a section, \a offset and \a
+ /// byte_size.
///
/// @param[in] section
/// A section pointer to a valid lldb::Section, or NULL if the
//------------------------------------------------------------------
/// Construct with a virtual address, section list and byte size.
///
- /// Initialize and resolve the address with the supplied virtual
- /// address \a file_addr, and byte size \a byte_size.
+ /// Initialize and resolve the address with the supplied virtual address \a
+ /// file_addr, and byte size \a byte_size.
///
/// @param[in] file_addr
/// A virtual address.
//------------------------------------------------------------------
/// Construct with a Address object address and byte size.
///
- /// Initialize by copying the section offset address in \a so_addr,
- /// and setting the byte size to \a 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
/// A section offset address object.
// Contains (const Address *so_addr_ptr) const;
//------------------------------------------------------------------
- /// Check if a section offset \a so_addr when represented as a file
- /// address is contained within this object's file address range.
+ /// 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
/// A section offset address object reference.
bool ContainsFileAddress(const Address &so_addr) const;
//------------------------------------------------------------------
- /// Check if the resolved file address \a file_addr is contained
- /// within this object's file address range.
+ /// Check if the resolved file address \a file_addr is contained within this
+ /// object's file address range.
///
/// @param[in] so_addr
/// A section offset address object reference.
bool ContainsFileAddress(lldb::addr_t file_addr) const;
//------------------------------------------------------------------
- /// Check if a section offset \a so_addr when represented as a load
- /// address is contained within this object's load address range.
+ /// 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
/// A section offset address object reference.
bool ContainsLoadAddress(const Address &so_addr, Target *target) const;
//------------------------------------------------------------------
- /// Check if the resolved load address \a load_addr is contained
- /// within this object's load address range.
+ /// Check if the resolved load address \a load_addr is contained within this
+ /// object's load address range.
///
/// @param[in] so_addr
/// A section offset address object reference.
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s. There are many ways to display a section
- /// offset based address range, and \a style lets the user choose
- /// how the base address gets displayed.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s. There are many ways to display a section offset based address
+ /// range, and \a style lets the user choose how the base address gets
+ /// displayed.
///
/// @param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Dump a debug description of this object to a Stream.
///
- /// Dump a debug description of the contents of this object to the
- /// supplied stream \a s.
+ /// Dump a debug description of the contents of this object to the supplied
+ /// stream \a s.
///
- /// The debug description contains verbose internal state such
- /// and pointer values, reference counts, etc.
+ /// The debug description contains verbose internal state such and pointer
+ /// values, reference counts, etc.
///
/// @param[in] s
/// The stream to which to dump the object description.
//----------------------------------------------------------------------
/// @class AddressResolver AddressResolver.h "lldb/Core/AddressResolver.h"
-/// @brief This class works with SearchFilter to resolve function names and
-/// source file locations to their concrete addresses.
+/// This class works with SearchFilter to resolve function names and source
+/// file locations to their concrete addresses.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// General Outline:
-/// The AddressResolver is a Searcher. In that protocol,
-/// the SearchFilter asks the question "At what depth of the symbol context
-/// descent do you want your callback to get called?" of the filter. The
-/// resolver
-/// answers this question (in the GetDepth method) and provides the resolution
-/// callback.
+/// The AddressResolver is a Searcher. In that protocol, the SearchFilter
+/// asks the question "At what depth of the symbol context descent do you want
+/// your callback to get called?" of the filter. The resolver answers this
+/// question (in the GetDepth method) and provides the resolution callback.
//----------------------------------------------------------------------
class AddressResolver : public Searcher {
//----------------------------------------------------------------------
/// @class AddressResolverFileLine AddressResolverFileLine.h
-/// "lldb/Core/AddressResolverFileLine.h"
-/// @brief This class finds address for source file and line. Optionally, it
-/// will look for inlined
-/// instances of the file and line specification.
+/// "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.
//----------------------------------------------------------------------
class AddressResolverFileLine : public AddressResolver {
//----------------------------------------------------------------------
/// @class AddressResolverName AddressResolverName.h
-/// "lldb/Core/AddressResolverName.h"
-/// @brief This class finds addresses for a given function name, either by exact
-/// match
-/// or by regular expression.
+/// "lldb/Core/AddressResolverName.h" This class finds addresses for a given
+/// function name, either by exact match or by regular expression.
//----------------------------------------------------------------------
class AddressResolverName : public AddressResolver {
};
//----------------------------------------------------------------------
-/// @class Broadcaster Broadcaster.h "lldb/Core/Broadcaster.h"
-/// @brief An event broadcasting class.
+/// @class Broadcaster Broadcaster.h "lldb/Core/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:
+/// 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)
/// or cleared:
/// @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).
+/// When an event gets set the Broadcaster object will notify the Listener
+/// object that is listening for the event (if there is one).
///
-/// Subclasses should provide broadcast bit definitions for any events
-/// they vend, typically using an enumeration:
+/// Subclasses should provide broadcast bit definitions for any events they
+/// vend, typically using an enumeration:
/// \code
/// class Foo : public Broadcaster
/// {
//------------------------------------------------------------------
/// Listen for any events specified by \a event_mask.
///
- /// Only one listener can listen to each event bit in a given
- /// Broadcaster. Once a listener has acquired an event bit, no
- /// other broadcaster will have access to it until it is
- /// relinquished by the first listener that gets it. The actual
- /// event bits that get acquired by \a listener may be different
- /// from what is requested in \a event_mask, and to track this the
+ /// Only one listener can listen to each event bit in a given Broadcaster.
+ /// Once a listener has acquired an event bit, no other broadcaster will
+ /// have access to it until it is relinquished by the first listener that
+ /// gets it. The actual event bits that get acquired by \a listener may be
+ /// 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
}
//------------------------------------------------------------------
- /// Get the NULL terminated C string name of this Broadcaster
- /// object.
+ /// Get the NULL terminated C string name of this Broadcaster object.
///
/// @return
/// The NULL terminated C string name of this Broadcaster.
}
//------------------------------------------------------------------
- /// Removes a Listener from this broadcasters list and frees the
- /// event bits specified by \a event_mask that were previously
- /// acquired by \a listener (assuming \a listener was listening to
- /// this object) for other listener objects to use.
+ /// Removes a Listener from this broadcasters list and frees the event bits
+ /// specified by \a event_mask that were previously acquired by \a listener
+ /// (assuming \a listener was listening to this object) for other listener
+ /// objects to use.
///
/// @param[in] listener
/// A Listener object that previously called AddListener.
//------------------------------------------------------------------
/// Provides a simple mechanism to temporarily redirect events from
/// broadcaster. When you call this function passing in a listener and
- /// event type mask, all events from the broadcaster matching the mask
- /// will 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.
+ /// event type mask, all events from the broadcaster matching the mask will
+ /// 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
/// A Listener object. You do not need to call StartListeningForEvents
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Communication Communication.h "lldb/Core/Communication.h"
-/// @brief An abstract communications class.
+/// @class Communication Communication.h "lldb/Core/Communication.h" An
+/// abstract communications class.
///
-/// Communication is an class that handles data communication
-/// between two data sources. It uses a Connection class to do the
-/// real communication. This approach has a couple of advantages: it
-/// allows a single instance of this class to be used even though its
-/// connection can change. Connections could negotiate for different
-/// connections based on abilities like starting with Bluetooth and
-/// negotiating up to WiFi if available. It also allows this class to be
-/// subclassed by any interfaces that don't want to give bytes but want
-/// to validate and give out packets. This can be done by overriding:
+/// Communication is an class that handles data communication between two data
+/// sources. It uses a Connection class to do the real communication. This
+/// approach has a couple of advantages: it allows a single instance of this
+/// class to be used even though its connection can change. Connections could
+/// negotiate for different connections based on abilities like starting with
+/// Bluetooth and negotiating up to WiFi if available. It also allows this
+/// class to be subclassed by any interfaces that don't want to give bytes but
+/// want to validate and give out packets. This can be done by overriding:
///
/// AppendBytesToCache (const uint8_t *src, size_t src_len, bool broadcast);
///
-/// Communication inherits from Broadcaster which means it can be
-/// used in conjunction with Listener to wait for multiple broadcaster
-/// objects and multiple events from each of those objects.
-/// Communication defines a set of pre-defined event bits (see
-/// enumerations definitions that start with "eBroadcastBit" below).
+/// Communication inherits from Broadcaster which means it can be used in
+/// conjunction with Listener to wait for multiple broadcaster objects and
+/// multiple events from each of those objects. Communication defines a set of
+/// pre-defined event bits (see enumerations definitions that start with
+/// "eBroadcastBit" below).
///
/// There are two modes in which communications can occur:
/// @li single-threaded
/// @li multi-threaded
///
-/// In single-threaded mode, all reads and writes happen synchronously
-/// on the calling thread.
+/// In single-threaded mode, all reads and writes happen synchronously on the
+/// calling thread.
///
-/// In multi-threaded mode, a read thread is spawned that continually
-/// reads data and caches any received bytes. To start the read thread
-/// clients call:
+/// In multi-threaded mode, a read thread is spawned that continually reads
+/// data and caches any received bytes. To start the read thread clients call:
///
/// bool Communication::StartReadThread (Status *);
///
-/// If true is returned a read thread has been spawned that will
-/// continually execute a call to the pure virtual DoRead function:
+/// If true is returned a read thread has been spawned that will continually
+/// execute a call to the pure virtual DoRead function:
///
/// size_t Communication::ReadFromConnection (void *, size_t, uint32_t);
///
-/// When bytes are received the data gets cached in \a m_bytes and this
-/// class will broadcast a \b eBroadcastBitReadThreadGotBytes event.
-/// Clients that want packet based communication should override
-/// AppendBytesToCache. The subclasses can choose to call the
-/// built in AppendBytesToCache with the \a broadcast parameter set to
-/// false. This will cause the \b eBroadcastBitReadThreadGotBytes event
-/// not get broadcast, and then the subclass can post a \b
-/// eBroadcastBitPacketAvailable event when a full packet of data has
-/// been received.
+/// When bytes are received the data gets cached in \a m_bytes and this class
+/// will broadcast a \b eBroadcastBitReadThreadGotBytes event. Clients that
+/// want packet based communication should override AppendBytesToCache. The
+/// subclasses can choose to call the built in AppendBytesToCache with the \a
+/// broadcast parameter set to false. This will cause the \b
+/// eBroadcastBitReadThreadGotBytes event not get broadcast, and then the
+/// subclass can post a \b eBroadcastBitPacketAvailable event when a full
+/// packet of data has been received.
///
-/// If the connection is disconnected a \b eBroadcastBitDisconnected
-/// event gets broadcast. If the read thread exits a \b
-/// eBroadcastBitReadThreadDidExit event will be broadcast. Clients
-/// can also post a \b eBroadcastBitReadThreadShouldExit event to this
-/// object which will cause the read thread to exit.
+/// If the connection is disconnected a \b eBroadcastBitDisconnected event
+/// gets broadcast. If the read thread exits a \b
+/// eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also
+/// post a \b eBroadcastBitReadThreadShouldExit event to this object which
+/// will cause the read thread to exit.
//----------------------------------------------------------------------
class Communication : public Broadcaster {
public:
size_t src_len);
//------------------------------------------------------------------
- /// Construct the Communication object with the specified name for
- /// the Broadcaster that this object inherits from.
+ /// Construct the Communication object with the specified name for the
+ /// Broadcaster that this object inherits from.
///
/// @param[in] broadcaster_name
/// The name of the broadcaster object. This name should be as
void Clear();
//------------------------------------------------------------------
- /// Connect using the current connection by passing \a url to its
- /// connect function.
- /// string.
+ /// Connect using the current connection by passing \a url to its connect
+ /// function. string.
///
/// @param[in] url
/// A string that contains all information needed by the
lldb::ConnectionStatus Connect(const char *url, Status *error_ptr);
//------------------------------------------------------------------
- /// Disconnect the communications connection if one is currently
- /// connected.
+ /// Disconnect the communications connection if one is currently connected.
///
/// @return
/// \b True if the disconnect succeeded, \b false otherwise. The
//------------------------------------------------------------------
/// Read bytes from the current connection.
///
- /// If no read thread is running, this function call the
- /// connection's Connection::Read(...) function to get any available.
+ /// If no read thread is running, this function call the connection's
+ /// Connection::Read(...) function to get any available.
///
- /// If a read thread has been started, this function will check for
- /// any cached bytes that have already been read and return any
- /// currently available bytes. If no bytes are cached, it will wait
- /// for the bytes to become available by listening for the \a
- /// eBroadcastBitReadThreadGotBytes event. If this function consumes
- /// all of the bytes in the cache, it will reset the
- /// \a eBroadcastBitReadThreadGotBytes event bit.
+ /// If a read thread has been started, this function will check for any
+ /// cached bytes that have already been read and return any currently
+ /// available bytes. If no bytes are cached, it will wait for the bytes to
+ /// become available by listening for the \a eBroadcastBitReadThreadGotBytes
+ /// event. If this function consumes all of the bytes in the cache, it will
+ /// reset the \a eBroadcastBitReadThreadGotBytes event bit.
///
/// @param[in] dst
/// A destination buffer that must be at least \a dst_len bytes
lldb::ConnectionStatus &status, Status *error_ptr);
//------------------------------------------------------------------
- /// The actual write function that attempts to write to the
- /// communications protocol.
+ /// The actual write function that attempts to write to the communications
+ /// protocol.
///
/// Subclasses must override this function.
///
//------------------------------------------------------------------
/// Sets the connection that it to be used by this class.
///
- /// By making a communication class that uses different connections
- /// it allows a single communication interface to negotiate and
- /// change its connection without any interruption to the client.
- /// It also allows the Communication class to be subclassed for
- /// packet based communication.
+ /// By making a communication class that uses different connections it
+ /// allows a single communication interface to negotiate and change its
+ /// connection without any interruption to the client. It also allows the
+ /// Communication class to be subclassed for packet based communication.
///
/// @param[in] connection
/// A connection that this class will own and destroy.
void SetConnection(Connection *connection);
//------------------------------------------------------------------
- /// Starts a read thread whose sole purpose it to read bytes from
- /// the current connection. This function will call connection's
- /// read function:
+ /// Starts a read thread whose sole purpose it to read bytes from the
+ /// current connection. This function will call connection's read function:
///
/// size_t Connection::Read (void *, size_t);
///
/// When bytes are read and cached, this function will call:
///
- /// Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool
+ /// Communication::AppendBytesToCache (const uint8_t * bytes, size_t len,
+ /// bool
/// broadcast);
///
- /// Subclasses should override this function if they wish to override
- /// the default action of caching the bytes and broadcasting a \b
+ /// Subclasses should override this function if they wish to override the
+ /// default action of caching the bytes and broadcasting a \b
/// eBroadcastBitReadThreadGotBytes event.
///
/// @return
/// false otherwise.
///
/// @see size_t Connection::Read (void *, size_t);
- /// @see void Communication::AppendBytesToCache (const uint8_t * bytes, size_t
- /// len, bool broadcast);
+ /// @see void Communication::AppendBytesToCache (const uint8_t * bytes,
+ /// size_t len, bool broadcast);
//------------------------------------------------------------------
virtual bool StartReadThread(Status *error_ptr = nullptr);
bool ReadThreadIsRunning();
//------------------------------------------------------------------
- /// The static read thread function. This function will call
- /// the "DoRead" function continuously and wait for data to become
- /// available. When data is received it will append the available
- /// data to the internal cache and broadcast a
- /// \b eBroadcastBitReadThreadGotBytes event.
+ /// The static read thread function. This function will call the "DoRead"
+ /// function continuously and wait for data to become available. When data
+ /// is received it will append the available data to the internal cache and
+ /// broadcast a \b eBroadcastBitReadThreadGotBytes event.
///
/// @param[in] comm_ptr
/// A pointer to an instance of this class.
lldb::ConnectionStatus &status, Status *error_ptr);
//------------------------------------------------------------------
- /// Append new bytes that get read from the read thread into the
- /// internal object byte cache. This will cause a \b
- /// eBroadcastBitReadThreadGotBytes event to be broadcast if \a
- /// broadcast is true.
+ /// Append new bytes that get read from the read thread into the internal
+ /// object byte cache. This will cause a \b eBroadcastBitReadThreadGotBytes
+ /// event to be broadcast if \a broadcast is true.
///
- /// Subclasses can override this function in order to inspect the
- /// received data and check if a packet is available.
+ /// Subclasses can override this function in order to inspect the received
+ /// data and check if a packet is available.
///
- /// Subclasses can also still call this function from the
- /// overridden method to allow the caching to correctly happen and
- /// suppress the broadcasting of the \a eBroadcastBitReadThreadGotBytes
- /// event by setting \a broadcast to false.
+ /// Subclasses can also still call this function from the overridden method
+ /// to allow the caching to correctly happen and suppress the broadcasting
+ /// of the \a eBroadcastBitReadThreadGotBytes event by setting \a broadcast
+ /// to false.
///
/// @param[in] src
/// A source buffer that must be at least \a src_len bytes
lldb::ConnectionStatus status);
//------------------------------------------------------------------
- /// Get any available bytes from our data cache. If this call
- /// empties the data cache, the \b eBroadcastBitReadThreadGotBytes event
- /// will be reset to signify no more bytes are available.
+ /// Get any available bytes from our data cache. If this call empties the
+ /// data cache, the \b eBroadcastBitReadThreadGotBytes event will be reset
+ /// to signify no more bytes are available.
///
/// @param[in] dst
/// A destination buffer that must be at least \a dst_len bytes
//----------------------------------------------------------------------
/// @class Debugger Debugger.h "lldb/Core/Debugger.h"
-/// @brief A class to manage flag bits.
+/// A class to manage flag bits.
///
/// Provides a global root objects for the debugger core.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Get accessor for the target list.
///
- /// The target list is part of the global debugger object. This
- /// the single debugger shared instance to control where targets
- /// get created and to allow for tracking and searching for targets
- /// based on certain criteria.
+ /// The target list is part of the global debugger object. This the single
+ /// debugger shared instance to control where targets get created and to
+ /// allow for tracking and searching for targets based on certain criteria.
///
/// @return
/// A global shared target list.
//----------------------------------------------------------------------
/// @class EmulateInstruction EmulateInstruction.h
/// "lldb/Core/EmulateInstruction.h"
-/// @brief A class that allows emulation of CPU opcodes.
+/// A class that allows emulation of CPU opcodes.
///
-/// This class is a plug-in interface that is accessed through the
-/// standard static FindPlugin function call in the EmulateInstruction
-/// class. The FindPlugin takes a target triple and returns a new object
-/// if there is a plug-in that supports the architecture and OS. Four
-/// callbacks and a baton are provided. The four callbacks are read
-/// register, write register, read memory and write memory.
+/// This class is a plug-in interface that is accessed through the standard
+/// static FindPlugin function call in the EmulateInstruction class. The
+/// FindPlugin takes a target triple and returns a new object if there is a
+/// plug-in that supports the architecture and OS. Four callbacks and a baton
+/// are provided. The four callbacks are read register, write register, read
+/// memory and write memory.
///
-/// This class is currently designed for these main use cases:
-/// - Auto generation of Call Frame Information (CFI) from assembly code
-/// - Predicting single step breakpoint locations
-/// - Emulating instructions for breakpoint traps
+/// This class is currently designed for these main use cases: - Auto
+/// generation of Call Frame Information (CFI) from assembly code - Predicting
+/// single step breakpoint locations - Emulating instructions for breakpoint
+/// traps
///
-/// Objects can be asked to read an instruction which will cause a call
-/// to the read register callback to get the PC, followed by a read
-/// memory call to read the opcode. If ReadInstruction () returns true,
-/// then a call to EmulateInstruction::EvaluateInstruction () can be
-/// made. At this point the EmulateInstruction subclass will use all of
-/// the callbacks to emulate an instruction.
+/// Objects can be asked to read an instruction which will cause a call to the
+/// read register callback to get the PC, followed by a read memory call to
+/// read the opcode. If ReadInstruction () returns true, then a call to
+/// EmulateInstruction::EvaluateInstruction () can be made. At this point the
+/// EmulateInstruction subclass will use all of the callbacks to emulate an
+/// instruction.
///
/// Clients that provide the callbacks can either do the read/write
-/// registers/memory to actually emulate the instruction on a real or
-/// virtual CPU, or watch for the EmulateInstruction::Context which
-/// is context for the read/write register/memory which explains why
-/// the callback is being called. Examples of a context are:
-/// "pushing register 3 onto the stack at offset -12", or "adjusting
-/// stack pointer by -16". This extra context allows the generation of
+/// registers/memory to actually emulate the instruction on a real or virtual
+/// CPU, or watch for the EmulateInstruction::Context which is context for the
+/// read/write register/memory which explains why the callback is being
+/// called. Examples of a context are: "pushing register 3 onto the stack at
+/// offset -12", or "adjusting stack pointer by -16". This extra context
+/// allows the generation of
/// CFI information from assembly code without having to actually do
/// the read/write register/memory.
///
-/// Clients must be prepared that not all instructions for an
-/// Instruction Set Architecture (ISA) will be emulated.
+/// Clients must be prepared that not all instructions for an Instruction Set
+/// Architecture (ISA) will be emulated.
///
-/// Subclasses at the very least should implement the instructions that
-/// save and restore registers onto the stack and adjustment to the stack
-/// pointer. By just implementing a few instructions for an ISA that are
-/// the typical prologue opcodes, you can then generate CFI using a
-/// class that will soon be available.
+/// Subclasses at the very least should implement the instructions that save
+/// and restore registers onto the stack and adjustment to the stack pointer.
+/// By just implementing a few instructions for an ISA that are the typical
+/// prologue opcodes, you can then generate CFI using a class that will soon
+/// be available.
///
-/// Implementing all of the instructions that affect the PC can then
-/// allow single step prediction support.
+/// Implementing all of the instructions that affect the PC can then allow
+/// single step prediction support.
///
-/// Implementing all of the instructions allows for emulation of opcodes
-/// for breakpoint traps and will pave the way for "thread centric"
-/// debugging. The current debugging model is "process centric" where
-/// all threads must be stopped when any thread is stopped; when
-/// hitting software breakpoints we must disable the breakpoint by
-/// restoring the original breakpoint opcode, single stepping and
-/// restoring the breakpoint trap. If all threads were allowed to run
-/// then other threads could miss the breakpoint.
+/// Implementing all of the instructions allows for emulation of opcodes for
+/// breakpoint traps and will pave the way for "thread centric" debugging. The
+/// current debugging model is "process centric" where all threads must be
+/// stopped when any thread is stopped; when hitting software breakpoints we
+/// must disable the breakpoint by restoring the original breakpoint opcode,
+/// single stepping and restoring the breakpoint trap. If all threads were
+/// allowed to run then other threads could miss the breakpoint.
///
-/// This class centralizes the code that usually is done in separate
-/// code paths in a debugger (single step prediction, finding save
-/// restore locations of registers for unwinding stack frame variables)
-/// and emulating the instruction is just a bonus.
+/// This class centralizes the code that usually is done in separate code
+/// paths in a debugger (single step prediction, finding save restore
+/// locations of registers for unwinding stack frame variables) and emulating
+/// the instruction is just a bonus.
//----------------------------------------------------------------------
class EmulateInstruction : public PluginInterface {
//----------------------------------------------------------------------
/// @class FileLineResolver FileLineResolver.h "lldb/Core/FileLineResolver.h"
-/// @brief This class finds address for source file and line. Optionally, it
-/// will look for inlined
-/// instances of the file and line specification.
+/// This class finds address for source file and line. Optionally, it will
+/// look for inlined instances of the file and line specification.
//----------------------------------------------------------------------
class FileLineResolver : public Searcher {
//----------------------------------------------------------------------
/// @class FileSpecList FileSpecList.h "lldb/Core/FileSpecList.h"
-/// @brief A file collection class.
+/// A file collection class.
///
/// A class that contains a mutable list of FileSpec objects.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Assignment operator.
///
- /// Replace the file list in this object with the file list from
- /// \a rhs.
+ /// Replace the file list in this object with the file list from \a rhs.
///
/// @param[in] rhs
/// A file list object to copy.
//------------------------------------------------------------------
/// Append a FileSpec object if unique.
///
- /// Appends \a file to the end of the file list if it doesn't
- /// already exist in the file list.
+ /// Appends \a file to the end of the file list if it doesn't already exist
+ /// in the file list.
///
/// @param[in] file
/// A new file to append to this file list.
//------------------------------------------------------------------
/// Find a file index.
///
- /// Find the index of the file in the file spec list that matches
- /// \a file starting \a idx entries into the file spec list.
+ /// 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
/// An index into the file list.
//------------------------------------------------------------------
/// Get file at index.
///
- /// Gets a file from the file list. If \a idx is not a valid index,
- /// an empty FileSpec object will be returned. The file objects
- /// that are returned can be tested using
- /// FileSpec::operator void*().
+ /// Gets a file from the file list. If \a idx is not a valid index, an empty
+ /// FileSpec object will be returned. The file objects that are returned can
+ /// be tested using FileSpec::operator void*().
///
/// @param[in] idx
/// An index into the file list.
//------------------------------------------------------------------
/// Get file specification pointer at index.
///
- /// Gets a file from the file list. The file objects that are
- /// returned can be tested using FileSpec::operator void*().
+ /// Gets a file from the file list. The file objects that are returned can
+ /// be tested using FileSpec::operator void*().
///
/// @param[in] idx
/// An index into the file list.
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// Return the size in bytes that this object takes in memory. This
- /// returns the size in bytes of this object, not any shared string
- /// values it may refer to.
+ /// Return the size in bytes that this object takes in memory. This returns
+ /// the size in bytes of this object, not any shared string values it may
+ /// refer to.
///
/// @return
/// The number of bytes that this object occupies in memory.
//----------------------------------------------------------------------
/// @class Mangled Mangled.h "lldb/Core/Mangled.h"
-/// @brief A class that handles mangled names.
+/// A class that handles mangled names.
///
-/// Designed to handle mangled names. The demangled version of any names
-/// will be computed when the demangled name is accessed through the
-/// Demangled() acccessor. This class can also tokenize the demangled
-/// version of the name for powerful searches. Functions and symbols
-/// could make instances of this class for their mangled names. Uniqued
-/// string pools are used for the mangled, demangled, and token string
-/// values to allow for faster comparisons and for efficient memory use.
+/// Designed to handle mangled names. The demangled version of any names will
+/// be computed when the demangled name is accessed through the Demangled()
+/// acccessor. This class can also tokenize the demangled version of the name
+/// for powerful searches. Functions and symbols could make instances of this
+/// class for their mangled names. Uniqued string pools are used for the
+/// mangled, demangled, and token string values to allow for faster
+/// comparisons and for efficient memory use.
//----------------------------------------------------------------------
class Mangled {
public:
//----------------------------------------------------------------------
/// Destructor
///
- /// Releases its ref counts on the mangled and demangled strings that
- /// live in the global string pool.
+ /// Releases its ref counts on the mangled and demangled strings that live
+ /// in the global string pool.
//----------------------------------------------------------------------
~Mangled();
//----------------------------------------------------------------------
/// Convert to pointer operator.
///
- /// This allows code to check a Mangled object to see if it contains
- /// a valid mangled name using code such as:
+ /// This allows code to check a Mangled object to see if it contains a valid
+ /// mangled name using code such as:
///
/// @code
/// Mangled mangled(...);
//----------------------------------------------------------------------
/// Logical NOT operator.
///
- /// This allows code to check a Mangled object to see if it contains
- /// an empty mangled name using code such as:
+ /// This allows code to check a Mangled object to see if it contains an
+ /// empty mangled name using code such as:
///
/// @code
/// Mangled mangled(...);
//----------------------------------------------------------------------
/// Dump a description of this object to a Stream \a s.
///
- /// 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).
+ /// 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
/// The stream to which to dump the object description.
//----------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// Return the size in bytes that this object takes in memory. This
- /// returns the size in bytes of this object, not any shared string
- /// values it may refer to.
+ /// Return the size in bytes that this object takes in memory. This returns
+ /// the size in bytes of this object, not any shared string values it may
+ /// refer to.
///
/// @return
/// The number of bytes that this object occupies in memory.
//----------------------------------------------------------------------
/// Set the string value in this object.
///
- /// 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.
+ /// 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
/// The already const version of the name for this object.
//----------------------------------------------------------------------
/// Try to guess the language from the mangling.
///
- /// For a mangled name to have a language it must have both a mangled
- /// and a demangled name and it can be guessed from the mangling what
- /// the language is. Note: this will return C++ for any language that
- /// uses Itanium ABI mangling.
+ /// For a mangled name to have a language it must have both a mangled and a
+ /// demangled name and it can be guessed from the mangling what the language
+ /// is. Note: this will return C++ for any language that uses Itanium ABI
+ /// mangling.
///
- /// Standard C function names will return eLanguageTypeUnknown because
- /// they aren't mangled and it isn't clear what language the name
- /// represents (there will be no mangled name).
+ /// Standard C function names will return eLanguageTypeUnknown because they
+ /// aren't mangled and it isn't clear what language the name represents
+ /// (there will be no mangled name).
///
/// @return
/// The language for the mangled/demangled name, eLanguageTypeUnknown
//----------------------------------------------------------------------
/// @class Module Module.h "lldb/Core/Module.h"
-/// @brief A class that describes an executable image and its associated
+/// A class that describes an executable image and its associated
/// object and symbol files.
///
/// The module is designed to be able to select a single slice of an
-/// executable image as it would appear on disk and during program
-/// execution.
+/// executable image as it would appear on disk and during program execution.
///
/// Modules control when and if information is parsed according to which
/// accessors are called. For example the object file (ObjectFile)
-/// representation will only be parsed if the object file is requested
-/// using the Module::GetObjectFile() is called. The debug symbols
-/// will only be parsed if the symbol vendor (SymbolVendor) is
-/// requested using the Module::GetSymbolVendor() is called.
+/// representation will only be parsed if the object file is requested using
+/// the Module::GetObjectFile() is called. The debug symbols will only be
+/// parsed if the symbol vendor (SymbolVendor) is requested using the
+/// Module::GetSymbolVendor() is called.
///
-/// The module will parse more detailed information as more queries are
-/// made.
+/// The module will parse more detailed information as more queries are made.
//----------------------------------------------------------------------
class Module : public std::enable_shared_from_this<Module>,
public SymbolContextScope {
//------------------------------------------------------------------
/// Construct with file specification and architecture.
///
- /// Clients that wish to share modules with other targets should
- /// use ModuleList::GetSharedModule().
+ /// Clients that wish to share modules with other targets should use
+ /// ModuleList::GetSharedModule().
///
/// @param[in] file_spec
/// The file specification for the on disk representation of
bool MatchesModuleSpec(const ModuleSpec &module_ref);
//------------------------------------------------------------------
- /// Set the load address for all sections in a module to be the
- /// file address plus \a slide.
+ /// Set the load address for all sections in a module to be the file address
+ /// plus \a slide.
///
- /// Many times a module will be loaded in a target with a constant
- /// offset applied to all top level sections. This function can
- /// set the load address for all top level sections to be the
- /// section file address + offset.
+ /// Many times a module will be loaded in a target with a constant offset
+ /// applied to all top level sections. This function can set the load
+ /// address for all top level sections to be the section file address +
+ /// offset.
///
/// @param[in] target
/// The target in which to apply the section load addresses.
//------------------------------------------------------------------
/// Get the module path and object name.
///
- /// Modules can refer to object files. In this case the specification
- /// is simple and would return the path to the file:
+ /// Modules can refer to object files. In this case the specification is
+ /// simple and would return the path to the file:
///
/// "/usr/lib/foo.dylib"
///
- /// Modules can be .o files inside of a BSD archive (.a file). In
- /// this case, the object specification will look like:
+ /// Modules can be .o files inside of a BSD archive (.a file). In this case,
+ /// the object specification will look like:
///
/// "/usr/lib/foo.a(bar.o)"
///
- /// There are many places where logging wants to log this fully
- /// qualified specification, so we centralize this functionality
- /// here.
+ /// There are many places where logging wants to log this fully qualified
+ /// specification, so we centralize this functionality here.
///
/// @return
/// The object path + object name if there is one.
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s. The dumped content will be only what has
- /// been loaded or parsed up to this point at which this function
- /// is called, so this is a good way to see what has been parsed
- /// in a module.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s. The dumped content will be only what has been loaded or parsed up
+ /// 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
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Find compile units by partial or full path.
///
- /// Finds all compile units that match \a path in all of the modules
- /// and returns the results in \a sc_list.
+ /// Finds all compile units that match \a path in all of the modules and
+ /// returns the results in \a sc_list.
///
/// @param[in] path
/// The name of the function we are looking for.
///
/// If the function is an inlined function, it will have a block,
/// representing the inlined function, and the function will be the
- /// containing function. If it is not inlined, then the block will
- /// be NULL.
+ /// containing function. If it is not inlined, then the block will be NULL.
///
/// @param[in] name
/// The name of the compile unit we are looking for.
///
/// If the function is an inlined function, it will have a block,
/// representing the inlined function, and the function will be the
- /// containing function. If it is not inlined, then the block will
- /// be NULL.
+ /// containing function. If it is not inlined, then the block will be NULL.
///
/// @param[in] regex
/// A regular expression to use when matching the name.
//------------------------------------------------------------------
/// Find types by name.
///
- /// Type lookups in modules go through the SymbolVendor (which will
- /// use one or more SymbolFile subclasses). The SymbolFile needs to
- /// be able to lookup types by basename and not the fully qualified
- /// typename. This allows the type accelerator tables to stay small,
- /// even with heavily templatized C++. The type search will then
- /// narrow down the search results. If "exact_match" is true, then
- /// the type search will only match exact type name matches. If
- /// "exact_match" is false, the type will match as long as the base
- /// typename matches and as long as any immediate containing
- /// namespaces/class scopes that are specified match. So to search
- /// for a type "d" in "b::c", the name "b::c::d" can be specified
- /// and it will match any class/namespace "b" which contains a
- /// class/namespace "c" which contains type "d". We do this to
- /// allow users to not always have to specify complete scoping on
- /// all expressions, but it also allows for exact matching when
- /// required.
+ /// Type lookups in modules go through the SymbolVendor (which will use one
+ /// or more SymbolFile subclasses). The SymbolFile needs to be able to
+ /// lookup types by basename and not the fully qualified typename. This
+ /// allows the type accelerator tables to stay small, even with heavily
+ /// templatized C++. The type search will then narrow down the search
+ /// results. If "exact_match" is true, then the type search will only match
+ /// exact type name matches. If "exact_match" is false, the type will match
+ /// as long as the base typename matches and as long as any immediate
+ /// containing namespaces/class scopes that are specified match. So to
+ /// search for a type "d" in "b::c", the name "b::c::d" can be specified and
+ /// it will match any class/namespace "b" which contains a class/namespace
+ /// "c" which contains type "d". We do this to allow users to not always
+ /// have to specify complete scoping on all expressions, but it also allows
+ /// for exact matching when required.
///
/// @param[in] sc
/// A symbol context that scopes where to extract a type list
const ConstString &type_name, bool exact_match);
//------------------------------------------------------------------
- /// Find types by name that are in a namespace. This function is
- /// used by the expression parser when searches need to happen in
- /// an exact namespace scope.
+ /// Find types by name that are in a namespace. This function is used by the
+ /// expression parser when searches need to happen in an exact namespace
+ /// scope.
///
/// @param[in] sc
/// A symbol context that scopes where to extract a type list
//------------------------------------------------------------------
/// Get const accessor for the module file specification.
///
- /// This function returns the file for the module on the host system
- /// that is running LLDB. This can differ from the path on the
- /// platform since we might be doing remote debugging.
+ /// This function returns the file for the module on the host system that is
+ /// running LLDB. This can differ from the path on the platform since we
+ /// might be doing remote debugging.
///
/// @return
/// A const reference to the file specification object.
//------------------------------------------------------------------
/// Get accessor for the module platform file specification.
///
- /// Platform file refers to the path of the module as it is known on
- /// the remote system on which it is being debugged. For local
- /// debugging this is always the same as Module::GetFileSpec(). But
- /// remote debugging might mention a file "/usr/lib/liba.dylib"
- /// which might be locally downloaded and cached. In this case the
- /// platform file could be something like:
- /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib"
- /// The file could also be cached in a local developer kit directory.
+ /// Platform file refers to the path of the module as it is known on the
+ /// remote system on which it is being debugged. For local debugging this is
+ /// always the same as Module::GetFileSpec(). But remote debugging might
+ /// mention a file "/usr/lib/liba.dylib" which might be locally downloaded
+ /// and cached. In this case the platform file could be something like:
+ /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The
+ /// file could also be cached in a local developer kit directory.
///
/// @return
/// A const reference to the file specification object.
}
//------------------------------------------------------------------
- /// Tells whether this module is capable of being the main executable
- /// for a process.
+ /// Tells whether this module is capable of being the main executable for a
+ /// process.
///
/// @return
/// \b true if it is, \b false otherwise.
bool IsExecutable();
//------------------------------------------------------------------
- /// Tells whether this module has been loaded in the target passed in.
- /// This call doesn't distinguish between whether the module is loaded
- /// by the dynamic loader, or by a "target module add" type call.
+ /// Tells whether this module has been loaded in the target passed in. This
+ /// 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
/// The target to check whether this is loaded in.
//------------------------------------------------------------------
/// Get the object file representation for the current architecture.
///
- /// 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.
+ /// 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
/// If Module::m_file does not exist, or no plug-in was found
virtual ObjectFile *GetObjectFile();
//------------------------------------------------------------------
- /// Get the unified section list for the module. This is the section
- /// list created by the module's object file and any debug info and
- /// symbol files created by the symbol vendor.
+ /// Get the unified section list for the module. This is the section list
+ /// created by the module's object file and any debug info and symbol files
+ /// created by the symbol vendor.
///
- /// If the symbol vendor has not been loaded yet, this function
- /// will return the section list for the object file.
+ /// If the symbol vendor has not been loaded yet, this function will return
+ /// the section list for the object file.
///
/// @return
/// Unified module section list.
virtual SectionList *GetSectionList();
//------------------------------------------------------------------
- /// Notify the module that the file addresses for the Sections have
- /// been updated.
+ /// Notify the module that the file addresses for the Sections have been
+ /// updated.
///
- /// If the Section file addresses for a module are updated, this
- /// method should be called. Any parts of the module, object file,
- /// or symbol file that has cached those file addresses must invalidate
- /// or update its cache.
+ /// If the Section file addresses for a module are updated, this method
+ /// should be called. Any parts of the module, object file, or symbol file
+ /// that has cached those file addresses must invalidate or update its
+ /// cache.
//------------------------------------------------------------------
virtual void SectionFileAddressesChanged();
//------------------------------------------------------------------
/// Load an object file from memory.
///
- /// If available, the size of the object file in memory may be
- /// passed to avoid additional round trips to process memory.
- /// If the size is not provided, a default value is used. This
- /// value should be large enough to enable the ObjectFile plugins
- /// to read the header of the object file without going back to the
- /// process.
+ /// If available, the size of the object file in memory may be passed to
+ /// avoid additional round trips to process memory. If the size is not
+ /// provided, a default value is used. This value should be large enough to
+ /// enable the ObjectFile plugins to read the header of the object file
+ /// without going back to the process.
///
/// @return
/// The object file loaded from memory or nullptr, if the operation
//------------------------------------------------------------------
/// Get the symbol vendor interface for the current architecture.
///
- /// 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.
+ /// 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
/// If this module does not have a valid object file, or no
//------------------------------------------------------------------
/// Get a pointer to the UUID value contained in this object.
///
- /// If the executable image file doesn't not have a UUID value built
- /// into the file format, an MD5 checksum of the entire file, or
- /// slice of the file for the current architecture should be used.
+ /// If the executable image file doesn't not have a UUID value built into
+ /// the file format, an MD5 checksum of the entire file, or slice of the
+ /// file for the current architecture should be used.
///
/// @return
/// A const pointer to the internal copy of the UUID value in
/// A debugging function that will cause everything in a module to
/// be parsed.
///
- /// All compile units will be parsed, along with all globals and
- /// static variables and all functions for those compile units.
- /// All types, scopes, local variables, static variables, global
- /// variables, and line tables will be parsed. This can be used
- /// prior to dumping a module to see a complete list of the
- /// resulting debug information that gets parsed, or as a debug
- /// function to ensure that the module can consume all of the
- /// debug data the symbol vendor provides.
+ /// All compile units will be parsed, along with all globals and static
+ /// variables and all functions for those compile units. All types, scopes,
+ /// local variables, static variables, global variables, and line tables
+ /// will be parsed. This can be used prior to dumping a module to see a
+ /// complete list of the resulting debug information that gets parsed, or as
+ /// a debug function to ensure that the module can consume all of the debug
+ /// data the symbol vendor provides.
//------------------------------------------------------------------
void ParseAllDebugSymbols();
//------------------------------------------------------------------
/// Resolve the symbol context for the given address.
///
- /// Tries to resolve the matching symbol context based on a lookup
- /// from the current symbol vendor. If the lazy lookup fails,
- /// an attempt is made to parse the eh_frame section to handle
- /// stripped symbols. If this fails, an attempt is made to resolve
- /// the symbol to the previous address to handle the case of a
- /// function with a tail call.
+ /// Tries to resolve the matching symbol context based on a lookup from the
+ /// current symbol vendor. If the lazy lookup fails, an attempt is made to
+ /// parse the eh_frame section to handle stripped symbols. If this fails,
+ /// an attempt is made to resolve the symbol to the previous address to
+ /// handle the case of a function with a tail call.
///
- /// Use properties of the modified SymbolContext to inspect any
- /// resolved target, module, compilation unit, symbol, function,
- /// function block or line entry. Use the return value to determine
- /// which of these properties have been modified.
+ /// Use properties of the modified SymbolContext to inspect any resolved
+ /// target, module, compilation unit, symbol, function, function block or
+ /// line entry. Use the return value to determine which of these properties
+ /// have been modified.
///
/// @param[in] so_addr
/// A load address to resolve.
//------------------------------------------------------------------
/// Resolve items in the symbol context for a given file and line.
///
- /// Tries to resolve \a file_path and \a line to a list of matching
- /// symbol contexts.
+ /// Tries to resolve \a file_path and \a line to a list of matching symbol
+ /// contexts.
///
- /// The line table entries contains addresses that can be used to
- /// further resolve the values in each match: the function, block,
- /// symbol. Care should be taken to minimize the amount of
- /// information that is requested to only what is needed --
- /// typically the module, compile unit, line table and line table
- /// entry are sufficient.
+ /// The line table entries contains addresses that can be used to further
+ /// resolve the values in each match: the function, block, symbol. Care
+ /// should be taken to minimize the amount of information that is requested
+ /// to only what is needed -- typically the module, compile unit, line table
+ /// and line table entry are sufficient.
///
/// @param[in] file_path
/// A path to a source file to match. If \a file_path does not
//------------------------------------------------------------------
/// Resolve items in the symbol context for a given file and line.
///
- /// Tries to resolve \a file_spec and \a line to a list of matching
- /// symbol contexts.
+ /// Tries to resolve \a file_spec and \a line to a list of matching symbol
+ /// contexts.
///
- /// The line table entries contains addresses that can be used to
- /// further resolve the values in each match: the function, block,
- /// symbol. Care should be taken to minimize the amount of
- /// information that is requested to only what is needed --
- /// typically the module, compile unit, line table and line table
- /// entry are sufficient.
+ /// The line table entries contains addresses that can be used to further
+ /// resolve the values in each match: the function, block, symbol. Care
+ /// should be taken to minimize the amount of information that is requested
+ /// to only what is needed -- typically the module, compile unit, line table
+ /// and line table entry are sufficient.
///
/// @param[in] file_spec
/// A file spec to a source file to match. If \a file_path does
}
//------------------------------------------------------------------
- /// Finds a source file given a file spec using the module source
- /// path remappings (if any).
+ /// Finds a source file given a file spec using the module source path
+ /// remappings (if any).
///
/// Tries to resolve \a orig_spec by checking the module source path
- /// remappings. It makes sure the file exists, so this call can be
- /// expensive if the remappings are on a network file system, so
- /// use this function sparingly (not in a tight debug info parsing
- /// loop).
+ /// remappings. It makes sure the file exists, so this call can be expensive
+ /// 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
/// The original source file path to try and remap.
//------------------------------------------------------------------
/// Remaps a source file given \a path into \a new_path.
///
- /// Remaps \a path if any source remappings match. This function
- /// does NOT stat the file system so it can be used in tight loops
- /// where debug info is being parsed.
+ /// Remaps \a path if any source remappings match. This function does NOT
+ /// stat the file system so it can be used in tight loops where debug info
+ /// is being parsed.
///
/// @param[in] path
/// The original source file path to try and remap.
//----------------------------------------------------------------------
/// @class LookupInfo Module.h "lldb/Core/Module.h"
- /// @brief A class that encapsulates name lookup information.
- ///
- /// Users can type a wide variety of partial names when setting
- /// breakpoints by name or when looking for functions by name.
- /// SymbolVendor and SymbolFile objects are only required to implement
- /// name lookup for function basenames and for fully mangled names.
- /// This means if the user types in a partial name, we must reduce this
- /// to a name lookup that will work with all SymbolFile objects. So we
- /// might reduce a name lookup to look for a basename, and then prune
- /// out any results that don't match.
- ///
- /// The "m_name" member variable represents the name as it was typed
- /// by the user. "m_lookup_name" will be the name we actually search
- /// for through the symbol or objects files. Lanaguage is included in
- /// case we need to filter results by language at a later date. The
- /// "m_name_type_mask" member variable tells us what kinds of names we
- /// are looking for and can help us prune out unwanted results.
+ /// A class that encapsulates name lookup information.
+ ///
+ /// Users can type a wide variety of partial names when setting breakpoints
+ /// by name or when looking for functions by name. SymbolVendor and
+ /// SymbolFile objects are only required to implement name lookup for
+ /// function basenames and for fully mangled names. This means if the user
+ /// types in a partial name, we must reduce this to a name lookup that will
+ /// work with all SymbolFile objects. So we might reduce a name lookup to
+ /// look for a basename, and then prune out any results that don't match.
+ ///
+ /// The "m_name" member variable represents the name as it was typed by the
+ /// user. "m_lookup_name" will be the name we actually search for through
+ /// the symbol or objects files. Lanaguage is included in case we need to
+ /// filter results by language at a later date. The "m_name_type_mask"
+ /// member variable tells us what kinds of names we are looking for and can
+ /// help us prune out unwanted results.
///
/// Function lookups are done in Module.cpp, ModuleList.cpp and in
- /// BreakpointResolverName.cpp and they all now use this class to do
- /// lookups correctly.
+ /// BreakpointResolverName.cpp and they all now use this class to do lookups
+ /// correctly.
//----------------------------------------------------------------------
class LookupInfo {
public:
///
/// Tries to resolve \a vm_addr as a file address (if \a
/// vm_addr_is_file_addr is true) or as a load address if \a
- /// vm_addr_is_file_addr is false) in the symbol vendor.
- /// \a resolve_scope indicates what clients wish to resolve
- /// and can be used to limit the scope of what is parsed.
+ /// vm_addr_is_file_addr is false) in the symbol vendor. \a resolve_scope
+ /// indicates what clients wish to resolve and can be used to limit the
+ /// scope of what is parsed.
///
/// @param[in] vm_addr
/// The load virtual address to resolve.
//----------------------------------------------------------------------
/// @class ModuleChild ModuleChild.h "lldb/Core/ModuleChild.h"
-/// @brief A mix in class that contains a pointer back to the module
+/// A mix in class that contains a pointer back to the module
/// that owns the object which inherits from it.
//----------------------------------------------------------------------
class ModuleChild {
//----------------------------------------------------------------------
/// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
-/// @brief A collection class for Module objects.
+/// A collection class for Module objects.
///
-/// Modules in the module collection class are stored as reference
-/// counted shared pointers to Module objects.
+/// Modules in the module collection class are stored as reference counted
+/// shared pointers to Module objects.
//----------------------------------------------------------------------
class ModuleList {
public:
//------------------------------------------------------------------
/// Copy Constructor.
///
- /// Creates a new module list object with a copy of the modules from
- /// \a rhs.
+ /// Creates a new module list object with a copy of the modules from \a rhs.
///
/// @param[in] rhs
/// Another module list object.
void Append(const lldb::ModuleSP &module_sp);
//------------------------------------------------------------------
- /// Append a module to the module list and remove any equivalent
- /// modules. Equivalent modules are ones whose file, platform file
- /// and architecture matches.
+ /// Append a module to the module list and remove any equivalent modules.
+ /// Equivalent modules are ones whose file, platform file and architecture
+ /// matches.
///
/// Replaces the module to the collection.
///
//------------------------------------------------------------------
/// Clear the object's state.
///
- /// Clears the list of modules and releases a reference to each
- /// module object and if the reference count goes to zero, the
- /// module will be deleted.
+ /// Clears the list of modules and releases a reference to each module
+ /// object and if the reference count goes to zero, the module will be
+ /// deleted.
//------------------------------------------------------------------
void Clear();
//------------------------------------------------------------------
/// Clear the object's state.
///
- /// Clears the list of modules and releases a reference to each
- /// module object and if the reference count goes to zero, the
- /// module will be deleted. Also release all memory that might be
- /// held by any collection classes (like std::vector)
+ /// Clears the list of modules and releases a reference to each module
+ /// object and if the reference count goes to zero, the module will be
+ /// deleted. Also release all memory that might be held by any collection
+ /// classes (like std::vector)
//------------------------------------------------------------------
void Destroy();
//------------------------------------------------------------------
/// Dump the description of each module contained in this list.
///
- /// Dump the description of each module contained in this list to
- /// the supplied stream \a s.
+ /// Dump the description of each module contained in this list to the
+ /// supplied stream \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Get the module shared pointer for the module at index \a idx without
- /// acquiring the ModuleList mutex. This MUST already have been
- /// acquired with ModuleList::GetMutex and locked for this call to be safe.
+ /// acquiring the ModuleList mutex. This MUST already have been acquired
+ /// with ModuleList::GetMutex and locked for this call to be safe.
///
/// @param[in] idx
/// An index into this module collection.
Module *GetModulePointerAtIndex(size_t idx) const;
//------------------------------------------------------------------
- /// Get the module pointer for the module at index \a idx without
- /// acquiring the ModuleList mutex. This MUST already have been
- /// acquired with ModuleList::GetMutex and locked for this call to be safe.
+ /// Get the module pointer for the module at index \a idx without acquiring
+ /// the ModuleList mutex. This MUST already have been acquired with
+ /// ModuleList::GetMutex and locked for this call to be safe.
///
/// @param[in] idx
/// An index into this module collection.
//------------------------------------------------------------------
/// Find compile units by partial or full path.
///
- /// Finds all compile units that match \a path in all of the modules
- /// and returns the results in \a sc_list.
+ /// Finds all compile units that match \a path in all of the modules and
+ /// returns the results in \a sc_list.
///
/// @param[in] path
/// The name of the compile unit we are looking for.
VariableList &variable_list) const;
//------------------------------------------------------------------
- /// Finds the first module whose file specification matches \a
- /// file_spec.
+ /// Finds the first module whose file specification matches \a file_spec.
///
/// @param[in] file_spec_ptr
/// A file specification object to match against the Module's
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h"
-/// @brief Class that is driven by the SearchFilter to search the
-/// SymbolContext space of the target program.
+/// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h" Class that is
+/// driven by the SearchFilter to search the SymbolContext space of the target
+/// program.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
};
//----------------------------------------------------------------------
-/// @class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h"
-/// @brief 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.
+/// @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.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// Provides the callback and search depth for the SearchFilter search.
///
/// The search is done by cooperation between the search filter and the
-/// searcher.
-/// The search filter does the heavy work of recursing through the SymbolContext
-/// space of the target program's symbol space. The Searcher specifies the
-/// depth
-/// at which it wants its callback to be invoked. Note that since the
-/// resolution
-/// of the Searcher may be greater than that of the SearchFilter, before the
-/// Searcher qualifies an address it should pass it to "AddressPasses."
-/// The default implementation is "Everything Passes."
+/// searcher. The search filter does the heavy work of recursing through the
+/// SymbolContext space of the target program's symbol space. The Searcher
+/// specifies the depth at which it wants its callback to be invoked. Note
+/// that since the resolution of the Searcher may be greater than that of the
+/// SearchFilter, before the Searcher qualifies an address it should pass it
+/// to "AddressPasses." The default implementation is "Everything Passes."
//----------------------------------------------------------------------
class SearchFilter {
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.
+ /// 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
/// The file spec to check against the filter.
virtual void SearchInModuleList(Searcher &searcher, ModuleList &modules);
//------------------------------------------------------------------
- /// This determines which items are REQUIRED for the filter to pass.
- /// For instance, if you are filtering by Compilation Unit, obviously
- /// symbols that have no compilation unit can't pass So return
- /// eSymbolContextCU
- /// and search callbacks can then short cut the search to avoid looking at
+ /// This determines which items are REQUIRED for the filter to pass. For
+ /// instance, if you are filtering by Compilation Unit, obviously symbols
+ /// that have no compilation unit can't pass So return eSymbolContextCU and
+ /// search callbacks can then short cut the search to avoid looking at
/// things that obviously won't pass.
///
/// @return
//----------------------------------------------------------------------
/// @class SearchFilterForUnconstrainedSearches SearchFilter.h
-/// "lldb/Core/SearchFilter.h"
-/// @brief This is a SearchFilter that searches through all modules. It also
-/// consults the Target::ModuleIsExcludedForUnconstrainedSearches.
+/// "lldb/Core/SearchFilter.h" This is a SearchFilter that searches through
+/// all modules. It also consults the
+/// Target::ModuleIsExcludedForUnconstrainedSearches.
//----------------------------------------------------------------------
class SearchFilterForUnconstrainedSearches : public SearchFilter {
public:
};
//----------------------------------------------------------------------
-/// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h"
-/// @brief This is a SearchFilter that restricts the search to a given module.
+/// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h" This
+/// is a SearchFilter that restricts the search to a given module.
//----------------------------------------------------------------------
class SearchFilterByModule : public SearchFilter {
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DWARFExpression DWARFExpression.h "lldb/Expression/DWARFExpression.h"
-/// @brief Encapsulates a DWARF location expression and interprets it.
+/// @class DWARFExpression DWARFExpression.h
+/// "lldb/Expression/DWARFExpression.h" Encapsulates a DWARF location
+/// expression and interprets it.
///
/// DWARF location expressions are used in two ways by LLDB. The first
-/// use is to find entities specified in the debug information, since
-/// their locations are specified in precisely this language. The second
-/// is to interpret expressions without having to run the target in cases
-/// where the overhead from copying JIT-compiled code into the target is
-/// too high or where the target cannot be run. This class encapsulates
-/// a single DWARF location expression or a location list and interprets
-/// it.
+/// use is to find entities specified in the debug information, since their
+/// locations are specified in precisely this language. The second is to
+/// interpret expressions without having to run the target in cases where the
+/// overhead from copying JIT-compiled code into the target is too high or
+/// where the target cannot be run. This class encapsulates a single DWARF
+/// location expression or a location list and interprets it.
//----------------------------------------------------------------------
class DWARFExpression {
public:
//------------------------------------------------------------------
/// If a location is not a location list, return true if the location
- /// contains a DW_OP_addr () opcode in the stream that matches \a
- /// file_addr. If file_addr is LLDB_INVALID_ADDRESS, the this
- /// function will return true if the variable there is any DW_OP_addr
- /// in a location that (yet still is NOT a location list). This helps
- /// us detect if a variable is a global or static variable since
- /// there is no other indication from DWARF debug info.
+ /// contains a DW_OP_addr () opcode in the stream that matches \a file_addr.
+ /// If file_addr is LLDB_INVALID_ADDRESS, the this function will return true
+ /// if the variable there is any DW_OP_addr in a location that (yet still is
+ /// NOT a location list). This helps us detect if a variable is a global or
+ /// static variable since there is no other indication from DWARF debug
+ /// info.
///
/// @param[in] op_addr_idx
/// The DW_OP_addr index to retrieve in case there is more than
&link_address_callback);
//------------------------------------------------------------------
- /// Make the expression parser read its location information from a
- /// given data source. Does not change the offset and length
+ /// Make the expression parser read its location information from a given
+ /// data source. Does not change the offset and length
///
/// @param[in] data
/// A data extractor configured to read the DWARF location expression's
void SetOpcodeData(const DataExtractor &data);
//------------------------------------------------------------------
- /// Make the expression parser read its location information from a
- /// given data source
+ /// Make the expression parser read its location information from a given
+ /// data source
///
/// @param[in] module_sp
/// The module that defines the DWARF expression.
//------------------------------------------------------------------
/// Copy the DWARF location expression into a local buffer.
///
- /// It is a good idea to copy the data so we don't keep the entire
- /// object file worth of data around just for a few bytes of location
- /// expression. LLDB typically will mmap the entire contents of debug
- /// information files, and if we use SetOpcodeData, it will get a
- /// shared reference to all of this data for the and cause the object
- /// file to have to stay around. Even worse, a very very large ".a"
- /// that contains one or more .o files could end up being referenced.
- /// Location lists are typically small so even though we are copying
- /// the data, it shouldn't amount to that much for the variables we
- /// end up parsing.
+ /// It is a good idea to copy the data so we don't keep the entire object
+ /// file worth of data around just for a few bytes of location expression.
+ /// LLDB typically will mmap the entire contents of debug information files,
+ /// and if we use SetOpcodeData, it will get a shared reference to all of
+ /// this data for the and cause the object file to have to stay around. Even
+ /// worse, a very very large ".a" that contains one or more .o files could
+ /// end up being referenced. Location lists are typically small so even
+ /// though we are copying the data, it shouldn't amount to that much for the
+ /// variables we end up parsing.
///
/// @param[in] module_sp
/// The module that defines the DWARF expression.
//------------------------------------------------------------------
/// Wrapper for the static evaluate function that accepts an
- /// ExecutionContextScope instead of an ExecutionContext and uses
- /// member variables to populate many operands
+ /// ExecutionContextScope instead of an ExecutionContext and uses member
+ /// variables to populate many operands
//------------------------------------------------------------------
bool Evaluate(ExecutionContextScope *exe_scope,
lldb::addr_t loclist_base_load_addr,
Value &result, Status *error_ptr) const;
//------------------------------------------------------------------
- /// Wrapper for the static evaluate function that uses member
- /// variables to populate many operands
+ /// Wrapper for the static evaluate function that uses member variables to
+ /// populate many operands
//------------------------------------------------------------------
bool Evaluate(ExecutionContext *exe_ctx, RegisterContext *reg_ctx,
lldb::addr_t loclist_base_load_addr,
class RecordingMemoryManager;
//----------------------------------------------------------------------
-/// @class Expression Expression.h "lldb/Expression/Expression.h"
-/// @brief Encapsulates a single expression for use in lldb
+/// @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
-/// and as a backend for the expr command. Expression encapsulates
-/// the objects needed to parse and interpret or JIT an expression. It
-/// uses the expression parser appropriate to the language of the expression
-/// to produce LLVM IR from the expression.
+/// and as a backend for the expr command. Expression encapsulates the
+/// objects needed to parse and interpret or JIT an expression. It uses the
+/// expression parser appropriate to the language of the expression to produce
+/// LLVM IR from the expression.
//----------------------------------------------------------------------
class Expression {
public:
//------------------------------------------------------------------
/// Return the function name that should be used for executing the
- /// expression. Text() should contain the definition of this
- /// function.
+ /// expression. Text() should contain the definition of this function.
//------------------------------------------------------------------
virtual const char *FunctionName() = 0;
//------------------------------------------------------------------
- /// Return the language that should be used when parsing. To use
- /// the default, return eLanguageTypeUnknown.
+ /// Return the language that should be used when parsing. To use the
+ /// default, return eLanguageTypeUnknown.
//------------------------------------------------------------------
virtual lldb::LanguageType Language() { return lldb::eLanguageTypeUnknown; }
//------------------------------------------------------------------
- /// Return the desired result type of the function, or
- /// eResultTypeAny if indifferent.
+ /// Return the desired result type of the function, or eResultTypeAny if
+ /// indifferent.
//------------------------------------------------------------------
virtual ResultType DesiredResultType() { return eResultTypeAny; }
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// Return true if validation code should be inserted into the
- /// expression.
+ /// Return true if validation code should be inserted into the expression.
//------------------------------------------------------------------
virtual bool NeedsValidation() = 0;
//------------------------------------------------------------------
- /// Return true if external variables in the expression should be
- /// resolved.
+ /// Return true if external variables in the expression should be resolved.
//------------------------------------------------------------------
virtual bool NeedsVariableResolution() = 0;
//----------------------------------------------------------------------
/// @class ExpressionParser ExpressionParser.h
-/// "lldb/Expression/ExpressionParser.h"
-/// @brief Encapsulates an instance of a compiler that can parse expressions.
+/// "lldb/Expression/ExpressionParser.h" Encapsulates an instance of a
+/// compiler that can parse expressions.
///
/// ExpressionParser is the base class for llvm based Expression parsers.
//----------------------------------------------------------------------
virtual ~ExpressionParser(){};
//------------------------------------------------------------------
- /// Parse a single expression and convert it to IR using Clang. Don't
- /// wrap the expression in anything at all.
+ /// Parse a single expression and convert it to IR using Clang. Don't wrap
+ /// the expression in anything at all.
///
/// @param[in] diagnostic_manager
/// The diagnostic manager in which to store the errors and warnings.
//------------------------------------------------------------------
/// Try to use the FixIts in the diagnostic_manager to rewrite the
- /// expression. If successful, the rewritten expression is stored
- /// in the diagnostic_manager, get it out with GetFixedExpression.
+ /// expression. If successful, the rewritten expression is stored in the
+ /// diagnostic_manager, get it out with GetFixedExpression.
///
/// @param[in] diagnostic_manager
/// The diagnostic manager containing fixit's to apply.
}
//------------------------------------------------------------------
- /// Ready an already-parsed expression for execution, possibly
- /// evaluating it statically.
+ /// Ready an already-parsed expression for execution, possibly evaluating it
+ /// statically.
///
/// @param[out] func_addr
/// The address to which the function has been written.
//----------------------------------------------------------------------
/// @class ExpressionTypeSystemHelper ExpressionTypeSystemHelper.h
/// "lldb/Expression/ExpressionTypeSystemHelper.h"
-/// @brief A helper object that the Expression can pass to its ExpressionParser
+/// A helper object that the Expression can pass to its ExpressionParser
/// to provide generic information that
/// any type of expression will need to supply. It's only job is to support
-/// dyn_cast so that the expression parser
-/// can cast it back to the requisite specific type.
+/// dyn_cast so that the expression parser can cast it back to the requisite
+/// specific type.
///
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class ExpressionVariableList ExpressionVariable.h
/// "lldb/Expression/ExpressionVariable.h"
-/// @brief A list of variable references.
+/// A list of variable references.
///
/// This class stores variables internally, acting as the permanent store.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h"
-/// @brief Encapsulates a function that can be called.
+/// Encapsulates a function that can be called.
///
/// A given FunctionCaller object can handle a single function signature.
/// Once constructed, it can set up any number of concurrent calls to
/// struct with the written arguments. This method lets Clang handle the
/// vagaries of function calling conventions.
///
-/// The simplest use of the FunctionCaller is to construct it with a
-/// function representative of the signature you want to use, then call
+/// The simplest use of the FunctionCaller is to construct it with a function
+/// representative of the signature you want to use, then call
/// ExecuteFunction(ExecutionContext &, Stream &, Value &).
///
/// If you need to reuse the arguments for several calls, you can call
/// If you need to call the function on the thread plan stack, you can also
/// call InsertFunction() followed by GetThreadPlanToCallFunction().
///
-/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed
-/// a pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated
+/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a
+/// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated
/// and its address returned in that variable.
///
/// Any of the methods that take arg_addr_ptr can be passed nullptr, and the
DiagnosticManager &diagnostic_manager);
//------------------------------------------------------------------
- /// Insert an argument struct with a non-default function address and
- /// non-default argument values
+ /// Insert an argument struct with a non-default function address and non-
+ /// default argument values
///
/// @param[in] exe_ctx
/// The execution context to insert the function and its arguments
//------------------------------------------------------------------
/// Return the function name that should be used for executing the
- /// expression. Text() should contain the definition of this
- /// function.
+ /// expression. Text() should contain the definition of this function.
//------------------------------------------------------------------
const char *FunctionName() override {
return m_wrapper_function_name.c_str();
}
//------------------------------------------------------------------
- /// Return the object that the parser should use when registering
- /// local variables. May be nullptr if the Expression doesn't care.
+ /// Return the object that the parser should use when registering local
+ /// variables. May be nullptr if the Expression doesn't care.
//------------------------------------------------------------------
ExpressionVariableList *LocalVariables() { return nullptr; }
//------------------------------------------------------------------
- /// Return true if validation code should be inserted into the
- /// expression.
+ /// Return true if validation code should be inserted into the expression.
//------------------------------------------------------------------
bool NeedsValidation() override { return false; }
//------------------------------------------------------------------
- /// Return true if external variables in the expression should be
- /// resolved.
+ /// Return true if external variables in the expression should be resolved.
//------------------------------------------------------------------
bool NeedsVariableResolution() override { return false; }
//----------------------------------------------------------------------
/// @class DynamicCheckerFunctions IRDynamicChecks.h
-/// "lldb/Expression/IRDynamicChecks.h"
-/// @brief Encapsulates dynamic check functions used by expressions.
+/// "lldb/Expression/IRDynamicChecks.h" Encapsulates dynamic check functions
+/// used by expressions.
///
/// Each of the utility functions encapsulated in this class is responsible
-/// for validating some data that an expression is about to use. Examples are:
+/// for validating some data that an expression is about to use. Examples
+/// are:
///
-/// a = *b; // check that b is a valid pointer
-/// [b init]; // check that b is a valid object to send "init" to
+/// a = *b; // check that b is a valid pointer [b init]; // check that b
+/// is a valid object to send "init" to
///
-/// The class installs each checker function into the target process and
-/// makes it available to IRDynamicChecks to use.
+/// The class installs each checker function into the target process and makes
+/// it available to IRDynamicChecks to use.
//----------------------------------------------------------------------
class DynamicCheckerFunctions {
public:
~DynamicCheckerFunctions();
//------------------------------------------------------------------
- /// Install the utility functions into a process. This binds the
- /// instance of DynamicCheckerFunctions to that process.
+ /// Install the utility functions into a process. This binds the instance
+ /// of DynamicCheckerFunctions to that process.
///
/// @param[in] diagnostic_manager
/// A diagnostic manager to report errors to.
};
//----------------------------------------------------------------------
-/// @class IRDynamicChecks IRDynamicChecks.h "lldb/Expression/IRDynamicChecks.h"
-/// @brief Adds dynamic checks to a user-entered expression to reduce its
-/// likelihood of crashing
+/// @class IRDynamicChecks IRDynamicChecks.h
+/// "lldb/Expression/IRDynamicChecks.h" Adds dynamic checks to a user-entered
+/// expression to reduce its likelihood of crashing
///
/// When an IR function is executed in the target process, it may cause
-/// crashes or hangs by dereferencing NULL pointers, trying to call Objective-C
-/// methods on objects that do not respond to them, and so forth.
+/// crashes or hangs by dereferencing NULL pointers, trying to call
+/// Objective-C methods on objects that do not respond to them, and so forth.
///
-/// IRDynamicChecks adds calls to the functions in DynamicCheckerFunctions
-/// to appropriate locations in an expression's IR.
+/// IRDynamicChecks adds calls to the functions in DynamicCheckerFunctions to
+/// appropriate locations in an expression's IR.
//----------------------------------------------------------------------
class IRDynamicChecks : public llvm::ModulePass {
public:
class Status;
//----------------------------------------------------------------------
-/// @class IRExecutionUnit IRExecutionUnit.h "lldb/Expression/IRExecutionUnit.h"
-/// @brief Contains the IR and, optionally, JIT-compiled code for a module.
+/// @class IRExecutionUnit IRExecutionUnit.h
+/// "lldb/Expression/IRExecutionUnit.h" Contains the IR and, optionally, JIT-
+/// compiled code for a module.
///
-/// This class encapsulates the compiled version of an expression, in IR
-/// form (for interpretation purposes) and in raw machine code form (for
-/// execution in the target).
+/// This class encapsulates the compiled version of an expression, in IR form
+/// (for interpretation purposes) and in raw machine code form (for execution
+/// in the target).
///
-/// This object wraps an IR module that comes from the expression parser,
-/// and knows how to use the JIT to make it into executable code. It can
-/// then be used as input to the IR interpreter, or the address of the
-/// executable code can be passed to a thread plan to run in the target.
+/// This object wraps an IR module that comes from the expression parser, and
+/// knows how to use the JIT to make it into executable code. It can then be
+/// used as input to the IR interpreter, or the address of the executable code
+/// can be passed to a thread plan to run in the target.
///
/// This class creates a subclass of LLVM's SectionMemoryManager, because that
-/// is
-/// how the JIT emits code. Because LLDB needs to move JIT-compiled code
-/// into the target process, the IRExecutionUnit knows how to copy the
-/// emitted code into the target process.
+/// is how the JIT emits code. Because LLDB needs to move JIT-compiled code
+/// into the target process, the IRExecutionUnit knows how to copy the emitted
+/// code into the target process.
//----------------------------------------------------------------------
class IRExecutionUnit : public std::enable_shared_from_this<IRExecutionUnit>,
public IRMemoryMap,
lldb::addr_t &func_end);
//------------------------------------------------------------------
- /// Accessors for IRForTarget and other clients that may want binary
- /// data placed on their behalf. The binary data is owned by the
- /// IRExecutionUnit unless the client explicitly chooses to free it.
+ /// Accessors for IRForTarget and other clients that may want binary data
+ /// placed on their behalf. The binary data is owned by the IRExecutionUnit
+ /// unless the client explicitly chooses to free it.
//------------------------------------------------------------------
lldb::addr_t WriteNow(const uint8_t *bytes, size_t size, Status &error);
//----------------------------------------------------------------------
/// @class JittedFunction IRExecutionUnit.h
/// "lldb/Expression/IRExecutionUnit.h"
- /// @brief Encapsulates a single function that has been generated by the JIT.
+ /// Encapsulates a single function that has been generated by the JIT.
///
/// Functions that have been generated by the JIT are first resident in the
/// local process, and then placed in the target process. JittedFunction
private:
//------------------------------------------------------------------
- /// Look up the object in m_address_map that contains a given address,
- /// find where it was copied to, and return the remote address at the
- /// same offset into the copied entity
+ /// Look up the object in m_address_map that contains a given address, find
+ /// where it was copied to, and return the remote address at the same offset
+ /// into the copied entity
///
/// @param[in] local_address
/// The address in the debugger.
lldb::addr_t GetRemoteAddressForLocal(lldb::addr_t local_address);
//------------------------------------------------------------------
- /// Look up the object in m_address_map that contains a given address,
- /// find where it was copied to, and return its address range in the
- /// target process
+ /// Look up the object in m_address_map that contains a given address, find
+ /// where it was copied to, and return its address range in the target
+ /// process
///
/// @param[in] local_address
/// The address in the debugger.
~MemoryManager() override;
//------------------------------------------------------------------
- /// Allocate space for executable code, and add it to the
- /// m_spaceBlocks map
+ /// Allocate space for executable code, and add it to the m_spaceBlocks
+ /// map
///
/// @param[in] Size
/// The size of the area.
bool IsReadOnly) override;
//------------------------------------------------------------------
- /// Called when object loading is complete and section page
- /// permissions can be applied. Currently unimplemented for LLDB.
+ /// Called when object loading is complete and section page permissions
+ /// can be applied. Currently unimplemented for LLDB.
///
/// @param[out] ErrMsg
/// The error that prevented the page protection from succeeding.
//----------------------------------------------------------------------
/// @class AllocationRecord IRExecutionUnit.h
- /// "lldb/Expression/IRExecutionUnit.h"
- /// @brief Encapsulates a single allocation request made by the JIT.
+ /// "lldb/Expression/IRExecutionUnit.h" Encapsulates a single allocation
+ /// request made by the JIT.
///
- /// Allocations made by the JIT are first queued up and then applied in
- /// bulk to the underlying process.
+ /// Allocations made by the JIT are first queued up and then applied in bulk
+ /// to the underlying process.
//----------------------------------------------------------------------
enum class AllocationKind { Stub, Code, Data, Global, Bytes };
//----------------------------------------------------------------------
/// @class IRInterpreter IRInterpreter.h "lldb/Expression/IRInterpreter.h"
-/// @brief Attempt to interpret the function's code if it does not require
+/// Attempt to interpret the function's code if it does not require
/// running the target.
///
-/// In some cases, the IR for an expression can be evaluated entirely
-/// in the debugger, manipulating variables but not executing any code
-/// in the target. The IRInterpreter attempts to do this.
+/// In some cases, the IR for an expression can be evaluated entirely in the
+/// debugger, manipulating variables but not executing any code in the target.
+/// The IRInterpreter attempts to do this.
//----------------------------------------------------------------------
class IRInterpreter {
public:
//----------------------------------------------------------------------
/// @class IRMemoryMap IRMemoryMap.h "lldb/Expression/IRMemoryMap.h"
-/// @brief Encapsulates memory that may exist in the process but must
+/// Encapsulates memory that may exist in the process but must
/// also be available in the host process.
///
-/// This class encapsulates a group of memory objects that must be readable
-/// or writable from the host process regardless of whether the process
-/// exists. This allows the IR interpreter as well as JITted code to access
-/// the same memory. All allocations made by this class are represented as
-/// disjoint intervals.
+/// This class encapsulates a group of memory objects that must be readable or
+/// writable from the host process regardless of whether the process exists.
+/// This allows the IR interpreter as well as JITted code to access the same
+/// memory. All allocations made by this class are represented as disjoint
+/// intervals.
///
/// Point queries against this group of memory objects can be made by the
-/// address in the tar at which they reside. If the inferior does not
-/// exist, allocations still get made-up addresses. If an inferior appears
-/// at some point, then those addresses need to be re-mapped.
+/// address in the tar at which they reside. If the inferior does not exist,
+/// allocations still get made-up addresses. If an inferior appears at some
+/// point, then those addresses need to be re-mapped.
//----------------------------------------------------------------------
class IRMemoryMap {
public:
//----------------------------------------------------------------------
/// @class LLVMUserExpression LLVMUserExpression.h
-/// "lldb/Expression/LLVMUserExpression.h"
-/// @brief Encapsulates a one-time expression for use in lldb.
+/// "lldb/Expression/LLVMUserExpression.h" Encapsulates a one-time expression
+/// for use in lldb.
///
/// LLDB uses expressions for various purposes, notably to call functions
-/// and as a backend for the expr command. LLVMUserExpression is a virtual base
-/// class that encapsulates the objects needed to parse and JIT an expression.
-/// The actual parsing part will be provided by the specific implementations
-/// of LLVMUserExpression - which will be vended through the appropriate
-/// TypeSystem.
+/// and as a backend for the expr command. LLVMUserExpression is a virtual
+/// base class that encapsulates the objects needed to parse and JIT an
+/// expression. The actual parsing part will be provided by the specific
+/// implementations of LLVMUserExpression - which will be vended through the
+/// appropriate TypeSystem.
//----------------------------------------------------------------------
class LLVMUserExpression : public UserExpression {
public:
//----------------------------------------------------------------------
/// @class UserExpression UserExpression.h "lldb/Expression/UserExpression.h"
-/// @brief Encapsulates a one-time expression for use in lldb.
+/// Encapsulates a one-time expression for use in lldb.
///
/// LLDB uses expressions for various purposes, notably to call functions
/// and as a backend for the expr command. UserExpression is a virtual base
bool MatchesContext(ExecutionContext &exe_ctx);
//------------------------------------------------------------------
- /// Execute the parsed expression by callinng the derived class's
- /// DoExecute method.
+ /// Execute the parsed expression by callinng the derived class's DoExecute
+ /// method.
///
/// @param[in] diagnostic_manager
/// A diagnostic manager to report errors to.
//------------------------------------------------------------------
/// Return the function name that should be used for executing the
- /// expression. Text() should contain the definition of this
- /// function.
+ /// expression. Text() should contain the definition of this function.
//------------------------------------------------------------------
const char *FunctionName() override { return "$__lldb_expr"; }
//------------------------------------------------------------------
- /// Return the language that should be used when parsing. To use
- /// the default, return eLanguageTypeUnknown.
+ /// Return the language that should be used when parsing. To use the
+ /// default, return eLanguageTypeUnknown.
//------------------------------------------------------------------
lldb::LanguageType Language() override { return m_language; }
//------------------------------------------------------------------
- /// Return the desired result type of the function, or
- /// eResultTypeAny if indifferent.
+ /// Return the desired result type of the function, or eResultTypeAny if
+ /// indifferent.
//------------------------------------------------------------------
ResultType DesiredResultType() override { return m_desired_type; }
//------------------------------------------------------------------
- /// Return true if validation code should be inserted into the
- /// expression.
+ /// Return true if validation code should be inserted into the expression.
//------------------------------------------------------------------
bool NeedsValidation() override { return true; }
//------------------------------------------------------------------
- /// Return true if external variables in the expression should be
- /// resolved.
+ /// Return true if external variables in the expression should be resolved.
//------------------------------------------------------------------
bool NeedsVariableResolution() override { return true; }
virtual lldb::ModuleSP GetJITModule() { return lldb::ModuleSP(); }
//------------------------------------------------------------------
- /// Evaluate one expression in the scratch context of the
- /// target passed in the exe_ctx and return its result.
+ /// Evaluate one expression in the scratch context of the target passed in
+ /// the exe_ctx and return its result.
///
/// @param[in] exe_ctx
/// The execution context to use when evaluating the expression.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class UtilityFunction UtilityFunction.h "lldb/Expression/UtilityFunction.h"
-/// @brief Encapsulates a bit of source code that provides a function that is
-/// callable
+/// @class UtilityFunction UtilityFunction.h
+/// "lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that
+/// provides a function that is callable
///
/// LLDB uses expressions for various purposes, notably to call functions
-/// and as a backend for the expr command. UtilityFunction encapsulates
-/// a self-contained function meant to be used from other code. Utility
+/// and as a backend for the expr command. UtilityFunction encapsulates a
+/// self-contained function meant to be used from other code. Utility
/// functions can perform error-checking for ClangUserExpressions,
//----------------------------------------------------------------------
class UtilityFunction : public Expression {
/// Check whether the given PC is inside the function
///
/// Especially useful if the function dereferences nullptr to indicate a
- /// failed
- /// assert.
+ /// failed assert.
///
/// @param[in] pc
/// The program counter to check.
//------------------------------------------------------------------
/// Return the function name that should be used for executing the
- /// expression. Text() should contain the definition of this
- /// function.
+ /// expression. Text() should contain the definition of this function.
//------------------------------------------------------------------
const char *FunctionName() override { return m_function_name.c_str(); }
//------------------------------------------------------------------
- /// Return the object that the parser should use when registering
- /// local variables. May be nullptr if the Expression doesn't care.
+ /// Return the object that the parser should use when registering local
+ /// variables. May be nullptr if the Expression doesn't care.
//------------------------------------------------------------------
ExpressionVariableList *LocalVariables() { return nullptr; }
//------------------------------------------------------------------
- /// Return true if validation code should be inserted into the
- /// expression.
+ /// Return true if validation code should be inserted into the expression.
//------------------------------------------------------------------
bool NeedsValidation() override { return false; }
//------------------------------------------------------------------
- /// Return true if external variables in the expression should be
- /// resolved.
+ /// Return true if external variables in the expression should be resolved.
//------------------------------------------------------------------
bool NeedsVariableResolution() override { return false; }
//----------------------------------------------------------------------
/// @class File File.h "lldb/Host/File.h"
-/// @brief A file class.
+/// A file class.
///
/// A file class that divides abstracts the LLDB core from host file
/// functionality.
//------------------------------------------------------------------
/// Constructor with path.
///
- /// Takes a path to a file which can be just a filename, or a full
- /// path. If \a path is not nullptr or empty, this function will call
- /// File::Open (const char *path, uint32_t options, uint32_t permissions).
+ /// Takes a path to a file which can be just a filename, or a full path. If
+ /// \a path is not nullptr or empty, this function will call File::Open
+ /// (const char *path, uint32_t options, uint32_t permissions).
///
/// @param[in] path
/// The full or partial path to a file.
/// @param[in] permissions
/// Options to use when opening (see File::Permissions)
///
- /// @see File::Open (const char *path, uint32_t options, uint32_t permissions)
+ /// @see File::Open (const char *path, uint32_t options, uint32_t
+ /// permissions)
//------------------------------------------------------------------
File(const char *path, uint32_t options,
uint32_t permissions = lldb::eFilePermissionsFileDefault);
/// Constructor with FileSpec.
///
/// Takes a FileSpec pointing to a file which can be just a filename, or a
- /// full
- /// path. If \a path is not nullptr or empty, this function will call
+ /// full path. If \a path is not nullptr or empty, this function will call
/// File::Open (const char *path, uint32_t options, uint32_t permissions).
///
/// @param[in] filespec
/// @param[in] permissions
/// Options to use when opening (see File::Permissions)
///
- /// @see File::Open (const char *path, uint32_t options, uint32_t permissions)
+ /// @see File::Open (const char *path, uint32_t options, uint32_t
+ /// permissions)
//------------------------------------------------------------------
File(const FileSpec &filespec, uint32_t options,
uint32_t permissions = lldb::eFilePermissionsFileDefault);
//------------------------------------------------------------------
/// Convert to pointer operator.
///
- /// This allows code to check a File object to see if it
- /// contains anything valid using code such as:
+ /// This allows code to check a File object to see if it contains anything
+ /// valid using code such as:
///
/// @code
/// File file(...);
//------------------------------------------------------------------
/// Logical NOT operator.
///
- /// This allows code to check a File object to see if it is
- /// invalid using code such as:
+ /// This allows code to check a File object to see if it is invalid using
+ /// code such as:
///
/// @code
/// File file(...);
//------------------------------------------------------------------
/// Open a file for read/writing with the specified options.
///
- /// Takes a path to a file which can be just a filename, or a full
- /// path.
+ /// Takes a path to a file which can be just a filename, or a full path.
///
/// @param[in] path
/// The full or partial path to a file.
/// Read bytes from a file from the current file position.
///
/// NOTE: This function is NOT thread safe. Use the read function
- /// that takes an "off_t &offset" to ensure correct operation in
- /// multi-threaded environments.
+ /// that takes an "off_t &offset" to ensure correct operation in multi-
+ /// threaded environments.
///
/// @param[in] buf
/// A buffer where to put the bytes that are read.
/// Write bytes to a file at the current file position.
///
/// NOTE: This function is NOT thread safe. Use the write function
- /// that takes an "off_t &offset" to ensure correct operation in
- /// multi-threaded environments.
+ /// that takes an "off_t &offset" to ensure correct operation in multi-
+ /// threaded environments.
///
/// @param[in] buf
/// A buffer where to put the bytes that are read.
/// Seek to an offset relative to the beginning of the file.
///
/// 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 *, size_t, off_t &)
+ /// 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 *,
+ /// size_t, off_t &)
///
/// @param[in] offset
/// The offset to seek to within the file relative to the
/// Seek to an offset relative to the current file position.
///
/// 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 *, size_t, off_t &)
+ /// 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 *,
+ /// size_t, off_t &)
///
/// @param[in] offset
/// The offset to seek to within the file relative to the
/// Seek to an offset relative to the end of the file.
///
/// 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 *, size_t, off_t &)
+ /// 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 *,
+ /// size_t, off_t &)
///
/// @param[in,out] offset
/// The offset to seek to within the file relative to the
/// Read bytes from a file from the specified file offset.
///
/// NOTE: This function is thread safe in that clients manager their
- /// own file position markers and reads on other threads won't mess
- /// up the current read.
+ /// own file position markers and reads on other threads won't mess up the
+ /// current read.
///
/// @param[in] dst
/// A buffer where to put the bytes that are read.
/// Read bytes from a file from the specified file offset.
///
/// NOTE: This function is thread safe in that clients manager their
- /// own file position markers and reads on other threads won't mess
- /// up the current read.
+ /// own file position markers and reads on other threads won't mess up the
+ /// current read.
///
/// @param[in,out] num_bytes
/// The number of bytes to read form the current file position
/// Write bytes to a file at the specified file offset.
///
/// NOTE: This function is thread safe in that clients manager their
- /// own file position markers, though clients will need to implement
- /// their own locking externally to avoid multiple people writing
- /// to the file at the same time.
+ /// own file position markers, though clients will need to implement their
+ /// own locking externally to avoid multiple people writing to the file at
+ /// the same time.
///
/// @param[in] src
/// A buffer containing the bytes to write.
//------------------------------------------------------------------
/// Return true if this file from a real terminal.
///
- /// Just knowing a file is a interactive isn't enough, we also need
- /// to know if the terminal has a width and height so we can do
- /// cursor movement and other terminal manipulations by sending
- /// escape sequences.
+ /// Just knowing a file is a interactive isn't enough, we also need to know
+ /// if the terminal has a width and height so we can do cursor movement and
+ /// other terminal manipulations by sending escape sequences.
///
/// @return
/// True if this file is a terminal (tty, not a pty) that has
//----------------------------------------------------------------------
/// @class Host Host.h "lldb/Host/Host.h"
-/// @brief A class that provides host computer information.
+/// A class that provides host computer information.
///
-/// Host is a class that answers information about the host operating
-/// system.
+/// Host is a class that answers information about the host operating system.
//----------------------------------------------------------------------
class Host {
public:
//------------------------------------------------------------------
/// Start monitoring a child process.
///
- /// Allows easy monitoring of child processes. \a callback will be
- /// called when the child process exits or if it gets a signal. The
- /// callback will only be called with signals if \a monitor_signals
- /// is \b true. \a callback will usually be called from another
- /// thread so the callback function must be thread safe.
+ /// Allows easy monitoring of child processes. \a callback will be called
+ /// when the child process exits or if it gets a signal. The callback will
+ /// only be called with signals if \a monitor_signals is \b true. \a
+ /// callback will usually be called from another thread so the callback
+ /// function must be thread safe.
///
- /// When the callback gets called, the return value indicates if
- /// monitoring should stop. If \b true is returned from \a callback
- /// the information will be removed. If \b false is returned then
- /// monitoring will continue. If the child process exits, the
- /// monitoring will automatically stop after the callback returned
- /// regardless of the callback return value.
+ /// When the callback gets called, the return value indicates if monitoring
+ /// should stop. If \b true is returned from \a callback the information
+ /// will be removed. If \b false is returned then monitoring will continue.
+ /// If the child process exits, the monitoring will automatically stop after
+ /// the callback returned regardless of the callback return value.
///
/// @param[in] callback
/// A function callback to call when a child receives a signal
static void Kill(lldb::pid_t pid, int signo);
//------------------------------------------------------------------
- /// Get the thread token (the one returned by ThreadCreate when the thread was
- /// created) for the
- /// calling thread in the current process.
+ /// Get the thread token (the one returned by ThreadCreate when the thread
+ /// was created) for the calling thread in the current process.
///
/// @return
/// The thread token for the calling thread in the current process.
static const char *GetSignalAsCString(int signo);
//------------------------------------------------------------------
- /// Given an address in the current process (the process that
- /// is running the LLDB code), return the name of the module that
- /// it comes from. This can be useful when you need to know the
- /// path to the shared library that your code is running in for
- /// loading resources that are relative to your binary.
+ /// Given an address in the current process (the process that is running the
+ /// LLDB code), return the name of the module that it comes from. This can
+ /// be useful when you need to know the path to the shared library that your
+ /// code is running in for loading resources that are relative to your
+ /// binary.
///
/// @param[in] host_addr
/// The pointer to some code in the current process.
static FileSpec GetModuleFileSpecForHostAddress(const void *host_addr);
//------------------------------------------------------------------
- /// If you have an executable that is in a bundle and want to get
- /// back to the bundle directory from the path itself, this
- /// function will change a path to a file within a bundle to the
- /// bundle directory itself.
+ /// If you have an executable that is in a bundle and want to get back to
+ /// 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
/// A file spec that might point to a file in a bundle.
FileSpec &bundle_directory);
//------------------------------------------------------------------
- /// When executable files may live within a directory, where the
- /// directory represents an executable bundle (like the MacOSX
- /// app bundles), then locate the executable within the containing
- /// bundle.
+ /// When executable files may live within a directory, where the directory
+ /// represents an executable bundle (like the MacOSX app bundles), then
+ /// locate the executable within the containing bundle.
///
/// @param[in,out] file
/// A file spec that currently points to the bundle that will
static Status LaunchProcess(ProcessLaunchInfo &launch_info);
//------------------------------------------------------------------
- /// Perform expansion of the command-line for this launch info
- /// This can potentially involve wildcard expansion
+ /// Perform expansion of the command-line for this launch info This can
+ /// potentially involve wildcard expansion
// environment variable replacement, and whatever other
// argument magic the platform defines as part of its typical
// user experience
namespace llvm {
template <> struct format_provider<lldb_private::WaitStatus> {
- /// Options = "" gives a human readable description of the status
- /// Options = "g" gives a gdb-remote protocol status (e.g., X09)
+ /// Options = "" gives a human readable description of the status Options =
+ /// "g" gives a gdb-remote protocol status (e.g., X09)
static void format(const lldb_private::WaitStatus &WS, raw_ostream &OS,
llvm::StringRef Options);
};
//----------------------------------------------------------------------
/// @class HostInfo HostInfo.h "lldb/Host/HostInfo.h"
-/// @brief A class that provides host computer information.
+/// A class that provides host computer information.
///
/// HostInfo is a class that answers information about the host operating
/// system. Note that HostInfo is NOT intended to be used to manipulate or
/// HostInfoWindows) in a separate file, and then typedefed to HostInfo here.
/// Users of the class reference it as HostInfo::method().
///
-/// Not all hosts provide the same functionality. It is important that methods
-/// only be implemented at the lowest level at which they make sense. It should
-/// be up to the clients of the class to ensure that they not attempt to call a
-/// method which doesn't make sense for a particular platform. For example,
-/// when implementing a method that only makes sense on a posix-compliant
-/// system, implement it on HostInfoPosix, and not on HostInfoBase with a
-/// default implementation. This way, users of HostInfo are required to think
-/// about the implications of calling a particular method and if used in a
-/// context where the method doesn't make sense, will generate a compiler error.
+/// Not all hosts provide the same functionality. It is important that
+/// methods only be implemented at the lowest level at which they make sense.
+/// It should be up to the clients of the class to ensure that they not
+/// attempt to call a method which doesn't make sense for a particular
+/// platform. For example, when implementing a method that only makes sense
+/// on a posix-compliant system, implement it on HostInfoPosix, and not on
+/// HostInfoBase with a default implementation. This way, users of HostInfo
+/// are required to think about the implications of calling a particular
+/// method and if used in a context where the method doesn't make sense, will
+/// generate a compiler error.
///
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class HostInfo HostInfo.h "lldb/Host/HostProcess.h"
-/// @brief A class that represents a running process on the host machine.
+/// A class that represents a running process on the host machine.
///
/// HostProcess allows querying and manipulation of processes running on the
-/// host machine. It is not intended to be represent a process which is
-/// being debugged, although the native debug engine of a platform may likely
-/// back inferior processes by a HostProcess.
+/// host machine. It is not intended to be represent a process which is being
+/// debugged, although the native debug engine of a platform may likely back
+/// inferior processes by a HostProcess.
///
/// HostProcess is implemented using static polymorphism so that on any given
-/// platform, an instance of HostProcess will always be able to bind statically
-/// to the concrete Process implementation for that platform. See HostInfo
-/// for more details.
+/// platform, an instance of HostProcess will always be able to bind
+/// statically to the concrete Process implementation for that platform. See
+/// HostInfo for more details.
///
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class HostInfo HostInfo.h "lldb/Host/HostThread.h"
-/// @brief A class that represents a thread running inside of a process on the
+/// A class that represents a thread running inside of a process on the
/// local machine.
///
/// HostThread allows querying and manipulation of threads running on the host
//----------------------------------------------------------------------
/// @class Predicate Predicate.h "lldb/Host/Predicate.h"
-/// @brief A C++ wrapper class for providing threaded access to a value
-/// of type T.
+/// A C++ wrapper class for providing threaded access to a value of
+/// type T.
///
/// A templatized class that provides multi-threaded access to a value
/// of type T. Threads can efficiently wait for bits within T to be set
//----------------------------------------------------------------------
/// @class ProcessRunLock ProcessRunLock.h "lldb/Host/ProcessRunLock.h"
-/// @brief 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.
+/// 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.
//----------------------------------------------------------------------
class ProcessRunLock {
//----------------------------------------------------------------------
/// @class PseudoTerminal PseudoTerminal.h "lldb/Host/PseudoTerminal.h"
-/// @brief A pseudo terminal helper class.
+/// A pseudo terminal helper class.
///
-/// The pseudo terminal class abstracts the use of pseudo terminals on
-/// the host system.
+/// The pseudo terminal class abstracts the use of pseudo terminals on the
+/// host system.
//----------------------------------------------------------------------
class PseudoTerminal {
public:
//------------------------------------------------------------------
/// Default constructor
///
- /// Constructs this object with invalid master and slave file
- /// descriptors.
+ /// Constructs this object with invalid master and slave file descriptors.
//------------------------------------------------------------------
PseudoTerminal();
//------------------------------------------------------------------
/// Destructor
///
- /// The destructor will close the master and slave file descriptors
- /// if they are valid and ownership has not been released using
- /// one of:
- /// @li PseudoTerminal::ReleaseMasterFileDescriptor()
- /// @li PseudoTerminal::ReleaseSaveFileDescriptor()
+ /// The destructor will close the master and slave file descriptors if they
+ /// are valid and ownership has not been released using one of: @li
+ /// PseudoTerminal::ReleaseMasterFileDescriptor() @li
+ /// PseudoTerminal::ReleaseSaveFileDescriptor()
//------------------------------------------------------------------
~PseudoTerminal();
//------------------------------------------------------------------
/// Fork a child process that uses pseudo terminals for its stdio.
///
- /// In the parent process, a call to this function results in a pid
- /// being returned. If the pid is valid, the master file descriptor
- /// can be used for read/write access to stdio of the child process.
+ /// In the parent process, a call to this function results in a pid being
+ /// returned. If the pid is valid, the master file descriptor can be used
+ /// for read/write access to stdio of the child process.
///
- /// In the child process the stdin/stdout/stderr will already be
- /// routed to the slave pseudo terminal and the master file
- /// descriptor will be closed as it is no longer needed by the child
- /// process.
+ /// In the child process the stdin/stdout/stderr will already be routed to
+ /// the slave pseudo terminal and the master file descriptor will be closed
+ /// as it is no longer needed by the child process.
///
- /// This class will close the file descriptors for the master/slave
- /// when the destructor is called. The file handles can be released
- /// using either:
- /// @li PseudoTerminal::ReleaseMasterFileDescriptor()
- /// @li PseudoTerminal::ReleaseSaveFileDescriptor()
+ /// This class will close the file descriptors for the master/slave when the
+ /// destructor is called. The file handles can be released using either: @li
+ /// PseudoTerminal::ReleaseMasterFileDescriptor() @li
+ /// PseudoTerminal::ReleaseSaveFileDescriptor()
///
/// @param[out] error
/// An pointer to an error that can describe any errors that
//------------------------------------------------------------------
/// The master file descriptor accessor.
///
- /// This object retains ownership of the master file descriptor when
- /// this accessor is used. Users can call the member function
- /// PseudoTerminal::ReleaseMasterFileDescriptor() if this
- /// object should release ownership of the slave file descriptor.
+ /// This object retains ownership of the master file descriptor when this
+ /// accessor is used. Users can call the member function
+ /// PseudoTerminal::ReleaseMasterFileDescriptor() if this object should
+ /// release ownership of the slave file descriptor.
///
/// @return
/// The master file descriptor, or PseudoTerminal::invalid_fd
//------------------------------------------------------------------
/// The slave file descriptor accessor.
///
- /// This object retains ownership of the slave file descriptor when
- /// this accessor is used. Users can call the member function
- /// PseudoTerminal::ReleaseSlaveFileDescriptor() if this
- /// object should release ownership of the slave file descriptor.
+ /// This object retains ownership of the slave file descriptor when this
+ /// accessor is used. Users can call the member function
+ /// PseudoTerminal::ReleaseSlaveFileDescriptor() if this object should
+ /// release ownership of the slave file descriptor.
///
/// @return
/// The slave file descriptor, or PseudoTerminal::invalid_fd
/// Open the first available pseudo terminal.
///
/// Opens the first available pseudo terminal with \a oflag as the
- /// permissions. The opened master file descriptor is stored in this
- /// object and can be accessed by calling the
- /// PseudoTerminal::GetMasterFileDescriptor() accessor. Clients
- /// can call the PseudoTerminal::ReleaseMasterFileDescriptor()
- /// accessor function if they wish to use the master file descriptor
- /// beyond the lifespan of this object.
+ /// permissions. The opened master file descriptor is stored in this object
+ /// and can be accessed by calling the
+ /// PseudoTerminal::GetMasterFileDescriptor() accessor. Clients can call the
+ /// PseudoTerminal::ReleaseMasterFileDescriptor() accessor function if they
+ /// wish to use the master file descriptor beyond the lifespan of this
+ /// object.
///
/// If this object still has a valid master file descriptor when its
/// destructor is called, it will close it.
/// successfully opened.
/// @li \b false if anything goes wrong.
///
- /// @see PseudoTerminal::GetMasterFileDescriptor()
- /// @see PseudoTerminal::ReleaseMasterFileDescriptor()
+ /// @see PseudoTerminal::GetMasterFileDescriptor() @see
+ /// PseudoTerminal::ReleaseMasterFileDescriptor()
//------------------------------------------------------------------
bool OpenFirstAvailableMaster(int oflag, char *error_str, size_t error_len);
/// Open the slave for the current master pseudo terminal.
///
/// A master pseudo terminal should already be valid prior to
- /// calling this function. The opened slave file descriptor is
- /// stored in this object and can be accessed by calling the
- /// PseudoTerminal::GetSlaveFileDescriptor() accessor. Clients
- /// can call the PseudoTerminal::ReleaseSlaveFileDescriptor()
- /// accessor function if they wish to use the slave file descriptor
- /// beyond the lifespan of this object.
+ /// calling this function. The opened slave file descriptor is stored in
+ /// this object and can be accessed by calling the
+ /// PseudoTerminal::GetSlaveFileDescriptor() accessor. Clients can call the
+ /// PseudoTerminal::ReleaseSlaveFileDescriptor() accessor function if they
+ /// wish to use the slave file descriptor beyond the lifespan of this
+ /// object.
///
/// If this object still has a valid slave file descriptor when its
/// destructor is called, it will close it.
/// successfully opened.
/// @li \b false if anything goes wrong.
///
- /// @see PseudoTerminal::OpenFirstAvailableMaster()
- /// @see PseudoTerminal::GetSlaveFileDescriptor()
- /// @see PseudoTerminal::ReleaseSlaveFileDescriptor()
+ /// @see PseudoTerminal::OpenFirstAvailableMaster() @see
+ /// PseudoTerminal::GetSlaveFileDescriptor() @see
+ /// PseudoTerminal::ReleaseSlaveFileDescriptor()
//------------------------------------------------------------------
bool OpenSlave(int oflag, char *error_str, size_t error_len);
//------------------------------------------------------------------
/// Release the master file descriptor.
///
- /// Releases ownership of the master pseudo terminal file descriptor
- /// without closing it. The destructor for this class will close the
- /// master file descriptor if the ownership isn't released using this
- /// call and the master file descriptor has been opened.
+ /// Releases ownership of the master pseudo terminal file descriptor without
+ /// closing it. The destructor for this class will close the master file
+ /// descriptor if the ownership isn't released using this call and the
+ /// master file descriptor has been opened.
///
/// @return
/// The master file descriptor, or PseudoTerminal::invalid_fd
//------------------------------------------------------------------
/// Release the slave file descriptor.
///
- /// Release ownership of the slave pseudo terminal file descriptor
- /// without closing it. The destructor for this class will close the
- /// slave file descriptor if the ownership isn't released using this
- /// call and the slave file descriptor has been opened.
+ /// Release ownership of the slave pseudo terminal file descriptor without
+ /// closing it. The destructor for this class will close the slave file
+ /// descriptor if the ownership isn't released using this call and the slave
+ /// file descriptor has been opened.
///
/// @return
/// The slave file descriptor, or PseudoTerminal::invalid_fd
//----------------------------------------------------------------------
/// @namespace StringConvert StringConvert.h "lldb/Host/StringConvert.h"
-/// @brief Utility classes for converting strings into Integers
+/// Utility classes for converting strings into Integers
//----------------------------------------------------------------------
int32_t ToSInt32(const char *s, int32_t fail_value = 0, int base = 0,
//----------------------------------------------------------------------
/// @class State Terminal.h "lldb/Host/Terminal.h"
-/// @brief A terminal state saving/restoring class.
+/// A terminal state saving/restoring class.
///
/// This class can be used to remember the terminal state for a file
/// descriptor and later restore that state as it originally was.
//------------------------------------------------------------------
/// Save the TTY state for \a fd.
///
- /// Save the current state of the TTY for the file descriptor "fd"
- /// and if "save_process_group" is true, attempt to save the process
- /// group info for the TTY.
+ /// Save the current state of the TTY for the file descriptor "fd" and if
+ /// "save_process_group" is true, attempt to save the process group info for
+ /// the TTY.
///
/// @param[in] fd
/// The file descriptor to save the state of.
//------------------------------------------------------------------
/// Restore the TTY state to the cached state.
///
- /// Restore the state of the TTY using the cached values from a
- /// previous call to TerminalState::Save(int,bool).
+ /// Restore the state of the TTY using the cached values from a previous
+ /// call to TerminalState::Save(int,bool).
///
/// @return
/// Returns \b true if the TTY state was successfully restored,
//----------------------------------------------------------------------
/// @class TerminalStateSwitcher Terminal.h "lldb/Host/Terminal.h"
-/// @brief A TTY state switching class.
+/// A TTY state switching class.
///
/// This class can be used to remember 2 TTY states for a given file
/// descriptor and switch between the two states.
bool Restore(uint32_t idx) const;
//------------------------------------------------------------------
- /// Save the TTY state information for the state at index \a idx.
- /// The TTY 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.
+ /// Save the TTY state information for the state at index \a idx. The TTY
+ /// 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
/// The index into the state array where the state should be
//----------------------------------------------------------------------
/// @class PipePosix PipePosix.h "lldb/Host/posix/PipePosix.h"
-/// @brief A posix-based implementation of Pipe, a class that abtracts
+/// A posix-based implementation of Pipe, a class that abtracts
/// unix style pipes.
///
/// A class that abstracts the LLDB core from host pipe functionality.
//----------------------------------------------------------------------
/// @class Pipe PipeWindows.h "lldb/Host/windows/PipeWindows.h"
-/// @brief A windows-based implementation of Pipe, a class that abtracts
+/// A windows-based implementation of Pipe, a class that abtracts
/// unix style pipes.
///
/// A class that abstracts the LLDB core from host pipe functionality.
//----------------------------------------------------------------------
/// @class Options Options.h "lldb/Interpreter/Options.h"
-/// @brief A command line option parsing protocol class.
+/// A command line option parsing protocol class.
///
-/// Options is designed to be subclassed to contain all needed
-/// options for a given command. The options can be parsed by calling the Parse
-/// function.
+/// Options is designed to be subclassed to contain all needed options for a
+/// given command. The options can be parsed by calling the Parse function.
///
-/// The options are specified using the format defined for the libc
-/// options parsing function getopt_long_only:
-/// \code
+/// The options are specified using the format defined for the libc options
+/// parsing function getopt_long_only: \code
/// #include <getopt.h>
/// int getopt_long_only(int argc, char * const *argv, const char
/// *optstring, const struct option *longopts, int *longindex);
/// Parse the provided arguments.
///
/// The parsed options are set via calls to SetOptionValue. In case of a
- /// successful parse, the function returns a copy of the input arguments with
- /// the parsed options removed. Otherwise, it returns an error.
+ /// successful parse, the function returns a copy of the input arguments
+ /// with the parsed options removed. Otherwise, it returns an error.
///
/// param[in] platform_sp
/// The platform used for option validation. This is necessary
ExecutionContext *execution_context) = 0;
//------------------------------------------------------------------
- /// Handles the generic bits of figuring out whether we are in an
- /// option, and if so completing it.
+ /// Handles the generic bits of figuring out whether we are in an option,
+ /// and if so completing it.
///
/// @param[in] input
/// The command line parsed into words
/// The array of matches returned.
///
/// 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.
+ /// make a distinction between total number of matches, and the window the
+ /// user wants returned.
///
/// @return
/// \btrue if we were in an option, \bfalse otherwise.
lldb_private::StringList &matches);
//------------------------------------------------------------------
- /// Handles the generic bits of figuring out whether we are in an
- /// option, and if so completing it.
+ /// Handles the generic bits of figuring out whether we are in an option,
+ /// and if so completing it.
///
/// @param[in] interpreter
/// The command interpreter doing the completion.
/// The array of matches returned.
///
/// 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.
+ /// make a distinction between total number of matches, and the window the
+ /// user wants returned.
///
/// @return
/// \btrue if we were in an option, \bfalse otherwise.
//----------------------------------------------------------------------
/// Append options from a OptionGroup class.
///
- /// Append all options from \a group using the exact same option groups
- /// that each option is defined with.
+ /// Append all options from \a group using the exact same option groups that
+ /// each option is defined with.
///
/// @param[in] group
/// A group of options to take option values from and copy their
//----------------------------------------------------------------------
/// Append options from a OptionGroup class.
///
- /// Append options from \a group that have a usage mask that has any bits
- /// in "src_mask" set. After the option definition is copied into the
- /// options definitions in this class, set the usage_mask to "dst_mask".
+ /// Append options from \a group that have a usage mask that has any bits in
+ /// "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
/// A group of options to take option values from and copy their
//----------------------------------------------------------------------
/// @class Block Block.h "lldb/Symbol/Block.h"
-/// @brief A class that describes a single lexical block.
+/// A class that describes a single lexical block.
///
/// A Function object owns a BlockList object which owns one or more
-/// Block objects. The BlockList object contains a section offset
-/// address range, and Block objects contain one or more ranges
-/// which are offsets into that range. Blocks are can have discontiguous
-/// ranges within the BlockList address range, and each block can
-/// contain child blocks each with their own sets of ranges.
+/// Block objects. The BlockList object contains a section offset address
+/// range, and Block objects contain one or more ranges which are offsets into
+/// that range. Blocks are can have discontiguous ranges within the BlockList
+/// address range, and each block can contain child blocks each with their own
+/// sets of ranges.
///
-/// Each block has a variable list that represents local, argument, and
-/// static variables that are scoped to the block.
+/// Each block has a variable list that represents local, argument, and static
+/// variables that are scoped to the block.
///
-/// Inlined functions are represented by attaching a
-/// InlineFunctionInfo shared pointer object to a block. Inlined
-/// functions are represented as named blocks.
+/// Inlined functions are represented by attaching a InlineFunctionInfo shared
+/// pointer object to a block. Inlined functions are represented as named
+/// blocks.
//----------------------------------------------------------------------
class Block : public UserID, public SymbolContextScope {
public:
//------------------------------------------------------------------
/// Construct with a User ID \a uid, \a depth.
///
- /// Initialize this block with the specified UID \a uid. The
- /// \a depth in the \a block_list is used to represent the parent,
- /// sibling, and child block information and also allows for partial
- /// parsing at the block level.
+ /// Initialize this block with the specified UID \a uid. The \a depth in the
+ /// \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
/// The UID for a given block. This value is given by the
bool Contains(const Range &range) const;
//------------------------------------------------------------------
- /// Check if this object contains "block" as a child block at any
- /// depth.
+ /// Check if this object contains "block" as a child block at any depth.
///
/// @param[in] block
/// A potential child block.
lldb::VariableListSP GetBlockVariableList(bool can_create);
//------------------------------------------------------------------
- /// Get the variable list for this block and optionally all child
- /// blocks if \a get_child_variables is \b true.
+ /// 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
/// If \b true, all variables from all child blocks will be
VariableList *variable_list);
//------------------------------------------------------------------
- /// Appends the variables from this block, and optionally from all
- /// parent blocks, to \a variable_list.
+ /// Appends the variables from this block, and optionally from all parent
+ /// blocks, to \a variable_list.
///
/// @param[in] can_create
/// If \b true, the variables can be parsed if they already
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// Returns the cost of this object plus any owned objects from the
- /// ranges, variables, and inline function information.
+ /// Returns the cost of this object plus any owned objects from the ranges,
+ /// variables, and inline function information.
///
/// @return
/// The number of bytes that this object occupies in memory.
//------------------------------------------------------------------
/// Set accessor for the variable list.
///
- /// 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.
+ /// 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
/// A shared pointer to a VariableList.
namespace lldb_private {
//----------------------------------------------------------------------
/// @class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
-/// @brief A class that describes a compilation unit.
+/// A class that describes a compilation unit.
///
/// A representation of a compilation unit, or compiled source file.
-/// The UserID of the compile unit is specified by the SymbolFile
-/// plug-in and can have any value as long as the value is unique
-/// within the Module that owns this compile units.
+/// The UserID of the compile unit is specified by the SymbolFile plug-in and
+/// can have any value as long as the value is unique within the Module that
+/// owns this compile units.
///
-/// Each compile unit has a list of functions, global and static
-/// variables, support file list (include files and inlined source
-/// files), and a line table.
+/// Each compile unit has a list of functions, global and static variables,
+/// support file list (include files and inlined source files), and a line
+/// table.
//----------------------------------------------------------------------
class CompileUnit : public std::enable_shared_from_this<CompileUnit>,
public ModuleChild,
//------------------------------------------------------------------
/// Construct with a module, path, UID and language.
///
- /// Initialize the compile unit given the owning \a module, a path
- /// to convert into a FileSpec, the SymbolFile plug-in supplied
- /// \a uid, and the source language type.
+ /// Initialize the compile unit given the owning \a module, a path to
+ /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
+ /// source language type.
///
/// @param[in] module
/// The parent module that owns this compile unit. This value
//------------------------------------------------------------------
/// Construct with a module, file spec, UID and language.
///
- /// Initialize the compile unit given the owning \a module, a path
- /// to convert into a FileSpec, the SymbolFile plug-in supplied
- /// \a uid, and the source language type.
+ /// Initialize the compile unit given the owning \a module, a path to
+ /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
+ /// source language type.
///
/// @param[in] module
/// The parent module that owns this compile unit. This value
//------------------------------------------------------------------
/// Add a function to this compile unit.
///
- /// Typically called by the SymbolFile plug-ins as they partially
- /// parse the debug information.
+ /// Typically called by the SymbolFile plug-ins as they partially parse the
+ /// debug information.
///
/// @param[in] function_sp
/// A shared pointer to the Function object.
void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
//------------------------------------------------------------------
- /// Get a shared pointer to a function in this compile unit by
- /// index.
+ /// Get a shared pointer to a function in this compile unit by index.
///
- /// Typically called when iterating though all functions in a
- /// compile unit after all functions have been parsed. This provides
- /// raw access to the function shared pointer list and will not
- /// cause the SymbolFile plug-in to parse any unparsed functions.
+ /// Typically called when iterating though all functions in a compile unit
+ /// after all functions have been parsed. This provides raw access to the
+ /// function shared pointer list and will not cause the SymbolFile plug-in
+ /// to parse any unparsed functions.
///
/// @param[in] idx
/// An index into the function list.
//------------------------------------------------------------------
/// Find the line entry by line and optional inlined file spec.
///
- /// Finds the first line entry that has an index greater than
- /// \a start_idx that matches \a line. If \a file_spec_ptr
- /// is NULL, then the search matches line entries whose file matches
- /// the file for the compile unit. If \a file_spec_ptr is
- /// not NULL, line entries must match the specified file spec (for
- /// inlined line table entries).
+ /// Finds the first line entry that has an index greater than \a start_idx
+ /// that matches \a line. If \a file_spec_ptr is NULL, then the search
+ /// matches line entries whose file matches the file for the compile unit.
+ /// If \a file_spec_ptr is not NULL, line entries must match the specified
+ /// file spec (for inlined line table entries).
///
- /// Multiple calls to this function can find all entries that match
- /// a given file and line by starting with \a start_idx equal to zero,
- /// and calling this function back with the return value + 1.
+ /// Multiple calls to this function can find all entries that match a given
+ /// 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
/// The zero based index at which to start looking for matches.
//------------------------------------------------------------------
/// Get the line table for the compile unit.
///
- /// Called by clients and the SymbolFile plug-in. The SymbolFile
- /// plug-ins 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.
+ /// Called by clients and the SymbolFile plug-in. The SymbolFile plug-ins
+ /// 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
/// The line table object pointer, or NULL if this line table
//------------------------------------------------------------------
/// Get the compile unit's support file list.
///
- /// The support file list is used by the line table, and any objects
- /// that have valid Declaration objects.
+ /// The support file list is used by the line table, and any objects that
+ /// have valid Declaration objects.
///
/// @return
/// A support file list object.
//------------------------------------------------------------------
/// Get the compile unit's imported module list.
///
- /// This reports all the imports that the compile unit made,
- /// including the current module.
+ /// This reports all the imports that the compile unit made, including the
+ /// current module.
///
/// @return
/// A list of imported module names.
//------------------------------------------------------------------
/// Get the SymbolFile plug-in user data.
///
- /// SymbolFile plug-ins can store user data to internal state or
- /// objects to quickly allow them to parse more information for a
- /// given object.
+ /// 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
/// The user data stored with the CompileUnit when it was
//------------------------------------------------------------------
/// Get the variable list for a compile unit.
///
- /// Called by clients to get the variable list for a compile unit.
- /// The variable list will contain all global and static variables
- /// that were defined at the compile unit level.
+ /// Called by clients to get the variable list for a compile unit. The
+ /// variable list will contain all global and static variables that were
+ /// defined at the compile unit level.
///
/// @param[in] can_create
/// If \b true, the variable list will be parsed on demand. If
//------------------------------------------------------------------
/// Finds a function by user ID.
///
- /// Typically used by SymbolFile plug-ins when partially parsing
- /// the debug information to see if the function has been parsed
- /// yet.
+ /// Typically used by SymbolFile plug-ins when partially parsing the debug
+ /// information to see if the function has been parsed yet.
///
/// @param[in] uid
/// The user ID of the function to find. This value is supplied
//------------------------------------------------------------------
/// Set the line table for the compile unit.
///
- /// Called by the SymbolFile plug-in when if first parses the line
- /// table and 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.
+ /// Called by the SymbolFile plug-in when if first parses the line table and
+ /// 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
/// A line table object pointer that this object now owns.
//------------------------------------------------------------------
/// Set accessor for the variable list.
///
- /// 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.
+ /// 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
/// A shared pointer to a VariableList.
//------------------------------------------------------------------
/// Resolve symbol contexts by file and line.
///
- /// 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.
+ /// 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
/// A file specification. If \a file_spec contains no directory
//------------------------------------------------------------------
/// Get whether compiler optimizations were enabled for this compile unit
///
- /// "optimized" means that the debug experience may be difficult
- /// for the user to understand. Variables may not be available when
- /// the developer would expect them, stepping through the source lines
- /// in the function may appear strange, etc.
+ /// "optimized" means that the debug experience may be difficult for the
+ /// user to understand. Variables may not be available when the developer
+ /// would expect them, stepping through the source lines in the function may
+ /// appear strange, etc.
///
/// @return
/// Returns 'true' if this compile unit was compiled with
//----------------------------------------------------------------------
/// @class Declaration Declaration.h "lldb/Symbol/Declaration.h"
-/// @brief A class that describes the declaration location of a
+/// A class that describes the declaration location of a
/// lldb object.
///
-/// The declarations include the file specification, line number, and
-/// the column info and can help track where functions, blocks, inlined
-/// functions, types, variables, any many other debug core objects were
-/// declared.
+/// The declarations include the file specification, line number, and the
+/// column info and can help track where functions, blocks, inlined functions,
+/// types, variables, any many other debug core objects were declared.
//----------------------------------------------------------------------
class Declaration {
public:
//------------------------------------------------------------------
/// Clear the object's state.
///
- /// Sets the file specification to be empty, and the line and column
- /// to zero.
+ /// Sets the file specification to be empty, and the line and column to
+ /// zero.
//------------------------------------------------------------------
void Clear() {
m_file.Clear();
//------------------------------------------------------------------
/// Compare two declaration objects.
///
- /// Compares the two file specifications from \a lhs and \a rhs. If
- /// the file specifications are equal, then continue to compare the
- /// line number and column numbers respectively.
+ /// Compares the two file specifications from \a lhs and \a rhs. If the file
+ /// specifications are equal, then continue to compare the line number and
+ /// column numbers respectively.
///
/// @param[in] lhs
/// The Left Hand Side const Declaration object reference.
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
//----------------------------------------------------------------------
/// @class FunctionInfo Function.h "lldb/Symbol/Function.h"
-/// @brief A class that contains generic function information.
+/// A class that contains generic function information.
///
-/// This provides generic function information that gets reused between
-/// inline functions and function types.
+/// This provides generic function information that gets reused between inline
+/// functions and function types.
//----------------------------------------------------------------------
class FunctionInfo {
public:
//------------------------------------------------------------------
/// Compare two function information objects.
///
- /// First compares the method names, and if equal, then compares
- /// the declaration information.
+ /// First compares the method names, and if equal, then compares the
+ /// declaration information.
///
/// @param[in] lhs
/// The Left Hand Side const FunctionInfo object reference.
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
//----------------------------------------------------------------------
/// @class InlineFunctionInfo Function.h "lldb/Symbol/Function.h"
-/// @brief A class that describes information for an inlined function.
+/// A class that describes information for an inlined function.
//----------------------------------------------------------------------
class InlineFunctionInfo : public FunctionInfo {
public:
//------------------------------------------------------------------
- /// Construct with the function method name, mangled name, and
- /// optional declaration information.
+ /// Construct with the function method name, mangled name, and optional
+ /// declaration information.
///
/// @param[in] name
/// A C string name for the method name for this function. This
const Declaration *call_decl_ptr);
//------------------------------------------------------------------
- /// Construct with the function method name, mangled name, and
- /// optional declaration information.
+ /// Construct with the function method name, mangled name, and optional
+ /// declaration information.
///
/// @param[in] name
/// A name for the method name for this function. This value
//------------------------------------------------------------------
/// Compare two inlined function information objects.
///
- /// First compares the FunctionInfo objects, and if equal,
- /// compares the mangled names.
+ /// First compares the FunctionInfo objects, and if equal, compares the
+ /// mangled names.
///
/// @param[in] lhs
/// The Left Hand Side const InlineFunctionInfo object
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
//----------------------------------------------------------------------
/// @class Function Function.h "lldb/Symbol/Function.h"
-/// @brief A class that describes a function.
+/// A class that describes a function.
///
-/// Functions belong to CompileUnit objects (Function::m_comp_unit),
-/// have unique user IDs (Function::UserID), know how to reconstruct
-/// their symbol context (Function::SymbolContextScope), have a
-/// specific function type (Function::m_type_uid), have a simple
-/// method name (FunctionInfo::m_name), be declared at a specific
-/// location (FunctionInfo::m_declaration), possibly have mangled
-/// names (Function::m_mangled), an optional return type
-/// (Function::m_type), and contains lexical blocks
-/// (Function::m_blocks).
+/// Functions belong to CompileUnit objects (Function::m_comp_unit), have
+/// unique user IDs (Function::UserID), know how to reconstruct their symbol
+/// context (Function::SymbolContextScope), have a specific function type
+/// (Function::m_type_uid), have a simple method name (FunctionInfo::m_name),
+/// be declared at a specific location (FunctionInfo::m_declaration), possibly
+/// have mangled names (Function::m_mangled), an optional return type
+/// (Function::m_type), and contains lexical blocks (Function::m_blocks).
///
/// The function information is split into a few pieces:
/// @li The concrete instance information
/// The abstract information is found in the function type (Type) that
/// describes a function information, return type and parameter types.
///
-/// The concrete information is the address range information and
-/// specific locations for an instance of this function.
+/// The concrete information is the address range information and specific
+/// locations for an instance of this function.
//----------------------------------------------------------------------
class Function : public UserID, public SymbolContextScope {
public:
//------------------------------------------------------------------
- /// Construct with a compile unit, function UID, function type UID,
- /// optional mangled name, function type, and a section offset
- /// based address range.
+ /// 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
/// The compile unit to which this function belongs.
Type *func_type, const AddressRange &range);
//------------------------------------------------------------------
- /// Construct with a compile unit, function UID, function type UID,
- /// optional mangled name, function type, and a section offset
- /// based address range.
+ /// 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
/// The compile unit to which this function belongs.
lldb::LanguageType GetLanguage() const;
//------------------------------------------------------------------
- /// Find the file and line number of the source location of the start
- /// of the function. This will use the declaration if present and fall
- /// back on the line table if that fails. So there may NOT be a line
- /// table entry for this source file/line combo.
+ /// Find the file and line number of the source location of the start of the
+ /// function. This will use the declaration if present and fall back on the
+ /// line table if that fails. So there may NOT be a line table entry for
+ /// this source file/line combo.
///
/// @param[out] source_file
/// The source file.
void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no);
//------------------------------------------------------------------
- /// Find the file and line number of the source location of the end
- /// of the function.
+ /// Find the file and line number of the source location of the end of the
+ /// function.
///
///
/// @param[out] source_file
CompilerDeclContext GetDeclContext();
//------------------------------------------------------------------
- /// Get accessor for the type that describes the function
- /// return value type, and parameter types.
+ /// Get accessor for the type that describes the function return value type,
+ /// and parameter types.
///
/// @return
/// A type object pointer.
Type *GetType();
//------------------------------------------------------------------
- /// Get const accessor for the type that describes the function
- /// return value type, and parameter types.
+ /// Get const accessor for the type that describes the function return value
+ /// type, and parameter types.
///
/// @return
/// A const type object pointer.
//------------------------------------------------------------------
/// Get the size of the prologue instructions for this function. The
- /// "prologue"
- /// instructions include any instructions given line number 0 immediately
- /// following
- /// the prologue end.
+ /// "prologue" instructions include any instructions given line number 0
+ /// immediately following the prologue end.
///
/// @return
/// The size of the prologue.
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
///
/// The debug information may provide information about whether this
/// function was compiled with optimization or not. In this case,
- /// "optimized" means that the debug experience may be difficult
- /// for the user to understand. Variables may not be available when
- /// the developer would expect them, stepping through the source lines
- /// in the function may appear strange, etc.
+ /// "optimized" means that the debug experience may be difficult for the
+ /// user to understand. Variables may not be available when the developer
+ /// would expect them, stepping through the source lines in the function may
+ /// appear strange, etc.
///
/// @return
/// Returns 'true' if this function was compiled with
//------------------------------------------------------------------
/// Get whether this function represents a 'top-level' function
///
- /// The concept of a top-level function is language-specific, mostly
- /// meant to represent the notion of scripting-style code that has
- /// global visibility of the variables/symbols/functions/...
- /// defined within the containing file/module
+ /// The concept of a top-level function is language-specific, mostly meant
+ /// to represent the notion of scripting-style code that has global
+ /// visibility of the variables/symbols/functions/... defined within the
+ /// containing file/module
///
/// If stopped in a top-level function, LLDB will expose global variables
/// as-if locals in the 'frame variable' command
//----------------------------------------------------------------------
/// @class LineEntry LineEntry.h "lldb/Symbol/LineEntry.h"
-/// @brief A line table entry class.
+/// A line table entry class.
//----------------------------------------------------------------------
struct LineEntry {
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
Target *target, bool show_address_only) const;
//------------------------------------------------------------------
- /// Dumps information specific to a process that stops at this
- /// line entry to the supplied stream \a s.
+ /// Dumps information specific to a process that stops at this line entry to
+ /// the supplied stream \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
static int Compare(const LineEntry &lhs, const LineEntry &rhs);
//------------------------------------------------------------------
- /// Give the range for this LineEntry + any additional LineEntries for
- /// this same source line that are contiguous.
+ /// Give the range for this LineEntry + any additional LineEntries for this
+ /// same source line that are contiguous.
///
/// A compiler may emit multiple line entries for a single source line,
- /// e.g. to indicate subexpressions at different columns. This method
- /// will get the AddressRange for all of the LineEntries for this source
- /// line that are contiguous.
+ /// e.g. to indicate subexpressions at different columns. This method will
+ /// get the AddressRange for all of the LineEntries for this source line
+ /// that are contiguous.
//
- /// Line entries with a line number of 0 are treated specially - these
- /// are compiler-generated line table entries that the user did not
- /// write in their source code, and we want to skip past in the debugger.
- /// If this LineEntry is for line 32, and the following LineEntry is for
- /// line 0, we will extend the range to include the AddressRange of the
- /// line 0 LineEntry (and it will include the range of the following
- /// LineEntries that match either 32 or 0.)
- ///
- /// If the initial LineEntry this method is called on is a line #0, only
- /// the range of contiuous LineEntries with line #0 will be included in
- /// the complete range.
+ /// Line entries with a line number of 0 are treated specially - these are
+ /// compiler-generated line table entries that the user did not write in
+ /// their source code, and we want to skip past in the debugger. If this
+ /// LineEntry is for line 32, and the following LineEntry is for line 0, we
+ /// will extend the range to include the AddressRange of the line 0
+ /// LineEntry (and it will include the range of the following LineEntries
+ /// that match either 32 or 0.)
+ ///
+ /// If the initial LineEntry this method is called on is a line #0, only the
+ /// range of contiuous LineEntries with line #0 will be included in the
+ /// complete range.
///
/// @return
/// The contiguous AddressRange for this source line.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class LineSequence LineTable.h "lldb/Symbol/LineTable.h"
-/// @brief An abstract base class used during symbol table creation.
+/// @class LineSequence LineTable.h "lldb/Symbol/LineTable.h" An abstract base
+/// class used during symbol table creation.
//----------------------------------------------------------------------
class LineSequence {
public:
//----------------------------------------------------------------------
/// @class LineTable LineTable.h "lldb/Symbol/LineTable.h"
-/// @brief A line table class.
+/// A line table class.
//----------------------------------------------------------------------
class LineTable {
public:
void GetDescription(Stream *s, Target *target, lldb::DescriptionLevel level);
//------------------------------------------------------------------
- /// Find a line entry that contains the section offset address \a
- /// so_addr.
+ /// Find a line entry that contains the section offset address \a so_addr.
///
/// @param[in] so_addr
/// A section offset address object containing the address we
uint32_t *index_ptr = nullptr);
//------------------------------------------------------------------
- /// Find a line entry index that has a matching file index and
- /// source line number.
+ /// Find a line entry index that has a matching file index and source line
+ /// number.
///
- /// Finds the next line entry that has a matching \a file_idx and
- /// source line number \a line starting at the \a start_idx entries
- /// into the line entry collection.
+ /// Finds the next line entry that has a matching \a file_idx and source
+ /// line number \a line starting at the \a start_idx entries into the line
+ /// entry collection.
///
/// @param[in] start_idx
/// The number of entries to skip when starting the search.
bool append);
//------------------------------------------------------------------
- /// Given a file range link map, relink the current line table
- /// and return a fixed up line table.
+ /// Given a file range link map, relink the current line table and return a
+ /// fixed up line table.
///
/// @param[out] file_range_map
/// A collection of file ranges that maps to new file ranges
//----------------------------------------------------------------------
/// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
-/// @brief A plug-in interface definition class for object containers.
+/// A plug-in interface definition class for object containers.
///
-/// Object containers contain object files from one or more
-/// architectures, and also can contain one or more named objects.
+/// Object containers contain object files from one or more architectures, and
+/// also can contain one or more named objects.
///
-/// Typical object containers are static libraries (.a files) that
-/// contain multiple named object files, and universal files that contain
-/// multiple architectures.
+/// Typical object containers are static libraries (.a files) that contain
+/// multiple named object files, and universal files that contain multiple
+/// architectures.
//----------------------------------------------------------------------
class ObjectContainer : public PluginInterface, public ModuleChild {
public:
//------------------------------------------------------------------
/// Construct with a parent module, offset, and header data.
///
- /// Object files belong to modules and a valid module must be
- /// supplied upon construction. The at an offset within a file for
- /// objects that contain more than one architecture or object.
+ /// Object files belong to modules and a valid module must be supplied upon
+ /// construction. The at an offset within a file for objects that contain
+ /// more than one architecture or object.
//------------------------------------------------------------------
ObjectContainer(const lldb::ModuleSP &module_sp, const FileSpec *file,
lldb::offset_t file_offset, lldb::offset_t length,
//------------------------------------------------------------------
/// Destructor.
///
- /// The destructor is virtual since this class is designed to be
- /// inherited from by the plug-in instance.
+ /// The destructor is virtual since this class is designed to be inherited
+ /// from by the plug-in instance.
//------------------------------------------------------------------
~ObjectContainer() override = default;
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the current contents of this object
- /// to the 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.
+ /// Dump a description of the current contents of this object to the
+ /// 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
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Returns the offset into a file at which this object resides.
///
- /// Some files contain many object files, and this function allows
- /// access to an object's offset within the file.
+ /// Some files contain many object files, and this function allows access to
+ /// an object's offset within the file.
///
/// @return
/// The offset in bytes into the file. Defaults to zero for
//------------------------------------------------------------------
/// Get the number of architectures in this object file.
///
- /// The default implementation returns 1 as for object files that
- /// contain a single architecture. ObjectContainer instances that
- /// contain more than one architecture should override this function
- /// and return an appropriate value.
+ /// The default implementation returns 1 as for object files that contain a
+ /// single architecture. ObjectContainer instances that contain more than
+ /// one architecture should override this function and return an appropriate
+ /// value.
///
/// @return
/// The number of architectures contained in this object file.
//------------------------------------------------------------------
/// Attempts to parse the object header.
///
- /// This function is used as a test to see if a given plug-in
- /// instance can parse the header data already contained in
- /// ObjectContainer::m_data. If an object file parser does not
- /// recognize that magic bytes in a header, false should be returned
- /// and the next plug-in can attempt to parse an object file.
+ /// This function is used as a test to see if a given plug-in instance can
+ /// parse the header data already contained in ObjectContainer::m_data. If
+ /// an object file parser does not recognize that magic bytes in a header,
+ /// false should be returned and the next plug-in can attempt to parse an
+ /// object file.
///
/// @return
/// Returns \b true if the header was parsed successfully, \b
//------------------------------------------------------------------
/// Selects an architecture in an object file.
///
- /// Object files that contain a single architecture should verify
- /// that the specified \a arch matches the architecture in in
- /// object file and return \b true or \b false accordingly.
+ /// Object files that contain a single architecture should verify that the
+ /// specified \a arch matches the architecture in in object file and return
+ /// \b true or \b false accordingly.
///
- /// Object files that contain more than one architecture should
- /// attempt to select that architecture, and if successful, clear
- /// out any previous state from any previously selected architecture
- /// and prepare to return information for the new architecture.
+ /// Object files that contain more than one architecture should attempt to
+ /// select that architecture, and if successful, clear out any previous
+ /// state from any previously selected architecture and prepare to return
+ /// information for the new architecture.
///
/// @return
/// Returns a pointer to the object file of the requested \a
//----------------------------------------------------------------------
/// @class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h"
-/// @brief A plug-in interface definition class for object file parsers.
+/// A plug-in interface definition class for object file parsers.
///
-/// Object files belong to Module objects and know how to extract
-/// information from executable, shared library, and object (.o) files
-/// used by operating system runtime. The symbol table and section list
-/// for an object file.
+/// Object files belong to Module objects and know how to extract information
+/// from executable, shared library, and object (.o) files used by operating
+/// system runtime. The symbol table and section list for an object file.
///
-/// Object files can be represented by the entire file, or by part of a
-/// file. An example of a partial file ObjectFile is one that contains
-/// information for one of multiple architectures in the same file.
+/// Object files can be represented by the entire file, or by part of a file.
+/// An example of a partial file ObjectFile is one that contains information
+/// for one of multiple architectures in the same file.
///
/// Once an architecture is selected the object file information can be
/// extracted from this abstract class.
//------------------------------------------------------------------
/// Construct with a parent module, offset, and header data.
///
- /// Object files belong to modules and a valid module must be
- /// supplied upon construction. The at an offset within a file for
- /// objects that contain more than one architecture or object.
+ /// Object files belong to modules and a valid module must be supplied upon
+ /// construction. The at an offset within a file for objects that contain
+ /// more than one architecture or object.
//------------------------------------------------------------------
ObjectFile(const lldb::ModuleSP &module_sp, const FileSpec *file_spec_ptr,
lldb::offset_t file_offset, lldb::offset_t length,
//------------------------------------------------------------------
/// Destructor.
///
- /// The destructor is virtual since this class is designed to be
- /// inherited from by the plug-in instance.
+ /// The destructor is virtual since this class is designed to be inherited
+ /// from by the plug-in instance.
//------------------------------------------------------------------
~ObjectFile() override;
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the current contents of this object
- /// to the 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.
+ /// Dump a description of the current contents of this object to the
+ /// 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
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Find a ObjectFile plug-in that can parse \a file_spec.
///
- /// Scans all loaded plug-in interfaces that implement versions of
- /// the ObjectFile plug-in interface and returns the first
- /// instance that can parse the file.
+ /// Scans all loaded plug-in interfaces that implement versions of the
+ /// ObjectFile plug-in interface and returns the first instance that can
+ /// parse the file.
///
/// @param[in] module
/// The parent module that owns this object file.
//------------------------------------------------------------------
/// Find a ObjectFile plug-in that can parse a file in memory.
///
- /// Scans all loaded plug-in interfaces that implement versions of
- /// the ObjectFile plug-in interface and returns the first
- /// instance that can parse the file.
+ /// Scans all loaded plug-in interfaces that implement versions of the
+ /// ObjectFile plug-in interface and returns the first instance that can
+ /// parse the file.
///
/// @param[in] module
/// The parent module that owns this object file.
//------------------------------------------------------------------
/// Split a path into a file path with object name.
///
- /// For paths like "/tmp/foo.a(bar.o)" we often need to split a path
- /// up into the actual path name and into the object name so we can
- /// make a valid object file from it.
+ /// For paths like "/tmp/foo.a(bar.o)" we often need to split a path up into
+ /// the actual path name and into the object name so we can make a valid
+ /// object file from it.
///
/// @param[in] path_with_object
/// A path that might contain an archive path with a .o file
//------------------------------------------------------------------
/// Get the address type given a file address in an object file.
///
- /// Many binary file formats know what kinds
- /// This is primarily for ARM 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
+ /// Many binary file formats know what kinds This is primarily for ARM
+ /// 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
/// 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.
//------------------------------------------------------------------
/// Extract the dependent modules from an object file.
///
- /// If an object file has information about which other images it
- /// depends on (such as shared libraries), this function will
- /// provide the list. Since many executables or shared libraries
- /// may depend on the same files,
- /// FileSpecList::AppendIfUnique(const FileSpec &) should be
- /// used to make sure any files that are added are not already in
- /// the list.
+ /// If an object file has information about which other images it depends on
+ /// (such as shared libraries), this function will provide the list. Since
+ /// many executables or shared libraries may depend on the same files,
+ /// 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
/// A list of file specification objects that gets dependent
//------------------------------------------------------------------
/// Returns the offset into a file at which this object resides.
///
- /// Some files contain many object files, and this function allows
- /// access to an object's offset within the file.
+ /// Some files contain many object files, and this function allows access to
+ /// an object's offset within the file.
///
/// @return
/// The offset in bytes into the file. Defaults to zero for
//------------------------------------------------------------------
/// Get the name of the cpu, vendor and OS for this object file.
///
- /// This value is a string that represents the target triple where
- /// the cpu type, the vendor and the OS are encoded into a string.
+ /// This value is a string that represents the target triple where the cpu
+ /// type, the vendor and the OS are encoded into a string.
///
/// @param[out] target_triple
/// The string value of the target triple.
virtual bool GetArchitecture(ArchSpec &arch) = 0;
//------------------------------------------------------------------
- /// Gets the section list for the currently selected architecture
- /// (and object for archives).
+ /// Gets the section list for the currently selected architecture (and
+ /// object for archives).
///
- /// Section list parsing can be deferred by ObjectFile instances
- /// until this accessor is called the first time.
+ /// Section list parsing can be deferred by ObjectFile instances until this
+ /// accessor is called the first time.
///
/// @return
/// The list of sections contained in this object file.
virtual void CreateSections(SectionList &unified_section_list) = 0;
//------------------------------------------------------------------
- /// Notify the ObjectFile that the file addresses in the Sections
- /// for this module have been changed.
+ /// Notify the ObjectFile that the file addresses in the Sections for this
+ /// module have been changed.
//------------------------------------------------------------------
virtual void SectionFileAddressesChanged() {}
//------------------------------------------------------------------
- /// Gets the symbol table for the currently selected architecture
- /// (and object for archives).
+ /// Gets the symbol table for the currently selected architecture (and
+ /// object for archives).
///
- /// Symbol table parsing can be deferred by ObjectFile instances
- /// until this accessor is called the first time.
+ /// Symbol table parsing can be deferred by ObjectFile instances until this
+ /// accessor is called the first time.
///
/// @return
/// The symbol table for this object file.
//------------------------------------------------------------------
/// Appends a Symbol for the specified so_addr to the symbol table.
///
- /// If verify_unique is false, the symbol table is not searched
- /// to determine if a Symbol found at this address has already been
- /// added to the symbol table. When verify_unique is true, this
- /// method resolves the Symbol as the first match in the SymbolTable
- /// and appends a Symbol only if required/found.
+ /// If verify_unique is false, the symbol table is not searched to determine
+ /// if a Symbol found at this address has already been added to the symbol
+ /// table. When verify_unique is true, this method resolves the Symbol as
+ /// the first match in the SymbolTable and appends a Symbol only if
+ /// required/found.
///
/// @return
/// The resolved symbol or nullptr. Returns nullptr if a
//------------------------------------------------------------------
/// Gets the UUID for this object file.
///
- /// If the object file format contains a UUID, the value should be
- /// returned. Else ObjectFile instances should return the MD5
- /// checksum of all of the bytes for the object file (or memory for
- /// memory based object files).
+ /// If the object file format contains a UUID, the value should be returned.
+ /// 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
/// Returns \b true if a UUID was successfully extracted into
//------------------------------------------------------------------
/// Gets the symbol file spec list for this object file.
///
- /// If the object file format contains a debug symbol file link,
- /// the values will be returned in the FileSpecList.
+ /// If the object file format contains a debug symbol file link, the values
+ /// will be returned in the FileSpecList.
///
/// @return
/// Returns filespeclist.
/// Gets the file spec list of libraries re-exported by this object file.
///
/// If the object file format has the notion of one library re-exporting the
- /// symbols from another,
- /// the re-exported libraries will be returned in the FileSpecList.
+ /// symbols from another, the re-exported libraries will be returned in the
+ /// FileSpecList.
///
/// @return
/// Returns filespeclist.
}
//------------------------------------------------------------------
- /// Sets the load address for an entire module, assuming a rigid
- /// slide of sections, if possible in the implementation.
+ /// Sets the load address for an entire module, assuming a rigid slide of
+ /// sections, if possible in the implementation.
///
/// @return
/// Returns true iff any section's load address changed.
}
//------------------------------------------------------------------
- /// Gets whether endian swapping should occur when extracting data
- /// from this object file.
+ /// Gets whether endian swapping should occur when extracting data from this
+ /// object file.
///
/// @return
/// Returns \b true if endian swapping is needed, \b false
//------------------------------------------------------------------
/// Attempts to parse the object header.
///
- /// This function is used as a test to see if a given plug-in
- /// instance can parse the header data already contained in
- /// ObjectFile::m_data. If an object file parser does not
- /// recognize that magic bytes in a header, false should be returned
- /// and the next plug-in can attempt to parse an object file.
+ /// This function is used as a test to see if a given plug-in instance can
+ /// parse the header data already contained in ObjectFile::m_data. If an
+ /// object file parser does not recognize that magic bytes in a header,
+ /// false should be returned and the next plug-in can attempt to parse an
+ /// object file.
///
/// @return
/// Returns \b true if the header was parsed successfully, \b
//------------------------------------------------------------------
/// Returns a reference to the UnwindTable for this ObjectFile
///
- /// The UnwindTable contains FuncUnwinders objects for any function in
- /// this ObjectFile. If a FuncUnwinders object hasn't been created yet
- /// (i.e. the function has yet to be unwound in a stack walk), it
- /// will be created when requested. Specifically, we do not create
- /// FuncUnwinders objects for functions until they are needed.
+ /// The UnwindTable contains FuncUnwinders objects for any function in this
+ /// ObjectFile. If a FuncUnwinders object hasn't been created yet (i.e. the
+ /// function has yet to be unwound in a stack walk), it will be created when
+ /// requested. Specifically, we do not create FuncUnwinders objects for
+ /// functions until they are needed.
///
/// @return
/// Returns the unwind table for this object file.
virtual lldb_private::UnwindTable &GetUnwindTable() { return m_unwind_table; }
//------------------------------------------------------------------
- /// Returns if the function bounds for symbols in this symbol file
- /// are likely accurate.
+ /// Returns if the function bounds for symbols in this symbol file are
+ /// likely accurate.
///
/// The unwinder can emulate the instructions of functions to understand
- /// prologue/epilogue code sequences, where registers are spilled on
- /// the stack, etc. This feature relies on having the correct start
- /// addresses of all functions. If the ObjectFile has a way to tell
- /// that symbols have been stripped and there's no way to reconstruct
- /// start addresses (e.g. LC_FUNCTION_STARTS on Mach-O, or eh_frame
- /// unwind info), the ObjectFile should indicate that assembly emulation
- /// should not be used for this module.
+ /// prologue/epilogue code sequences, where registers are spilled on the
+ /// stack, etc. This feature relies on having the correct start addresses
+ /// of all functions. If the ObjectFile has a way to tell that symbols have
+ /// been stripped and there's no way to reconstruct start addresses (e.g.
+ /// LC_FUNCTION_STARTS on Mach-O, or eh_frame unwind info), the ObjectFile
+ /// should indicate that assembly emulation should not be used for this
+ /// module.
///
- /// It is uncommon for this to return false. An ObjectFile needs to
- /// be sure that symbol start addresses are unavailable before false
- /// is returned. If it is unclear, this should return true.
+ /// It is uncommon for this to return false. An ObjectFile needs to be sure
+ /// that symbol start addresses are unavailable before false is returned.
+ /// If it is unclear, this should return true.
///
/// @return
/// Returns true if assembly emulation should be used for this
}
//------------------------------------------------------------------
- /// Returns the address of the Entry Point in this object file - if
- /// the object file doesn't have an entry point (because it is not an
- /// executable file) then an invalid address is returned.
+ /// Returns the address of the Entry Point in this object file - if the
+ /// object file doesn't have an entry point (because it is not an executable
+ /// file) then an invalid address is returned.
///
/// @return
/// Returns the entry address for this module.
virtual lldb_private::Address GetEntryPointAddress() { return Address(); }
//------------------------------------------------------------------
- /// Returns the address that represents the header of this object
- /// file.
+ /// Returns the address that represents the header of this object file.
///
- /// The header address is defined as where the header for the object
- /// file is that describes the content of the file. If the header
- /// doesn't appear in a section that is defined in the object file,
- /// an address with no section is returned that has the file offset
- /// set in the m_file_offset member of the lldb_private::Address object.
+ /// The header address is defined as where the header for the object file is
+ /// that describes the content of the file. If the header doesn't appear in
+ /// a section that is defined in the object file, an address with no section
+ /// is returned that has the file offset set in the m_file_offset member of
+ /// the lldb_private::Address object.
///
/// @return
/// Returns the entry address for this module.
virtual uint32_t GetNumThreadContexts() { return 0; }
//------------------------------------------------------------------
- /// Some object files may have an identifier string embedded in them,
- /// e.g. in a Mach-O core file using the LC_IDENT load command (which
- /// is obsolete, but can still be found in some old files)
+ /// Some object files may have an identifier string embedded in them, e.g.
+ /// 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
/// Returns the identifier string if one exists, else an empty
}
//------------------------------------------------------------------
- /// When the ObjectFile is a core file, lldb needs to locate the
- /// "binary" in the core file. lldb can iterate over the pages looking
- /// for a valid binary, but some core files may have metadata
- /// describing where the main binary is exactly which removes ambiguity
- /// when there are multiple binaries present in the captured memory pages.
+ /// When the ObjectFile is a core file, lldb needs to locate the "binary" in
+ /// the core file. lldb can iterate over the pages looking for a valid
+ /// binary, but some core files may have metadata describing where the main
+ /// binary is exactly which removes ambiguity when there are multiple
+ /// binaries present in the captured memory pages.
///
/// @param[out] address
/// If the address of the binary is specified, this will be set.
}
//------------------------------------------------------------------
- /// The object file should be able to calculate its type by looking
- /// at its file header and possibly the sections or other data in
- /// the object file. The file type is used in the debugger to help
- /// select the correct plug-ins for the job at hand, so this is
- /// important to get right. If any eTypeXXX definitions do not match
- /// up with the type of file you are loading, please feel free to
- /// add a new enumeration value.
+ /// The object file should be able to calculate its type by looking at its
+ /// file header and possibly the sections or other data in the object file.
+ /// The file type is used in the debugger to help select the correct plug-
+ /// ins for the job at hand, so this is important to get right. If any
+ /// eTypeXXX definitions do not match up with the type of file you are
+ /// loading, please feel free to add a new enumeration value.
///
/// @return
/// The calculated file type for the current object file.
virtual Type CalculateType() = 0;
//------------------------------------------------------------------
- /// In cases where the type can't be calculated (elf files), this
- /// routine allows someone to explicitly set it. As an example,
- /// SymbolVendorELF uses this routine to set eTypeDebugInfo when
- /// loading debug link files.
+ /// In cases where the type can't be calculated (elf files), this routine
+ /// allows someone to explicitly set it. As an example, SymbolVendorELF uses
+ /// this routine to set eTypeDebugInfo when loading debug link files.
virtual void SetType(Type type) { m_type = type; }
//------------------------------------------------------------------
- /// The object file should be able to calculate the strata of the
- /// object file.
+ /// The object file should be able to calculate the strata of the object
+ /// file.
///
- /// Many object files for platforms might be for either user space
- /// debugging or for kernel debugging. If your object file subclass
- /// can figure this out, it will help with debugger plug-in selection
- /// when it comes time to debug.
+ /// Many object files for platforms might be for either user space debugging
+ /// or for kernel debugging. If your object file subclass can figure this
+ /// out, it will help with debugger plug-in selection when it comes time to
+ /// debug.
///
/// @return
/// The calculated object file strata for the current object
//------------------------------------------------------------------
/// Get the object file version numbers.
///
- /// Many object files have a set of version numbers that describe
- /// the version of the executable or shared library. Typically there
- /// are major, minor and build, but there may be more. This function
- /// will extract the versions from object files if they are available.
+ /// Many object files have a set of version numbers that describe the
+ /// version of the executable or shared library. Typically there are major,
+ /// minor and build, but there may be more. This function will extract the
+ /// versions from object files if they are available.
///
- /// If \a versions is NULL, or if \a num_versions is 0, the return
- /// value will indicate how many version numbers are available in
- /// this object file. Then a subsequent call can be made to this
- /// function with a value of \a versions and \a num_versions that
- /// has enough storage to store some or all version numbers.
+ /// If \a versions is NULL, or if \a num_versions is 0, the return value
+ /// will indicate how many version numbers are available in this object
+ /// file. Then a subsequent call can be made to this 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
/// A pointer to an array of uint32_t types that is \a num_versions
//------------------------------------------------------------------
/// Get the minimum OS version this object file can run on.
///
- /// Some object files have information that specifies the minimum OS
- /// version that they can be used on.
+ /// Some object files have information that specifies the minimum OS version
+ /// that they can be used on.
///
- /// If \a versions is NULL, or if \a num_versions is 0, the return
- /// value will indicate how many version numbers are available in
- /// this object file. Then a subsequent call can be made to this
- /// function with a value of \a versions and \a num_versions that
- /// has enough storage to store some or all version numbers.
+ /// If \a versions is NULL, or if \a num_versions is 0, the return value
+ /// will indicate how many version numbers are available in this object
+ /// file. Then a subsequent call can be made to this 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
/// A pointer to an array of uint32_t types that is \a num_versions
//------------------------------------------------------------------
/// Return true if this file is a dynamic link editor (dyld)
///
- /// Often times dyld has symbols that mirror symbols in libc and
- /// other shared libraries (like "malloc" and "free") and the user
- /// does _not_ want to stop in these shared libraries by default.
- /// We can ask the ObjectFile if it is such a file and should be
- /// avoided for things like settings breakpoints and doing function
- /// lookups for expressions.
+ /// Often times dyld has symbols that mirror symbols in libc and other
+ /// shared libraries (like "malloc" and "free") and the user does _not_ want
+ /// to stop in these shared libraries by default. We can ask the ObjectFile
+ /// if it is such a file and should be avoided for things like settings
+ /// breakpoints and doing function lookups for expressions.
//------------------------------------------------------------------
virtual bool GetIsDynamicLinkEditor() { return false; }
//------------------------------------------------------------------
/// Loads this objfile to memory.
///
- /// Loads the bits needed to create an executable image to the memory.
- /// It is useful with bare-metal targets where target does not have the
- /// ability to start a process itself.
+ /// Loads the bits needed to create an executable image to the memory. It is
+ /// useful with bare-metal targets where target does not have the ability to
+ /// start a process itself.
///
/// @param[in] target
/// Target where to load.
uint32_t m_synthetic_symbol_idx;
//------------------------------------------------------------------
- /// Sets the architecture for a module. At present the architecture
- /// can only be set if it is invalid. It is not allowed to switch from
- /// one concrete architecture to another.
+ /// Sets the architecture for a module. At present the architecture can
+ /// only be set if it is invalid. It is not allowed to switch from one
+ /// concrete architecture to another.
///
/// @param[in] new_arch
/// The architecture this module will be set to.
class SymbolContextScope;
//----------------------------------------------------------------------
-/// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h"
-/// @brief Defines a symbol context baton that can be handed other debug
-/// core functions.
+/// @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
+/// 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.
//----------------------------------------------------------------------
class SymbolContext {
//------------------------------------------------------------------
/// Default constructor.
///
- /// Initialize all pointer members to nullptr and all struct members
- /// to their default state.
+ /// Initialize all pointer members to nullptr and all struct members to
+ /// their default state.
//------------------------------------------------------------------
SymbolContext();
//------------------------------------------------------------------
- /// Construct with an object that knows how to reconstruct its
- /// symbol context.
+ /// Construct with an object that knows how to reconstruct its symbol
+ /// context.
///
/// @param[in] sc_scope
/// A symbol context scope object that knows how to reconstruct
explicit SymbolContext(SymbolContextScope *sc_scope);
//------------------------------------------------------------------
- /// Construct with module, and optional compile unit, function,
- /// block, line table, line entry and symbol.
+ /// Construct with module, and optional compile unit, function, block, line
+ /// table, line entry and symbol.
///
/// Initialize all pointer to the specified values.
///
//------------------------------------------------------------------
/// Assignment operator.
///
- /// Copies the address value from another SymbolContext object \a
- /// rhs into \a this object.
+ /// Copies the address value from another SymbolContext object \a rhs into
+ /// \a this object.
///
/// @param[in] rhs
/// A const SymbolContext object reference to copy.
//------------------------------------------------------------------
/// Clear the object's state.
///
- /// Resets all pointer members to nullptr, and clears any class objects
- /// to their default state.
+ /// Resets all pointer members to nullptr, and clears any class objects to
+ /// their default state.
//------------------------------------------------------------------
void Clear(bool clear_target);
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of this object to the
- /// supplied stream \a s.
+ /// Dump a description of the contents of this object to the supplied stream
+ /// \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Dump the stop context in this object to a Stream.
///
- /// Dump the best description of this object to the stream. The
- /// information displayed depends on the amount and quality of the
- /// information in this context. If a module, function, file and
- /// line number are available, they will be dumped. If only a
- /// module and function or symbol name with offset is available,
- /// that will be output. Else just the address at which the target
- /// was stopped will be displayed.
+ /// Dump the best description of this object to the stream. The information
+ /// displayed depends on the amount and quality of the information in this
+ /// context. If a module, function, file and line number are available, they
+ /// will be dumped. If only a module and function or symbol name with offset
+ /// is available, that will be output. Else just the address at which the
+ /// target was stopped will be displayed.
///
/// @param[in] s
/// The stream to which to dump the object description.
lldb::LanguageType GetLanguage() const;
//------------------------------------------------------------------
- /// Find a block that defines the function represented by this
- /// symbol context.
+ /// Find a block that defines the function represented by this symbol
+ /// context.
///
- /// If this symbol context points to a block that is an inlined
- /// function, or is contained within an inlined function, the block
- /// that defines the inlined function is returned.
+ /// If this symbol context points to a block that is an inlined function, or
+ /// is contained within an inlined function, the block that defines the
+ /// inlined function is returned.
///
- /// If this symbol context has no block in it, or the block is not
- /// itself an inlined function block or contained within one, we
- /// return the top level function block.
+ /// If this symbol context has no block in it, or the block is not itself an
+ /// inlined function block or contained within one, we return the top level
+ /// function block.
///
- /// This is a handy function to call when you want to get the block
- /// whose variable list will include the arguments for the function
- /// that is represented by this symbol context (whether the function
- /// is an inline function or not).
+ /// This is a handy function to call when you want to get the block whose
+ /// variable list will include the arguments for the function that is
+ /// represented by this symbol context (whether the function is an inline
+ /// function or not).
///
/// @return
/// The block object pointer that defines the function that is
Block *GetFunctionBlock();
//------------------------------------------------------------------
- /// If this symbol context represents a function that is a method,
- /// return true and provide information about the method.
+ /// If this symbol context represents a function that is a method, return
+ /// true and provide information about the method.
///
/// @param[out] language
/// If \b true is returned, the language for the method.
ConstString &language_object_name);
//------------------------------------------------------------------
- /// Sorts the types in TypeMap according to SymbolContext
- /// to TypeList
+ /// Sorts the types in TypeMap according to SymbolContext to TypeList
///
//------------------------------------------------------------------
void SortTypeList(TypeMap &type_map, TypeList &type_list) const;
//------------------------------------------------------------------
/// Find a name of the innermost function for the symbol context.
///
- /// For instance, if the symbol context contains an inlined block,
- /// it will return the inlined function name.
+ /// For instance, if the symbol context contains an inlined block, it will
+ /// return the inlined function name.
///
/// @param[in] prefer_mangled
/// if \btrue, then the mangled name will be returned if there
//------------------------------------------------------------------
/// Get the line entry that corresponds to the function.
///
- /// If the symbol context contains an inlined block, the line entry
- /// for the start address of the inlined function will be returned,
- /// otherwise the line entry for the start address of the function
- /// will be returned. This can be used after doing a
- /// Module::FindFunctions(...) or ModuleList::FindFunctions(...)
- /// call in order to get the correct line table information for
- /// the symbol context.
- /// it will return the inlined function name.
+ /// If the symbol context contains an inlined block, the line entry for the
+ /// start address of the inlined function will be returned, otherwise the
+ /// line entry for the start address of the function will be returned. This
+ /// can be used after doing a Module::FindFunctions(...) or
+ /// ModuleList::FindFunctions(...) call in order to get the correct line
+ /// table information for the symbol context. it will return the inlined
+ /// function name.
///
/// @param[in] prefer_mangled
/// if \btrue, then the mangled name will be returned if there
//------------------------------------------------------------------
/// Find the block containing the inlined block that contains this block.
///
- /// For instance, if the symbol context contains an inlined block,
- /// it will return the inlined function name.
+ /// For instance, if the symbol context contains an inlined block, it will
+ /// return the inlined function name.
///
/// @param[in] curr_frame_pc
/// The address within the block of this object.
//----------------------------------------------------------------------
/// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
-/// @brief Defines a list of symbol context objects.
+/// 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:
+/// 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.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Dump a description of this object to a Stream.
///
- /// Dump a description of the contents of each symbol context in
- /// the list to the supplied stream \a s.
+ /// Dump a description of the contents of each symbol context in the list to
+ /// the supplied stream \a s.
///
/// @param[in] s
/// The stream to which to dump the object description.
//------------------------------------------------------------------
/// Get accessor for a symbol context at index \a idx.
///
- /// Dump a description of the contents of each symbol context in
- /// the list to the supplied stream \a s.
+ /// Dump a description of the contents of each symbol context in the list to
+ /// the supplied stream \a s.
///
/// @param[in] idx
/// The zero based index into the symbol context list.
//------------------------------------------------------------------
/// Direct reference accessor for a symbol context at index \a idx.
///
- /// The index \a idx must be a valid index, no error checking will
- /// be done to ensure that it is valid.
+ /// The index \a idx must be a valid index, no error checking will be done
+ /// to ensure that it is valid.
///
/// @param[in] idx
/// The zero based index into the symbol context list.
//----------------------------------------------------------------------
/// @class SymbolContextScope SymbolContextScope.h
-/// "lldb/Symbol/SymbolContextScope.h"
-/// @brief Inherit from this if your object is part of a symbol context
+/// "lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is
+/// part of a symbol context
/// and can reconstruct its symbol context.
///
-/// Many objects that are part of a symbol context that have pointers
-/// back to parent objects that own them. Any members of a symbol
-/// context that, once they are built, will not go away, can inherit
-/// from this pure virtual class and can then reconstruct their symbol
-/// context without having to keep a complete SymbolContext object in
-/// the object.
+/// Many objects that are part of a symbol context that have pointers back to
+/// parent objects that own them. Any members of a symbol context that, once
+/// they are built, will not go away, can inherit from this pure virtual class
+/// and can then reconstruct their symbol context without having to keep a
+/// complete SymbolContext object in the object.
///
/// Examples of these objects include:
/// @li Module
/// @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 uniquely will identify a symbol context. Those clients
-/// can then always reconstruct the symbol context using the pointer, or
-/// use it to uniquely identify a symbol context for an object.
+/// Other objects can store a "SymbolContextScope *" using any pointers to one
+/// of the above objects. This allows clients to hold onto a pointer that
+/// uniquely will identify a symbol context. Those clients can then always
+/// reconstruct the symbol context using the pointer, or use it to uniquely
+/// identify a symbol context for an object.
///
-/// Example objects include that currently use "SymbolContextScope *"
-/// objects include:
+/// Example objects include that currently use "SymbolContextScope *" objects
+/// include:
/// @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,
/// location) match within the same thread, that the stack
/// frame is the same as the previous stack frame.
///
-/// Objects that adhere to this protocol can reconstruct enough of a
-/// symbol context to allow functions that take a symbol context to be
-/// called. Lists can also be created using a SymbolContextScope* and
-/// and object pairs that allow large collections of objects to be
-/// passed around with minimal overhead.
+/// Objects that adhere to this protocol can reconstruct enough of a symbol
+/// context to allow functions that take a symbol context to be called. Lists
+/// can also be created using a SymbolContextScope* and and object pairs that
+/// allow large collections of objects to be passed around with minimal
+/// overhead.
//----------------------------------------------------------------------
class SymbolContextScope {
public:
//------------------------------------------------------------------
/// Reconstruct the object's symbol context into \a sc.
///
- /// The object should fill in as much of the SymbolContext as it
- /// can so function calls that require a symbol context can be made
- /// for the given object.
+ /// The object should fill in as much of the SymbolContext as it can so
+ /// function calls that require a symbol context can be made for the given
+ /// object.
///
/// @param[out] sc
/// A symbol context object pointer that gets filled in.
//------------------------------------------------------------------
/// Dump the object's symbol context to the stream \a s.
///
- /// The object should dump its symbol context to the stream \a s.
- /// This function is widely used in the DumpDebug and verbose output
- /// for lldb objects.
+ /// The object should dump its symbol context to the stream \a s. This
+ /// function is widely used in the DumpDebug and verbose output for lldb
+ /// objects.
///
/// @param[in] s
/// The stream to which to dump the object's symbol context.
//----------------------------------------------------------------------
/// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
-/// @brief A plug-in interface definition class for dynamic loaders.
+/// A plug-in interface definition class for dynamic loaders.
///
/// Dynamic loader plug-ins track image (shared library) loading and
-/// unloading. The class is initialized given a live process that is
-/// halted at its entry point or just after attaching.
+/// unloading. The class is initialized given a live process that is halted at
+/// its entry point or just after attaching.
///
-/// Dynamic loader plug-ins can track the process by registering
-/// callbacks using the:
-/// Process::RegisterNotificationCallbacks (const Notifications&)
+/// Dynamic loader plug-ins can track the process by registering callbacks
+/// using the: Process::RegisterNotificationCallbacks (const Notifications&)
/// function.
///
-/// Breakpoints can also be set in the process which can register
-/// functions that get called using:
-/// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void
-/// *).
-/// These breakpoint callbacks return a boolean value that indicates if
-/// the process should continue or halt and should return the global
-/// setting for this using:
+/// Breakpoints can also be set in the process which can register functions
+/// that get called using: Process::BreakpointSetCallback (lldb::user_id_t,
+/// BreakpointHitCallback, void *). These breakpoint callbacks return a
+/// boolean value that indicates if the process should continue or halt and
+/// should return the global setting for this using:
/// DynamicLoader::StopWhenImagesChange() const.
//----------------------------------------------------------------------
class DynamicLoader : public PluginInterface {
//------------------------------------------------------------------
/// Find a dynamic loader plugin for a given process.
///
- /// Scans the installed DynamicLoader plug-ins and tries to find
- /// an instance that can be used to track image changes in \a
- /// process.
+ /// 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
/// The process for which to try and locate a dynamic loader
//------------------------------------------------------------------
/// Destructor.
///
- /// The destructor is virtual since this class is designed to be
- /// inherited from by the plug-in instance.
+ /// The destructor is virtual since this class is designed to be inherited
+ /// from by the plug-in instance.
//------------------------------------------------------------------
virtual ~DynamicLoader() override;
//------------------------------------------------------------------
/// Called after attaching a process.
///
- /// Allow DynamicLoader plug-ins to execute some code after
- /// attaching to a process.
+ /// Allow DynamicLoader plug-ins to execute some code after attaching to a
+ /// process.
//------------------------------------------------------------------
virtual void DidAttach() = 0;
//------------------------------------------------------------------
/// Called after launching a process.
///
- /// Allow DynamicLoader plug-ins to execute some code after
- /// the process has stopped for the first time on launch.
+ /// Allow DynamicLoader plug-ins to execute some code after the process has
+ /// stopped for the first time on launch.
//------------------------------------------------------------------
virtual void DidLaunch() = 0;
//------------------------------------------------------------------
- /// Helper function that can be used to detect when a process has
- /// called exec and is now a new and different process. This can
- /// be called when necessary to try and detect the exec. The process
- /// might be able to answer this question, but sometimes it might
- /// not be able and the dynamic loader often knows what the program
- /// entry point is. So the process and the dynamic loader can work
- /// together to detect this.
+ /// Helper function that can be used to detect when a process has called
+ /// exec and is now a new and different process. This can be called when
+ /// necessary to try and detect the exec. The process might be able to
+ /// answer this question, but sometimes it might not be able and the dynamic
+ /// loader often knows what the program entry point is. So the process and
+ /// the dynamic loader can work together to detect this.
//------------------------------------------------------------------
virtual bool ProcessDidExec() { return false; }
//------------------------------------------------------------------
/// Get whether the process should stop when images change.
///
- /// When images (executables and shared libraries) get loaded or
- /// unloaded, often debug sessions will want to try and resolve or
- /// unresolve breakpoints that are set in these images. Any
- /// breakpoints set by DynamicLoader plug-in instances should
- /// return this value to ensure consistent debug session behaviour.
+ /// When images (executables and shared libraries) get loaded or unloaded,
+ /// often debug sessions will want to try and resolve or unresolve
+ /// breakpoints that are set in these images. Any breakpoints set by
+ /// DynamicLoader plug-in instances should return this value to ensure
+ /// consistent debug session behaviour.
///
/// @return
/// Returns \b true if the process should stop when images
//------------------------------------------------------------------
/// Set whether the process should stop when images change.
///
- /// When images (executables and shared libraries) get loaded or
- /// unloaded, often debug sessions will want to try and resolve or
- /// unresolve breakpoints that are set in these images. The default
- /// is set so that the process stops when images change, but this
- /// can be overridden using this function callback.
+ /// When images (executables and shared libraries) get loaded or unloaded,
+ /// often debug sessions will want to try and resolve or unresolve
+ /// breakpoints that are set in these images. The default is set so that the
+ /// process stops when images change, but this can be overridden using this
+ /// function callback.
///
/// @param[in] stop
/// Boolean value that indicates whether the process should stop
void SetStopWhenImagesChange(bool stop);
//------------------------------------------------------------------
- /// Provides a plan to step through the dynamic loader trampoline
- /// for the current state of \a thread.
+ /// Provides a plan to step through the dynamic loader trampoline for the
+ /// current state of \a thread.
///
///
/// @param[in] stop_others
//------------------------------------------------------------------
/// Some dynamic loaders provide features where there are a group of symbols
- /// "equivalent to"
- /// a given symbol one of which will be chosen when the symbol is bound. If
- /// you want to
- /// set a breakpoint on one of these symbols, you really need to set it on all
- /// the
- /// equivalent symbols.
+ /// "equivalent to" a given symbol one of which will be chosen when the
+ /// symbol is bound. If you want to set a breakpoint on one of these
+ /// symbols, you really need to set it on all the equivalent symbols.
///
///
/// @param[in] original_symbol
}
//------------------------------------------------------------------
- /// Ask if it is ok to try and load or unload an shared library
- /// (image).
+ /// Ask if it is ok to try and load or unload an shared library (image).
///
- /// The dynamic loader often knows when it would be ok to try and
- /// load or unload a shared library. This function call allows the
- /// dynamic loader plug-ins to check any current dyld state to make
- /// sure it is an ok time to load a shared library.
+ /// The dynamic loader often knows when it would be ok to try and load or
+ /// unload a shared library. This function call allows the dynamic loader
+ /// plug-ins to check any current dyld state to make sure it is an ok time
+ /// to load a shared library.
///
/// @return
/// \b true if it is currently ok to try and load a shared
virtual Status CanLoadImage() = 0;
//------------------------------------------------------------------
- /// Ask if the eh_frame information for the given SymbolContext should
- /// be relied on even when it's the first frame in a stack unwind.
+ /// Ask if the eh_frame information for the given SymbolContext should be
+ /// relied on even when it's the first frame in a stack unwind.
///
- /// The CFI instructions from the eh_frame section are normally only
- /// valid at call sites -- places where a program could throw an
- /// exception and need to unwind out. But some Modules may be known
- /// to the system as having reliable eh_frame information at all call
- /// sites. This would be the case if the Module's contents are largely
- /// hand-written assembly with hand-written eh_frame information.
- /// Normally when unwinding from a function at the beginning of a stack
- /// unwind lldb will examine the assembly instructions to understand
- /// how the stack frame is set up and where saved registers are stored.
- /// But with hand-written assembly this is not reliable enough -- we need
- /// to consult those function's hand-written eh_frame information.
+ /// The CFI instructions from the eh_frame section are normally only valid
+ /// at call sites -- places where a program could throw an exception and
+ /// need to unwind out. But some Modules may be known to the system as
+ /// having reliable eh_frame information at all call sites. This would be
+ /// the case if the Module's contents are largely hand-written assembly with
+ /// hand-written eh_frame information. Normally when unwinding from a
+ /// function at the beginning of a stack unwind lldb will examine the
+ /// assembly instructions to understand how the stack frame is set up and
+ /// where saved registers are stored. But with hand-written assembly this is
+ /// not reliable enough -- we need to consult those function's hand-written
+ /// eh_frame information.
///
/// @return
/// \b True if the symbol context should use eh_frame instructions
//------------------------------------------------------------------
/// Get information about the shared cache for a process, if possible.
///
- /// On some systems (e.g. Darwin based systems), a set of libraries
- /// that are common to most processes may be put in a single region
- /// of memory and mapped into every process, this is called the
- /// shared cache, as a performance optimization.
+ /// On some systems (e.g. Darwin based systems), a set of libraries that are
+ /// common to most processes may be put in a single region of memory and
+ /// mapped into every process, this is called the shared cache, as a
+ /// performance optimization.
///
/// Many targets will not have the concept of a shared cache.
///
- /// Depending on how the DynamicLoader gathers information about the
- /// shared cache, it may be able to only return basic information -
- /// like the UUID of the cache - or it may be able to return additional
- /// information about the cache.
+ /// Depending on how the DynamicLoader gathers information about the shared
+ /// cache, it may be able to only return basic information - like the UUID
+ /// of the cache - or it may be able to return additional information about
+ /// the cache.
///
/// @param[out] base_address
/// The base address (load address) of the shared cache.
namespace lldb_private {
//===----------------------------------------------------------------------===//
-/// Execution context objects refer to objects in the execution of the
-/// program that is being debugged. The consist of one or more of the
-/// following objects: target, process, thread, and frame. Many objects
-/// in the debugger need to track different executions contexts. For
-/// example, a local function variable might have an execution context
-/// that refers to a stack frame. A global or static variable might
-/// refer to a target since a stack frame isn't required in order to
-/// evaluate a global or static variable (a process isn't necessarily
-/// needed for a global variable since we might be able to read the
-/// variable value from a data section in one of the object files in
+/// Execution context objects refer to objects in the execution of the program
+/// that is being debugged. The consist of one or more of the following
+/// objects: target, process, thread, and frame. Many objects in the debugger
+/// need to track different executions contexts. For example, a local function
+/// variable might have an execution context that refers to a stack frame. A
+/// global or static variable might refer to a target since a stack frame
+/// isn't required in order to evaluate a global or static variable (a process
+/// isn't necessarily needed for a global variable since we might be able to
+/// read the variable value from a data section in one of the object files in
/// a target). There are two types of objects that hold onto execution
-/// contexts: ExecutionContextRef and ExecutionContext. Both of these
-/// objects are described below.
+/// contexts: ExecutionContextRef and ExecutionContext. Both of these objects
+/// are described below.
///
/// Not all objects in an ExectionContext objects will be valid. If you want
-/// to refer strongly (ExectionContext) or weakly (ExectionContextRef) to
-/// a process, then only the process and target references will be valid.
-/// For threads, only the thread, process and target references will be
-/// filled in. For frames, all of the objects will be filled in.
+/// to refer strongly (ExectionContext) or weakly (ExectionContextRef) to a
+/// process, then only the process and target references will be valid. For
+/// threads, only the thread, process and target references will be filled in.
+/// For frames, all of the objects will be filled in.
///
-/// These classes are designed to be used as baton objects that get passed
-/// to a wide variety of functions that require execution contexts.
+/// These classes are designed to be used as baton objects that get passed to
+/// a wide variety of functions that require execution contexts.
//===----------------------------------------------------------------------===//
//----------------------------------------------------------------------
/// @class ExecutionContextRef ExecutionContext.h
/// "lldb/Target/ExecutionContext.h"
-/// @brief A class that holds a weak reference to an execution context.
+/// A class that holds a weak reference to an execution context.
///
-/// ExecutionContextRef objects are designed to hold onto an execution
-/// context that might change over time. For example, if an object wants
-/// to refer to a stack frame, it should hold onto an ExecutionContextRef
-/// to a frame object. The backing object that represents the stack frame
-/// might change over time and instances of this object can track the logical
-/// object that refers to a frame even if it does change.
+/// ExecutionContextRef objects are designed to hold onto an execution context
+/// that might change over time. For example, if an object wants to refer to a
+/// stack frame, it should hold onto an ExecutionContextRef to a frame object.
+/// The backing object that represents the stack frame might change over time
+/// and instances of this object can track the logical object that refers to a
+/// frame even if it does change.
///
/// These objects also don't keep execution objects around longer than they
-/// should since they use weak pointers. For example if an object refers
-/// to a stack frame and a stack frame is no longer in a thread, then a
-/// ExecutionContextRef object that refers to that frame will not be able
-/// to get a shared pointer to those objects since they are no longer around.
+/// should since they use weak pointers. For example if an object refers to a
+/// stack frame and a stack frame is no longer in a thread, then a
+/// ExecutionContextRef object that refers to that frame will not be able to
+/// get a shared pointer to those objects since they are no longer around.
///
-/// ExecutionContextRef objects can also be used as objects in classes
-/// that want to track a "previous execution context". Since the weak
-/// references to the execution objects (target, process, thread and frame)
-/// don't keep these objects around, they are safe to keep around.
+/// ExecutionContextRef objects can also be used as objects in classes that
+/// want to track a "previous execution context". Since the weak references to
+/// the execution objects (target, process, thread and frame) don't keep these
+/// objects around, they are safe to keep around.
///
-/// The general rule of thumb is all long lived objects that want to
-/// refer to execution contexts should use ExecutionContextRef objects.
-/// The ExecutionContext class is used to temporarily get shared
-/// pointers to any execution context objects that are still around
-/// so they are guaranteed to exist during a function that requires the
-/// objects. ExecutionContext objects should NOT be used for long term
-/// storage since they will keep objects alive with extra shared pointer
-/// references to these objects.
+/// The general rule of thumb is all long lived objects that want to refer to
+/// execution contexts should use ExecutionContextRef objects. The
+/// ExecutionContext class is used to temporarily get shared pointers to any
+/// execution context objects that are still around so they are guaranteed to
+/// exist during a function that requires the objects. ExecutionContext
+/// objects should NOT be used for long term storage since they will keep
+/// objects alive with extra shared pointer references to these objects.
//----------------------------------------------------------------------
class ExecutionContextRef {
public:
//------------------------------------------------------------------
/// Construct using an ExecutionContext object that might be nullptr.
///
- /// If \a exe_ctx_ptr is valid, then make weak references to any
- /// valid objects in the ExecutionContext, otherwise no weak
- /// references to any execution context objects will be made.
+ /// If \a exe_ctx_ptr is valid, then make weak references to any valid
+ /// objects in the ExecutionContext, otherwise no weak references to any
+ /// execution context objects will be made.
//------------------------------------------------------------------
ExecutionContextRef(const ExecutionContext *exe_ctx_ptr);
ExecutionContextRef(const ExecutionContext &exe_ctx);
//------------------------------------------------------------------
- /// Construct using the target and all the selected items inside of it
- /// (the process and its selected thread, and the thread's selected
- /// frame). If there is no selected thread, default to the first thread
- /// If there is no selected frame, default to the first frame.
+ /// Construct using the target and all the selected items inside of it (the
+ /// process and its selected thread, and the thread's selected frame). If
+ /// there is no selected thread, default to the first thread If there is no
+ /// selected frame, default to the first frame.
//------------------------------------------------------------------
ExecutionContextRef(Target *target, bool adopt_selected);
//------------------------------------------------------------------
/// Construct using an execution context scope.
///
- /// If the ExecutionContextScope object is valid and refers to a frame,
- /// make weak references too the frame, thread, process and target.
- /// If the ExecutionContextScope object is valid and refers to a thread,
- /// make weak references too the thread, process and target.
- /// If the ExecutionContextScope object is valid and refers to a process,
- /// make weak references too the process and target.
- /// If the ExecutionContextScope object is valid and refers to a target,
- /// make weak references too the target.
+ /// If the ExecutionContextScope object is valid and refers to a frame, make
+ /// weak references too the frame, thread, process and target. If the
+ /// ExecutionContextScope object is valid and refers to a thread, make weak
+ /// references too the thread, process and target. If the
+ /// ExecutionContextScope object is valid and refers to a process, make weak
+ /// references too the process and target. If the ExecutionContextScope
+ /// object is valid and refers to a target, make weak references too the
+ /// target.
//------------------------------------------------------------------
ExecutionContextRef(ExecutionContextScope *exe_scope);
//------------------------------------------------------------------
/// Construct using an execution context scope.
///
- /// If the ExecutionContextScope object refers to a frame,
- /// make weak references too the frame, thread, process and target.
- /// If the ExecutionContextScope object refers to a thread,
- /// make weak references too the thread, process and target.
- /// If the ExecutionContextScope object refers to a process,
- /// make weak references too the process and target.
- /// If the ExecutionContextScope object refers to a target,
- /// make weak references too the target.
+ /// If the ExecutionContextScope object refers to a frame, make weak
+ /// references too the frame, thread, process and target. If the
+ /// ExecutionContextScope object refers to a thread, make weak references
+ /// too the thread, process and target. If the ExecutionContextScope object
+ /// refers to a process, make weak references too the process and target. If
+ /// the ExecutionContextScope object refers to a target, make weak
+ /// references too the target.
//------------------------------------------------------------------
ExecutionContextRef(ExecutionContextScope &exe_scope);
void Clear();
//------------------------------------------------------------------
- /// Set accessor that creates a weak reference to the target
- /// referenced in \a target_sp.
+ /// Set accessor that creates a weak reference to the target referenced in
+ /// \a target_sp.
///
- /// If \a target_sp is valid this object will create a weak
- /// reference to that object, otherwise any previous target weak
- /// reference contained in this object will be reset.
+ /// If \a target_sp is valid this object will create a weak reference to
+ /// that object, otherwise any previous target weak reference contained in
+ /// this object will be reset.
///
- /// Only the weak reference to the target will be updated, no other
- /// weak references will be modified. If you want this execution
- /// context to make a weak reference to the target's process, use
- /// the ExecutionContextRef::SetContext() functions.
+ /// Only the weak reference to the target will be updated, no other weak
+ /// references will be modified. If you want this execution context to make
+ /// a weak reference to the target's process, use the
+ /// ExecutionContextRef::SetContext() functions.
///
/// @see ExecutionContextRef::SetContext(const lldb::TargetSP &, bool)
//------------------------------------------------------------------
void SetTargetSP(const lldb::TargetSP &target_sp);
//------------------------------------------------------------------
- /// Set accessor that creates a weak reference to the process
- /// referenced in \a process_sp.
+ /// Set accessor that creates a weak reference to the process referenced in
+ /// \a process_sp.
///
- /// If \a process_sp is valid this object will create a weak
- /// reference to that object, otherwise any previous process weak
- /// reference contained in this object will be reset.
+ /// If \a process_sp is valid this object will create a weak reference to
+ /// that object, otherwise any previous process weak reference contained in
+ /// this object will be reset.
///
- /// Only the weak reference to the process will be updated, no other
- /// weak references will be modified. If you want this execution
- /// context to make a weak reference to the target, use the
+ /// Only the weak reference to the process will be updated, no other weak
+ /// references will be modified. If you want this execution context to make
+ /// a weak reference to the target, use the
/// ExecutionContextRef::SetContext() functions.
///
/// @see ExecutionContextRef::SetContext(const lldb::ProcessSP &)
void SetProcessSP(const lldb::ProcessSP &process_sp);
//------------------------------------------------------------------
- /// Set accessor that creates a weak reference to the thread
- /// referenced in \a thread_sp.
+ /// Set accessor that creates a weak reference to the thread referenced in
+ /// \a thread_sp.
///
- /// If \a thread_sp is valid this object will create a weak
- /// reference to that object, otherwise any previous thread weak
- /// reference contained in this object will be reset.
+ /// If \a thread_sp is valid this object will create a weak reference to
+ /// that object, otherwise any previous thread weak reference contained in
+ /// this object will be reset.
///
- /// Only the weak reference to the thread will be updated, no other
- /// weak references will be modified. If you want this execution
- /// context to make a weak reference to the thread's process and
- /// target, use the ExecutionContextRef::SetContext() functions.
+ /// Only the weak reference to the thread will be updated, no other weak
+ /// references will be modified. If you want this execution context to make
+ /// a weak reference to the thread's process and target, use the
+ /// ExecutionContextRef::SetContext() functions.
///
/// @see ExecutionContextRef::SetContext(const lldb::ThreadSP &)
//------------------------------------------------------------------
void SetThreadSP(const lldb::ThreadSP &thread_sp);
//------------------------------------------------------------------
- /// Set accessor that creates a weak reference to the frame
- /// referenced in \a frame_sp.
+ /// Set accessor that creates a weak reference to the frame referenced in \a
+ /// frame_sp.
///
- /// If \a frame_sp is valid this object will create a weak
- /// reference to that object, otherwise any previous frame weak
- /// reference contained in this object will be reset.
+ /// If \a frame_sp is valid this object will create a weak reference to that
+ /// object, otherwise any previous frame weak reference contained in this
+ /// object will be reset.
///
- /// Only the weak reference to the frame will be updated, no other
- /// weak references will be modified. If you want this execution
- /// context to make a weak reference to the frame's thread, process
- /// and target, use the ExecutionContextRef::SetContext() functions.
+ /// Only the weak reference to the frame will be updated, no other weak
+ /// references will be modified. If you want this execution context to make
+ /// a weak reference to the frame's thread, process and target, use the
+ /// ExecutionContextRef::SetContext() functions.
///
/// @see ExecutionContextRef::SetContext(const lldb::StackFrameSP &)
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Create an ExecutionContext object from this object.
///
- /// 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
+ /// 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
/// An execution context object that has strong references to
/// any valid weak references in this object.
//------------------------------------------------------------------
ExecutionContext Lock(bool thread_and_frame_only_if_stopped) const;
//------------------------------------------------------------------
- /// Returns true if this object has a weak reference to a thread.
- /// The return value is only an indication of whether this object has
- /// a weak reference and does not indicate whether the weak reference
- /// is valid or not.
+ /// Returns true if this object has a weak reference to a thread. The return
+ /// value is only an indication of whether this object has a weak reference
+ /// and does not indicate whether the weak reference is valid or not.
//------------------------------------------------------------------
bool HasThreadRef() const { return m_tid != LLDB_INVALID_THREAD_ID; }
//------------------------------------------------------------------
- /// Returns true if this object has a weak reference to a frame.
- /// The return value is only an indication of whether this object has
- /// a weak reference and does not indicate whether the weak reference
- /// is valid or not.
+ /// Returns true if this object has a weak reference to a frame. The return
+ /// value is only an indication of whether this object has a weak reference
+ /// and does not indicate whether the weak reference is valid or not.
//------------------------------------------------------------------
bool HasFrameRef() const { return m_stack_id.IsValid(); }
};
//----------------------------------------------------------------------
-/// @class ExecutionContext ExecutionContext.h "lldb/Target/ExecutionContext.h"
-/// @brief A class that contains an execution context.
+/// @class ExecutionContext ExecutionContext.h
+/// "lldb/Target/ExecutionContext.h"
+/// A class that contains an execution context.
///
-/// This baton object can be passed into any function that requires
-/// a context that specifies a target, process, thread and frame.
-/// These objects are designed to be used for short term execution
-/// context object storage while a function might be trying to evaluate
-/// something that requires a thread or frame. ExecutionContextRef
-/// objects can be used to initialize one of these objects to turn
-/// the weak execution context object references to the target, process,
-/// thread and frame into strong references (shared pointers) so that
-/// functions can guarantee that these objects won't go away in the
+/// This baton object can be passed into any function that requires a context
+/// that specifies a target, process, thread and frame. These objects are
+/// designed to be used for short term execution context object storage while
+/// a function might be trying to evaluate something that requires a thread or
+/// frame. ExecutionContextRef objects can be used to initialize one of these
+/// objects to turn the weak execution context object references to the
+/// target, process, thread and frame into strong references (shared pointers)
+/// so that functions can guarantee that these objects won't go away in the
/// middle of a function.
///
-/// ExecutionContext objects should be used as short lived objects
-/// (typically on the stack) in order to lock down an execution context
-/// for local use and for passing down to other functions that also
-/// require specific contexts. They should NOT be used for long term
-/// storage, for long term storage use ExecutionContextRef objects.
+/// ExecutionContext objects should be used as short lived objects (typically
+/// on the stack) in order to lock down an execution context for local use and
+/// for passing down to other functions that also require specific contexts.
+/// They should NOT be used for long term storage, for long term storage use
+/// ExecutionContextRef objects.
//----------------------------------------------------------------------
class ExecutionContext {
public:
/// Returns a pointer to the target object.
///
/// The returned pointer might be nullptr. Calling HasTargetScope(),
- /// HasProcessScope(), HasThreadScope(), or HasFrameScope()
- /// can help to pre-validate this pointer so that this accessor can
- /// freely be used without having to check for nullptr each time.
+ /// HasProcessScope(), HasThreadScope(), or HasFrameScope() can help to pre-
+ /// validate this pointer so that this accessor can freely be used without
+ /// having to check for nullptr each time.
///
- /// @see ExecutionContext::HasTargetScope() const
- /// @see ExecutionContext::HasProcessScope() const
- /// @see ExecutionContext::HasThreadScope() const
- /// @see ExecutionContext::HasFrameScope() const
+ /// @see ExecutionContext::HasTargetScope() const @see
+ /// ExecutionContext::HasProcessScope() const @see
+ /// ExecutionContext::HasThreadScope() const @see
+ /// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Target *GetTargetPtr() const;
/// Returns a pointer to the process object.
///
/// The returned pointer might be nullptr. Calling HasProcessScope(),
- /// HasThreadScope(), or HasFrameScope() can help to pre-validate
- /// this pointer so that this accessor can freely be used without
- /// having to check for nullptr each time.
+ /// HasThreadScope(), or HasFrameScope() can help to pre-validate this
+ /// pointer so that this accessor can freely be used without having to check
+ /// for nullptr each time.
///
- /// @see ExecutionContext::HasProcessScope() const
- /// @see ExecutionContext::HasThreadScope() const
- /// @see ExecutionContext::HasFrameScope() const
+ /// @see ExecutionContext::HasProcessScope() const @see
+ /// ExecutionContext::HasThreadScope() const @see
+ /// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Process *GetProcessPtr() const;
/// Returns a pointer to the thread object.
///
/// The returned pointer might be nullptr. Calling HasThreadScope() or
- /// HasFrameScope() can help to pre-validate this pointer so that
- /// this accessor can freely be used without having to check for
- /// nullptr each time.
+ /// HasFrameScope() can help to pre-validate this pointer so that this
+ /// accessor can freely be used without having to check for nullptr each
+ /// time.
///
- /// @see ExecutionContext::HasThreadScope() const
- /// @see ExecutionContext::HasFrameScope() const
+ /// @see ExecutionContext::HasThreadScope() const @see
+ /// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Thread *GetThreadPtr() const { return m_thread_sp.get(); }
//------------------------------------------------------------------
/// Returns a pointer to the frame object.
///
- /// The returned pointer might be nullptr. Calling HasFrameScope(),
- /// can help to pre-validate this pointer so that this accessor can
- /// freely be used without having to check for nullptr each time.
+ /// The returned pointer might be nullptr. Calling HasFrameScope(), can help
+ /// 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
//------------------------------------------------------------------
/// Returns a reference to the target object.
///
/// Clients should call HasTargetScope(), HasProcessScope(),
- /// HasThreadScope(), or HasFrameScope() prior to calling this
- /// function to ensure that this ExecutionContext object contains
- /// a valid target.
+ /// HasThreadScope(), or HasFrameScope() prior to calling this function to
+ /// ensure that this ExecutionContext object contains a valid target.
///
- /// @see ExecutionContext::HasTargetScope() const
- /// @see ExecutionContext::HasProcessScope() const
- /// @see ExecutionContext::HasThreadScope() const
- /// @see ExecutionContext::HasFrameScope() const
+ /// @see ExecutionContext::HasTargetScope() const @see
+ /// ExecutionContext::HasProcessScope() const @see
+ /// ExecutionContext::HasThreadScope() const @see
+ /// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Target &GetTargetRef() const;
/// Returns a reference to the process object.
///
/// Clients should call HasProcessScope(), HasThreadScope(), or
- /// HasFrameScope() prior to calling this function to ensure that
- /// this ExecutionContext object contains a valid target.
+ /// HasFrameScope() prior to calling this function to ensure that this
+ /// ExecutionContext object contains a valid target.
///
- /// @see ExecutionContext::HasProcessScope() const
- /// @see ExecutionContext::HasThreadScope() const
- /// @see ExecutionContext::HasFrameScope() const
+ /// @see ExecutionContext::HasProcessScope() const @see
+ /// ExecutionContext::HasThreadScope() const @see
+ /// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Process &GetProcessRef() const;
//------------------------------------------------------------------
/// Returns a reference to the thread object.
///
- /// Clients should call HasThreadScope(), or HasFrameScope() prior
- /// to calling this function to ensure that this ExecutionContext
- /// object contains a valid target.
+ /// Clients should call HasThreadScope(), or HasFrameScope() prior to
+ /// calling this function to ensure that this ExecutionContext object
+ /// contains a valid target.
///
- /// @see ExecutionContext::HasThreadScope() const
- /// @see ExecutionContext::HasFrameScope() const
+ /// @see ExecutionContext::HasThreadScope() const @see
+ /// ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
Thread &GetThreadRef() const;
//------------------------------------------------------------------
/// Returns a reference to the thread object.
///
- /// Clients should call HasFrameScope() prior to calling this
- /// function to ensure that this ExecutionContext object contains
- /// a valid target.
+ /// Clients should call HasFrameScope() prior to calling this function to
+ /// ensure that this ExecutionContext object contains a valid target.
///
/// @see ExecutionContext::HasFrameScope() const
//------------------------------------------------------------------
void SetTargetPtr(Target *target);
//------------------------------------------------------------------
- /// Set accessor to set only the process shared pointer from a
- /// process pointer.
+ /// Set accessor to set only the process shared pointer from a process
+ /// pointer.
//------------------------------------------------------------------
void SetProcessPtr(Process *process);
void SetThreadPtr(Thread *thread);
//------------------------------------------------------------------
- /// Set accessor to set only the frame shared pointer from a frame
- /// pointer.
+ /// Set accessor to set only the frame shared pointer from a frame pointer.
//------------------------------------------------------------------
void SetFramePtr(StackFrame *frame);
void SetContext(const lldb::StackFrameSP &frame_sp);
//------------------------------------------------------------------
- /// Returns true the ExecutionContext object contains a valid
- /// target.
+ /// Returns true the ExecutionContext object contains a valid target.
///
/// This function can be called after initializing an ExecutionContext
/// object, and if it returns true, calls to GetTargetPtr() and
bool HasTargetScope() const;
//------------------------------------------------------------------
- /// Returns true the ExecutionContext object contains a valid
- /// target and process.
+ /// Returns true the ExecutionContext object contains a valid target and
+ /// process.
///
/// This function can be called after initializing an ExecutionContext
/// object, and if it returns true, calls to GetTargetPtr() and
- /// GetTargetRef(), GetProcessPtr(), and GetProcessRef(), do not
- /// need to be checked for validity.
+ /// GetTargetRef(), GetProcessPtr(), and GetProcessRef(), do not need to be
+ /// checked for validity.
//------------------------------------------------------------------
bool HasProcessScope() const;
//------------------------------------------------------------------
- /// Returns true the ExecutionContext object contains a valid
- /// target, process, and thread.
+ /// Returns true the ExecutionContext object contains a valid target,
+ /// process, and thread.
///
/// This function can be called after initializing an ExecutionContext
- /// object, and if it returns true, calls to GetTargetPtr(),
- /// GetTargetRef(), GetProcessPtr(), GetProcessRef(), GetThreadPtr(),
- /// and GetThreadRef() do not need to be checked for validity.
+ /// object, and if it returns true, calls to GetTargetPtr(), GetTargetRef(),
+ /// GetProcessPtr(), GetProcessRef(), GetThreadPtr(), and GetThreadRef() do
+ /// not need to be checked for validity.
//------------------------------------------------------------------
bool HasThreadScope() const;
//------------------------------------------------------------------
- /// Returns true the ExecutionContext object contains a valid
- /// target, process, thread and frame.
+ /// Returns true the ExecutionContext object contains a valid target,
+ /// process, thread and frame.
///
/// This function can be called after initializing an ExecutionContext
- /// object, and if it returns true, calls to GetTargetPtr(),
- /// GetTargetRef(), GetProcessPtr(), GetProcessRef(), GetThreadPtr(),
- /// GetThreadRef(), GetFramePtr(), and GetFrameRef() do not need
- /// to be checked for validity.
+ /// object, and if it returns true, calls to GetTargetPtr(), GetTargetRef(),
+ /// GetProcessPtr(), GetProcessRef(), GetThreadPtr(), GetThreadRef(),
+ /// GetFramePtr(), and GetFrameRef() do not need to be checked for validity.
//------------------------------------------------------------------
bool HasFrameScope() const;
//----------------------------------------------------------------------
/// @class ExecutionContextScope ExecutionContextScope.h
-/// "lldb/Symbol/ExecutionContextScope.h"
-/// @brief Inherit from this if your object can reconstruct its
+/// "lldb/Symbol/ExecutionContextScope.h" Inherit from this if your object can
+/// reconstruct its
/// execution context.
///
-/// Many objects that have pointers back to parent execution context
-/// objects can inherit from this pure virtual class can reconstruct
-/// their execution context without having to keep a complete
-/// ExecutionContext object in the object state. Examples of these
-/// objects include: Process, Thread, RegisterContext and StackFrame.
+/// Many objects that have pointers back to parent execution context objects
+/// can inherit from this pure virtual class can reconstruct their execution
+/// context without having to keep a complete ExecutionContext object in the
+/// object state. Examples of these objects include: Process, Thread,
+/// RegisterContext and StackFrame.
///
-/// Objects can contain a valid pointer to an instance of this so they
-/// can reconstruct the execution context.
+/// Objects can contain a valid pointer to an instance of this so they can
+/// reconstruct the execution context.
///
-/// Objects that adhere to this protocol can reconstruct enough of a
-/// execution context to allow functions that take a execution contexts
-/// to be called.
+/// Objects that adhere to this protocol can reconstruct enough of a execution
+/// context to allow functions that take a execution contexts to be called.
//----------------------------------------------------------------------
class ExecutionContextScope {
public:
//------------------------------------------------------------------
/// Reconstruct the object's execution context into \a sc.
///
- /// The object should fill in as much of the ExecutionContextScope as it
- /// can so function calls that require a execution context can be made
- /// for the given object.
+ /// The object should fill in as much of the ExecutionContextScope as it can
+ /// so function calls that require a execution context can be made for the
+ /// given object.
///
/// @param[out] exe_ctx
/// A reference to an execution context object that gets filled
//----------------------------------------------------------------------
/// @class JITLoader JITLoader.h "lldb/Target/JITLoader.h"
-/// @brief A plug-in interface definition class for JIT loaders.
+/// A plug-in interface definition class for JIT loaders.
///
-/// Plugins of this kind listen for code generated at runtime in the
-/// target. They are very similar to dynamic loader, with the difference
-/// that they do not have information about the target's dyld and
-/// that there may be multiple JITLoader plugins per process, while
-/// there is at most one DynamicLoader.
+/// Plugins of this kind listen for code generated at runtime in the target.
+/// They are very similar to dynamic loader, with the difference that they do
+/// not have information about the target's dyld and that there may be
+/// multiple JITLoader plugins per process, while there is at most one
+/// DynamicLoader.
//----------------------------------------------------------------------
class JITLoader : public PluginInterface {
public:
//------------------------------------------------------------------
/// Find a JIT loader plugin for a given process.
///
- /// Scans the installed DynamicLoader plug-ins and tries to find
- /// all applicable instances for the current process.
+ /// Scans the installed DynamicLoader plug-ins and tries to find all
+ /// applicable instances for the current process.
///
/// @param[in] process
/// The process for which to try and locate a JIT loader
//------------------------------------------------------------------
/// Called after attaching a process.
///
- /// Allow JITLoader plug-ins to execute some code after
- /// attaching to a process.
+ /// Allow JITLoader plug-ins to execute some code after attaching to a
+ /// process.
//------------------------------------------------------------------
virtual void DidAttach() = 0;
//------------------------------------------------------------------
/// Called after launching a process.
///
- /// Allow JITLoader plug-ins to execute some code after
- /// the process has stopped for the first time on launch.
+ /// Allow JITLoader plug-ins to execute some code after the process has
+ /// stopped for the first time on launch.
//------------------------------------------------------------------
virtual void DidLaunch() = 0;
//------------------------------------------------------------------
- /// Called after a new shared object has been loaded so that it can
- /// be probed for JIT entry point hooks.
+ /// Called after a new shared object has been loaded so that it can be
+ /// probed for JIT entry point hooks.
//------------------------------------------------------------------
virtual void ModulesDidLoad(lldb_private::ModuleList &module_list) = 0;
//----------------------------------------------------------------------
/// @class ModuleCache ModuleCache.h "lldb/Target/ModuleCache.h"
-/// @brief A module cache class.
+/// A module cache class.
///
-/// Caches locally modules that are downloaded from remote targets.
-/// Each cached module maintains 2 views:
+/// Caches locally modules that are downloaded from remote targets. Each
+/// cached module maintains 2 views:
/// - UUID view:
/// /${CACHE_ROOT}/${PLATFORM_NAME}/.cache/${UUID}/${MODULE_FILENAME}
/// - Sysroot view:
///
/// Example:
/// UUID view :
-/// /tmp/lldb/remote-linux/.cache/30C94DC6-6A1F-E951-80C3-D68D2B89E576-D5AE213C/libc.so.6
+/// /tmp/lldb/remote-
+/// linux/.cache/30C94DC6-6A1F-E951-80C3-D68D2B89E576-D5AE213C/libc.so.6
/// Sysroot view: /tmp/lldb/remote-linux/ubuntu/lib/x86_64-linux-gnu/libc.so.6
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class OperatingSystem OperatingSystem.h "lldb/Target/OperatingSystem.h"
-/// @brief A plug-in interface definition class for halted OS helpers.
+/// A plug-in interface definition class for halted OS helpers.
///
/// Halted OS plug-ins can be used by any process to locate and create
/// OS objects, like threads, during the lifetime of a debug session.
/// This is commonly used when attaching to an operating system that is
-/// halted, such as when debugging over JTAG or connecting to low level
-/// kernel debug services.
+/// halted, such as when debugging over JTAG or connecting to low level kernel
+/// debug services.
//----------------------------------------------------------------------
class OperatingSystem : public PluginInterface {
//------------------------------------------------------------------
/// Find a halted OS plugin for a given process.
///
- /// Scans the installed OperatingSystem plug-ins and tries to find
- /// an instance that matches the current target triple and
- /// executable.
+ /// Scans the installed OperatingSystem plug-ins and tries to find an
+ /// instance that matches the current target triple and executable.
///
/// @param[in] process
/// The process for which to try and locate a halted OS
//----------------------------------------------------------------------
/// @class Platform Platform.h "lldb/Target/Platform.h"
-/// @brief A plug-in interface definition class for debug platform that
+/// A plug-in interface definition class for debug platform that
/// includes many platform abilities such as:
/// @li getting platform information such as supported architectures,
/// supported binary file formats and more
//------------------------------------------------------------------
/// Destructor.
///
- /// The destructor is virtual since this class is designed to be
- /// inherited from by the plug-in instance.
+ /// The destructor is virtual since this class is designed to be inherited
+ /// from by the plug-in instance.
//------------------------------------------------------------------
~Platform() override;
//------------------------------------------------------------------
/// Get the native host platform plug-in.
///
- /// There should only be one of these for each host that LLDB runs
- /// upon that should be statically compiled in and registered using
- /// preprocessor macros or other similar build mechanisms in a
+ /// There should only be one of these for each host that LLDB runs upon that
+ /// should be statically compiled in and registered using preprocessor
+ /// macros or other similar build mechanisms in a
/// PlatformSubclass::Initialize() function.
///
- /// This platform will be used as the default platform when launching
- /// or attaching to processes unless another platform is specified.
+ /// This platform will be used as the default platform when launching or
+ /// attaching to processes unless another platform is specified.
//------------------------------------------------------------------
static lldb::PlatformSP GetHostPlatform();
//------------------------------------------------------------------
/// Find a platform plugin for a given process.
///
- /// Scans the installed Platform plug-ins and tries to find
- /// an instance that can be used for \a process
+ /// Scans the installed Platform plug-ins and tries to find an instance that
+ /// can be used for \a process
///
/// @param[in] process
/// The process for which to try and locate a platform
// FindPlugin (Process *process, const ConstString &plugin_name);
//------------------------------------------------------------------
- /// Set the target's executable based off of the existing
- /// architecture information in \a target given a path to an
- /// executable \a exe_file.
+ /// Set the target's executable based off of the existing architecture
+ /// information in \a target given a path to an executable \a exe_file.
///
- /// Each platform knows the architectures that it supports and can
- /// select the correct architecture slice within \a exe_file by
- /// inspecting the architecture in \a target. If the target had an
- /// architecture specified, then in can try and obey that request
- /// and optionally fail if the architecture doesn't match up.
- /// If no architecture is specified, the platform should select the
- /// default architecture from \a exe_file. Any application bundles
- /// or executable wrappers can also be inspected for the actual
- /// application binary within the bundle that should be used.
+ /// Each platform knows the architectures that it supports and can select
+ /// the correct architecture slice within \a exe_file by inspecting the
+ /// architecture in \a target. If the target had an architecture specified,
+ /// then in can try and obey that request and optionally fail if the
+ /// architecture doesn't match up. If no architecture is specified, the
+ /// platform should select the default architecture from \a exe_file. Any
+ /// application bundles or executable wrappers can also be inspected for the
+ /// actual application binary within the bundle that should be used.
///
/// @return
/// Returns \b true if this Platform plug-in was able to find
//------------------------------------------------------------------
/// Find a symbol file given a symbol file module specification.
///
- /// Each platform might have tricks to find symbol files for an
- /// executable given information in a symbol file ModuleSpec. Some
- /// platforms might also support symbol files that are bundles and
- /// know how to extract the right symbol file given a bundle.
+ /// Each platform might have tricks to find symbol files for an executable
+ /// given information in a symbol file ModuleSpec. Some platforms might also
+ /// support symbol files that are bundles and know how to extract the right
+ /// symbol file given a bundle.
///
/// @param[in] target
/// The target in which we are trying to resolve the symbol file.
FileSpec &sym_file);
//------------------------------------------------------------------
- /// Resolves the FileSpec to a (possibly) remote path. Remote
- /// platforms must override this to resolve to a path on the remote
- /// side.
+ /// Resolves the FileSpec to a (possibly) remote path. Remote platforms must
+ /// override this to resolve to a path on the remote side.
//------------------------------------------------------------------
virtual bool ResolveRemotePath(const FileSpec &platform_path,
FileSpec &resolved_platform_path);
//------------------------------------------------------------------
/// Get the OS version from a connected platform.
///
- /// Some platforms might not be connected to a remote platform, but
- /// can figure out the OS version for a process. This is common for
- /// simulator platforms that will run native programs on the current
- /// host, but the simulator might be simulating a different OS. The
- /// \a process parameter might be specified to help to determine
- /// the OS version.
+ /// Some platforms might not be connected to a remote platform, but can
+ /// figure out the OS version for a process. This is common for simulator
+ /// platforms that will run native programs on the current host, but the
+ /// simulator might be simulating a different OS. The \a process parameter
+ /// might be specified to help to determine the OS version.
//------------------------------------------------------------------
virtual bool GetOSVersion(uint32_t &major, uint32_t &minor, uint32_t &update,
Process *process = nullptr);
//------------------------------------------------------------------
/// Report the current status for this platform.
///
- /// The returned string usually involves returning the OS version
- /// (if available), and any SDK directory that might be being used
- /// for local file caching, and if connected a quick blurb about
- /// what this platform is connected to.
+ /// The returned string usually involves returning the OS version (if
+ /// available), and any SDK directory that might be being used for local
+ /// file caching, and if connected a quick blurb about what this platform is
+ /// connected to.
//------------------------------------------------------------------
virtual void GetStatus(Stream &strm);
//------------------------------------------------------------------
/// Locate a file for a platform.
///
- /// The default implementation of this function will return the same
- /// file patch in \a local_file as was in \a platform_file.
+ /// 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
/// The platform file path to locate and cache locally.
virtual Status DisconnectRemote();
//------------------------------------------------------------------
- /// Get the platform's supported architectures in the order in which
- /// they should be searched.
+ /// Get the platform's supported architectures in the order in which they
+ /// should be searched.
///
/// @param[in] idx
/// A zero based architecture index
BreakpointSite *bp_site);
//------------------------------------------------------------------
- /// Launch a new process on a platform, not necessarily for
- /// debugging, it could be just for running the process.
+ /// Launch a new process on a platform, not necessarily for debugging, it
+ /// could be just for running the process.
//------------------------------------------------------------------
virtual Status LaunchProcess(ProcessLaunchInfo &launch_info);
//------------------------------------------------------------------
- /// Perform expansion of the command-line for this launch info
- /// This can potentially involve wildcard expansion
+ /// Perform expansion of the command-line for this launch info This can
+ /// potentially involve wildcard expansion
// environment variable replacement, and whatever other
// argument magic the platform defines as part of its typical
// user experience
virtual Status KillProcess(const lldb::pid_t pid);
//------------------------------------------------------------------
- /// Lets a platform answer if it is compatible with a given
- /// architecture and the target triple contained within.
+ /// Lets a platform answer if it is compatible with a given architecture and
+ /// the target triple contained within.
//------------------------------------------------------------------
virtual bool IsCompatibleArchitecture(const ArchSpec &arch,
bool exact_arch_match,
ArchSpec *compatible_arch_ptr);
//------------------------------------------------------------------
- /// Not all platforms will support debugging a process by spawning
- /// somehow halted for a debugger (specified using the
- /// "eLaunchFlagDebug" launch flag) and then attaching. If your
- /// platform doesn't support this, override this function and return
- /// false.
+ /// Not all platforms will support debugging a process by spawning somehow
+ /// halted for a debugger (specified using the "eLaunchFlagDebug" launch
+ /// flag) and then attaching. If your platform doesn't support this,
+ /// override this function and return false.
//------------------------------------------------------------------
virtual bool CanDebugProcess() { return true; }
//------------------------------------------------------------------
- /// Subclasses do not need to implement this function as it uses
- /// the Platform::LaunchProcess() followed by Platform::Attach ().
- /// Remote platforms will want to subclass this function in order
- /// to be able to intercept STDIO and possibly launch a separate
- /// process that will debug the debuggee.
+ /// Subclasses do not need to implement this function as it uses the
+ /// Platform::LaunchProcess() followed by Platform::Attach (). Remote
+ /// platforms will want to subclass this function in order to be able to
+ /// intercept STDIO and possibly launch a separate process that will debug
+ /// the debuggee.
//------------------------------------------------------------------
virtual lldb::ProcessSP
DebugProcess(ProcessLaunchInfo &launch_info, Debugger &debugger,
//------------------------------------------------------------------
/// Attach to an existing process using a process ID.
///
- /// Each platform subclass needs to implement this function and
- /// attempt to attach to the process with the process ID of \a pid.
- /// The platform subclass should return an appropriate ProcessSP
- /// subclass that is attached to the process, or an empty shared
- /// pointer with an appropriate error.
+ /// Each platform subclass needs to implement this function and attempt to
+ /// attach to the process with the process ID of \a pid. The platform
+ /// subclass should return an appropriate ProcessSP subclass that is
+ /// attached to the process, or an empty shared pointer with an appropriate
+ /// error.
///
/// @param[in] pid
/// The process ID that we should attempt to attach to.
//------------------------------------------------------------------
/// Attach to an existing process by process name.
///
- /// This function is not meant to be overridden by Process
- /// subclasses. It will first call
- /// Process::WillAttach (const char *) and if that returns \b
- /// true, Process::DoAttach (const char *) will be called to
- /// actually do the attach. If DoAttach returns \b true, then
- /// Process::DidAttach() will be called.
+ /// This function is not meant to be overridden by Process subclasses. It
+ /// will first call Process::WillAttach (const char *) and if that returns
+ /// \b true, Process::DoAttach (const char *) will be called to actually do
+ /// the attach. If DoAttach returns \b true, then Process::DidAttach() will
+ /// be called.
///
/// @param[in] process_name
/// A process name to match against the current process list.
}
//---------------------------------------------------------------------------
- /// If the triple contains not specify the vendor, os, and environment parts,
- /// we "augment" these using information from the platform and return the
- /// resulting ArchSpec object.
+ /// If the triple contains not specify the vendor, os, and environment
+ /// parts, we "augment" these using information from the platform and return
+ /// the resulting ArchSpec object.
//---------------------------------------------------------------------------
ArchSpec GetAugmentedArchSpec(llvm::StringRef triple);
//----------------------------------------------------------------------
/// Install a file or directory to the remote system.
///
- /// Install is similar to Platform::PutFile(), but it differs in that if
- /// an application/framework/shared library is installed on a remote
- /// platform and the remote platform requires something to be done to
- /// register the application/framework/shared library, then this extra
- /// registration can be done.
+ /// Install is similar to Platform::PutFile(), but it differs in that if an
+ /// application/framework/shared library is installed on a remote platform
+ /// and the remote platform requires something to be done to register the
+ /// application/framework/shared library, then this extra registration can
+ /// be done.
///
/// @param[in] src
/// The source file/directory to install on the remote system.
//------------------------------------------------------------------
/// Locate a queue name given a thread's qaddr
///
- /// On a system using libdispatch ("Grand Central Dispatch") style
- /// queues, a thread may be associated with a GCD queue or not,
- /// and a queue may be associated with multiple threads.
- /// The process/thread must provide a way to find the "dispatch_qaddr"
- /// for each thread, and from that dispatch_qaddr this Platform method
- /// will locate the queue name and provide that.
+ /// On a system using libdispatch ("Grand Central Dispatch") style queues, a
+ /// thread may be associated with a GCD queue or not, and a queue may be
+ /// associated with multiple threads. The process/thread must provide a way
+ /// to find the "dispatch_qaddr" for each thread, and from that
+ /// dispatch_qaddr this Platform method will locate the queue name and
+ /// provide that.
///
/// @param[in] process
/// A process is required for reading memory.
//------------------------------------------------------------------
/// Locate a queue ID given a thread's qaddr
///
- /// On a system using libdispatch ("Grand Central Dispatch") style
- /// queues, a thread may be associated with a GCD queue or not,
- /// and a queue may be associated with multiple threads.
- /// The process/thread must provide a way to find the "dispatch_qaddr"
- /// for each thread, and from that dispatch_qaddr this Platform method
- /// will locate the queue ID and provide that.
+ /// On a system using libdispatch ("Grand Central Dispatch") style queues, a
+ /// thread may be associated with a GCD queue or not, and a queue may be
+ /// associated with multiple threads. The process/thread must provide a way
+ /// to find the "dispatch_qaddr" for each thread, and from that
+ /// dispatch_qaddr this Platform method will locate the queue ID and provide
+ /// that.
///
/// @param[in] process
/// A process is required for reading memory.
//------------------------------------------------------------------
/// Provide a list of trap handler function names for this platform
///
- /// The unwinder needs to treat trap handlers specially -- the stack
- /// frame may not be aligned correctly for a trap handler (the kernel
- /// often won't perturb the stack pointer, or won't re-align it properly,
- /// in the process of calling the handler) and the frame above the handler
- /// needs to be treated by the unwinder's "frame 0" rules instead of its
- /// "middle of the stack frame" rules.
+ /// The unwinder needs to treat trap handlers specially -- the stack frame
+ /// may not be aligned correctly for a trap handler (the kernel often won't
+ /// perturb the stack pointer, or won't re-align it properly, in the process
+ /// of calling the handler) and the frame above the handler needs to be
+ /// treated by the unwinder's "frame 0" rules instead of its "middle of the
+ /// stack frame" rules.
///
/// In a user process debugging scenario, the list of trap handlers is
/// typically just "_sigtramp".
virtual const std::vector<ConstString> &GetTrapHandlerSymbolNames();
//------------------------------------------------------------------
- /// Find a support executable that may not live within in the
- /// standard locations related to LLDB.
+ /// Find a support executable that may not live within in the standard
+ /// locations related to LLDB.
///
- /// Executable might exist within the Platform SDK directories, or
- /// in standard tool directories within the current IDE that is
- /// running LLDB.
+ /// Executable might exist within the Platform SDK directories, or in
+ /// standard tool directories within the current IDE that is running LLDB.
///
/// @param[in] basename
/// The basename of the executable to locate in the current
//------------------------------------------------------------------
/// Allow the platform to set preferred memory cache line size. If non-zero
- /// (and the user
- /// has not set cache line size explicitly), this value will be used as the
- /// cache line
- /// size for memory reads.
+ /// (and the user has not set cache line size explicitly), this value will
+ /// be used as the cache line size for memory reads.
//------------------------------------------------------------------
virtual uint32_t GetDefaultMemoryCacheLineSize() { return 0; }
//------------------------------------------------------------------
/// Load a shared library into this process.
///
- /// Try and load a shared library into the current process. This
- /// call might fail in the dynamic loader plug-in says it isn't safe
- /// to try and load shared libraries at the moment.
+ /// Try and load a shared library into the current process. This call might
+ /// fail in the dynamic loader plug-in says it isn't safe to try and load
+ /// shared libraries at the moment.
///
/// @param[in] process
/// The process to load the image.
//------------------------------------------------------------------
/// Connect to all processes waiting for a debugger to attach
///
- /// If the platform have a list of processes waiting for a debugger
- /// to connect to them then connect to all of these pending processes.
+ /// 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
/// The debugger used for the connect.
//------------------------------------------------------------------
/// Ask the Platform subclass to fill in the list of trap handler names
///
- /// For most Unix user process environments, this will be a single
- /// function name, _sigtramp. More specialized environments may have
- /// additional handler names. The unwinder code needs to know when a
- /// trap handler is on the stack because the unwind rules for the frame
- /// that caused the trap are different.
+ /// For most Unix user process environments, this will be a single function
+ /// name, _sigtramp. More specialized environments may have additional
+ /// handler names. The unwinder code needs to know when a trap handler is
+ /// on the stack because the unwind rules for the frame that caused the trap
+ /// are different.
///
- /// The base class Platform ivar m_trap_handlers should be updated by
- /// the Platform subclass when this method is called. If there are no
+ /// The base class Platform ivar m_trap_handlers should be updated by the
+ /// Platform subclass when this method is called. If there are no
/// predefined trap handlers, this method may be a no-op.
//------------------------------------------------------------------
virtual void CalculateTrapHandlerSymbolNames() = 0;
//------------------------------------------------------------------
/// Select the active platform.
///
- /// In order to debug remotely, other platform's can be remotely
- /// connected to and set as the selected platform for any subsequent
- /// debugging. This allows connection to remote targets and allows
- /// the ability to discover process info, launch and attach to remote
- /// processes.
+ /// In order to debug remotely, other platform's can be remotely connected
+ /// to and set as the selected platform for any subsequent debugging. This
+ /// allows connection to remote targets and allows the ability to discover
+ /// process info, launch and attach to remote processes.
//------------------------------------------------------------------
lldb::PlatformSP GetSelectedPlatform() {
std::lock_guard<std::recursive_mutex> guard(m_mutex);
//----------------------------------------------------------------------
/// @class Process Process.h "lldb/Target/Process.h"
-/// @brief A plug-in interface definition class for debugging a process.
+/// A plug-in interface definition class for debugging a process.
//----------------------------------------------------------------------
class Process : public std::enable_shared_from_this<Process>,
public ProcessProperties,
/// A notification structure that can be used by clients to listen
/// for changes in a process's lifetime.
///
-/// @see RegisterNotificationCallbacks (const Notifications&)
-/// @see UnregisterNotificationCallbacks (const Notifications&)
+/// @see RegisterNotificationCallbacks (const Notifications&) @see
+/// UnregisterNotificationCallbacks (const Notifications&)
//------------------------------------------------------------------
#ifndef SWIG
typedef struct {
Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp);
//------------------------------------------------------------------
- /// Construct with a shared pointer to a target, the Process listener,
- /// and the appropriate UnixSignalsSP for the process.
+ /// Construct with a shared pointer to a target, the Process listener, and
+ /// the appropriate UnixSignalsSP for the process.
//------------------------------------------------------------------
Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp,
const lldb::UnixSignalsSP &unix_signals_sp);
//------------------------------------------------------------------
/// Destructor.
///
- /// The destructor is virtual since this class is designed to be
- /// inherited from by the plug-in instance.
+ /// The destructor is virtual since this class is designed to be inherited
+ /// from by the plug-in instance.
//------------------------------------------------------------------
~Process() override;
static const ProcessPropertiesSP &GetGlobalProperties();
//------------------------------------------------------------------
- /// Find a Process plug-in that can debug \a module using the
- /// currently selected architecture.
+ /// Find a Process plug-in that can debug \a module using the currently
+ /// selected architecture.
///
- /// Scans all loaded plug-in interfaces that implement versions of
- /// the Process plug-in interface and returns the first instance
- /// that can debug the file.
+ /// Scans all loaded plug-in interfaces that implement versions of the
+ /// Process plug-in interface and returns the first instance that can debug
+ /// the file.
///
/// @param[in] module_sp
/// The module shared pointer that this process will debug.
/// Static function that can be used with the \b host function
/// Host::StartMonitoringChildProcess ().
///
- /// This function can be used by lldb_private::Process subclasses
- /// when they want to watch for a local process and have its exit
- /// status automatically set when the host child process exits.
- /// Subclasses should call Host::StartMonitoringChildProcess ()
- /// with:
+ /// This function can be used by lldb_private::Process subclasses when they
+ /// want to watch for a local process and have its exit status automatically
+ /// set when the host child process exits. Subclasses should call
+ /// Host::StartMonitoringChildProcess () with:
/// callback = Process::SetHostProcessExitStatus
/// pid = Process::GetID()
/// monitor_signals = false
//------------------------------------------------------------------
/// Check if a plug-in instance can debug the file in \a module.
///
- /// Each plug-in is given a chance to say whether it can debug
- /// the file in \a module. If the Process plug-in instance can
- /// debug a file on the current system, it should return \b true.
+ /// Each plug-in is given a chance to say whether it can debug the file in
+ /// \a module. If the Process plug-in instance can debug a file on the
+ /// current system, it should return \b true.
///
/// @return
/// Returns \b true if this Process plug-in instance can
//------------------------------------------------------------------
/// This object is about to be destroyed, do any necessary cleanup.
///
- /// Subclasses that override this method should always call this
- /// superclass method.
+ /// Subclasses that override this method should always call this superclass
+ /// method.
//------------------------------------------------------------------
virtual void Finalize();
bool IsValid() const { return !m_finalize_called; }
//------------------------------------------------------------------
- /// Return a multi-word command object that can be used to expose
- /// plug-in specific commands.
+ /// Return a multi-word command object that can be used to expose plug-in
+ /// specific commands.
///
/// This object will be used to resolve plug-in commands and can be
/// triggered by a call to:
//------------------------------------------------------------------
/// Launch a new process.
///
- /// Launch a new process by spawning a new process using the
- /// target object's executable module's file as the file to launch.
+ /// Launch a new process by spawning a new process using the target object's
+ /// executable module's file as the file to launch.
///
- /// This function is not meant to be overridden by Process
- /// subclasses. It will first call Process::WillLaunch (Module *)
- /// and if that returns \b true, Process::DoLaunch (Module*,
- /// char const *[],char const *[],const char *,const char *,
- /// const char *) will be called to actually do the launching. If
- /// DoLaunch returns \b true, then Process::DidLaunch() will be
- /// called.
+ /// This function is not meant to be overridden by Process subclasses. It
+ /// will first call Process::WillLaunch (Module *) and if that returns \b
+ /// true, Process::DoLaunch (Module*, char const *[],char const *[],const
+ /// char *,const char *, const char *) will be called to actually do the
+ /// launching. If DoLaunch returns \b true, then Process::DidLaunch() will
+ /// be called.
///
/// @param[in] launch_info
/// Details regarding the environment, STDIN/STDOUT/STDERR
// We are postponing designing this till we have at least a second use case.
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// Set the cached UtilityFunction that assists in loading binary
- /// images into the process.
+ /// Set the cached UtilityFunction that assists in loading binary images
+ /// into the process.
///
/// This UtilityFunction is maintained in the Process since the Platforms
- /// don't track the lifespan of the Targets/Processes that use them.
- /// But it is not intended to be comprehended by the Process, it's up to the
+ /// don't track the lifespan of the Targets/Processes that use them. But
+ /// it is not intended to be comprehended by the Process, it's up to the
/// Platform that set it to do it right.
///
/// @param[in] utility_func_up
utility_func_up);
//------------------------------------------------------------------
- /// Get the cached UtilityFunction that assists in loading binary
- /// images into the process.
+ /// Get the cached UtilityFunction that assists in loading binary images
+ /// into the process.
///
/// @param[in] platform
/// The platform fetching the UtilityFunction.
//------------------------------------------------------------------
/// Get the dynamic loader plug-in for this process.
///
- /// The default action is to let the DynamicLoader plug-ins check
- /// the main executable and the DynamicLoader will select itself
- /// automatically. Subclasses can override this if inspecting the
- /// executable is not desired, or if Process subclasses can only
- /// use a specific DynamicLoader plug-in.
+ /// The default action is to let the DynamicLoader plug-ins check the main
+ /// executable and the DynamicLoader will select itself automatically.
+ /// Subclasses can override this if inspecting the executable is not
+ /// desired, or if Process subclasses can only use a specific DynamicLoader
+ /// plug-in.
//------------------------------------------------------------------
virtual DynamicLoader *GetDynamicLoader();
virtual const lldb::DataBufferSP GetAuxvData();
//------------------------------------------------------------------
- /// Sometimes processes know how to retrieve and load shared libraries.
- /// This is normally done by DynamicLoader plug-ins, but sometimes the
- /// connection to the process allows retrieving this information. The
- /// dynamic loader plug-ins can use this function if they can't
- /// determine the current shared library load state.
+ /// Sometimes processes know how to retrieve and load shared libraries. This
+ /// is normally done by DynamicLoader plug-ins, but sometimes the connection
+ /// to the process allows retrieving this information. The dynamic loader
+ /// plug-ins can use this function if they can't determine the current
+ /// shared library load state.
///
/// @return
/// The number of shared libraries that were loaded
//------------------------------------------------------------------
/// Attach to an existing process using the process attach info.
///
- /// This function is not meant to be overridden by Process
- /// subclasses. It will first call WillAttach (lldb::pid_t)
- /// or WillAttach (const char *), and if that returns \b
- /// true, DoAttach (lldb::pid_t) or DoAttach (const char *) will
- /// be called to actually do the attach. If DoAttach returns \b
+ /// This function is not meant to be overridden by Process subclasses. It
+ /// will first call WillAttach (lldb::pid_t) or WillAttach (const char *),
+ /// and if that returns \b true, DoAttach (lldb::pid_t) or DoAttach (const
+ /// char *) will be called to actually do the attach. If DoAttach returns \b
/// true, then Process::DidAttach() will be called.
///
/// @param[in] pid
//------------------------------------------------------------------
/// Get the image information address for the current process.
///
- /// Some runtimes have system functions that can help dynamic
- /// loaders locate the dynamic loader information needed to observe
- /// shared libraries being loaded or unloaded. This function is
- /// in the Process interface (as opposed to the DynamicLoader
- /// interface) to ensure that remote debugging can take advantage of
- /// this functionality.
+ /// Some runtimes have system functions that can help dynamic loaders locate
+ /// the dynamic loader information needed to observe shared libraries being
+ /// loaded or unloaded. This function is in the Process interface (as
+ /// opposed to the DynamicLoader interface) to ensure that remote debugging
+ /// can take advantage of this functionality.
///
/// @return
/// The address of the dynamic loader information, or
//------------------------------------------------------------------
/// Called when the process is about to broadcast a public stop.
///
- /// There are public and private stops. Private stops are when the
- /// process is doing things like stepping and the client doesn't
- /// need to know about starts and stop that implement a thread plan.
- /// Single stepping over a source line in code might end up being
- /// implemented by one or more process starts and stops. Public stops
- /// are when clients will be notified that the process is stopped.
- /// These events typically trigger UI updates (thread stack frames to
- /// be displayed, variables to be displayed, and more). This function
- /// can be overriden and allows process subclasses to do something
- /// before the eBroadcastBitStateChanged event is sent to public
- /// clients.
+ /// There are public and private stops. Private stops are when the process
+ /// is doing things like stepping and the client doesn't need to know about
+ /// starts and stop that implement a thread plan. Single stepping over a
+ /// source line in code might end up being implemented by one or more
+ /// process starts and stops. Public stops are when clients will be notified
+ /// that the process is stopped. These events typically trigger UI updates
+ /// (thread stack frames to be displayed, variables to be displayed, and
+ /// more). This function can be overriden and allows process subclasses to
+ /// do something before the eBroadcastBitStateChanged event is sent to
+ /// public clients.
//------------------------------------------------------------------
virtual void WillPublicStop() {}
//------------------------------------------------------------------
/// Unregister for process and thread notifications.
///
-/// Clients can unregister notification callbacks by passing a copy of
-/// the original baton and callbacks in \a callbacks.
+/// Clients can unregister notification callbacks by passing a copy of the
+/// original baton and callbacks in \a callbacks.
///
/// @param[in] callbacks
/// A structure that contains the notification baton and
// Built in Process Control functions
//==================================================================
//------------------------------------------------------------------
- /// Resumes all of a process's threads as configured using the
- /// Thread run control functions.
+ /// Resumes all of a process's threads as configured using the Thread run
+ /// control functions.
///
- /// Threads for a process should be updated with one of the run
- /// control actions (resume, step, or suspend) that they should take
- /// when the process is resumed. If no run control action is given
- /// to a thread it will be resumed by default.
+ /// Threads for a process should be updated with one of the run control
+ /// actions (resume, step, or suspend) that they should take when the
+ /// process is resumed. If no run control action is given to a thread it
+ /// will be resumed by default.
///
- /// This function is not meant to be overridden by Process
- /// subclasses. This function will take care of disabling any
- /// breakpoints that threads may be stopped at, single stepping, and
- /// re-enabling breakpoints, and enabling the basic flow control
- /// that the plug-in instances need not worry about.
+ /// This function is not meant to be overridden by Process subclasses. This
+ /// function will take care of disabling any breakpoints that threads may be
+ /// stopped at, single stepping, and re-enabling breakpoints, and enabling
+ /// the basic flow control that the plug-in instances need not worry about.
///
- /// N.B. This function also sets the Write side of the Run Lock,
- /// which is unset when the corresponding stop event is pulled off
- /// the Public Event Queue. If you need to resume the process without
- /// setting the Run Lock, use PrivateResume (though you should only do
- /// that from inside the Process class.
+ /// N.B. This function also sets the Write side of the Run Lock, which is
+ /// unset when the corresponding stop event is pulled off the Public Event
+ /// Queue. If you need to resume the process without setting the Run Lock,
+ /// use PrivateResume (though you should only do that from inside the
+ /// Process class.
///
/// @return
/// Returns an error object.
//------------------------------------------------------------------
/// Halts a running process.
///
- /// This function is not meant to be overridden by Process
- /// subclasses.
- /// If the process is successfully halted, a eStateStopped
- /// process event with GetInterrupted will be broadcast. If false, we will
- /// halt the process with no events generated by the halt.
+ /// This function is not meant to be overridden by Process subclasses. If
+ /// the process is successfully halted, a eStateStopped process event with
+ /// GetInterrupted will be broadcast. If false, we will halt the process
+ /// with no events generated by the halt.
///
/// @param[in] clear_thread_plans
/// If true, when the process stops, clear all thread plans.
//------------------------------------------------------------------
/// Detaches from a running or stopped process.
///
- /// This function is not meant to be overridden by Process
- /// subclasses.
+ /// This function is not meant to be overridden by Process subclasses.
///
/// @param[in] keep_stopped
/// If true, don't resume the process on detach.
Status Detach(bool keep_stopped);
//------------------------------------------------------------------
- /// Kills the process and shuts down all threads that were spawned
- /// to track and monitor the process.
+ /// Kills the process and shuts down all threads that were spawned to track
+ /// and monitor the process.
///
- /// This function is not meant to be overridden by Process
- /// subclasses.
+ /// This function is not meant to be overridden by Process subclasses.
///
/// @param[in] force_kill
/// Whether lldb should force a kill (instead of a detach) from
//------------------------------------------------------------------
/// Sends a process a UNIX signal \a signal.
///
- /// This function is not meant to be overridden by Process
- /// subclasses.
+ /// This function is not meant to be overridden by Process subclasses.
///
/// @return
/// Returns an error object.
//------------------------------------------------------------------
/// Called before attaching to a process.
///
- /// Allow Process plug-ins to execute some code before attaching a
- /// process.
+ /// Allow Process plug-ins to execute some code before attaching a process.
///
/// @return
/// Returns an error object.
//------------------------------------------------------------------
/// Called before attaching to a process.
///
- /// Allow Process plug-ins to execute some code before attaching a
- /// process.
+ /// Allow Process plug-ins to execute some code before attaching a process.
///
/// @return
/// Returns an error object.
/// If you can figure out the process architecture after attach, fill it
/// in here.
///
- /// Allow Process plug-ins to execute some code after attaching to
- /// a process.
+ /// Allow Process plug-ins to execute some code after attaching to a
+ /// process.
//------------------------------------------------------------------
virtual void DidAttach(ArchSpec &process_arch) { process_arch.Clear(); }
//------------------------------------------------------------------
/// Called after a process re-execs itself.
///
- /// Allow Process plug-ins to execute some code after a process has
- /// exec'ed itself. Subclasses typically should override DoDidExec()
- /// as the lldb_private::Process class needs to remove its dynamic
- /// loader, runtime, ABI and other plug-ins, as well as unload all
- /// shared libraries.
+ /// Allow Process plug-ins to execute some code after a process has exec'ed
+ /// itself. Subclasses typically should override DoDidExec() as the
+ /// lldb_private::Process class needs to remove its dynamic loader, runtime,
+ /// ABI and other plug-ins, as well as unload all shared libraries.
//------------------------------------------------------------------
virtual void DidExec();
//------------------------------------------------------------------
- /// Subclasses of Process should implement this function if they
- /// need to do anything after a process exec's itself.
+ /// Subclasses of Process should implement this function if they need to do
+ /// anything after a process exec's itself.
//------------------------------------------------------------------
virtual void DoDidExec() {}
//------------------------------------------------------------------
/// Called before launching to a process.
///
- /// Allow Process plug-ins to execute some code before launching a
- /// process.
+ /// Allow Process plug-ins to execute some code before launching a process.
///
/// @return
/// Returns an error object.
//------------------------------------------------------------------
/// Launch a new process.
///
- /// Launch a new process by spawning a new process using
- /// \a exe_module's file as the file to launch. Launch details are
- /// provided in \a launch_info.
+ /// Launch a new process by spawning a new process using \a exe_module's
+ /// file as the file to launch. Launch details are provided in \a
+ /// launch_info.
///
/// @param[in] exe_module
/// The module from which to extract the file specification and
//------------------------------------------------------------------
/// Called after launching a process.
///
- /// Allow Process plug-ins to execute some code after launching
- /// a process.
+ /// Allow Process plug-ins to execute some code after launching a process.
//------------------------------------------------------------------
virtual void DidLaunch() {}
//------------------------------------------------------------------
/// Called before resuming to a process.
///
- /// Allow Process plug-ins to execute some code before resuming a
- /// process.
+ /// Allow Process plug-ins to execute some code before resuming a process.
///
/// @return
/// Returns an error object.
virtual Status WillResume() { return Status(); }
//------------------------------------------------------------------
- /// Resumes all of a process's threads as configured using the
- /// Thread run control functions.
+ /// Resumes all of a process's threads as configured using the Thread run
+ /// control functions.
///
- /// Threads for a process should be updated with one of the run
- /// control actions (resume, step, or suspend) that they should take
- /// when the process is resumed. If no run control action is given
- /// to a thread it will be resumed by default.
+ /// Threads for a process should be updated with one of the run control
+ /// actions (resume, step, or suspend) that they should take when the
+ /// process is resumed. If no run control action is given to a thread it
+ /// will be resumed by default.
///
/// @return
/// Returns \b true if the process successfully resumes using
//------------------------------------------------------------------
/// Called after resuming a process.
///
- /// Allow Process plug-ins to execute some code after resuming
- /// a process.
+ /// Allow Process plug-ins to execute some code after resuming a process.
//------------------------------------------------------------------
virtual void DidResume() {}
//------------------------------------------------------------------
/// Called before halting to a process.
///
- /// Allow Process plug-ins to execute some code before halting a
- /// process.
+ /// Allow Process plug-ins to execute some code before halting a process.
///
/// @return
/// Returns an error object.
/// Halts a running process.
///
/// DoHalt must produce one and only one stop StateChanged event if it
- /// actually
- /// stops the process. If the stop happens through some natural event (for
- /// instance a SIGSTOP), then forwarding that event will do. Otherwise, you
- /// must
- /// generate the event manually. This function is called from the context of
- /// the
- /// private state thread.
+ /// actually stops the process. If the stop happens through some natural
+ /// event (for instance a SIGSTOP), then forwarding that event will do.
+ /// Otherwise, you must generate the event manually. This function is called
+ /// from the context of the private state thread.
///
/// @param[out] caused_stop
/// If true, then this Halt caused the stop, otherwise, the
//------------------------------------------------------------------
/// Called after halting a process.
///
- /// Allow Process plug-ins to execute some code after halting
- /// a process.
+ /// Allow Process plug-ins to execute some code after halting a process.
//------------------------------------------------------------------
virtual void DidHalt() {}
//------------------------------------------------------------------
/// Called before detaching from a process.
///
- /// Allow Process plug-ins to execute some code before detaching
- /// from a process.
+ /// Allow Process plug-ins to execute some code before detaching from a
+ /// process.
///
/// @return
/// Returns an error object.
//------------------------------------------------------------------
/// Called after detaching from a process.
///
- /// Allow Process plug-ins to execute some code after detaching
- /// from a process.
+ /// Allow Process plug-ins to execute some code after detaching from a
+ /// process.
//------------------------------------------------------------------
virtual void DidDetach() {}
//------------------------------------------------------------------
/// Called before sending a signal to a process.
///
- /// Allow Process plug-ins to execute some code before sending a
- /// signal to a process.
+ /// Allow Process plug-ins to execute some code before sending a signal to a
+ /// process.
///
/// @return
/// Returns no error if it is safe to proceed with a call to
//------------------------------------------------------------------
/// Called after sending a signal to a process.
///
- /// Allow Process plug-ins to execute some code after sending a
- /// signal to a process.
+ /// Allow Process plug-ins to execute some code after sending a signal to a
+ /// process.
//------------------------------------------------------------------
virtual void DidSignal() {}
/// event is taken from the queue...
///
/// This callback is called as the event
- /// is about to be queued up to allow Process plug-ins to execute
- /// some code prior to clients being notified that a process was
- /// stopped. Common operations include updating the thread list,
- /// invalidating any thread state (registers, stack, etc) prior to
- /// letting the notification go out.
+ /// is about to be queued up to allow Process plug-ins to execute some code
+ /// prior to clients being notified that a process was stopped. Common
+ /// operations include updating the thread list, invalidating any thread
+ /// state (registers, stack, etc) prior to letting the notification go out.
///
//------------------------------------------------------------------
virtual void RefreshStateAfterStop() = 0;
//------------------------------------------------------------------
- /// Sometimes the connection to a process can detect the host OS
- /// version that the process is running on. The current platform
- /// should be checked first in case the platform is connected, but
- /// clients can fall back onto this function if the platform fails
- /// to identify the host OS version. The platform should be checked
- /// first in case you are running a simulator platform that might
- /// itself be running natively, but have different heuristics for
- /// figuring out which OS is is emulating.
+ /// Sometimes the connection to a process can detect the host OS version
+ /// that the process is running on. The current platform should be checked
+ /// first in case the platform is connected, but clients can fall back onto
+ /// this function if the platform fails to identify the host OS version. The
+ /// platform should be checked first in case you are running a simulator
+ /// platform that might itself be running natively, but have different
+ /// heuristics for figuring out which OS is is emulating.
///
/// @param[out] major
/// The major OS version, or UINT32_MAX if it can't be determined
//------------------------------------------------------------------
/// Flush all data in the process.
///
- /// Flush the memory caches, all threads, and any other cached data
- /// in the process.
+ /// Flush the memory caches, all threads, and any other cached data in the
+ /// process.
///
- /// This function can be called after a world changing event like
- /// adding a new symbol file, or after the process makes a large
- /// context switch (from boot ROM to booted into an OS).
+ /// This function can be called after a world changing event like adding a
+ /// new symbol file, or after the process makes a large context switch (from
+ /// boot ROM to booted into an OS).
//------------------------------------------------------------------
void Flush();
//------------------------------------------------------------------
/// Retrieve the list of shared libraries that are loaded for this process
- /// This method is used on pre-macOS 10.12, pre-iOS 10, pre-tvOS 10,
- /// pre-watchOS 3 systems. The following two methods are for newer versions
- /// of those OSes.
+ /// This method is used on pre-macOS 10.12, pre-iOS 10, pre-tvOS 10, pre-
+ /// watchOS 3 systems. The following two methods are for newer versions of
+ /// those OSes.
///
/// For certain platforms, the time it takes for the DynamicLoader plugin to
/// read all of the shared libraries out of memory over a slow communication
/// channel may be too long. In that instance, the gdb-remote stub may be
- /// able to retrieve the necessary information about the solibs out of memory
- /// and return a concise summary sufficient for the DynamicLoader plugin.
+ /// able to retrieve the necessary information about the solibs out of
+ /// memory and return a concise summary sufficient for the DynamicLoader
+ /// plugin.
///
/// @param [in] image_list_address
/// The address where the table of shared libraries is stored in memory,
}
//------------------------------------------------------------------
- /// Print a user-visible warning about a module being built with optimization
+ /// Print a user-visible warning about a module being built with
+ /// optimization
///
- /// Prints a async warning message to the user one time per Module
- /// where a function is found that was compiled with optimization, per
- /// Process.
+ /// 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
/// A SymbolContext with eSymbolContextFunction and eSymbolContextModule
//------------------------------------------------------------------
/// Set accessor for the process exit status (return code).
///
- /// Sometimes a child exits and the exit can be detected by global
- /// functions (signal handler for SIGCHLD for example). This
- /// accessor allows the exit status to be set from an external
- /// source.
+ /// Sometimes a child exits and the exit can be detected by global functions
+ /// (signal handler for SIGCHLD for example). This accessor allows the exit
+ /// status to be set from an external source.
///
- /// Setting this will cause a eStateExited event to be posted to
- /// the process event queue.
+ /// Setting this will cause a eStateExited event to be posted to the process
+ /// event queue.
///
/// @param[in] exit_status
/// The value for the process's return code.
virtual bool IsAlive();
//------------------------------------------------------------------
- /// Before lldb detaches from a process, it warns the user that they are about
- /// to lose their debug session.
- /// In some cases, this warning doesn't need to be emitted -- for instance,
- /// with core file debugging where
- /// the user can reconstruct the "state" by simply re-running the debugger on
+ /// Before lldb detaches from a process, it warns the user that they are
+ /// about to lose their debug session. In some cases, this warning doesn't
+ /// need to be emitted -- for instance, with core file debugging where the
+ /// user can reconstruct the "state" by simply re-running the debugger on
/// the core file.
///
/// @return
//------------------------------------------------------------------
/// Actually do the reading of memory from a process.
///
- /// Subclasses must override this function and can return fewer
- /// bytes than requested when memory requests are too large. This
- /// class will break up the memory requests and keep advancing the
- /// arguments along as needed.
+ /// Subclasses must override this function and can return fewer bytes than
+ /// 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
/// A virtual load address that indicates where to start reading
//------------------------------------------------------------------
/// Read of memory from a process.
///
- /// This function will read memory from the current process's
- /// address space and remove any traps that may have been inserted
- /// into the memory.
+ /// This function will read memory from the current process's address space
+ /// and remove any traps that may have been inserted into the memory.
///
- /// This function is not meant to be overridden by Process
- /// subclasses, the subclasses should implement
- /// Process::DoReadMemory (lldb::addr_t, size_t, void *).
+ /// This function is not meant to be overridden by Process subclasses, the
+ /// subclasses should implement Process::DoReadMemory (lldb::addr_t, size_t,
+ /// void *).
///
/// @param[in] vm_addr
/// A virtual load address that indicates where to start reading
//------------------------------------------------------------------
/// Read a NULL terminated string from memory
///
- /// This function will read a cache page at a time until a NULL
- /// string terminator is found. It will stop reading if an aligned
- /// sequence of NULL termination \a type_width bytes is not found
- /// before reading \a cstr_max_len bytes. The results are always
- /// guaranteed to be NULL terminated, and that no more than
- /// (max_bytes - type_width) bytes will be read.
+ /// This function will read a cache page at a time until a NULL string
+ /// terminator is found. It will stop reading if an aligned sequence of NULL
+ /// termination \a type_width bytes is not found before reading \a
+ /// cstr_max_len bytes. The results are always guaranteed to be NULL
+ /// terminated, and that no more than (max_bytes - type_width) bytes will be
+ /// read.
///
/// @param[in] vm_addr
/// The virtual load address to start the memory read.
///
/// This function will read a cache page at a time until the NULL
/// C string terminator is found. It will stop reading if the NULL
- /// termination byte isn't found before reading \a cstr_max_len
- /// bytes, and the results are always guaranteed to be NULL
- /// terminated (at most cstr_max_len - 1 bytes will be read).
+ /// termination byte isn't found before reading \a cstr_max_len bytes, and
+ /// the results are always guaranteed to be NULL terminated (at most
+ /// cstr_max_len - 1 bytes will be read).
//------------------------------------------------------------------
size_t ReadCStringFromMemory(lldb::addr_t vm_addr, char *cstr,
size_t cstr_max_len, Status &error);
Status &error);
//------------------------------------------------------------------
- /// Reads an unsigned integer of the specified byte size from
- /// process memory.
+ /// Reads an unsigned integer of the specified byte size from process
+ /// memory.
///
/// @param[in] load_addr
/// A load address of the integer to read.
//------------------------------------------------------------------
/// Write all or part of a scalar value to memory.
///
- /// The value contained in \a scalar will be swapped to match the
- /// byte order of the process that is being debugged. If \a size is
- /// less than the size of scalar, the least significant \a size bytes
- /// from scalar will be written. If \a size is larger than the byte
- /// size of scalar, then the extra space will be padded with zeros
- /// and the scalar value will be placed in the least significant
- /// bytes in memory.
+ /// The value contained in \a scalar will be swapped to match the byte order
+ /// of the process that is being debugged. If \a size is less than the size
+ /// of scalar, the least significant \a size bytes from scalar will be
+ /// written. If \a size is larger than the byte size of scalar, then the
+ /// 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
/// A virtual load address that indicates where to start writing
//------------------------------------------------------------------
/// Write memory to a process.
///
- /// This function will write memory to the current process's
- /// address space and maintain any traps that might be present due
- /// to software breakpoints.
+ /// This function will write memory to the current process's address space
+ /// and maintain any traps that might be present due to software
+ /// breakpoints.
///
- /// This function is not meant to be overridden by Process
- /// subclasses, the subclasses should implement
- /// Process::DoWriteMemory (lldb::addr_t, size_t, void *).
+ /// This function is not meant to be overridden by Process subclasses, the
+ /// subclasses should implement Process::DoWriteMemory (lldb::addr_t,
+ /// size_t, void *).
///
/// @param[in] vm_addr
/// A virtual load address that indicates where to start writing
//------------------------------------------------------------------
/// Actually allocate memory in the process.
///
- /// This function will allocate memory in the process's address
- /// space. This can't rely on the generic function calling mechanism,
- /// since that requires this function.
+ /// This function will allocate memory in the process's address space. This
+ /// can't rely on the generic function calling mechanism, since that
+ /// requires this function.
///
/// @param[in] size
/// The size of the allocation requested.
//------------------------------------------------------------------
/// The public interface to allocating memory in the process.
///
- /// This function will allocate memory in the process's address
- /// space. This can't rely on the generic function calling mechanism,
- /// since that requires this function.
+ /// This function will allocate memory in the process's address space. This
+ /// can't rely on the generic function calling mechanism, since that
+ /// requires this function.
///
/// @param[in] size
/// The size of the allocation requested.
/// The public interface to allocating memory in the process, this also
/// clears the allocated memory.
///
- /// This function will allocate memory in the process's address
- /// space. This can't rely on the generic function calling mechanism,
- /// since that requires this function.
+ /// This function will allocate memory in the process's address space. This
+ /// can't rely on the generic function calling mechanism, since that
+ /// requires this function.
///
/// @param[in] size
/// The size of the allocation requested.
/// Locate the memory region that contains load_addr.
///
/// If load_addr is within the address space the process has mapped
- /// range_info will be filled in with the start and end of that range
- /// as well as the permissions for that range and range_info.GetMapped
- /// will return true.
+ /// range_info will be filled in with the start and end of that range as
+ /// well as the permissions for that range and range_info.GetMapped will
+ /// return true.
///
- /// If load_addr is outside any mapped region then range_info will
- /// have its start address set to load_addr and the end of the
- /// range will indicate the start of the next mapped range or be
- /// set to LLDB_INVALID_ADDRESS if there are no valid mapped ranges
- /// between load_addr and the end of the process address space.
+ /// If load_addr is outside any mapped region then range_info will have its
+ /// start address set to load_addr and the end of the range will indicate
+ /// the start of the next mapped range or be set to LLDB_INVALID_ADDRESS if
+ /// there are no valid mapped ranges between load_addr and the end of the
+ /// process address space.
///
- /// GetMemoryRegionInfo will only return an error if it is
- /// unimplemented for the current process.
+ /// GetMemoryRegionInfo will only return an error if it is unimplemented for
+ /// the current process.
///
/// @param[in] load_addr
/// The load address to query the range_info for.
//------------------------------------------------------------------
/// Attempt to get the attributes for a region of memory in the process.
///
- /// It may be possible for the remote debug server to inspect attributes
- /// for a region of memory in the process, such as whether there is a
- /// valid page of memory at a given address or whether that page is
+ /// It may be possible for the remote debug server to inspect attributes for
+ /// a region of memory in the process, such as whether there is a valid page
+ /// of memory at a given address or whether that page is
/// readable/writable/executable by the process.
///
/// @param[in] load_addr
uint32_t &permissions);
//------------------------------------------------------------------
- /// Determines whether executing JIT-compiled code in this process
- /// is possible.
+ /// Determines whether executing JIT-compiled code in this process is
+ /// possible.
///
/// @return
/// True if execution of JIT code is possible; false otherwise.
bool CanJIT();
//------------------------------------------------------------------
- /// Sets whether executing JIT-compiled code in this process
- /// is possible.
+ /// Sets whether executing JIT-compiled code in this process is possible.
///
/// @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.
+ /// Determines whether executing function calls using the interpreter is
+ /// possible for this process.
///
/// @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.
+ /// Sets whether executing function calls using the interpreter is possible
+ /// for this process.
///
/// @param[in] can_interpret_function_calls
/// True if possible; false otherwise.
}
//------------------------------------------------------------------
- /// Sets whether executing code in this process is possible.
- /// This could be either through JIT or interpreting.
+ /// Sets whether executing code in this process is possible. This could be
+ /// either through JIT or interpreting.
///
/// @param[in] can_run_code
/// True if execution of code is possible; false otherwise.
//------------------------------------------------------------------
/// Actually deallocate memory in the process.
///
- /// This function will deallocate memory in the process's address
- /// space that was allocated with AllocateMemory.
+ /// This function will deallocate memory in the process's address space that
+ /// was allocated with AllocateMemory.
///
/// @param[in] ptr
/// A return value from AllocateMemory, pointing to the memory you
//------------------------------------------------------------------
/// The public interface to deallocating memory in the process.
///
- /// This function will deallocate memory in the process's address
- /// space that was allocated with AllocateMemory.
+ /// This function will deallocate memory in the process's address space that
+ /// was allocated with AllocateMemory.
///
/// @param[in] ptr
/// A return value from AllocateMemory, pointing to the memory you
//------------------------------------------------------------------
/// Get any available STDOUT.
///
- /// Calling this method is a valid operation only if all of the
- /// following conditions are true:
- /// 1) The process was launched, and not attached to.
- /// 2) The process was not launched with eLaunchFlagDisableSTDIO.
- /// 3) The process was launched without supplying a valid file path
+ /// Calling this method is a valid operation only if all of the following
+ /// conditions are true: 1) The process was launched, and not attached to.
+ /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The
+ /// process was launched without supplying a valid file path
/// for STDOUT.
///
- /// Note that the implementation will probably need to start a read
- /// thread in the background to make sure that the pipe is drained
- /// and the STDOUT buffered appropriately, to prevent the process
- /// from deadlocking trying to write to a full buffer.
+ /// Note that the implementation will probably need to start a read thread
+ /// in the background to make sure that the pipe is drained and the STDOUT
+ /// buffered appropriately, to prevent the process from deadlocking trying
+ /// to write to a full buffer.
///
- /// Events will be queued indicating that there is STDOUT available
- /// that can be retrieved using this function.
+ /// Events will be queued indicating that there is STDOUT available that can
+ /// be retrieved using this function.
///
/// @param[out] buf
/// A buffer that will receive any STDOUT bytes that are
//------------------------------------------------------------------
/// Get any available STDERR.
///
- /// Calling this method is a valid operation only if all of the
- /// following conditions are true:
- /// 1) The process was launched, and not attached to.
- /// 2) The process was not launched with eLaunchFlagDisableSTDIO.
- /// 3) The process was launched without supplying a valid file path
+ /// Calling this method is a valid operation only if all of the following
+ /// conditions are true: 1) The process was launched, and not attached to.
+ /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The
+ /// process was launched without supplying a valid file path
/// for STDERR.
///
- /// Note that the implementation will probably need to start a read
- /// thread in the background to make sure that the pipe is drained
- /// and the STDERR buffered appropriately, to prevent the process
- /// from deadlocking trying to write to a full buffer.
+ /// Note that the implementation will probably need to start a read thread
+ /// in the background to make sure that the pipe is drained and the STDERR
+ /// buffered appropriately, to prevent the process from deadlocking trying
+ /// to write to a full buffer.
///
- /// Events will be queued indicating that there is STDERR available
- /// that can be retrieved using this function.
+ /// Events will be queued indicating that there is STDERR available that can
+ /// be retrieved using this function.
///
/// @param[in] buf
/// A buffer that will receive any STDERR bytes that are
//------------------------------------------------------------------
/// Puts data into this process's STDIN.
///
- /// Calling this method is a valid operation only if all of the
- /// following conditions are true:
- /// 1) The process was launched, and not attached to.
- /// 2) The process was not launched with eLaunchFlagDisableSTDIO.
- /// 3) The process was launched without supplying a valid file path
+ /// Calling this method is a valid operation only if all of the following
+ /// conditions are true: 1) The process was launched, and not attached to.
+ /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The
+ /// process was launched without supplying a valid file path
/// for STDIN.
///
/// @param[in] buf
/// Waits for the process state to be running within a given msec timeout.
///
/// The main purpose of this is to implement an interlock waiting for
- /// HandlePrivateEvent
- /// to push an IOHandler.
+ /// HandlePrivateEvent to push an IOHandler.
///
/// @param[in] timeout_msec
/// The maximum time length to wait for the process to transition to the
hijack_listener); // Pass an empty ListenerSP to use builtin listener
//--------------------------------------------------------------------------------------
- /// Centralize the code that handles and prints descriptions for process state
- /// changes.
+ /// Centralize the code that handles and prints descriptions for process
+ /// state changes.
///
/// @param[in] event_sp
/// The process state changed event
/// event, then make a new listener, set to listen to process events, and
/// then call this with that listener. Then you will have to wait on that
/// listener explicitly for events (rather than using the GetNextEvent &
- /// WaitFor*
- /// calls above. Be sure to call RestoreProcessEvents when you are done.
+ /// WaitFor* calls above. Be sure to call RestoreProcessEvents when you are
+ /// done.
///
/// @param[in] listener
/// This is the new listener to whom all process events will be delivered.
GetInstrumentationRuntime(lldb::InstrumentationRuntimeType type);
//------------------------------------------------------------------
- /// Try to fetch the module specification for a module with the
- /// given file name and architecture. Process sub-classes have to
- /// override this method if they support platforms where the
- /// Platform object can't get the module spec for all module.
+ /// Try to fetch the module specification for a module with the given file
+ /// name and architecture. Process sub-classes have to override this method
+ /// if they support platforms where the Platform object can't get the module
+ /// spec for all module.
///
/// @param[in] module_file_spec
/// The file name of the module to get specification for.
//------------------------------------------------------------------
/// Try to find the load address of a file.
- /// The load address is defined as the address of the first memory
- /// region what contains data mapped from the specified file.
+ /// The load address is defined as the address of the first memory region
+ /// what contains data mapped from the specified file.
///
/// @param[in] file
/// The name of the file whose load address we are looking for
//------------------------------------------------------------------
/// Find the next branch instruction to set a breakpoint on
///
- /// When instruction stepping through a source line, instead of
- /// stepping through each instruction, we can put a breakpoint on
- /// the next branch instruction (within the range of instructions
- /// we are stepping through) and continue the process to there,
- /// yielding significant performance benefits over instruction
- /// stepping.
+ /// When instruction stepping through a source line, instead of stepping
+ /// through each instruction, we can put a breakpoint on the next branch
+ /// instruction (within the range of instructions we are stepping through)
+ /// and continue the process to there, yielding significant performance
+ /// benefits over instruction stepping.
///
/// @param[in] default_stop_addr
/// The address of the instruction where lldb would put a
/// The default implementation here will always return an error indiciating
/// the feature is unsupported.
///
- /// StructuredDataPlugin implementations will call this to configure
- /// a feature that has been reported as being supported.
+ /// StructuredDataPlugin implementations will call this to configure a
+ /// feature that has been reported as being supported.
///
/// @param[in] type_name
/// The StructuredData type name as previously discovered by
const StructuredData::ObjectSP &config_sp);
//------------------------------------------------------------------
- /// Broadcasts the given structured data object from the given
- /// plugin.
+ /// Broadcasts the given structured data object from the given plugin.
///
- /// StructuredDataPlugin instances can use this to optionally
- /// broadcast any of their data if they want to make it available
- /// for clients. The data will come in on the structured data
- /// event bit (eBroadcastBitStructuredData).
+ /// StructuredDataPlugin instances can use this to optionally broadcast any
+ /// of their data if they want to make it available for clients. The data
+ /// will come in on the structured data event bit
+ /// (eBroadcastBitStructuredData).
///
/// @param[in] object_sp
/// The structured data object to broadcast.
const lldb::StructuredDataPluginSP &plugin_sp);
//------------------------------------------------------------------
- /// Returns the StructuredDataPlugin associated with a given type
- /// name, if there is one.
+ /// Returns the StructuredDataPlugin associated with a given type name, if
+ /// there is one.
///
/// There will only be a plugin for a given StructuredDataType if the
- /// debugged process monitor claims that the feature is supported.
- /// This is one way to tell whether a feature is available.
+ /// debugged process monitor claims that the feature is supported. This is
+ /// one way to tell whether a feature is available.
///
/// @return
/// The plugin if one is available for the specified feature;
GetStructuredDataPlugin(const ConstString &type_name) const;
//------------------------------------------------------------------
- /// Starts tracing with the configuration provided in options. To
- /// enable tracing on the complete process the thread_id in the
- /// options should be set to LLDB_INVALID_THREAD_ID. The API returns
- /// a user_id which is needed by other API's that manipulate the
- /// trace instance.
- /// The handling of erroneous or unsupported configuration is left
- /// to the trace technology implementations in the server, as they
- /// could be returned as an error, or rounded to a valid
- /// configuration to start tracing. In the later case the
- /// GetTraceConfig should supply the actual used trace
- /// configuration.
+ /// Starts tracing with the configuration provided in options. To enable
+ /// tracing on the complete process the thread_id in the options should be
+ /// set to LLDB_INVALID_THREAD_ID. The API returns a user_id which is needed
+ /// by other API's that manipulate the trace instance. The handling of
+ /// erroneous or unsupported configuration is left to the trace technology
+ /// implementations in the server, as they could be returned as an error, or
+ /// rounded to a valid configuration to start tracing. In the later case the
+ /// GetTraceConfig should supply the actual used trace configuration.
//------------------------------------------------------------------
virtual lldb::user_id_t StartTrace(const TraceOptions &options,
Status &error) {
}
//------------------------------------------------------------------
- /// Stops the tracing instance leading to deletion of the trace
- /// data. The tracing instance is identified by the user_id which
- /// is obtained when tracing was started from the StartTrace.
- /// In case tracing of the complete process needs to be stopped
- /// the thread_id should be set to LLDB_INVALID_THREAD_ID.
- /// In the other case that tracing on an individual thread needs
- /// to be stopped a thread_id can be supplied.
+ /// Stops the tracing instance leading to deletion of the trace data. The
+ /// tracing instance is identified by the user_id which is obtained when
+ /// tracing was started from the StartTrace. In case tracing of the complete
+ /// process needs to be stopped the thread_id should be set to
+ /// LLDB_INVALID_THREAD_ID. In the other case that tracing on an individual
+ /// thread needs to be stopped a thread_id can be supplied.
//------------------------------------------------------------------
virtual Status StopTrace(lldb::user_id_t uid, lldb::tid_t thread_id) {
return Status("Not implemented");
}
//------------------------------------------------------------------
- /// Provides the trace data as raw bytes. A buffer needs to be
- /// supplied to copy the trace data. The exact behavior of this API
- /// may vary across trace technology, as some may support partial
- /// reading of the trace data from a specified offset while some
- /// may not. The thread_id should be used to select a particular
- /// thread for trace extraction.
+ /// Provides the trace data as raw bytes. A buffer needs to be supplied to
+ /// copy the trace data. The exact behavior of this API may vary across
+ /// trace technology, as some may support partial reading of the trace data
+ /// from a specified offset while some may not. The thread_id should be used
+ /// to select a particular thread for trace extraction.
//------------------------------------------------------------------
virtual Status GetData(lldb::user_id_t uid, lldb::tid_t thread_id,
llvm::MutableArrayRef<uint8_t> &buffer,
//------------------------------------------------------------------
/// API to obtain the trace configuration used by a trace instance.
- /// Configurations that may be specific to some trace technology
- /// should be stored in the custom parameters. The options are
- /// transported to the server, which shall interpret accordingly.
- /// The thread_id can be specified in the options to obtain the
- /// configuration used by a specific thread. The thread_id specified
- /// should also match the uid otherwise an error will be returned.
+ /// Configurations that may be specific to some trace technology should be
+ /// stored in the custom parameters. The options are transported to the
+ /// server, which shall interpret accordingly. The thread_id can be
+ /// specified in the options to obtain the configuration used by a specific
+ /// thread. The thread_id specified should also match the uid otherwise an
+ /// error will be returned.
//------------------------------------------------------------------
virtual Status GetTraceConfig(lldb::user_id_t uid, TraceOptions &options) {
return Status("Not implemented");
lldb::StateType GetPrivateState();
//------------------------------------------------------------------
- /// The "private" side of resuming a process. This doesn't alter the
- /// state of m_run_lock, but just causes the process to resume.
+ /// 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
/// An Status object describing the success or failure of the resume.
///
/// A facility for printing a warning to the user once per repeat_key.
///
- /// warning_type is from the Process::Warnings enums.
- /// repeat_key is a pointer value that will be used to ensure that the
- /// warning message is not printed multiple times. For instance, with a
- /// warning about a function being optimized, you can pass the CompileUnit
- /// pointer to have the warning issued for only the first function in a
- /// CU, or the Function pointer to have it issued once for every function,
- /// or a Module pointer to have it issued once per Module.
+ /// warning_type is from the Process::Warnings enums. repeat_key is a
+ /// pointer value that will be used to ensure that the warning message is
+ /// not printed multiple times. For instance, with a warning about a
+ /// function being optimized, you can pass the CompileUnit pointer to have
+ /// the warning issued for only the first function in a CU, or the Function
+ /// pointer to have it issued once for every function, or a Module pointer
+ /// to have it issued once per Module.
///
- /// Classes outside Process should call a specific PrintWarning method
- /// so that the warning strings are all centralized in Process, instead of
+ /// Classes outside Process should call a specific PrintWarning method so
+ /// that the warning strings are all centralized in Process, instead of
/// calling PrintWarning() directly.
///
/// @param [in] warning_type
void ForceNextEventDelivery() { m_force_next_event_delivery = true; }
//------------------------------------------------------------------
- /// Loads any plugins associated with asynchronous structured data
- /// and maps the relevant supported type name to the plugin.
+ /// Loads any plugins associated with asynchronous structured data and maps
+ /// the relevant supported type name to the plugin.
///
- /// Processes can receive asynchronous structured data from the
- /// process monitor. This method will load and map any structured
- /// data plugins that support the given set of supported type names.
- /// Later, if any of these features are enabled, the process monitor
- /// is free to generate asynchronous structured data. The data must
- /// come in as a single \b StructuredData::Dictionary. That dictionary
- /// must have a string field named 'type', with a value that equals
- /// the relevant type name string (one of the values in
- /// \b supported_type_names).
+ /// Processes can receive asynchronous structured data from the process
+ /// monitor. This method will load and map any structured data plugins that
+ /// support the given set of supported type names. Later, if any of these
+ /// features are enabled, the process monitor is free to generate
+ /// asynchronous structured data. The data must come in as a single \b
+ /// StructuredData::Dictionary. That dictionary must have a string field
+ /// 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
/// An array of zero or more type names. Each must be unique.
//------------------------------------------------------------------
/// Route the incoming structured data dictionary to the right plugin.
///
- /// The incoming structured data must be a dictionary, and it must
- /// have a 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.
+ /// The incoming structured data must be a dictionary, and it must have a
+ /// 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
/// When non-null and pointing to a dictionary, the 'type'
private:
//------------------------------------------------------------------
- /// This is the part of the event handling that for a process event.
- /// It decides what to do with the event and returns true if the
- /// event needs to be propagated to the user, and false otherwise.
- /// If the event is not propagated, this call will most likely set
- /// the target to executing again.
- /// There is only one place where this call should be called,
- /// HandlePrivateEvent.
- /// Don't call it from anywhere else...
+ /// This is the part of the event handling that for a process event. It
+ /// decides what to do with the event and returns true if the event needs to
+ /// be propagated to the user, and false otherwise. If the event is not
+ /// propagated, this call will most likely set the target to executing
+ /// again. There is only one place where this call should be called,
+ /// HandlePrivateEvent. Don't call it from anywhere else...
///
/// @param[in] event_ptr
/// This is the event we are handling.
/// @class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
///
-/// @brief This base class provides an interface to stack frames.
+/// This base class provides an interface to stack frames.
///
/// StackFrames may have a Canonical Frame Address (CFA) or not.
/// A frame may have a plain pc value or it may have a pc value + stop_id
///
/// This is the one constructor that doesn't take a RegisterContext
/// parameter. This ctor may be called when creating a history StackFrame;
- /// these are used if we've collected a stack trace of pc addresses at
- /// some point in the past. We may only have pc values. We may have pc
- /// values and the stop_id when the stack trace was recorded. We may have a
- /// CFA, or more likely, we won't.
+ /// these are used if we've collected a stack trace of pc addresses at some
+ /// point in the past. We may only have pc values. We may have pc values
+ /// and the stop_id when the stack trace was recorded. We may have a CFA,
+ /// or more likely, we won't.
///
/// @param [in] thread_sp
/// The Thread that this frame belongs to.
/// Provide a SymbolContext for this StackFrame's current pc value.
///
/// The StackFrame maintains this SymbolContext and adds additional
- /// information
- /// to it on an as-needed basis. This helps to avoid different functions
- /// looking up symbolic information for a given pc value multiple times.
+ /// information to it on an as-needed basis. This helps to avoid different
+ /// functions looking up symbolic information for a given pc value multiple
+ /// times.
///
/// @params [in] resolve_scope
/// Flags from the SymbolContextItem enumerated type which specify what
//------------------------------------------------------------------
/// Return the Canonical Frame Address (DWARF term) for this frame.
///
- /// The CFA is typically the value of the stack pointer register before
- /// the call invocation is made. It will not change during the lifetime
- /// of a stack frame. It is often not the same thing as the frame pointer
+ /// The CFA is typically the value of the stack pointer register before the
+ /// call invocation is made. It will not change during the lifetime of a
+ /// stack frame. It is often not the same thing as the frame pointer
/// register value.
///
/// Live StackFrames will always have a CFA but other types of frames may
//------------------------------------------------------------------
/// Get the current lexical scope block for this StackFrame, if possible.
///
- /// If debug information is available for this stack frame, return a
- /// pointer to the innermost lexical Block that the frame is currently
- /// executing.
+ /// If debug information is available for this stack frame, return a pointer
+ /// to the innermost lexical Block that the frame is currently executing.
///
/// @return
/// A pointer to the current Block. nullptr is returned if this can
}
//------------------------------------------------------------------
- /// Retrieve the list of variables that are in scope at this StackFrame's pc.
+ /// Retrieve the list of variables that are in scope at this StackFrame's
+ /// pc.
///
/// A frame that is not live may return an empty VariableList for a given
- /// pc value even though variables would be available at this point if
- /// it were a live stack frame.
+ /// pc value even though variables would be available at this point if it
+ /// were a live stack frame.
///
/// @param[in] get_file_globals
/// Whether to also retrieve compilation-unit scoped variables
VariableList *GetVariableList(bool get_file_globals);
//------------------------------------------------------------------
- /// Retrieve the list of variables that are in scope at this StackFrame's pc.
+ /// Retrieve the list of variables that are in scope at this StackFrame's
+ /// pc.
///
/// A frame that is not live may return an empty VariableListSP for a
- /// given pc value even though variables would be available at this point
- /// if it were a live stack frame.
+ /// given pc value even though variables would be available at this point if
+ /// it were a live stack frame.
///
/// @param[in] get_file_globals
/// Whether to also retrieve compilation-unit scoped variables
bool must_have_valid_location = false);
//------------------------------------------------------------------
- /// Create a ValueObject for a variable name / pathname, possibly
- /// including simple dereference/child selection syntax.
+ /// Create a ValueObject for a variable name / pathname, possibly including
+ /// simple dereference/child selection syntax.
///
/// @param[in] var_expr
/// The string specifying a variable to base the VariableObject off
bool HasDebugInformation();
//------------------------------------------------------------------
- /// Return the disassembly for the instructions of this StackFrame's function
- /// as a single C string.
+ /// Return the disassembly for the instructions of this StackFrame's
+ /// function as a single C string.
///
/// @return
// C string with the assembly instructions for this function.
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.
+ /// Print a description of this stack frame and/or the source
+ /// context/assembly for this stack frame.
///
/// @param[in] strm
/// The Stream to send the output to.
bool show_unique = false, const char *frame_marker = nullptr);
//------------------------------------------------------------------
- /// Query whether this frame is a concrete frame on the call stack,
- /// or if it is an inlined frame derived from the debug information
- /// and presented by the debugger.
+ /// Query whether this frame is a concrete frame on the call stack, or if it
+ /// is an inlined frame derived from the debug information and presented by
+ /// the debugger.
///
/// @return
/// true if this is an inlined frame.
bool IsInlined();
//------------------------------------------------------------------
- /// Query this frame to find what frame it is in this Thread's StackFrameList.
+ /// Query this frame to find what frame it is in this Thread's
+ /// StackFrameList.
///
/// @return
/// StackFrame index 0 indicates the currently-executing function. Inline
uint32_t GetFrameIndex() const;
//------------------------------------------------------------------
- /// Query this frame to find what frame it is in this Thread's StackFrameList,
- /// not counting inlined frames.
+ /// Query this frame to find what frame it is in this Thread's
+ /// StackFrameList, not counting inlined frames.
///
/// @return
/// StackFrame index 0 indicates the currently-executing function. Inline
//------------------------------------------------------------------
/// Add an arbitrary Variable object (e.g. one that specifics a global or
- /// static)
- /// to a StackFrame's list of ValueObjects.
+ /// static) to a StackFrame's list of ValueObjects.
///
/// @params [in] variable_sp
/// The Variable to base this ValueObject on
lldb::DynamicValueType use_dynamic);
//------------------------------------------------------------------
- /// Query this frame to determine what the default language should be
- /// when parsing expressions given the execution context.
+ /// Query this frame to determine what the default language should be when
+ /// parsing expressions given the execution context.
///
/// @return
/// The language of the frame if known, else lldb::eLanguageTypeUnknown.
//------------------------------------------------------------------
/// Attempt to reconstruct the ValueObject for the address contained in a
- /// given register plus an offset. The ExpressionPath should indicate how to
- /// get to this value using "frame variable."
+ /// given register plus an offset. The ExpressionPath should indicate how
+ /// to get to this value using "frame variable."
///
/// @params [in] reg
/// The name of the register.
//----------------------------------------------------------------------
/// @class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h"
-/// @brief A plug-in interface definition class for system runtimes.
+/// A plug-in interface definition class for system runtimes.
///
/// The system runtime plugins can collect information from the system
-/// libraries during a Process' lifetime and provide information about
-/// how objects/threads were originated.
+/// libraries during a Process' lifetime and provide information about how
+/// objects/threads were originated.
///
-/// For instance, a system runtime plugin use a breakpoint when threads
-/// are created to record the backtrace of where that thread was created.
-/// Later, when backtracing the created thread, it could extend the backtrace
-/// to show where it was originally created from.
+/// For instance, a system runtime plugin use a breakpoint when threads are
+/// created to record the backtrace of where that thread was created. Later,
+/// when backtracing the created thread, it could extend the backtrace to show
+/// where it was originally created from.
///
-/// The plugin will insert its own breakpoint when Created and start collecting
-/// information. Later when it comes time to augment a Thread, it can be
-/// asked to provide that information.
+/// The plugin will insert its own breakpoint when Created and start
+/// collecting information. Later when it comes time to augment a Thread, it
+/// can be asked to provide that information.
///
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Find a system runtime plugin for a given process.
///
- /// Scans the installed SystemRuntime plugins and tries to find
- /// an instance that can be used to track image changes in \a
- /// process.
+ /// 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
/// The process for which to try and locate a system runtime
//------------------------------------------------------------------
/// Destructor.
///
- /// The destructor is virtual since this class is designed to be
- /// inherited by the plug-in instance.
+ /// The destructor is virtual since this class is designed to be inherited
+ /// by the plug-in instance.
//------------------------------------------------------------------
~SystemRuntime() override;
//------------------------------------------------------------------
/// Called after attaching to a process.
///
- /// Allow the SystemRuntime plugin to execute some code after attaching
- /// to a process.
+ /// Allow the SystemRuntime plugin to execute some code after attaching to a
+ /// process.
//------------------------------------------------------------------
virtual void DidAttach();
//------------------------------------------------------------------
/// Called after launching a process.
///
- /// Allow the SystemRuntime plugin to execute some code after launching
- /// a process.
+ /// Allow the SystemRuntime plugin to execute some code after launching a
+ /// process.
//------------------------------------------------------------------
virtual void DidLaunch();
//------------------------------------------------------------------
/// Called when modules have been loaded in the process.
///
- /// Allow the SystemRuntime plugin to enable logging features in the
- /// system runtime libraries.
+ /// Allow the SystemRuntime plugin to enable logging features in the system
+ /// runtime libraries.
//------------------------------------------------------------------
virtual void ModulesDidLoad(lldb_private::ModuleList &module_list);
//------------------------------------------------------------------
/// Called before detaching from a process.
///
- /// This will give a SystemRuntime plugin a chance to free any resources
- /// in the inferior process before we detach.
+ /// This will give a SystemRuntime plugin a chance to free any resources in
+ /// the inferior process before we detach.
//------------------------------------------------------------------
virtual void Detach();
//------------------------------------------------------------------
- /// Return a list of thread origin extended backtraces that may
- /// be available.
+ /// Return a list of thread origin extended backtraces that may be
+ /// available.
///
/// A System Runtime may be able to provide a backtrace of when this
- /// thread was originally created. Furthermore, it may be able to
- /// provide that extended backtrace for different styles of creation.
- /// On a system with both pthreads and libdispatch, aka Grand Central
- /// Dispatch, queues, the system runtime may be able to provide the
- /// pthread creation of the thread and it may also be able to provide
- /// the backtrace of when this GCD queue work block was enqueued.
- /// The caller may request these different origins by name.
- ///
- /// The names will be provided in the order that they are most likely
- /// to be requested. For instance, a most natural order may be to
- /// request the GCD libdispatch queue origin. If there is none, then
- /// request the pthread origin.
+ /// thread was originally created. Furthermore, it may be able to provide
+ /// that extended backtrace for different styles of creation. On a system
+ /// with both pthreads and libdispatch, aka Grand Central Dispatch, queues,
+ /// the system runtime may be able to provide the pthread creation of the
+ /// thread and it may also be able to provide the backtrace of when this GCD
+ /// queue work block was enqueued. The caller may request these different
+ /// origins by name.
+ ///
+ /// The names will be provided in the order that they are most likely to be
+ /// requested. For instance, a most natural order may be to request the GCD
+ /// libdispatch queue origin. If there is none, then request the pthread
+ /// origin.
///
/// @return
/// A vector of ConstStrings with names like "pthread" or "libdispatch".
/// Return a Thread which shows the origin of this thread's creation.
///
/// This likely returns a HistoryThread which shows how thread was
- /// originally created (e.g. "pthread" type), or how the work that
- /// is currently executing on it was originally enqueued (e.g.
- /// "libdispatch" type).
+ /// originally created (e.g. "pthread" type), or how the work that is
+ /// currently executing on it was originally enqueued (e.g. "libdispatch"
+ /// type).
///
- /// 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.
+ /// 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
/// The thread to examine.
/// a libdispatch queue in the future, or it represents a function/block
/// that is currently executing on a thread.
///
- /// This method will report a thread backtrace of the function that
- /// enqueued it originally, if possible.
+ /// This method will report a thread backtrace of the function that enqueued
+ /// it originally, if possible.
///
/// @param [in] queue_item_sp
/// The QueueItem that we are getting an extended backtrace for.
}
//------------------------------------------------------------------
- /// Populate the Process' QueueList with libdispatch / GCD queues that exist.
+ /// Populate the Process' QueueList with libdispatch / GCD queues that
+ /// exist.
///
- /// When process execution is paused, the SystemRuntime may be called to fill
- /// in the list of Queues that currently exist.
+ /// When process execution is paused, the SystemRuntime may be called to
+ /// fill in the list of Queues that currently exist.
///
/// @param [out] queue_list
/// This QueueList will be cleared, and any queues that currently exist
/// Get the queue name for a thread given a thread's dispatch_qaddr.
///
/// On systems using libdispatch queues, a thread may be associated with a
- /// queue.
- /// There will be a call to get the thread's dispatch_qaddr. At the
- /// dispatch_qaddr
- /// we will find the address of this thread's dispatch_queue_t structure.
- /// Given the address of the dispatch_queue_t structure for a thread,
- /// get the queue name and return it.
+ /// queue. There will be a call to get the thread's dispatch_qaddr. At the
+ /// dispatch_qaddr we will find the address of this thread's
+ /// 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
/// The address of the dispatch_qaddr pointer for this thread.
/// dispatch_qaddr.
///
/// On systems using libdispatch queues, a thread may be associated with a
- /// queue.
- /// There will be a call to get the thread's dispatch_qaddr. At the
- /// dispatch_qaddr
- /// we will find the address of this thread's dispatch_queue_t structure.
- /// Given the address of the dispatch_queue_t structure for a thread,
- /// get the queue ID and return it.
+ /// queue. There will be a call to get the thread's dispatch_qaddr. At the
+ /// dispatch_qaddr we will find the address of this thread's
+ /// 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
/// The address of the dispatch_qaddr pointer for this thread.
/// dispatch_qaddr.
///
/// On systems using libdispatch queues, a thread may be associated with a
- /// queue.
- /// There will be a call to get the thread's dispatch_qaddr.
- /// Given the thread's dispatch_qaddr, find the libdispatch_queue_t address
- /// and
+ /// queue. There will be a call to get the thread's dispatch_qaddr. Given
+ /// the thread's dispatch_qaddr, find the libdispatch_queue_t address and
/// return it.
///
/// @param [in] dispatch_qaddr
/// Retrieve the Queue kind for the queue at a thread's dispatch_qaddr.
///
/// Retrieve the Queue kind - either eQueueKindSerial or
- /// eQueueKindConcurrent, indicating that this queue processes work
- /// items serially or concurrently.
+ /// eQueueKindConcurrent, indicating that this queue processes work items
+ /// serially or concurrently.
///
/// @return
/// The Queue kind, if it could be read, else eQueueKindUnknown.
/// Get the pending work items for a libdispatch Queue
///
/// If this system/process is using libdispatch and the runtime can do so,
- /// retrieve the list of pending work items for the specified Queue and
- /// add it to the Queue.
+ /// retrieve the list of pending work items for the specified Queue and add
+ /// it to the Queue.
///
/// @param [in] queue
/// The queue of interest.
/// Complete the fields in a QueueItem
///
/// PopulatePendingItemsForQueue() may not fill in all of the QueueItem
- /// details; when the remaining fields are needed, they will be
- /// fetched by call this method.
+ /// details; when the remaining fields are needed, they will be fetched by
+ /// call this method.
///
/// @param [in] queue_item
/// The QueueItem that we will be completing.
//------------------------------------------------------------------
/// Add key-value pairs to the StructuredData dictionary object with
/// information debugserver may need when constructing the
- /// jThreadExtendedInfo
- /// packet.
+ /// jThreadExtendedInfo packet.
///
/// @param [out] dict
/// Dictionary to which key-value pairs should be added; they will
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class ArchSpec ArchSpec.h "lldb/Utility/ArchSpec.h"
-/// @brief An architecture specification class.
+/// @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
-/// string representation, or an llvm::Triple. Keeping all of the
-/// conversions of strings to architecture enumeration values confined
-/// to this class allows new architecture support to be added easily.
+/// string representation, or an llvm::Triple. Keeping all of the conversions
+/// of strings to architecture enumeration values confined to this class
+/// allows new architecture support to be added easily.
//----------------------------------------------------------------------
class ArchSpec {
public:
//------------------------------------------------------------------
/// Default constructor.
///
- /// Default constructor that initializes the object with invalid
- /// cpu type and subtype values.
+ /// Default constructor that initializes the object with invalid cpu type
+ /// and subtype values.
//------------------------------------------------------------------
ArchSpec();
//------------------------------------------------------------------
/// Constructor over triple.
///
- /// Constructs an ArchSpec with properties consistent with the given
- /// Triple.
+ /// Constructs an ArchSpec with properties consistent with the given Triple.
//------------------------------------------------------------------
explicit ArchSpec(const llvm::Triple &triple);
explicit ArchSpec(const char *triple_cstr);
//------------------------------------------------------------------
/// Constructor over architecture name.
///
- /// Constructs an ArchSpec with properties consistent with the given
- /// object type and architecture name.
+ /// Constructs an ArchSpec with properties consistent with the given object
+ /// type and architecture name.
//------------------------------------------------------------------
explicit ArchSpec(ArchitectureType arch_type, uint32_t cpu_type,
uint32_t cpu_subtype);
//---------------------------------------------------------------------------
/// Returns true if the OS, vendor and environment fields of the triple are
- /// unset. The triple is expected to be normalized (llvm::Triple::normalize).
+ /// unset. The triple is expected to be normalized
+ /// (llvm::Triple::normalize).
//---------------------------------------------------------------------------
static bool ContainsOnlyArch(const llvm::Triple &normalized_triple);
bool IsMIPS() const;
//------------------------------------------------------------------
- /// Returns a string representing current architecture as a target CPU
- /// for tools like compiler, disassembler etc.
+ /// 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
/// architecture.
void Clear();
//------------------------------------------------------------------
- /// Returns the size in bytes of an address of the current
- /// architecture.
+ /// Returns the size in bytes of an address of the current architecture.
///
/// @return The byte size of an address of the current architecture.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Set the distribution id of the architecture.
///
- /// This will be something like "ubuntu", "fedora", etc. on Linux.
- /// This should be the same value returned by
- /// HostInfo::GetDistributionId ().
+ /// This will be something like "ubuntu", "fedora", etc. on Linux. This
+ /// should be the same value returned by HostInfo::GetDistributionId ().
///------------------------------------------------------------------
void SetDistributionId(const char *distribution_id);
//------------------------------------------------------------------
/// Merges fields from another ArchSpec into this ArchSpec.
///
- /// This will use the supplied ArchSpec to fill in any fields of
- /// the triple in this ArchSpec which were unspecified. This can
- /// be used to refine a generic ArchSpec with a more specific one.
- /// For example, if this ArchSpec's triple is something like
- /// i386-unknown-unknown-unknown, and we have a triple which is
- /// x64-pc-windows-msvc, then merging that triple into this one
- /// will result in the triple i386-pc-windows-msvc.
+ /// This will use the supplied ArchSpec to fill in any fields of the triple
+ /// in this ArchSpec which were unspecified. This can be used to refine a
+ /// generic ArchSpec with a more specific one. For example, if this
+ /// ArchSpec's triple is something like i386-unknown-unknown-unknown, and we
+ /// have a triple which is x64-pc-windows-msvc, then merging that triple
+ /// into this one will result in the triple i386-pc-windows-msvc.
///
//------------------------------------------------------------------
void MergeFrom(const ArchSpec &other);
///
/// @return True if the object, and CPU were successfully set.
///
- /// As a side effect, the vendor value is usually set to unknown.
- /// The exections are
+ /// As a side effect, the vendor value is usually set to unknown. The
+ /// exections are
/// aarch64-apple-ios
/// arm-apple-ios
/// thumb-apple-ios
/// x86-apple-
/// x86_64-apple-
///
- /// As a side effect, the os value is usually set to unknown
- /// The exceptions are
+ /// As a side effect, the os value is usually set to unknown The exceptions
+ /// are
/// *-*-aix
/// aarch64-apple-ios
/// arm-apple-ios
//------------------------------------------------------------------
/// Sets this ArchSpec's byte order.
///
- /// In the common case there is no need to call this method as the
- /// byte order can almost always be determined by the architecture.
- /// However, many CPU's are bi-endian (ARM, Alpha, PowerPC, etc)
- /// and the default/assumed byte order may be incorrect.
+ /// In the common case there is no need to call this method as the byte
+ /// order can almost always be determined by the architecture. However, many
+ /// CPU's are bi-endian (ARM, Alpha, PowerPC, etc) and the default/assumed
+ /// byte order may be incorrect.
//------------------------------------------------------------------
void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; }
//------------------------------------------------------------------
/// Architecture data byte width accessor
///
- /// @return the size in 8-bit (host) bytes of a minimum addressable
- /// unit from the Architecture's data bus
+ /// @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 from the Architecture's code bus
+ /// @return the size in 8-bit (host) bytes of a minimum addressable unit
+ /// from the Architecture's code bus
//------------------------------------------------------------------
uint32_t GetCodeByteSize() const;
//------------------------------------------------------------------
/// Architecture tripple setter.
///
- /// Configures this ArchSpec according to the given triple. If the
- /// triple has unknown components in all of the vendor, OS, and
- /// the optional environment field (i.e. "i386-unknown-unknown")
- /// then default values are taken from the host. Architecture and
- /// environment components are used to further resolve the CPU type
- /// and subtype, endian characteristics, etc.
+ /// Configures this ArchSpec according to the given triple. If the triple
+ /// has unknown components in all of the vendor, OS, and the optional
+ /// environment field (i.e. "i386-unknown-unknown") then default values are
+ /// taken from the host. Architecture and environment components are used
+ /// to further resolve the CPU type and subtype, endian characteristics,
+ /// etc.
///
/// @return A triple describing this ArchSpec.
//------------------------------------------------------------------
lldb::ByteOrder GetDefaultEndian() const;
//------------------------------------------------------------------
- /// Returns true if 'char' is a signed type by defualt in the
- /// architecture false otherwise
+ /// Returns true if 'char' is a signed type by defualt in the architecture
+ /// false otherwise
///
/// @return True if 'char' is a signed type by default on the
/// architecture and false otherwise.
bool CharIsSignedByDefault() const;
//------------------------------------------------------------------
- /// Compare an ArchSpec to another ArchSpec, requiring an exact cpu
- /// type match between them.
- /// e.g. armv7s is not an exact match with armv7 - this would return false
+ /// Compare an ArchSpec to another ArchSpec, requiring an exact cpu type
+ /// match between them. e.g. armv7s is not an exact match with armv7 - this
+ /// would return false
///
/// @return true if the two ArchSpecs match.
//------------------------------------------------------------------
bool IsExactMatch(const ArchSpec &rhs) const;
//------------------------------------------------------------------
- /// Compare an ArchSpec to another ArchSpec, requiring a compatible
- /// cpu type match between them.
- /// e.g. armv7s is compatible with armv7 - this method would return true
+ /// Compare an ArchSpec to another ArchSpec, requiring a compatible cpu type
+ /// match between them. e.g. armv7s is compatible with armv7 - this method
+ /// would return true
///
/// @return true if the two ArchSpecs are compatible
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Detect whether this architecture uses thumb code exclusively
///
- /// Some embedded ARM chips (e.g. the ARM Cortex M0-7 line) can
- /// only execute the Thumb instructions, never Arm. We should normally
- /// pick up arm/thumbness from their the processor status bits (cpsr/xpsr)
- /// or hints on each function - but when doing bare-boards low level
- /// debugging (especially common with these embedded processors), we may
- /// not have those things easily accessible.
+ /// Some embedded ARM chips (e.g. the ARM Cortex M0-7 line) can only execute
+ /// the Thumb instructions, never Arm. We should normally pick up
+ /// arm/thumbness from their the processor status bits (cpsr/xpsr) or hints
+ /// on each function - but when doing bare-boards low level debugging
+ /// (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
/// instructions
};
//------------------------------------------------------------------
-/// @fn bool operator< (const ArchSpec& lhs, const ArchSpec& rhs)
-/// @brief Less than operator.
+/// @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.
+/// 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] rhs The Left Hand Side ArchSpec object to compare.
+/// @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
//------------------------------------------------------------------
//----------------------------------------------------------------------
/// @class Args Args.h "lldb/Utility/Args.h"
-/// @brief A command line argument class.
+/// A command line argument class.
///
-/// The Args class is designed to be fed a command line. The
-/// command line is copied into an internal buffer and then split up
-/// into arguments. Arguments are space delimited if there are no quotes
-/// (single, double, or backtick quotes) surrounding the argument. Spaces
-/// can be escaped using a \ character to avoid having to surround an
-/// argument that contains a space with quotes.
+/// The Args class is designed to be fed a command line. The command line is
+/// copied into an internal buffer and then split up into arguments. Arguments
+/// are space delimited if there are no quotes (single, double, or backtick
+/// quotes) surrounding the argument. Spaces can be escaped using a \
+/// character to avoid having to surround an argument that contains a space
+/// with quotes.
//----------------------------------------------------------------------
class Args {
public:
//------------------------------------------------------------------
/// Sets the command string contained by this object.
///
- /// The command string will be copied and split up into arguments
- /// that can be accessed via the accessor functions.
+ /// The command string will be copied and split up into arguments that can
+ /// be accessed via the accessor functions.
///
/// @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 char *)
+ /// @see Args::GetArgumentAtIndex (size_t) const @see
+ /// Args::GetArgumentVector () @see Args::Shift () @see Args::Unshift (const
+ /// char *)
//------------------------------------------------------------------
void SetCommandString(llvm::StringRef command);
bool empty() const { return GetArgumentCount() == 0; }
//------------------------------------------------------------------
- /// Gets the NULL terminated C string argument pointer for the
- /// argument at index \a idx.
+ /// Gets the NULL terminated C string argument pointer for the argument at
+ /// index \a idx.
///
/// @return
/// The NULL terminated C string argument pointer if \a idx is a
//------------------------------------------------------------------
/// Gets the argument vector.
///
- /// The value returned by this function can be used by any function
- /// that takes and vector. The return value is just like \a argv
- /// in the standard C entry point function:
+ /// The value returned by this function can be used by any function that
+ /// takes and vector. The return value is just like \a argv in the standard
+ /// C entry point function:
/// \code
/// int main (int argc, const char **argv);
/// \endcode
//------------------------------------------------------------------
/// Gets the argument vector.
///
- /// The value returned by this function can be used by any function
- /// that takes and vector. The return value is just like \a argv
- /// in the standard C entry point function:
+ /// The value returned by this function can be used by any function that
+ /// takes and vector. The return value is just like \a argv in the standard
+ /// C entry point function:
/// \code
/// int main (int argc, const char **argv);
/// \endcode
char quote_char = '\0');
//------------------------------------------------------------------
- /// Replaces the argument value at index \a idx to \a arg_cstr
- /// if \a idx is a valid argument index.
+ /// Replaces the argument value at index \a idx to \a arg_cstr if \a idx is
+ /// a valid argument index.
///
/// @param[in] idx
/// The index of the argument that will have its value replaced.
void DeleteArgumentAtIndex(size_t idx);
//------------------------------------------------------------------
- /// Sets the argument vector value, optionally copying all
- /// arguments into an internal buffer.
+ /// Sets the argument vector value, optionally copying all arguments into an
+ /// internal buffer.
///
- /// Sets the arguments to match those found in \a argv. All argument
- /// strings will be copied into an internal buffers.
+ /// Sets the arguments to match those found in \a argv. All argument strings
+ /// will be copied into an internal buffers.
//
// FIXME: Handle the quote character somehow.
//------------------------------------------------------------------
void SetArguments(const char **argv);
//------------------------------------------------------------------
- /// Shifts the first argument C string value of the array off the
- /// argument array.
+ /// Shifts the first argument C string value of the array off the argument
+ /// array.
///
- /// The string value will be freed, so a copy of the string should
- /// be made by calling Args::GetArgumentAtIndex (size_t) const
- /// first and copying the returned value before calling
- /// Args::Shift().
+ /// The string value will be freed, so a copy of the string should be made
+ /// by calling Args::GetArgumentAtIndex (size_t) const first and copying the
+ /// returned value before calling Args::Shift().
///
/// @see Args::GetArgumentAtIndex (size_t) const
//------------------------------------------------------------------
void Shift();
//------------------------------------------------------------------
- /// Inserts a class owned copy of \a arg_cstr at the beginning of
- /// the argument vector.
+ /// Inserts a class owned copy of \a arg_cstr at the beginning of the
+ /// argument vector.
///
/// A copy \a arg_cstr will be made.
///
//----------------------------------------------------------------------
/// @class Baton Baton.h "lldb/Core/Baton.h"
-/// @brief A class designed to wrap callback batons so they can cleanup
+/// A class designed to wrap callback batons so they can cleanup
/// any acquired resources
///
-/// This class is designed to be used by any objects that have a
-/// callback function that takes a baton where the baton might need to
+/// This class is designed to be used by any objects that have a callback
+/// function that takes a baton where the baton might need to
/// free/delete/close itself.
///
-/// The default behavior is to not free anything. Subclasses can
-/// free any needed resources in their destructors.
+/// The default behavior is to not free anything. Subclasses can free any
+/// needed resources in their destructors.
//----------------------------------------------------------------------
class Baton {
public:
//----------------------------------------------------------------------
/// @class Connection Connection.h "lldb/Utility/Connection.h"
-/// @brief A communication connection class.
+/// A communication connection class.
///
/// A class that implements that actual communication functions for
-/// connecting/disconnecting, reading/writing, and waiting for bytes
-/// to become available from a two way communication connection.
+/// connecting/disconnecting, reading/writing, and waiting for bytes to become
+/// available from a two way communication connection.
///
-/// This class is designed to only do very simple communication
-/// functions. Instances can be instantiated and given to a
-/// Communication class to perform communications where clients can
-/// listen for broadcasts, and perform other higher level communications.
+/// This class is designed to only do very simple communication functions.
+/// Instances can be instantiated and given to a Communication class to
+/// perform communications where clients can listen for broadcasts, and
+/// perform other higher level communications.
//----------------------------------------------------------------------
class Connection {
public:
Connection() = default;
//------------------------------------------------------------------
- /// Virtual destructor since this class gets subclassed and handed
- /// to a Communication object.
+ /// Virtual destructor since this class gets subclassed and handed to a
+ /// Communication object.
//------------------------------------------------------------------
virtual ~Connection();
Status *error_ptr) = 0;
//------------------------------------------------------------------
- /// Disconnect the communications connection if one is currently
- /// connected.
+ /// Disconnect the communications connection if one is currently connected.
///
/// @param[out] error_ptr
/// A pointer to an error object that should be given an
lldb::ConnectionStatus &status, Status *error_ptr) = 0;
//------------------------------------------------------------------
- /// The actual write function that attempts to write to the
- /// communications protocol.
+ /// The actual write function that attempts to write to the communications
+ /// protocol.
///
/// Subclasses must override this function.
///
//------------------------------------------------------------------
/// Returns the underlying IOObject used by the Connection.
///
- /// The IOObject can be used to wait for data to become available
- /// on the connection. If the Connection does not use IOObjects (and
- /// hence does not support waiting) this function should return a
- /// null pointer.
+ /// The IOObject can be used to wait for data to become available on the
+ /// connection. If the Connection does not use IOObjects (and hence does not
+ /// support waiting) this function should return a null pointer.
///
/// @return
/// The underlying IOObject used for reading.
//----------------------------------------------------------------------
/// @class ConstString ConstString.h "lldb/Utility/ConstString.h"
-/// @brief A uniqued constant string class.
+/// A uniqued constant string class.
///
-/// Provides an efficient way to store strings as uniqued strings. After
-/// the strings are uniqued, finding strings that are equal to one
-/// another is very fast as just the pointers need to be compared. It
-/// also allows for many common strings from many different sources to
-/// be shared to keep the memory footprint low.
+/// Provides an efficient way to store strings as uniqued strings. After the
+/// strings are uniqued, finding strings that are equal to one another is very
+/// fast as just the pointers need to be compared. It also allows for many
+/// common strings from many different sources to be shared to keep the memory
+/// footprint low.
///
-/// No reference counting is done on strings that are added to the
-/// string pool, once strings are added they are in the string pool for
-/// the life of the program.
+/// No reference counting is done on strings that are added to the string
+/// pool, once strings are added they are in the string pool for the life of
+/// the program.
//----------------------------------------------------------------------
class ConstString {
public:
//------------------------------------------------------------------
/// Construct with C String value with max length
///
- /// Constructs this object with a C string with a length. If
- /// \a max_cstr_len is greater than the actual length of the string,
- /// the string length will be truncated. This allows substrings to
- /// be created without the need to NULL terminate the string as it
- /// is passed into this function.
+ /// Constructs this object with a C string with a length. If \a max_cstr_len
+ /// is greater than the actual length of the string, the string length will
+ /// 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
/// A pointer to the first character in the C string. The C
//------------------------------------------------------------------
/// Destructor
///
- /// Since constant string values are currently not reference counted,
- /// there isn't much to do here.
+ /// Since constant string values are currently not reference counted, there
+ /// isn't much to do here.
//------------------------------------------------------------------
~ConstString() = default;
//--------------------------------------------------------------
/// C equality test.
///
- /// Two C strings are equal when they are contained in ConstString
- /// objects when their pointer values are equal to each other.
+ /// Two C strings are equal when they are contained in ConstString objects
+ /// when their pointer values are equal to each other.
///
/// @return
/// Returns \b true if the C string in \a lhs is equal to
//------------------------------------------------------------------
/// Convert to bool operator.
///
- /// This allows code to check a ConstString object to see if it
- /// contains a valid string using code such as:
+ /// This allows code to check a ConstString object to see if it contains a
+ /// valid string using code such as:
///
/// @code
/// ConstString str(...);
//------------------------------------------------------------------
/// Equal to operator
///
- /// Returns true if this string is equal to the string in \a rhs.
- /// This operation is very fast as it results in a pointer
- /// comparison since all strings are in a uniqued in a global string
- /// pool.
+ /// Returns true if this string is equal to the string in \a rhs. This
+ /// 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
/// Another string object to compare this object to.
//------------------------------------------------------------------
/// Not equal to operator
///
- /// Returns true if this string is not equal to the string in \a rhs.
- /// This operation is very fast as it results in a pointer
- /// comparison since all strings are in a uniqued in a global string
- /// pool.
+ /// Returns true if this string is not equal to the string in \a rhs. This
+ /// 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
/// Another string object to compare this object to.
//------------------------------------------------------------------
/// Get the string value as a C string.
///
- /// Get the value of the contained string as a NULL terminated C
- /// string value.
+ /// Get the value of the contained string as a NULL terminated C string
+ /// value.
///
/// If \a value_if_empty is nullptr, then nullptr will be returned.
///
//------------------------------------------------------------------
/// Get the string value as a C string.
///
- /// Get the value of the contained string as a NULL terminated C
- /// string value. Similar to the ConstString::AsCString() function,
- /// yet this function will always return nullptr if the string is not
- /// valid. So this function is a direct accessor to the string
- /// pointer value.
+ /// Get the value of the contained string as a NULL terminated C string
+ /// value. Similar to the ConstString::AsCString() function, yet this
+ /// function will always return nullptr if the string is not valid. So this
+ /// function is a direct accessor to the string pointer value.
///
/// @return
/// Returns nullptr the string is invalid, otherwise the C string
//------------------------------------------------------------------
/// Get the length in bytes of string value.
///
- /// The string pool stores the length of the string, so we can avoid
- /// calling strlen() on the pointer value with this function.
+ /// The string pool stores the length of the string, so we can avoid calling
+ /// strlen() on the pointer value with this function.
///
/// @return
/// Returns the number of bytes that this string occupies in
//------------------------------------------------------------------
/// Clear this object's state.
///
- /// Clear any contained string and reset the value to the an empty
- /// string value.
+ /// Clear any contained string and reset the value to the an empty string
+ /// value.
//------------------------------------------------------------------
void Clear() { m_string = nullptr; }
//------------------------------------------------------------------
/// Equal to operator
///
- /// Returns true if this string is equal to the string in \a rhs.
- /// If case sensitive equality is tested, this operation is very
- /// fast as it results in a pointer comparison since all strings
- /// are in a uniqued in a global string pool.
+ /// Returns true if this string is equal to the string in \a rhs. If case
+ /// sensitive equality is tested, this 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
/// The Left Hand Side const ConstString object reference.
//------------------------------------------------------------------
/// Compare two string objects.
///
- /// Compares the C string values contained in \a lhs and \a rhs and
- /// returns an integer result.
+ /// Compares the C string values contained in \a lhs and \a rhs and returns
+ /// an integer result.
///
/// NOTE: only call this function when you want a true string
- /// comparison. If you want string equality use the, use the ==
- /// operator as it is much more efficient. Also if you want string
- /// inequality, use the != operator for the same reasons.
+ /// comparison. If you want string equality use the, use the == operator as
+ /// it is much more efficient. Also if you want string inequality, use the
+ /// != operator for the same reasons.
///
/// @param[in] lhs
/// The Left Hand Side const ConstString object reference.
//------------------------------------------------------------------
/// Dump the object description to a stream.
///
- /// Dump the string value to the stream \a s. If the contained string
- /// is 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.
+ /// Dump the string value to the stream \a s. If the contained string is
+ /// 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
/// The stream that will be used to dump the object description.
//------------------------------------------------------------------
/// Set the C string value.
///
- /// Set the string value in the object by uniquing the \a cstr
- /// string value in our global string pool.
+ /// Set the string value in the object by uniquing the \a cstr string value
+ /// in our global string pool.
///
- /// If the C string already exists in the global string pool, it
- /// finds the current entry and returns the existing value. If it
- /// doesn't exist, it is added to the string pool.
+ /// If the C string already exists in the global string pool, it finds the
+ /// current entry and returns the existing value. If it doesn't exist, it is
+ /// added to the string pool.
///
/// @param[in] cstr
/// A NULL terminated C string to add to the string pool.
//------------------------------------------------------------------
/// Set the C string value and its mangled counterpart.
///
- /// Object files and debug symbols often use mangled string to
- /// represent the linkage name for a symbol, function or global.
- /// The string pool can efficiently store these values and their
- /// counterparts so when we run into another instance of a mangled
- /// name, we can avoid calling the name demangler over and over on
- /// the same strings and then trying to unique them.
+ /// Object files and debug symbols often use mangled string to represent the
+ /// linkage name for a symbol, function or global. The string pool can
+ /// efficiently store these values and their counterparts so when we run
+ /// into another instance of a mangled name, we can avoid calling the name
+ /// demangler over and over on the same strings and then trying to unique
+ /// them.
///
/// @param[in] demangled
/// The demangled C string to correlate with the \a mangled
const ConstString &mangled);
//------------------------------------------------------------------
- /// Retrieve the mangled or demangled counterpart for a mangled
- /// or demangled ConstString.
+ /// Retrieve the mangled or demangled counterpart for a mangled or demangled
+ /// ConstString.
///
- /// Object files and debug symbols often use mangled string to
- /// represent the linkage name for a symbol, function or global.
- /// The string pool can efficiently store these values and their
- /// counterparts so when we run into another instance of a mangled
- /// name, we can avoid calling the name demangler over and over on
- /// the same strings and then trying to unique them.
+ /// Object files and debug symbols often use mangled string to represent the
+ /// linkage name for a symbol, function or global. The string pool can
+ /// efficiently store these values and their counterparts so when we run
+ /// into another instance of a mangled name, we can avoid calling the name
+ /// demangler over and over on the same strings and then trying to unique
+ /// them.
///
/// @param[in] counterpart
/// A reference to a ConstString object that might get filled in
/// Set the C string value with length.
///
/// Set the string value in the object by uniquing \a cstr_len bytes
- /// starting at the \a cstr string value in our global string pool.
- /// If trim is true, then \a cstr_len indicates a maximum length of
- /// the CString and if the actual length of the string is less, then
- /// it will be trimmed.
+ /// starting at the \a cstr string value in our global string pool. If trim
+ /// is true, then \a cstr_len indicates a maximum length of the CString and
+ /// if the actual length of the string is less, then it will be trimmed.
///
- /// If the C string already exists in the global string pool, it
- /// finds the current entry and returns the existing value. If it
- /// doesn't exist, it is added to the string pool.
+ /// If the C string already exists in the global string pool, it finds the
+ /// current entry and returns the existing value. If it doesn't exist, it is
+ /// added to the string pool.
///
/// @param[in] cstr
/// A NULL terminated C string to add to the string pool.
void SetCStringWithLength(const char *cstr, size_t cstr_len);
//------------------------------------------------------------------
- /// Set the C string value with the minimum length between
- /// \a fixed_cstr_len and the actual length of the C string. This
- /// can be used for data structures that have a fixed length to
- /// store a C string where the string might not be NULL terminated
- /// if the string takes the entire buffer.
+ /// Set the C string value with the minimum length between \a fixed_cstr_len
+ /// and the actual length of the C string. This can be used for data
+ /// structures that have a fixed length to store a C string where the string
+ /// might not be NULL terminated if the string takes the entire buffer.
//------------------------------------------------------------------
void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len);
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// Return the size in bytes that this object takes in memory. This
- /// returns the size in bytes of this object, which does not include
- /// any the shared string values it may refer to.
+ /// Return the size in bytes that this object takes in memory. This returns
+ /// the size in bytes of this object, which does not include any the shared
+ /// string values it may refer to.
///
/// @return
/// The number of bytes that this object occupies in memory.
//------------------------------------------------------------------
/// Get the size in bytes of the current global string pool.
///
- /// 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.
+ /// 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
/// The number of bytes that the global string pool occupies
//----------------------------------------------------------------------
/// @class DataBuffer DataBuffer.h "lldb/Core/DataBuffer.h"
-/// @brief A pure virtual protocol class for abstracted data buffers.
+/// A pure virtual protocol class for abstracted data buffers.
///
/// DataBuffer is an abstract class that gets packaged into a shared pointer
-/// that can use to implement various ways to store data (on the heap,
-/// memory mapped, cached inferior memory). It gets used by DataExtractor
-/// so many DataExtractor objects can share the same data and sub-ranges
-/// of that shared data, and the last object that contains a reference
-/// to the shared data will free it.
+/// that can use to implement various ways to store data (on the heap, memory
+/// mapped, cached inferior memory). It gets used by DataExtractor so many
+/// DataExtractor objects can share the same data and sub-ranges of that
+/// shared data, and the last object that contains a reference to the shared
+/// data will free it.
///
/// Subclasses can implement as many different constructors or member
-/// functions that allow data to be stored in the object's buffer prior
-/// to handing the shared data to clients that use these buffers.
+/// functions that allow data to be stored in the object's buffer prior to
+/// handing the shared data to clients that use these buffers.
///
-/// All subclasses must override all of the pure virtual functions as
-/// they are used by clients to access the data. Having a common
-/// interface allows different ways of storing data, yet using it in
-/// one common way.
+/// All subclasses must override all of the pure virtual functions as they are
+/// used by clients to access the data. Having a common interface allows
+/// different ways of storing data, yet using it in one common way.
///
-/// This class currently expects all data to be available without any
-/// extra calls being made, but we can modify it to optionally get
-/// data on demand with some extra function calls to load the data
-/// before it gets accessed.
+/// This class currently expects all data to be available without any extra
+/// calls being made, but we can modify it to optionally get data on demand
+/// with some extra function calls to load the data before it gets accessed.
//----------------------------------------------------------------------
class DataBuffer {
public:
//------------------------------------------------------------------
/// Destructor
///
- /// The destructor is virtual as other classes will inherit from
- /// this class and be downcast to the DataBuffer pure virtual
- /// interface. The virtual destructor ensures that destructing the
- /// base class will destruct the class that inherited from it
- /// correctly.
+ /// The destructor is virtual as other classes will inherit from this class
+ /// and be downcast to the DataBuffer pure virtual interface. The virtual
+ /// destructor ensures that destructing the base class will destruct the
+ /// class that inherited from it correctly.
//------------------------------------------------------------------
virtual ~DataBuffer() {}
//----------------------------------------------------------------------
/// @class DataBufferHeap DataBufferHeap.h "lldb/Core/DataBufferHeap.h"
-/// @brief A subclass of DataBuffer that stores a data buffer on the heap.
+/// 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 object. This class is best used to store chunks of data that
-/// are created or read from sources that can't intelligently and lazily
-/// fault new data pages in. Large amounts of data that comes from files
-/// should probably use DataBufferLLVM, which can intelligently determine
-/// when memory mapping is optimal.
+/// This class keeps its data in a heap based buffer that is owned by the
+/// object. This class is best used to store chunks of data that are created
+/// or read from sources that can't intelligently and lazily fault new data
+/// pages in. Large amounts of data that comes from files should probably use
+/// DataBufferLLVM, which can intelligently determine when memory mapping is
+/// optimal.
//----------------------------------------------------------------------
class DataBufferHeap : public DataBuffer {
public:
//------------------------------------------------------------------
/// Construct with size \a n and fill with \a ch.
///
- /// Initialize this class with \a n bytes and fills the buffer with
- /// \a ch.
+ /// Initialize this class with \a n bytes and fills the buffer with \a ch.
///
/// @param[in] n
/// The number of bytes that heap based buffer should contain.
//------------------------------------------------------------------
/// Destructor.
///
- /// Virtual destructor since this class inherits from a pure virtual
- /// base class #DataBuffer.
+ /// Virtual destructor since this class inherits from a pure virtual base
+ /// class #DataBuffer.
//------------------------------------------------------------------
~DataBufferHeap() override;
//------------------------------------------------------------------
/// Set the number of bytes in the data buffer.
///
- /// Sets the number of bytes that this object should be able to
- /// contain. This can be used prior to copying data into the buffer.
+ /// Sets the number of bytes that this object should be able to contain.
+ /// This can be used prior to copying data into the buffer.
///
/// @param[in] byte_size
/// The new size in bytes that this data buffer should attempt
char *GetChars() { return reinterpret_cast<char *>(GetBytes()); }
private:
- /// \brief Construct a DataBufferLLVM from \p Buffer. \p Buffer must be a
- /// valid pointer.
+ /// Construct a DataBufferLLVM from \p Buffer. \p Buffer must be a valid
+ /// pointer.
explicit DataBufferLLVM(std::unique_ptr<llvm::WritableMemoryBuffer> Buffer);
std::unique_ptr<llvm::WritableMemoryBuffer> Buffer;
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h"
-/// @brief An binary data encoding class.
+/// @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.
+/// 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
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Construct with a buffer that is owned by the caller.
///
- /// 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.
+ /// 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
/// A pointer to caller owned data.
//------------------------------------------------------------------
/// Construct with shared data.
///
- /// Copies the data shared pointer which adds a reference to the
- /// contained in \a data_sp. The shared data reference is reference
- /// counted to ensure the data lives as long as anyone still has a
- /// valid shared pointer to the data in \a data_sp.
+ /// Copies the data shared pointer which adds a reference to the contained
+ /// in \a data_sp. The shared data reference is reference counted to ensure
+ /// the data lives as long as anyone still has a valid shared pointer to the
+ /// data in \a data_sp.
///
/// @param[in] data_sp
/// A shared pointer to data.
//------------------------------------------------------------------
/// Destructor
///
- /// If this object contains a valid shared data reference, the
- /// reference count on the data will be decremented, and if zero,
- /// the data will be freed.
+ /// If this object contains a valid shared data reference, the reference
+ /// count on the data will be decremented, and if zero, the data will be
+ /// freed.
//------------------------------------------------------------------
~DataEncoder();
//------------------------------------------------------------------
/// Clears the object state.
///
- /// Clears the object contents back to a default invalid state, and
- /// release any references to shared data that this object may
- /// contain.
+ /// Clears the object contents back to a default invalid state, and release
+ /// any references to shared data that this object may contain.
//------------------------------------------------------------------
void Clear();
//------------------------------------------------------------------
/// Get the current address size.
///
- /// Return the size in bytes of any address values this object will
- /// extract.
+ /// Return the size in bytes of any address values this object will extract.
///
/// @return
/// The size in bytes of address values that will be extracted.
//------------------------------------------------------------------
/// Get the shared data offset.
///
- /// Get the offset of the first byte of data in the shared data (if
- /// any).
+ /// Get the offset of the first byte of data in the shared data (if any).
///
/// @return
/// If this object contains shared data, this function returns
//------------------------------------------------------------------
/// Encode an unsigned integer of size \a byte_size to \a offset.
///
- /// Encode a single integer value at \a offset and return the offset
- /// that follows the newly encoded integer when the data is successfully
- /// encoded into the existing data. There must be enough room in the
- /// data, else UINT32_MAX will be returned to indicate that encoding
- /// failed.
+ /// Encode a single integer value at \a offset and return the offset that
+ /// follows the newly encoded integer when the data is successfully encoded
+ /// 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
/// The offset within the contained data at which to put the
uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len);
//------------------------------------------------------------------
- /// Encode an address in the existing buffer at \a offset bytes into
- /// the buffer.
+ /// Encode an address in the existing buffer at \a offset bytes into the
+ /// buffer.
///
- /// Encode a single address (honoring the m_addr_size member) to
- /// the data and return the next offset where subsequent data would
- /// go.
- /// pointed to by \a offset_ptr. The size of the extracted address
- /// comes from the \a m_addr_size member variable and should be
- /// set correctly prior to extracting any address values.
+ /// Encode a single address (honoring the m_addr_size member) to the data
+ /// and return the next offset where subsequent data would go. pointed to by
+ /// \a offset_ptr. The size of the extracted address comes from the \a
+ /// m_addr_size member variable and should be set correctly prior to
+ /// extracting any address values.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Put a C string to \a offset.
///
- /// Encodes a C string into the existing data including the
- /// terminating
+ /// Encodes a C string into the existing data including the terminating
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Set the address byte size.
///
- /// Set the size in bytes that will be used when extracting any
- /// address and pointer values from data contained in this object.
+ /// 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
/// The size in bytes to use when extracting addresses.
//------------------------------------------------------------------
/// Set data with a buffer that is caller owned.
///
- /// Use data that is owned by the caller when extracting values.
- /// The data must stay around as long as this object, or any object
- /// that copies a subset of this object's data, is valid. If \a
- /// bytes is NULL, or \a length is zero, this object will contain
- /// no data.
+ /// Use data that is owned by the caller when extracting values. The data
+ /// must stay around as long as this object, or any object that copies a
+ /// 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
/// A pointer to caller owned data.
//------------------------------------------------------------------
/// Adopt a subset of shared data in \a data_sp.
///
- /// Copies the data shared pointer which adds a reference to the
- /// contained in \a data_sp. The shared data reference is reference
- /// counted to ensure the data lives as long as anyone still has a
- /// valid shared pointer to the data in \a data_sp. The byte order
- /// and address byte size settings remain the same. If
- /// \a offset is not a valid offset in \a data_sp, then no reference
- /// to the shared data will be added. If there 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.
+ /// Copies the data shared pointer which adds a reference to the contained
+ /// in \a data_sp. The shared data reference is reference counted to ensure
+ /// the data lives as long as anyone still has a valid shared pointer to the
+ /// data in \a data_sp. The byte order and address byte size settings remain
+ /// the same. If \a offset is not a valid offset in \a data_sp, then no
+ /// reference to the shared data will be added. If there 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_sp
/// A shared pointer to data.
//------------------------------------------------------------------
/// Set the byte_order value.
///
- /// Sets the byte order of the data to extract. Extracted values
- /// will be swapped if necessary when decoding.
+ /// Sets the byte order of the data to extract. Extracted values will be
+ /// swapped if necessary when decoding.
///
/// @param[in] byte_order
/// The byte order value to use when extracting data.
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h"
-/// @brief An data extractor class.
+/// @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 data buffer. The data buffer can be caller owned, or can be
-/// shared data that can be shared between multiple DataExtractor
-/// instances. Multiple DataExtractor objects can share the same data,
-/// yet extract values in different address sizes and byte order modes.
-/// Each object can have a unique position in the shared data and extract
-/// data from different offsets.
+/// DataExtractor is a class that can extract data (swapping if needed) from a
+/// data buffer. The data buffer can be caller owned, or can be shared data
+/// that can be shared between multiple DataExtractor instances. Multiple
+/// DataExtractor objects can share the same data, yet extract values in
+/// different address sizes and byte order modes. Each object can have a
+/// unique position in the shared data and extract data from different
+/// offsets.
///
/// @see DataBuffer
//----------------------------------------------------------------------
public:
//------------------------------------------------------------------
/// @typedef DataExtractor::Type
- /// @brief Type enumerations used in the dump routines.
+ /// Type enumerations used in the dump routines.
//------------------------------------------------------------------
typedef enum {
TypeUInt8, ///< Format output as unsigned 8 bit integers
//------------------------------------------------------------------
/// Construct with a buffer that is owned by the caller.
///
- /// 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.
+ /// 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
/// A pointer to caller owned data.
//------------------------------------------------------------------
/// Construct with shared data.
///
- /// Copies the data shared pointer which adds a reference to the
- /// contained in \a data_sp. The shared data reference is reference
- /// counted to ensure the data lives as long as anyone still has a
- /// valid shared pointer to the data in \a data_sp.
+ /// Copies the data shared pointer which adds a reference to the contained
+ /// in \a data_sp. The shared data reference is reference counted to ensure
+ /// the data lives as long as anyone still has a valid shared pointer to the
+ /// data in \a data_sp.
///
/// @param[in] data_sp
/// A shared pointer to data.
//------------------------------------------------------------------
/// Construct with a subset of \a data.
///
- /// Initialize this object with a subset of the data bytes in \a
- /// data. If \a data contains shared data, then a reference to the
- /// shared data will be added to ensure the shared data stays around
- /// as long as any objects have references to the shared data. The
- /// byte order value and the address size settings are copied from \a
- /// data. If \a offset is not a valid offset in \a data, then no
- /// reference to the shared data will be added. If there 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.
+ /// Initialize this object with a subset of the data bytes in \a data. If \a
+ /// data contains shared data, then a reference to the shared data will be
+ /// added to ensure the shared data stays around as long as any objects have
+ /// references to the shared data. The byte order value and the address size
+ /// settings are copied from \a data. If \a offset is not a valid offset in
+ /// \a data, then no reference to the shared data will be added. If there
+ /// 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
/// Another DataExtractor object that contains data.
/// Assignment operator.
///
/// Copies all data, byte order and address size settings from \a rhs into
- /// this object. If \a rhs contains shared data, a reference to that
- /// shared data will be added.
+ /// this object. If \a rhs contains shared data, a reference to that shared
+ /// data will be added.
///
/// @param[in] rhs
/// Another DataExtractor object to copy.
//------------------------------------------------------------------
/// Destructor
///
- /// If this object contains a valid shared data reference, the
- /// reference count on the data will be decremented, and if zero,
- /// the data will be freed.
+ /// If this object contains a valid shared data reference, the reference
+ /// count on the data will be decremented, and if zero, the data will be
+ /// freed.
//------------------------------------------------------------------
virtual ~DataExtractor();
//------------------------------------------------------------------
/// Clears the object state.
///
- /// Clears the object contents back to a default invalid state, and
- /// release any references to shared data that this object may
- /// contain.
+ /// Clears the object contents back to a default invalid state, and release
+ /// any references to shared data that this object may contain.
//------------------------------------------------------------------
void Clear();
//------------------------------------------------------------------
- /// Dumps the binary data as \a type objects to stream \a s (or to
- /// Log() if \a s is nullptr) starting \a offset bytes into the data
- /// and stopping after dumping \a length bytes. The offset into the
- /// data is displayed at 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.
+ /// Dumps the binary data as \a type objects to stream \a s (or to Log() if
+ /// \a s is nullptr) starting \a offset bytes into the data and stopping
+ /// after dumping \a length bytes. The offset into the data is displayed at
+ /// 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
/// The stream to dump the output to. If nullptr the output will
//------------------------------------------------------------------
/// Dump a UUID value at \a offset.
///
- /// Dump a UUID starting at \a offset bytes into this object's data.
- /// If the stream \a s is nullptr, the output will be sent to Log().
+ /// Dump a UUID starting at \a offset bytes into this object's data. If the
+ /// stream \a s is nullptr, the output will be sent to Log().
///
/// @param[in] s
/// The stream to dump the output to. If nullptr the output will
void DumpUUID(Stream *s, lldb::offset_t offset) const;
//------------------------------------------------------------------
- /// Extract an arbitrary number of bytes in the specified byte
- /// order.
+ /// Extract an arbitrary number of bytes in the specified byte order.
///
- /// Attemps to extract \a length bytes starting at \a offset bytes
- /// into this 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.
+ /// Attemps to extract \a length bytes starting at \a offset bytes into this
+ /// 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
/// The offset in bytes into the contained data at which to
//------------------------------------------------------------------
/// Extract an address from \a *offset_ptr.
///
- /// Extract a single address from the data and update the offset
- /// pointed to by \a offset_ptr. The size of the extracted address
- /// comes from the \a m_addr_size member variable and should be
- /// set correctly prior to extracting any address values.
+ /// Extract a single address from the data and update the offset pointed to
+ /// by \a offset_ptr. The size of the extracted address comes from the \a
+ /// m_addr_size member variable and should be set correctly prior to
+ /// extracting any address values.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Get the current address size.
///
- /// Return the size in bytes of any address values this object will
- /// extract.
+ /// Return the size in bytes of any address values this object will extract.
///
/// @return
/// The size in bytes of address values that will be extracted.
//------------------------------------------------------------------
/// Extract a C string from \a *offset_ptr.
///
- /// Returns a pointer to a C String from the data at the offset
- /// pointed to by \a offset_ptr. A variable length NULL terminated C
- /// string will be extracted and the \a offset_ptr will be
- /// updated with the offset of the byte that follows the NULL
- /// terminator byte.
+ /// Returns a pointer to a C String from the data at the offset pointed to
+ /// by \a offset_ptr. A variable length NULL terminated C string will be
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract a C string from \a *offset_ptr with field size \a len.
///
- /// Returns a pointer to a C String from the data at the offset
- /// pointed to by \a offset_ptr, with a field length of \a len.
+ /// Returns a pointer to a C String from the data at the offset pointed to
+ /// by \a offset_ptr, with a field length of \a len.
/// A NULL terminated C string will be extracted and the \a offset_ptr
/// will be updated with the offset of the byte that follows the fixed
/// length field.
//------------------------------------------------------------------
/// Extract \a length bytes from \a *offset_ptr.
///
- /// Returns a pointer to a bytes in this object's data at the offset
- /// pointed to by \a offset_ptr. If \a length is zero or too large,
- /// then the offset pointed to by \a offset_ptr will not be updated
- /// and nullptr will be returned.
+ /// Returns a pointer to a bytes in this object's data at the offset pointed
+ /// to by \a offset_ptr. If \a length is zero or too large, then the offset
+ /// pointed to by \a offset_ptr will not be updated and nullptr will be
+ /// returned.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
void *dst) const;
//------------------------------------------------------------------
- /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied
- /// data is treated as a value that can be swapped to match the
- /// specified byte order.
+ /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied data is
+ /// treated as a value that can be swapped to match the specified byte
+ /// order.
///
- /// For values that are larger than the supported integer sizes,
- /// this function can be used to extract data in a specified byte
- /// order. It can also be used to copy a smaller integer value from
- /// to a larger value. The extra bytes left over will be padded
- /// correctly according to the byte 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.
+ /// For values that are larger than the supported integer sizes, this
+ /// function can be used to extract data in a specified byte order. It can
+ /// also be used to copy a smaller integer value from to a larger value. The
+ /// extra bytes left over will be padded correctly according to the byte
+ /// 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
/// The offset into this data from which to start copying an
//------------------------------------------------------------------
/// Get the shared data offset.
///
- /// Get the offset of the first byte of data in the shared data (if
- /// any).
+ /// Get the offset of the first byte of data in the shared data (if any).
///
/// @return
/// If this object contains shared data, this function returns
//------------------------------------------------------------------
/// Extract an integer of size \a byte_size from \a *offset_ptr.
///
- /// Extract a single integer value and update the offset pointed to
- /// by \a offset_ptr. The size of the extracted integer is specified
- /// by the \a byte_size argument. \a byte_size must have a value
- /// >= 1 and <= 4 since the return value is only 32 bits wide.
+ /// Extract a single integer value and update the offset pointed to by \a
+ /// offset_ptr. The size of the extracted integer is specified by the \a
+ /// 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
/// A pointer to an offset within the data that will be advanced
uint32_t GetMaxU32(lldb::offset_t *offset_ptr, size_t byte_size) const;
//------------------------------------------------------------------
- /// Extract an unsigned integer of size \a byte_size from \a
- /// *offset_ptr.
+ /// Extract an unsigned integer of size \a byte_size from \a *offset_ptr.
///
- /// Extract a single unsigned integer value and update the offset
- /// pointed to by \a offset_ptr. The size of the extracted integer
- /// is specified by the \a byte_size argument. \a byte_size must
- /// have a value greater than or equal to one and less than or equal
- /// to eight since the return value is 64 bits wide.
+ /// Extract a single unsigned integer value and update the offset pointed to
+ /// by \a offset_ptr. The size of the extracted integer is specified by the
+ /// \a byte_size argument. \a byte_size must 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract an signed integer of size \a byte_size from \a *offset_ptr.
///
- /// Extract a single signed integer value (sign extending if required)
- /// and update the offset pointed to by \a offset_ptr. The size of
- /// the extracted integer is specified by the \a byte_size argument.
- /// \a byte_size must have a value greater than or equal to one and
- /// less than or equal to eight since the return value is 64 bits
- /// wide.
+ /// Extract a single signed integer value (sign extending if required) and
+ /// update the offset pointed to by \a offset_ptr. The size of the extracted
+ /// integer is specified by the \a byte_size argument. \a byte_size must
+ /// 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
/// A pointer to an offset within the data that will be advanced
int64_t GetMaxS64(lldb::offset_t *offset_ptr, size_t byte_size) const;
//------------------------------------------------------------------
- /// Extract an unsigned integer of size \a byte_size from \a
- /// *offset_ptr, then extract the bitfield from this value if
- /// \a bitfield_bit_size is non-zero.
+ /// Extract an unsigned integer of size \a byte_size from \a *offset_ptr,
+ /// then extract the bitfield from this value if \a bitfield_bit_size is
+ /// non-zero.
///
- /// Extract a single unsigned integer value and update the offset
- /// pointed to by \a offset_ptr. The size of the extracted integer
- /// is specified by the \a byte_size argument. \a byte_size must
- /// have a value greater than or equal to one and less than or equal
- /// to 8 since the return value is 64 bits wide.
+ /// Extract a single unsigned integer value and update the offset pointed to
+ /// by \a offset_ptr. The size of the extracted integer is specified by the
+ /// \a byte_size argument. \a byte_size must have a value greater than or
+ /// equal to one and less than or equal to 8 since the return value is 64
+ /// bits wide.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
uint32_t bitfield_bit_offset) const;
//------------------------------------------------------------------
- /// Extract an signed integer of size \a byte_size from \a
- /// *offset_ptr, then extract and signe extend the bitfield from
- /// this value if \a bitfield_bit_size is non-zero.
+ /// Extract an signed integer of size \a byte_size from \a *offset_ptr, then
+ /// extract and signe extend the bitfield from this value if \a
+ /// bitfield_bit_size is non-zero.
///
- /// Extract a single signed integer value (sign extending if required)
- /// and update the offset pointed to by \a offset_ptr. The size of
- /// the extracted integer is specified by the \a byte_size argument.
- /// \a byte_size must have a value greater than or equal to one and
- /// less than or equal to eight since the return value is 64 bits
- /// wide.
+ /// Extract a single signed integer value (sign extending if required) and
+ /// update the offset pointed to by \a offset_ptr. The size of the extracted
+ /// integer is specified by the \a byte_size argument. \a byte_size must
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract an pointer from \a *offset_ptr.
///
- /// Extract a single pointer from the data and update the offset
- /// pointed to by \a offset_ptr. The size of the extracted pointer
- /// comes from the \a m_addr_size member variable and should be
- /// set correctly prior to extracting any pointer values.
+ /// Extract a single pointer from the data and update the offset pointed to
+ /// by \a offset_ptr. The size of the extracted pointer comes from the \a
+ /// m_addr_size member variable and should be set correctly prior to
+ /// extracting any pointer values.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract a uint8_t value from \a *offset_ptr.
///
- /// Extract a single uint8_t from the binary data at the offset
- /// pointed to by \a offset_ptr, and advance the offset on success.
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract \a count uint8_t values from \a *offset_ptr.
///
- /// Extract \a count uint8_t values from the binary data at the
- /// offset pointed to by \a offset_ptr, and advance the offset on
- /// success. The extracted values are copied into \a dst.
+ /// Extract \a count uint8_t values from the binary data at the offset
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract a uint16_t value from \a *offset_ptr.
///
- /// Extract a single uint16_t from the binary data at the offset
- /// pointed to by \a offset_ptr, and update the offset on success.
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract \a count uint16_t values from \a *offset_ptr.
///
- /// Extract \a count uint16_t values from the binary data at the
- /// offset pointed to by \a offset_ptr, and advance the offset on
- /// success. The extracted values are copied into \a dst.
+ /// Extract \a count uint16_t values from the binary data at the offset
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract a uint32_t value from \a *offset_ptr.
///
- /// Extract a single uint32_t from the binary data at the offset
- /// pointed to by \a offset_ptr, and update the offset on success.
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract \a count uint32_t values from \a *offset_ptr.
///
- /// Extract \a count uint32_t values from the binary data at the
- /// offset pointed to by \a offset_ptr, and advance the offset on
- /// success. The extracted values are copied into \a dst.
+ /// Extract \a count uint32_t values from the binary data at the offset
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract a uint64_t value from \a *offset_ptr.
///
- /// Extract a single uint64_t from the binary data at the offset
- /// pointed to by \a offset_ptr, and update the offset on success.
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract \a count uint64_t values from \a *offset_ptr.
///
- /// Extract \a count uint64_t values from the binary data at the
- /// offset pointed to by \a offset_ptr, and advance the offset on
- /// success. The extracted values are copied into \a dst.
+ /// Extract \a count uint64_t values from the binary data at the offset
+ /// 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
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract a signed LEB128 value from \a *offset_ptr.
///
- /// Extracts an signed LEB128 number from this object's data
- /// starting at the offset pointed to by \a offset_ptr. The offset
- /// pointed to by \a offset_ptr will be updated with the offset of
- /// the byte following the last extracted byte.
+ /// Extracts an signed LEB128 number from this object's data starting at the
+ /// offset pointed to by \a offset_ptr. The offset pointed to by \a
+ /// offset_ptr will be updated with the offset of the byte following the
+ /// last extracted byte.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Extract a unsigned LEB128 value from \a *offset_ptr.
///
- /// Extracts an unsigned LEB128 number from this object's data
- /// starting at the offset pointed to by \a offset_ptr. The offset
- /// pointed to by \a offset_ptr will be updated with the offset of
- /// the byte following the last extracted byte.
+ /// Extracts an unsigned LEB128 number from this object's data starting at
+ /// the offset pointed to by \a offset_ptr. The offset pointed to by \a
+ /// offset_ptr will be updated with the offset of the byte following the
+ /// last extracted byte.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
//------------------------------------------------------------------
/// Peek at a C string at \a offset.
///
- /// Peeks at a string in the contained data. No verification is done
- /// to make sure the entire string lies within the bounds of this
- /// object's data, only \a offset is verified to be a valid offset.
+ /// Peeks at a string in the contained data. No verification is done to make
+ /// 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
/// An offset into the data.
//------------------------------------------------------------------
/// Peek at a bytes at \a offset.
///
- /// Returns a pointer to \a length bytes at \a offset as long as
- /// there are \a length bytes available starting at \a offset.
+ /// Returns a pointer to \a length bytes at \a offset as long as there are
+ /// \a length bytes available starting at \a offset.
///
/// @return
/// A non-nullptr data pointer if \a offset is a valid offset and
//------------------------------------------------------------------
/// Set the address byte size.
///
- /// Set the size in bytes that will be used when extracting any
- /// address and pointer values from data contained in this object.
+ /// 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
/// The size in bytes to use when extracting addresses.
//------------------------------------------------------------------
/// Set data with a buffer that is caller owned.
///
- /// Use data that is owned by the caller when extracting values.
- /// The data must stay around as long as this object, or any object
- /// that copies a subset of this object's data, is valid. If \a
- /// bytes is nullptr, or \a length is zero, this object will contain
- /// no data.
+ /// Use data that is owned by the caller when extracting values. The data
+ /// must stay around as long as this object, or any object that copies a
+ /// 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
/// A pointer to caller owned data.
//------------------------------------------------------------------
/// Adopt a subset of \a data.
///
- /// Set this object's data to be a subset of the data bytes in \a
- /// data. If \a data contains shared data, then a reference to the
- /// shared data will be added to ensure the shared data stays around
- /// as long as any objects have references to the shared data. The
- /// byte order and the address size settings are copied from \a
- /// data. If \a offset is not a valid offset in \a data, then no
- /// reference to the shared data will be added. If there 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.
+ /// Set this object's data to be a subset of the data bytes in \a data. If
+ /// \a data contains shared data, then a reference to the shared data will
+ /// be added to ensure the shared data stays around as long as any objects
+ /// have references to the shared data. The byte order and the address size
+ /// settings are copied from \a data. If \a offset is not a valid offset in
+ /// \a data, then no reference to the shared data will be added. If there
+ /// 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
/// Another DataExtractor object that contains data.
//------------------------------------------------------------------
/// Adopt a subset of shared data in \a data_sp.
///
- /// Copies the data shared pointer which adds a reference to the
- /// contained in \a data_sp. The shared data reference is reference
- /// counted to ensure the data lives as long as anyone still has a
- /// valid shared pointer to the data in \a data_sp. The byte order
- /// and address byte size settings remain the same. If
- /// \a offset is not a valid offset in \a data_sp, then no reference
- /// to the shared data will be added. If there 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.
+ /// Copies the data shared pointer which adds a reference to the contained
+ /// in \a data_sp. The shared data reference is reference counted to ensure
+ /// the data lives as long as anyone still has a valid shared pointer to the
+ /// data in \a data_sp. The byte order and address byte size settings remain
+ /// the same. If \a offset is not a valid offset in \a data_sp, then no
+ /// reference to the shared data will be added. If there 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_sp
/// A shared pointer to data.
//------------------------------------------------------------------
/// Set the byte_order value.
///
- /// Sets the byte order of the data to extract. Extracted values
- /// will be swapped if necessary when decoding.
+ /// Sets the byte order of the data to extract. Extracted values will be
+ /// swapped if necessary when decoding.
///
/// @param[in] byte_order
/// The byte order value to use when extracting data.
//------------------------------------------------------------------
/// Skip an LEB128 number at \a *offset_ptr.
///
- /// Skips a LEB128 number (signed or unsigned) from this object's
- /// data starting at the offset pointed to by \a offset_ptr. The
- /// offset pointed to by \a offset_ptr will be updated with the
- /// offset of the byte following the last extracted byte.
+ /// Skips a LEB128 number (signed or unsigned) from this object's data
+ /// starting at the offset pointed to by \a offset_ptr. The offset pointed
+ /// to by \a offset_ptr will be updated with the offset of the byte
+ /// following the last extracted byte.
///
/// @param[in,out] offset_ptr
/// A pointer to an offset within the data that will be advanced
//----------------------------------------------------------------------
/// @class FileSpec FileSpec.h "lldb/Host/FileSpec.h"
-/// @brief A file utility class.
+/// A file utility class.
///
/// A file specification class that divides paths up into a directory
-/// and basename. These string values of the paths are put into uniqued
-/// string pools for fast comparisons and efficient memory usage.
+/// and basename. These string values of the paths are put into uniqued string
+/// pools for fast comparisons and efficient memory usage.
///
-/// Another reason the paths are split into the directory and basename
-/// is to allow efficient debugger searching. Often in a debugger the
-/// user types in the basename of the file, for example setting a
-/// breakpoint by file and line, or specifying a module (shared library)
-/// to limit the scope in which to execute a command. The user rarely
-/// types in a full path. When the paths are already split up, it makes
-/// it easy for us to compare only the basenames of a lot of file
-/// specifications without having to split up the file path each time
-/// to get to the basename.
+/// Another reason the paths are split into the directory and basename is to
+/// allow efficient debugger searching. Often in a debugger the user types in
+/// the basename of the file, for example setting a breakpoint by file and
+/// line, or specifying a module (shared library) to limit the scope in which
+/// to execute a command. The user rarely types in a full path. When the paths
+/// are already split up, it makes it easy for us to compare only the
+/// basenames of a lot of file specifications without having to split up the
+/// file path each time to get to the basename.
//----------------------------------------------------------------------
class FileSpec {
public:
//------------------------------------------------------------------
/// Constructor with path.
///
- /// Takes a path to a file which can be just a filename, or a full
- /// path. If \a path is not nullptr or empty, this function will call
+ /// Takes a path to a file which can be just a filename, or a full path. If
+ /// \a path is not nullptr or empty, this function will call
/// FileSpec::SetFile (const char *path, bool resolve).
///
/// @param[in] path
//------------------------------------------------------------------
/// Copy constructor
///
- /// Makes a copy of the uniqued directory and filename strings from
- /// \a rhs.
+ /// Makes a copy of the uniqued directory and filename strings from \a rhs.
///
/// @param[in] rhs
/// A const FileSpec object reference to copy.
//------------------------------------------------------------------
/// Copy constructor
///
- /// Makes a copy of the uniqued directory and filename strings from
- /// \a rhs if it is not nullptr.
+ /// Makes a copy of the uniqued directory and filename strings from \a rhs
+ /// if it is not nullptr.
///
/// @param[in] rhs
/// A const FileSpec object pointer to copy if non-nullptr.
//------------------------------------------------------------------
/// Assignment operator.
///
- /// Makes a copy of the uniqued directory and filename strings from
- /// \a rhs.
+ /// Makes a copy of the uniqued directory and filename strings from \a rhs.
///
/// @param[in] rhs
/// A const FileSpec object reference to assign to this object.
//------------------------------------------------------------------
/// Convert to pointer operator.
///
- /// This allows code to check a FileSpec object to see if it
- /// contains anything valid using code such as:
+ /// This allows code to check a FileSpec object to see if it contains
+ /// anything valid using code such as:
///
/// @code
/// FileSpec file_spec(...);
//------------------------------------------------------------------
/// Logical NOT operator.
///
- /// This allows code to check a FileSpec object to see if it is
- /// invalid using code such as:
+ /// This allows code to check a FileSpec object to see if it is invalid
+ /// using code such as:
///
/// @code
/// FileSpec file_spec(...);
//------------------------------------------------------------------
/// Clears the object state.
///
- /// Clear this object by releasing both the directory and filename
- /// string values and reverting them to empty strings.
+ /// Clear this object by releasing both the directory and filename string
+ /// values and reverting them to empty strings.
//------------------------------------------------------------------
void Clear();
//------------------------------------------------------------------
/// Compare two FileSpec objects.
///
- /// If \a full is true, then both the directory and the filename
- /// must match. If \a full is false, then the directory names for
- /// \a lhs and \a rhs are only compared if they are both not empty.
- /// This allows a FileSpec object to only contain a filename
- /// and it can match FileSpec objects that have matching
- /// filenames with different paths.
+ /// If \a full is true, then both the directory and the filename must match.
+ /// If \a full is false, then the directory names for \a lhs and \a rhs are
+ /// only compared if they are both not empty. This allows a FileSpec object
+ /// to only contain a filename and it can match FileSpec objects that have
+ /// matching filenames with different paths.
///
/// @param[in] lhs
/// A const reference to the Left Hand Side object to compare.
//------------------------------------------------------------------
/// Dump this object to a Stream.
///
- /// Dump the object to the supplied stream \a s. If the object
- /// contains a valid directory name, it will be displayed followed
- /// by a directory delimiter, and the filename.
+ /// Dump the object to the supplied stream \a s. If the object contains a
+ /// valid directory name, it will be displayed followed by a directory
+ /// delimiter, and the filename.
///
/// @param[in] s
/// The stream to which to dump the object description.
/// Call into the Host to see if it can help find the file (e.g. by
/// searching paths set in the environment, etc.).
///
- /// If found, sets the value of m_directory to the directory where
- /// the file was found.
+ /// If found, sets the value of m_directory to the directory where the file
+ /// was found.
///
/// @return
/// \b true if was able to find the file using expanded search
//------------------------------------------------------------------
/// Canonicalize this file path (basically running the static
- /// FileSpec::Resolve method on it). Useful if you asked us not to
- /// resolve the file path when you set the file.
+ /// FileSpec::Resolve method on it). Useful if you asked us not to resolve
+ /// the file path when you set the file.
//------------------------------------------------------------------
bool ResolvePath();
const ConstString &GetFilename() const;
//------------------------------------------------------------------
- /// Returns true if the filespec represents an implementation source
- /// file (files with a ".c", ".cpp", ".m", ".mm" (many more)
- /// extension).
+ /// Returns true if the filespec represents an implementation source file
+ /// (files with a ".c", ".cpp", ".m", ".mm" (many more) extension).
///
/// @return
/// \b true if the filespec represents an implementation source
//------------------------------------------------------------------
/// Extract the full path to the file.
///
- /// Extract the directory and path into a fixed buffer. This is
- /// needed as the directory and path are stored in separate string
- /// values.
+ /// 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
/// The buffer in which to place the extracted full path.
//------------------------------------------------------------------
/// Extract the extension of the file.
///
- /// Returns a ConstString that represents the extension of the filename
- /// for this FileSpec object. If this object does not represent a file,
- /// or the filename has no extension, ConstString(nullptr) is returned.
- /// The dot ('.') character is not returned as part of the extension
+ /// Returns a ConstString that represents the extension of the filename for
+ /// this FileSpec object. If this object does not represent a file, or the
+ /// filename has no extension, ConstString(nullptr) is returned. The dot
+ /// ('.') character is not returned as part of the extension
///
/// @return
/// Returns the extension of the file as a ConstString object.
/// Return the filename without the extension part
///
/// Returns a ConstString that represents the filename of this object
- /// without the extension part (e.g. for a file named "foo.bar", "foo"
- /// is returned)
+ /// without the extension part (e.g. for a file named "foo.bar", "foo" is
+ /// returned)
///
/// @return
/// Returns the filename without extension
//------------------------------------------------------------------
/// Return the current permissions of the path.
///
- /// Returns a bitmask for the current permissions of the file
- /// ( zero or more of the permission bits defined in
- /// File::Permissions).
+ /// Returns a bitmask for the current permissions of the file ( zero or more
+ /// of the permission bits defined in File::Permissions).
///
/// @return
/// Zero if the file doesn't exist or we are unable to get
//------------------------------------------------------------------
/// Get the memory cost of this object.
///
- /// Return the size in bytes that this object takes in memory. This
- /// returns the size in bytes of this object, not any shared string
- /// values it may refer to.
+ /// Return the size in bytes that this object takes in memory. This returns
+ /// the size in bytes of this object, not any shared string values it may
+ /// refer to.
///
/// @return
/// The number of bytes that this object occupies in memory.
//------------------------------------------------------------------
/// Change the file specified with a new path.
///
- /// Update the contents of this object with a new path. The path will
- /// be split up into a directory and filename and stored as uniqued
- /// string values for quick comparison and efficient memory usage.
+ /// Update the contents of this object with a new path. The path will be
+ /// split up into a directory and filename and stored as uniqued string
+ /// values for quick comparison and efficient memory usage.
///
/// @param[in] path
/// A full, partial, or relative path to a file.
//------------------------------------------------------------------
/// Set if the file path has been resolved or not.
///
- /// If you know a file path is already resolved and avoided passing
- /// a \b true parameter for any functions that take a "bool
- /// resolve_path" parameter, you can set the value manually using
- /// this call to make sure we don't try and resolve it later, or try
- /// and resolve a path that has already been resolved.
+ /// If you know a file path is already resolved and avoided passing a \b
+ /// true parameter for any functions that take a "bool resolve_path"
+ /// parameter, you can set the value manually using this call to make sure
+ /// we don't try and resolve it later, or try and resolve a path that has
+ /// already been resolved.
///
/// @param[in] is_resolved
/// A boolean value that will replace the current value that
//----------------------------------------------------------------------
/// @class Flags Flags.h "lldb/Utility/Flags.h"
-/// @brief A class to manage flags.
+/// A class to manage flags.
///
-/// The Flags class managed flag bits and allows testing and
-/// modification of individual or multiple flag bits.
+/// The Flags class managed flag bits and allows testing and modification of
+/// individual or multiple flag bits.
//----------------------------------------------------------------------
class Flags {
public:
//----------------------------------------------------------------------
/// Construct with initial flag bit values.
///
- /// Constructs this object with \a mask as the initial value for all
- /// of the flags.
+ /// Constructs this object with \a mask as the initial value for all of the
+ /// flags.
///
/// @param[in] mask
/// The initial value for all flags.
ValueType Get() const { return m_flags; }
//----------------------------------------------------------------------
- /// Return the number of flags that can be represented in this
- /// object.
+ /// Return the number of flags that can be represented in this object.
///
/// @return
/// The maximum number bits in this flag object.
}
//----------------------------------------------------------------------
- /// Set one or more flags by logical OR'ing \a mask with the current
- /// flags.
+ /// Set one or more flags by logical OR'ing \a mask with the current flags.
///
/// @param[in] mask
/// A bitfield containing one or more flags.
//----------------------------------------------------------------------
/// @class HistorySource History.h "lldb/Core/History.h"
-/// @brief A class that defines history events.
+/// A class that defines history events.
//----------------------------------------------------------------------
class HistorySource {
//----------------------------------------------------------------------
/// @class HistorySourceUInt History.h "lldb/Core/History.h"
-/// @brief A class that defines history events that are represented by
+/// A class that defines history events that are represented by
/// unsigned integers.
///
-/// Any history event that is defined by a unique monotonically
-/// increasing unsigned integer
+/// Any history event that is defined by a unique monotonically increasing
+/// unsigned integer
//----------------------------------------------------------------------
class HistorySourceUInt : public HistorySource {
//----------------------------------------------------------------------
/// @class RegularExpression RegularExpression.h
/// "lldb/Utility/RegularExpression.h"
-/// @brief A C++ wrapper class for regex.
+/// A C++ wrapper class for regex.
///
-/// This regular expression class wraps the posix regex functions
-/// \c regcomp(), \c regerror(), \c regexec(), and \c regfree() from
-/// the header file in \c /usr/include/regex\.h.
+/// This regular expression class wraps the posix regex functions \c
+/// regcomp(), \c regerror(), \c regexec(), and \c regfree() from the header
+/// file in \c /usr/include/regex\.h.
//----------------------------------------------------------------------
class RegularExpression {
public:
//------------------------------------------------------------------
/// Default constructor.
///
- /// The default constructor that initializes the object state such
- /// that it contains no compiled regular expression.
+ /// The default constructor that initializes the object state such that it
+ /// contains no compiled regular expression.
//------------------------------------------------------------------
RegularExpression();
//------------------------------------------------------------------
/// Destructor.
///
- /// Any previously compiled regular expression contained in this
- /// object will be freed.
+ /// Any previously compiled regular expression contained in this object will
+ /// be freed.
//------------------------------------------------------------------
~RegularExpression();
//------------------------------------------------------------------
/// Compile a regular expression.
///
- /// Compile a regular expression using the supplied regular
- /// expression text. The compiled regular expression lives
- /// in this object so that it can be readily used for regular
- /// expression matches. Execute() can be called after the regular
- /// expression is compiled. Any previously compiled regular
- /// expression contained in this object will be freed.
+ /// Compile a regular expression using the supplied regular expression text.
+ /// The compiled regular expression lives in this object so that it can be
+ /// readily used for regular expression matches. Execute() can be called
+ /// after the regular expression is compiled. Any previously compiled
+ /// regular expression contained in this object will be freed.
///
/// @param[in] re
/// A NULL terminated C string that represents the regular
//------------------------------------------------------------------
/// Executes a regular expression.
///
- /// Execute a regular expression match using the compiled regular
- /// expression that is already in this object against the match
- /// string \a s. If any parens are used for regular expression
- /// matches \a match_count should indicate the number of regmatch_t
- /// values that are present in \a match_ptr.
+ /// Execute a regular expression match using the compiled regular expression
+ /// that is already in this object against the match string \a s. If any
+ /// parens are used for regular expression matches \a match_count should
+ /// indicate the number of regmatch_t values that are present in \a
+ /// match_ptr.
///
/// @param[in] string
/// The string to match against the compile regular expression.
//------------------------------------------------------------------
/// Free the compiled regular expression.
///
- /// If this object contains a valid compiled regular expression,
- /// this function will free any resources it was consuming.
+ /// If this object contains a valid compiled regular expression, this
+ /// function will free any resources it was consuming.
//------------------------------------------------------------------
void Free();
namespace lldb_private {
//----------------------------------------------------------------------
-/// @class Status Status.h "lldb/Utility/Status.h"
-/// @brief 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 Status::ValueType. This value should be large enough to hold
-/// any and all errors that the class supports. Each error has an
-/// associated type that is of type lldb::ErrorType. New types
-/// can be added to support new error types, and architecture specific
-/// types can be enabled. In the future we may wish to switch to a
-/// registration mechanism where new error types can be registered at
-/// runtime instead of a hard coded scheme.
+/// encountered on a given platform. The errors are stored as a value of type
+/// Status::ValueType. This value should be large enough to hold any and all
+/// errors that the class supports. Each error has an associated type that is
+/// of type lldb::ErrorType. New types can be added to support new error
+/// types, and architecture specific types can be enabled. In the future we
+/// may wish to switch to a registration mechanism where new error types can
+/// be registered at runtime instead of a hard coded scheme.
///
-/// All errors in this class also know how to generate a string
-/// representation of themselves for printing results and error codes.
-/// The string value will be fetched on demand and its string value will
-/// be cached until the error is cleared of the value of the error
-/// changes.
+/// All errors in this class also know how to generate a string representation
+/// of themselves for printing results and error codes. The string value will
+/// be fetched on demand and its string value will be cached until the error
+/// is cleared of the value of the error changes.
//----------------------------------------------------------------------
class Status {
public:
//------------------------------------------------------------------
- /// Every error value that this object can contain needs to be able
- /// to fit into ValueType.
+ /// Every error value that this object can contain needs to be able to fit
+ /// into ValueType.
//------------------------------------------------------------------
typedef uint32_t ValueType;
//------------------------------------------------------------------
/// Get the error string associated with the current error.
//
- /// Gets the error value as a NULL terminated C string. The error
- /// string will be fetched and cached on demand. The error string
- /// will be retrieved from a callback that is appropriate for the
- /// type of the error and will be cached until the error value is
- /// changed or cleared.
+ /// Gets the error value as a NULL terminated C string. The error string
+ /// will be fetched and cached on demand. The error string will be retrieved
+ /// 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
/// The error as a NULL terminated C string value if the error
//------------------------------------------------------------------
/// Clear the object state.
///
- /// Reverts the state of this object to contain a generic success
- /// value and frees any cached error string value.
+ /// Reverts the state of this object to contain a generic success value and
+ /// frees any cached error string value.
//------------------------------------------------------------------
void Clear();
//------------------------------------------------------------------
/// Set accessor from a kern_return_t.
///
- /// Set accesssor for the error value to \a err and the error type
- /// to \c MachKernel.
+ /// Set accesssor for the error value to \a err and the error type to \c
+ /// MachKernel.
///
/// @param[in] err
/// A mach error code.
//------------------------------------------------------------------
/// Set accesssor with an error value and type.
///
- /// Set accesssor for the error value to \a err and the error type
- /// to \a type.
+ /// Set accesssor for the error value to \a err and the error type to \a
+ /// type.
///
/// @param[in] err
/// A mach error code.
//------------------------------------------------------------------
/// Set the current error to errno.
///
- /// Update the error value to be \c errno and update the type to
- /// be \c Status::POSIX.
+ /// Update the error value to be \c errno and update the type to be \c
+ /// Status::POSIX.
//------------------------------------------------------------------
void SetErrorToErrno();
//------------------------------------------------------------------
/// Set the current error to a generic error.
///
- /// Update the error value to be \c LLDB_GENERIC_ERROR and update the
- /// type to be \c Status::Generic.
+ /// Update the error value to be \c LLDB_GENERIC_ERROR and update the type
+ /// to be \c Status::Generic.
//------------------------------------------------------------------
void SetErrorToGenericError();
//------------------------------------------------------------------
/// Set the current error string to \a err_str.
///
- /// Set accessor for the error string value for a generic errors,
- /// or to supply additional details above and beyond the standard
- /// error strings that the standard type callbacks typically
- /// provide. This allows custom strings to be supplied as an
- /// error explanation. The error string value will remain until the
- /// error value is cleared or a new error value/type is assigned.
+ /// Set accessor for the error string value for a generic errors, or to
+ /// supply additional details above and beyond the standard error strings
+ /// that the standard type callbacks typically provide. This allows custom
+ /// strings to be supplied as an error explanation. The error string value
+ /// will remain until the error value is cleared or a new error value/type
+ /// is assigned.
///
/// @param err_str
/// The new custom error string to copy and cache.
//------------------------------------------------------------------
/// Test for success condition.
///
- /// Returns true if the error code in this object is considered a
- /// successful return value.
+ /// Returns true if the error code in this object is considered a successful
+ /// return value.
///
/// @return
/// \b true if this object contains an value that describes
//------------------------------------------------------------------
/// Test for a failure due to a generic interrupt.
///
- /// Returns true if the error code in this object was caused by an interrupt.
- /// At present only supports Posix EINTR.
+ /// Returns true if the error code in this object was caused by an
+ /// interrupt. At present only supports Posix EINTR.
///
/// @return
/// \b true if this object contains an value that describes
//----------------------------------------------------------------------
/// @class Stream Stream.h "lldb/Utility/Stream.h"
-/// @brief A stream class that can stream formatted output to a file.
+/// A stream class that can stream formatted output to a file.
//----------------------------------------------------------------------
class Stream {
public:
//------------------------------------------------------------------
/// Construct with flags and address size and byte order.
///
- /// Construct with dump flags \a flags and the default address
- /// size. \a flags can be any of the above enumeration logical OR'ed
- /// together.
+ /// Construct with dump flags \a flags and the default address size. \a
+ /// flags can be any of the above enumeration logical OR'ed together.
//------------------------------------------------------------------
Stream(uint32_t flags, uint32_t addr_size, lldb::ByteOrder byte_order);
//------------------------------------------------------------------
- /// Construct a default Stream, not binary, host byte order and
- /// host addr size.
+ /// Construct a default Stream, not binary, host byte order and host addr
+ /// size.
///
//------------------------------------------------------------------
Stream();
//------------------------------------------------------------------
/// Flush the stream.
///
- /// Subclasses should flush the stream to make any output appear
- /// if the stream has any buffering.
+ /// Subclasses should flush the stream to make any output appear if the
+ /// stream has any buffering.
//------------------------------------------------------------------
virtual void Flush() = 0;
//------------------------------------------------------------------
/// Output character bytes to the stream.
///
- /// Appends \a src_len characters from the buffer \a src to the
- /// stream.
+ /// Appends \a src_len characters from the buffer \a src to the stream.
///
/// @param[in] src
/// A buffer containing at least \a src_len bytes of data.
//------------------------------------------------------------------
/// Set the byte_order value.
///
- /// Sets the byte order of the data to extract. Extracted values
- /// will be swapped if necessary when decoding.
+ /// Sets the byte order of the data to extract. Extracted values will be
+ /// swapped if necessary when decoding.
///
/// @param[in] byte_order
/// The byte order value to use when extracting data.
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.
+ /// 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
/// A printf style format string.
__attribute__((__format__(__printf__, 2, 3)));
//------------------------------------------------------------------
- /// Format a C string from a printf style format and variable
- /// arguments and encode and append the resulting C string as hex
- /// bytes.
+ /// 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
/// A printf style format string.
//------------------------------------------------------------------
/// Output an address value to this stream.
///
- /// Put an address \a addr out to the stream with optional \a prefix
- /// and \a suffix strings.
+ /// Put an address \a addr out to the stream with optional \a prefix and \a
+ /// suffix strings.
///
/// @param[in] addr
/// An address value.
//------------------------------------------------------------------
/// Output an address range to this stream.
///
- /// Put an address range \a lo_addr - \a hi_addr out to the stream
- /// with optional \a prefix and \a suffix strings.
+ /// 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
/// The start address of the address range.
//------------------------------------------------------------------
/// Indent the current line in the stream.
///
- /// Indent the current line using the current indentation level and
- /// print an optional string following the indentation spaces.
+ /// Indent the current line using the current indentation level and print an
+ /// optional string following the indentation spaces.
///
/// @param[in] s
/// A C string to print following the indentation. If nullptr, just
//------------------------------------------------------------------
/// Output an offset value.
///
- /// Put an offset \a uval out to the stream using the printf format
- /// in \a format.
+ /// Put an offset \a uval out to the stream using the printf format in \a
+ /// format.
///
/// @param[in] offset
/// The offset value.
//------------------------------------------------------------------
/// Output a quoted C string value to the stream.
///
- /// Print a double quoted NULL terminated C string to the stream
- /// using the printf format in \a format.
+ /// Print a double quoted NULL terminated C string to the stream using the
+ /// printf format in \a format.
///
/// @param[in] cstr
/// A NULL terminated C string value.
//------------------------------------------------------------------
/// Output a SLEB128 number to the stream.
///
- /// Put an SLEB128 \a uval out to the stream using the printf format
- /// in \a format.
+ /// Put an SLEB128 \a uval out to the stream using the printf format in \a
+ /// format.
///
/// @param[in] uval
/// A uint64_t value that was extracted as a SLEB128 value.
//------------------------------------------------------------------
/// Output a ULEB128 number to the stream.
///
- /// Put an ULEB128 \a uval out to the stream using the printf format
- /// in \a format.
+ /// Put an ULEB128 \a uval out to the stream using the printf format in \a
+ /// format.
///
/// @param[in] uval
/// A uint64_t value that was extracted as a ULEB128 value.
//----------------------------------------------------------------------
/// @class StructuredData StructuredData.h "lldb/Utility/StructuredData.h"
-/// @brief A class which can hold structured data
+/// A class which can hold structured data
///
-/// The StructuredData class is designed to hold the data from a JSON
-/// or plist style file -- a serialized data structure with dictionaries
-/// (maps, hashes), arrays, and concrete values like integers, floating
-/// point numbers, strings, booleans.
+/// The StructuredData class is designed to hold the data from a JSON or plist
+/// style file -- a serialized data structure with dictionaries (maps,
+/// hashes), arrays, and concrete values like integers, floating point
+/// numbers, strings, booleans.
///
-/// StructuredData does not presuppose any knowledge of the schema for
-/// the data it is holding; it can parse JSON data, for instance, and
-/// other parts of lldb can iterate through the parsed data set to find
-/// keys and values that may be present.
+/// StructuredData does not presuppose any knowledge of the schema for the
+/// data it is holding; it can parse JSON data, for instance, and other parts
+/// of lldb can iterate through the parsed data set to find keys and values
+/// that may be present.
//----------------------------------------------------------------------
class StructuredData {
public:
virtual ~TildeExpressionResolver();
- /// \brief Resolve a Tilde Expression contained according to bash rules.
+ /// Resolve a Tilde Expression contained according to bash rules.
///
/// \param Expr Contains the tilde expression to resolve. A valid tilde
/// expression must begin with a tilde and contain only non
virtual bool ResolveExact(llvm::StringRef Expr,
llvm::SmallVectorImpl<char> &Output) = 0;
- /// \brief Auto-complete a tilde expression with all matching values.
+ /// Auto-complete a tilde expression with all matching values.
///
/// \param Expr Contains the tilde expression prefix to resolve. See
/// ResolveExact() for validity rules.
virtual bool ResolvePartial(llvm::StringRef Expr,
llvm::StringSet<> &Output) = 0;
- /// \brief Resolve an entire path that begins with a tilde expression,
- /// replacing the username portion with the matched result.
+ /// Resolve an entire path that begins with a tilde expression, replacing
+ /// the username portion with the matched result.
bool ResolveFullPath(llvm::StringRef Expr,
llvm::SmallVectorImpl<char> &Output);
};
//----------------------------------------------------------------------
/// @class Timer Timer.h "lldb/Utility/Timer.h"
-/// @brief A timer class that simplifies common timing metrics.
+/// A timer class that simplifies common timing metrics.
//----------------------------------------------------------------------
class Timer {
//----------------------------------------------------------------------
/// @class UserID UserID.h "lldb/Core/UserID.h"
-/// @brief A mix in class that contains a generic user ID.
+/// A mix in class that contains a generic user ID.
///
-/// UserID is designed as a mix in class that can contain an integer
-/// based unique identifier for a variety of objects in lldb.
+/// UserID is designed as a mix in class that can contain an integer based
+/// unique identifier for a variety of objects in lldb.
///
-/// The value for this identifier is chosen by each parser plug-in. A
-/// value should be chosen that makes sense for each kind of object
-/// and should allow quick access to further and more in depth parsing.
+/// The value for this identifier is chosen by each parser plug-in. A value
+/// should be chosen that makes sense for each kind of object and should allow
+/// quick access to further and more in depth parsing.
///
/// Symbol table entries can use this to store the original symbol table
/// index, functions can use it to store the symbol table index or the
void SetID(lldb::user_id_t uid) { m_uid = uid; }
//------------------------------------------------------------------
- /// Unary predicate function object that can search for a matching
- /// user ID.
+ /// Unary predicate function object that can search for a matching user ID.
///
- /// Function object that can be used on any class that inherits
- /// from UserID:
+ /// Function object that can be used on any class that inherits from UserID:
/// \code
/// iterator pos;
/// pos = std::find_if (coll.begin(), coll.end(), UserID::IDMatches(blockID));
#endif
/// \macro LLVM_FALLTHROUGH
-/// \brief Marks an empty statement preceding a deliberate switch fallthrough.
+/// Marks an empty statement preceding a deliberate switch fallthrough.
#if __has_cpp_attribute(clang::fallthrough)
#define LLVM_FALLTHROUGH [[clang::fallthrough]]
#else
//----------------------------------------------------------------------
/// @class Instrumenter IRDynamicChecks.cpp
-/// @brief Finds and instruments individual LLVM IR instructions
+/// Finds and instruments individual LLVM IR instructions
///
-/// When instrumenting LLVM IR, it is frequently desirable to first search
-/// for instructions, and then later modify them. This way iterators
-/// remain intact, and multiple passes can look at the same code base without
+/// When instrumenting LLVM IR, it is frequently desirable to first search for
+/// instructions, and then later modify them. This way iterators remain
+/// intact, and multiple passes can look at the same code base without
/// treading on each other's toes.
///
/// The Instrumenter class implements this functionality. A client first
-/// calls Inspect on a function, which populates a list of instructions to
-/// be instrumented. Then, later, when all passes' Inspect functions have
-/// been called, the client calls Instrument, which adds the desired
+/// calls Inspect on a function, which populates a list of instructions to be
+/// instrumented. Then, later, when all passes' Inspect functions have been
+/// called, the client calls Instrument, which adds the desired
/// instrumentation.
///
/// A subclass of Instrumenter must override InstrumentInstruction, which
}
//------------------------------------------------------------------
- /// Determine whether a single instruction is interesting to
- /// instrument, and, if so, call RegisterInstruction
+ /// Determine whether a single instruction is interesting to instrument,
+ /// and, if so, call RegisterInstruction
///
/// @param[in] i
/// The instruction to be inspected.
}
//------------------------------------------------------------------
- /// Build a function pointer for a function with signature
- /// void (*)(uint8_t*) with a given address
+ /// Build a function pointer for a function with signature void
+ /// (*)(uint8_t*) with a given address
///
/// @param[in] start_address
/// The address of the function.
}
//------------------------------------------------------------------
- /// Build a function pointer for a function with signature
- /// void (*)(uint8_t*, uint8_t*) with a given address
+ /// Build a function pointer for a function with signature void
+ /// (*)(uint8_t*, uint8_t*) with a given address
///
/// @param[in] start_address
/// The address of the function.
}
/// @class HexagonDYLDRendezvous
-/// @brief Interface to the runtime linker.
+/// Interface to the runtime linker.
///
/// A structure is present in a processes memory space which is updated by the
-/// runtime liker each time a module is loaded or unloaded. This class provides
-/// an interface to this structure and maintains a consistent snapshot of the
-/// currently loaded modules.
+/// runtime liker each time a module is loaded or unloaded. This class
+/// provides an interface to this structure and maintains a consistent
+/// snapshot of the currently loaded modules.
class HexagonDYLDRendezvous {
// This structure is used to hold the contents of the debug rendezvous
void DumpToLog(lldb_private::Log *log) const;
- /// @brief Constants describing the state of the rendezvous.
+ /// Constants describing the state of the rendezvous.
///
/// @see GetState().
enum RendezvousState {
eDelete,
};
- /// @brief Structure representing the shared objects currently loaded into
- /// the inferior process.
+ /// Structure representing the shared objects currently loaded into the
+ /// inferior process.
///
/// This object is a rough analogue to the struct link_map object which
/// actually lives in the inferiors memory.
/// List of SOEntry objects corresponding to the current link map state.
SOEntryList m_soentries;
- /// List of SOEntry's added to the link map since the last call to Resolve().
+ /// List of SOEntry's added to the link map since the last call to
+ /// Resolve().
SOEntryList m_added_soentries;
/// List of SOEntry's removed from the link map since the last call to
}
/// @class AuxVector
-/// @brief Represents a processes auxiliary vector.
+/// Represents a processes auxiliary vector.
///
/// When a process is loaded on Linux a vector of values is placed onto the
-/// stack communicating operating system specific information. On construction
-/// this class locates and parses this information and provides a simple
-/// read-only interface to the entries found.
+/// stack communicating operating system specific information. On
+/// construction this class locates and parses this information and provides a
+/// simple read-only interface to the entries found.
class AuxVector {
public:
};
/// Constants describing the type of entry.
- /// On Linux, running "LD_SHOW_AUXV=1 ./executable" will spew AUX information.
- /// Added AUXV prefix to avoid potential conflicts with system-defined macros
+ /// On Linux, running "LD_SHOW_AUXV=1 ./executable" will spew AUX
+ /// information. Added AUXV prefix to avoid potential conflicts with system-
+ /// defined macros
enum EntryType {
AUXV_AT_NULL = 0, ///< End of auxv.
AUXV_AT_IGNORE = 1, ///< Ignore entry.
}
/// @class DYLDRendezvous
-/// @brief Interface to the runtime linker.
+/// Interface to the runtime linker.
///
/// A structure is present in a processes memory space which is updated by the
-/// runtime liker each time a module is loaded or unloaded. This class provides
-/// an interface to this structure and maintains a consistent snapshot of the
-/// currently loaded modules.
+/// runtime liker each time a module is loaded or unloaded. This class
+/// provides an interface to this structure and maintains a consistent
+/// snapshot of the currently loaded modules.
class DYLDRendezvous {
// This structure is used to hold the contents of the debug rendezvous
void DumpToLog(lldb_private::Log *log) const;
- /// @brief Constants describing the state of the rendezvous.
+ /// Constants describing the state of the rendezvous.
///
/// @see GetState().
enum RendezvousState { eConsistent, eAdd, eDelete };
- /// @brief Structure representing the shared objects currently loaded into
- /// the inferior process.
+ /// Structure representing the shared objects currently loaded into the
+ /// inferior process.
///
/// This object is a rough analogue to the struct link_map object which
/// actually lives in the inferiors memory.
/// List of SOEntry objects corresponding to the current link map state.
SOEntryList m_soentries;
- /// List of SOEntry's added to the link map since the last call to Resolve().
+ /// List of SOEntry's added to the link map since the last call to
+ /// Resolve().
SOEntryList m_added_soentries;
/// List of SOEntry's removed from the link map since the last call to
//----------------------------------------------------------------------
/// @class ASTResultSynthesizer ASTResultSynthesizer.h
-/// "lldb/Expression/ASTResultSynthesizer.h"
-/// @brief Adds a result variable declaration to the ASTs for an expression.
+/// "lldb/Expression/ASTResultSynthesizer.h" Adds a result variable
+/// declaration to the ASTs for an expression.
///
/// Users expect the expression "i + 3" to return a result, even if a result
/// variable wasn't specifically declared. To fulfil this requirement, LLDB
-/// adds
-/// a result variable to the expression, transforming it to
-/// "int $__lldb_expr_result = i + 3." The IR transformers ensure that the
+/// adds a result variable to the expression, transforming it to "int
+/// $__lldb_expr_result = i + 3." The IR transformers ensure that the
/// resulting variable is mapped to the right piece of memory.
-/// ASTResultSynthesizer's job is to add the variable and its initialization to
-/// the ASTs for the expression, and it does so by acting as a SemaConsumer for
-/// Clang.
+/// ASTResultSynthesizer's job is to add the variable and its initialization
+/// to the ASTs for the expression, and it does so by acting as a SemaConsumer
+/// for Clang.
//----------------------------------------------------------------------
class ASTResultSynthesizer : public clang::SemaConsumer {
public:
void Initialize(clang::ASTContext &Context) override;
//----------------------------------------------------------------------
- /// Examine a list of Decls to find the function $__lldb_expr and
- /// transform its code
+ /// Examine a list of Decls to find the function $__lldb_expr and transform
+ /// its code
///
/// @param[in] D
/// The list of Decls to search. These may contain LinkageSpecDecls,
private:
//----------------------------------------------------------------------
- /// Hunt the given Decl for FunctionDecls named $__lldb_expr, recursing
- /// as necessary through LinkageSpecDecls, and calling SynthesizeResult on
+ /// Hunt the given Decl for FunctionDecls named $__lldb_expr, recursing as
+ /// necessary through LinkageSpecDecls, and calling SynthesizeResult on
/// anything that was found
///
/// @param[in] D
bool SynthesizeBodyResult(clang::CompoundStmt *Body, clang::DeclContext *DC);
//----------------------------------------------------------------------
- /// Given a DeclContext for a function or method, find all types
- /// declared in the context and record any persistent types found.
+ /// Given a DeclContext for a function or method, find all types declared in
+ /// the context and record any persistent types found.
///
/// @param[in] FunDeclCtx
/// The context for the function to process.
void RecordPersistentTypes(clang::DeclContext *FunDeclCtx);
//----------------------------------------------------------------------
- /// Given a TypeDecl, if it declares a type whose name starts with a
- /// dollar sign, register it as a pointer type in the target's scratch
+ /// Given a TypeDecl, if it declares a type whose name starts with a dollar
+ /// sign, register it as a pointer type in the target's scratch
/// AST context.
///
/// @param[in] Body
//----------------------------------------------------------------------
/// @class ASTStructExtractor ASTStructExtractor.h
-/// "lldb/Expression/ASTStructExtractor.h"
-/// @brief Extracts and describes the argument structure for a wrapped function.
+/// "lldb/Expression/ASTStructExtractor.h" Extracts and describes the argument
+/// structure for a wrapped function.
///
/// This pass integrates with ClangFunctionCaller, which calls functions with
-/// custom
-/// sets of arguments. To avoid having to implement the full calling convention
-/// for the target's architecture, ClangFunctionCaller writes a simple wrapper
-/// function that takes a pointer to an argument structure that contains room
-/// for the address of the function to be called, the values of all its
-/// arguments, and room for the function's return value.
+/// custom sets of arguments. To avoid having to implement the full calling
+/// convention for the target's architecture, ClangFunctionCaller writes a
+/// simple wrapper function that takes a pointer to an argument structure that
+/// contains room for the address of the function to be called, the values of
+/// all its arguments, and room for the function's return value.
///
-/// The definition of this struct is itself in the body of the wrapper function,
-/// so Clang does the structure layout itself. ASTStructExtractor reads through
-/// the AST for the wrapper function and finds the struct.
+/// The definition of this struct is itself in the body of the wrapper
+/// function, so Clang does the structure layout itself. ASTStructExtractor
+/// reads through the AST for the wrapper function and finds the struct.
//----------------------------------------------------------------------
class ASTStructExtractor : public clang::SemaConsumer {
public:
void Initialize(clang::ASTContext &Context) override;
//----------------------------------------------------------------------
- /// Examine a list of Decls to find the function $__lldb_expr and
- /// transform its code
+ /// Examine a list of Decls to find the function $__lldb_expr and transform
+ /// its code
///
/// @param[in] D
/// The list of Decls to search. These may contain LinkageSpecDecls,
//----------------------------------------------------------------------
/// @class ClangASTSource ClangASTSource.h "lldb/Expression/ClangASTSource.h"
-/// @brief Provider for named objects defined in the debug info for Clang
+/// Provider for named objects defined in the debug info for Clang
///
-/// As Clang parses an expression, it may encounter names that are not
-/// defined inside the expression, including variables, functions, and
-/// types. Clang knows the name it is looking for, but nothing else.
-/// The ExternalSemaSource class provides Decls (VarDecl, FunDecl, TypeDecl)
-/// to Clang for these names, consulting the ClangExpressionDeclMap to do
-/// the actual lookups.
+/// As Clang parses an expression, it may encounter names that are not defined
+/// inside the expression, including variables, functions, and types. Clang
+/// knows the name it is looking for, but nothing else. The ExternalSemaSource
+/// class provides Decls (VarDecl, FunDecl, TypeDecl) to Clang for these
+/// names, consulting the ClangExpressionDeclMap to do the actual lookups.
//----------------------------------------------------------------------
class ClangASTSource : public ClangExternalASTSourceCommon,
public ClangASTImporter::MapCompleter {
//------------------------------------------------------------------
/// Look up all Decls that match a particular name. Only handles
/// Identifiers and DeclContexts that are either NamespaceDecls or
- /// TranslationUnitDecls. Calls SetExternalVisibleDeclsForName with
- /// the result.
+ /// TranslationUnitDecls. Calls SetExternalVisibleDeclsForName with the
+ /// result.
///
/// The work for this function is done by
/// void FindExternalVisibleDecls (NameSearchContext &);
//------------------------------------------------------------------
/// Called on entering a translation unit. Tells Clang by calling
- /// setHasExternalVisibleStorage() and setHasExternalLexicalStorage()
- /// that this object has something to say about undefined names.
+ /// setHasExternalVisibleStorage() and setHasExternalLexicalStorage() that
+ /// this object has something to say about undefined names.
///
/// @param[in] ASTConsumer
/// Unused.
//
//------------------------------------------------------------------
- /// Look up the modules containing a given namespace and put the
- /// appropriate entries in the namespace map.
+ /// Look up the modules containing a given namespace and put the appropriate
+ /// entries in the namespace map.
///
/// @param[in] namespace_map
/// The map to be completed.
//----------------------------------------------------------------------
/// @class ClangASTSourceProxy ClangASTSource.h
- /// "lldb/Expression/ClangASTSource.h"
- /// @brief Proxy for ClangASTSource
+ /// "lldb/Expression/ClangASTSource.h" Proxy for ClangASTSource
///
- /// Clang AST contexts like to own their AST sources, so this is a
- /// state-free proxy object.
+ /// Clang AST contexts like to own their AST sources, so this is a state-
+ /// free proxy object.
//----------------------------------------------------------------------
class ClangASTSourceProxy : public ClangExternalASTSourceCommon {
public:
protected:
//------------------------------------------------------------------
- /// Look for the complete version of an Objective-C interface, and
- /// return it if found.
+ /// Look for the complete version of an Objective-C interface, and return it
+ /// if found.
///
/// @param[in] interface_decl
/// An ObjCInterfaceDecl that may not be the complete one.
GetCompleteObjCInterface(const clang::ObjCInterfaceDecl *interface_decl);
//------------------------------------------------------------------
- /// Find all entities matching a given name in a given module,
- /// using a NameSearchContext to make Decls for them.
+ /// Find all entities matching a given name in a given module, using a
+ /// NameSearchContext to make Decls for them.
///
/// @param[in] context
/// The NameSearchContext that can construct Decls for this name.
};
//----------------------------------------------------------------------
-/// @class NameSearchContext ClangASTSource.h "lldb/Expression/ClangASTSource.h"
-/// @brief Container for all objects relevant to a single name lookup
+/// @class NameSearchContext ClangASTSource.h
+/// "lldb/Expression/ClangASTSource.h" Container for all objects relevant to a
+/// single name lookup
///
/// LLDB needs to create Decls for entities it finds. This class communicates
/// what name is being searched for and provides helper functions to construct
}
//------------------------------------------------------------------
- /// Create a VarDecl with the name being searched for and the provided
- /// type and register it in the right places.
+ /// Create a VarDecl with the name being searched for and the provided type
+ /// and register it in the right places.
///
/// @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.
+ /// Create a FunDecl with the name being searched for and the provided type
+ /// and register it in the right places.
///
/// @param[in] type
/// The opaque QualType for the FunDecl being registered.
clang::NamedDecl *AddFunDecl(const CompilerType &type, bool extern_c = false);
//------------------------------------------------------------------
- /// Create a FunDecl with the name being searched for and generic
- /// type (i.e. intptr_t NAME_GOES_HERE(...)) and register it in the
- /// right places.
+ /// Create a FunDecl with the name being searched for and generic type (i.e.
+ /// intptr_t NAME_GOES_HERE(...)) and register it in the right places.
//------------------------------------------------------------------
clang::NamedDecl *AddGenericFunDecl();
//------------------------------------------------------------------
- /// Create a TypeDecl with the name being searched for and the provided
- /// type and register it in the right places.
+ /// Create a TypeDecl with the name being searched for and the provided type
+ /// and register it in the right places.
///
/// @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.
+ /// Add Decls from the provided DeclContextLookupResult to the list of
+ /// results.
///
/// @param[in] result
/// The DeclContextLookupResult, usually returned as the result
//----------------------------------------------------------------------
/// @class ClangExpressionDeclMap ClangExpressionDeclMap.h
-/// "lldb/Expression/ClangExpressionDeclMap.h"
-/// @brief Manages named entities that are defined in LLDB's debug information.
+/// "lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are
+/// defined in LLDB's debug information.
///
/// The Clang parser uses the ClangASTSource as an interface to request named
/// entities from outside an expression. The ClangASTSource reports back,
-/// listing
-/// all possible objects corresponding to a particular name. But it in turn
-/// relies on ClangExpressionDeclMap, which performs several important
+/// listing all possible objects corresponding to a particular name. But it
+/// in turn relies on ClangExpressionDeclMap, which performs several important
/// functions.
///
-/// First, it records what variables and functions were looked up and what Decls
-/// were returned for them.
+/// First, it records what variables and functions were looked up and what
+/// Decls were returned for them.
///
/// Second, it constructs a struct on behalf of IRForTarget, recording which
-/// variables should be placed where and relaying this information back so that
-/// IRForTarget can generate context-independent code.
+/// variables should be placed where and relaying this information back so
+/// that IRForTarget can generate context-independent code.
///
/// Third, it "materializes" this struct on behalf of the expression command,
/// finding the current values of each variable and placing them into the
/// struct so that it can be passed to the JITted version of the IR.
///
-/// Fourth and finally, it "dematerializes" the struct after the JITted code has
-/// has executed, placing the new values back where it found the old ones.
+/// Fourth and finally, it "dematerializes" the struct after the JITted code
+/// has has executed, placing the new values back where it found the old ones.
//----------------------------------------------------------------------
class ClangExpressionDeclMap : public ClangASTSource {
public:
lldb::offset_t alignment);
//------------------------------------------------------------------
- /// [Used by IRForTarget] Finalize the struct, laying out the position
- /// of each object in it.
+ /// [Used by IRForTarget] Finalize the struct, laying out the position of
+ /// each object in it.
///
/// @return
/// True on success; false otherwise.
bool DoStructLayout();
//------------------------------------------------------------------
- /// [Used by IRForTarget] Get general information about the laid-out
- /// struct after DoStructLayout() has been called.
+ /// [Used by IRForTarget] Get general information about the laid-out struct
+ /// after DoStructLayout() has been called.
///
/// @param[out] num_elements
/// The number of elements in the struct.
lldb::offset_t &alignment);
//------------------------------------------------------------------
- /// [Used by IRForTarget] Get specific information about one field
- /// of the laid-out struct after DoStructLayout() has been called.
+ /// [Used by IRForTarget] Get specific information about one field of the
+ /// laid-out struct after DoStructLayout() has been called.
///
/// @param[out] decl
/// The parsed Decl for the field, as generated by ClangASTSource
uint32_t index);
//------------------------------------------------------------------
- /// [Used by IRForTarget] Get information about a function given its
- /// Decl.
+ /// [Used by IRForTarget] Get information about a function given its Decl.
///
/// @param[in] decl
/// The parsed Decl for the Function, as generated by ClangASTSource
bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr);
//------------------------------------------------------------------
- /// [Used by IRForTarget] Get the address of a symbol given nothing
- /// but its name.
+ /// [Used by IRForTarget] Get the address of a symbol given nothing but its
+ /// name.
///
/// @param[in] target
/// The target to find the symbol in. If not provided,
TargetInfo GetTargetInfo();
//------------------------------------------------------------------
- /// [Used by ClangASTSource] Find all entities matching a given name,
- /// using a NameSearchContext to make Decls for them.
+ /// [Used by ClangASTSource] Find all entities matching a given name, using
+ /// a NameSearchContext to make Decls for them.
///
/// @param[in] context
/// The NameSearchContext that can construct Decls for this name.
void DisableStructVars() { m_struct_vars.reset(); }
//----------------------------------------------------------------------
- /// Get this parser's ID for use in extracting parser- and JIT-specific
- /// data from persistent variables.
+ /// Get this parser's ID for use in extracting parser- and JIT-specific data
+ /// from persistent variables.
//----------------------------------------------------------------------
uint64_t GetParserID() { return (uint64_t) this; }
//------------------------------------------------------------------
- /// Given a target, find a variable that matches the given name and
- /// type.
+ /// Given a target, find a variable that matches the given name and type.
///
/// @param[in] target
/// The target to use as a basis for finding the variable.
TypeFromUser *type = NULL);
//------------------------------------------------------------------
- /// Get the value of a variable in a given execution context and return
- /// the associated Types if needed.
+ /// Get the value of a variable in a given execution context and return the
+ /// associated Types if needed.
///
/// @param[in] var
/// The variable to evaluate.
lldb::ValueObjectSP valobj, unsigned int current_id);
//------------------------------------------------------------------
- /// Use the NameSearchContext to generate a Decl for the given
- /// persistent variable, and put it in the list of found entities.
+ /// Use the NameSearchContext to generate a Decl for the given persistent
+ /// variable, and put it in the list of found entities.
///
/// @param[in] context
/// The NameSearchContext to use when constructing the Decl.
unsigned int current_id);
//------------------------------------------------------------------
- /// 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.
+ /// 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
/// The NameSearchContext to use when constructing the Decl.
unsigned int current_id);
//------------------------------------------------------------------
- /// Use the NameSearchContext to generate a Decl for the given
- /// function. (Functions are not placed in the Tuple list.) Can
- /// handle both fully typed functions and generic functions.
+ /// Use the NameSearchContext to generate a Decl for the given function.
+ /// (Functions are not placed in the Tuple list.) Can handle both fully
+ /// typed functions and generic functions.
///
/// @param[in] context
/// The NameSearchContext to use when constructing the Decl.
unsigned int current_id);
//------------------------------------------------------------------
- /// Use the NameSearchContext to generate a Decl for the given
- /// register.
+ /// Use the NameSearchContext to generate a Decl for the given register.
///
/// @param[in] context
/// The NameSearchContext to use when constructing the Decl.
unsigned int current_id);
//------------------------------------------------------------------
- /// Use the NameSearchContext to generate a Decl for the given
- /// type. (Types are not placed in the Tuple list.)
+ /// Use the NameSearchContext to generate a Decl for the given type. (Types
+ /// are not placed in the Tuple list.)
///
/// @param[in] context
/// The NameSearchContext to use when constructing the Decl.
unsigned int current_id);
//------------------------------------------------------------------
- /// Generate a Decl for "*this" and add a member function declaration
- /// to it for the expression, then report it.
+ /// Generate a Decl for "*this" and add a member function declaration to it
+ /// for the expression, then report it.
///
/// @param[in] context
/// The NameSearchContext to use when constructing the Decl.
//----------------------------------------------------------------------
/// @class ClangExpressionParser ClangExpressionParser.h
-/// "lldb/Expression/ClangExpressionParser.h"
-/// @brief Encapsulates an instance of Clang that can parse expressions.
+/// "lldb/Expression/ClangExpressionParser.h" Encapsulates an instance of
+/// Clang that can parse expressions.
///
/// ClangExpressionParser is responsible for preparing an instance of
/// ClangExpression for execution. ClangExpressionParser uses ClangExpression
/// as a glorified parameter list, performing the required parsing and
-/// conversion to formats (DWARF bytecode, or JIT compiled machine code)
-/// that can be executed.
+/// conversion to formats (DWARF bytecode, or JIT compiled machine code) that
+/// can be executed.
//----------------------------------------------------------------------
class ClangExpressionParser : public ExpressionParser {
public:
~ClangExpressionParser() override;
//------------------------------------------------------------------
- /// Parse a single expression and convert it to IR using Clang. Don't
- /// wrap the expression in anything at all.
+ /// Parse a single expression and convert it to IR using Clang. Don't wrap
+ /// the expression in anything at all.
///
/// @param[in] diagnostic_manager
/// The diagnostic manager to report errors to.
bool RewriteExpression(DiagnosticManager &diagnostic_manager) override;
//------------------------------------------------------------------
- /// Ready an already-parsed expression for execution, possibly
- /// evaluating it statically.
+ /// Ready an already-parsed expression for execution, possibly evaluating it
+ /// statically.
///
/// @param[out] func_addr
/// The address to which the function has been written.
//----------------------------------------------------------------------
/// @class ClangExpressionVariable ClangExpressionVariable.h
-/// "lldb/Expression/ClangExpressionVariable.h"
-/// @brief Encapsulates one variable for the expression parser.
+/// "lldb/Expression/ClangExpressionVariable.h" Encapsulates one variable for
+/// the expression parser.
///
/// The expression parser uses variables in three different contexts:
///
-/// First, it stores persistent variables along with the process for use
-/// in expressions. These persistent variables contain their own data
-/// and are typed.
+/// First, it stores persistent variables along with the process for use in
+/// expressions. These persistent variables contain their own data and are
+/// typed.
///
-/// Second, in an interpreted expression, it stores the local variables
-/// for the expression along with the expression. These variables
-/// contain their own data and are typed.
+/// Second, in an interpreted expression, it stores the local variables for
+/// the expression along with the expression. These variables contain their
+/// own data and are typed.
///
-/// Third, in a JIT-compiled expression, it stores the variables that
-/// the expression needs to have materialized and dematerialized at each
-/// execution. These do not contain their own data but are named and
-/// typed.
+/// Third, in a JIT-compiled expression, it stores the variables that the
+/// expression needs to have materialized and dematerialized at each
+/// execution. These do not contain their own data but are named and typed.
///
-/// This class supports all of these use cases using simple type
-/// polymorphism, and provides necessary support methods. Its interface
-/// is RTTI-neutral.
+/// This class supports all of these use cases using simple type polymorphism,
+/// and provides necessary support methods. Its interface is RTTI-neutral.
//----------------------------------------------------------------------
class ClangExpressionVariable : public ExpressionVariable {
public:
lldb::ByteOrder byte_order, uint32_t addr_byte_size);
//----------------------------------------------------------------------
- /// Utility functions for dealing with ExpressionVariableLists in
- /// Clang-specific ways
+ /// Utility functions for dealing with ExpressionVariableLists in Clang-
+ /// specific ways
//----------------------------------------------------------------------
//----------------------------------------------------------------------
}
//----------------------------------------------------------------------
- /// If the variable contains its own data, make a Value point at it.
- /// If \a exe_ctx in not NULL, the value will be resolved in with
- /// that execution context.
+ /// If the variable contains its own data, make a Value point at it. If \a
+ /// exe_ctx in not NULL, the value will be resolved in with that execution
+ /// context.
///
/// @param[in] value
/// The value to point at the data.
public:
//----------------------------------------------------------------------
- /// Make this variable usable by the parser by allocating space for
- /// parser-specific variables
+ /// Make this variable usable by the parser by allocating space for parser-
+ /// specific variables
//----------------------------------------------------------------------
void EnableParserVars(uint64_t parser_id) {
m_parser_vars.insert(std::make_pair(parser_id, ParserVars()));
//----------------------------------------------------------------------
/// @class ClangFunctionCaller ClangFunctionCaller.h
-/// "lldb/Expression/ClangFunctionCaller.h"
-/// @brief Encapsulates a function that can be called.
+/// "lldb/Expression/ClangFunctionCaller.h" Encapsulates a function that can
+/// be called.
///
/// A given ClangFunctionCaller object can handle a single function signature.
/// Once constructed, it can set up any number of concurrent calls to
/// If you need to call the function on the thread plan stack, you can also
/// call InsertFunction() followed by GetThreadPlanToCallFunction().
///
-/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed
-/// a pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated
+/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a
+/// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated
/// and its address returned in that variable.
///
/// Any of the methods that take arg_addr_ptr can be passed NULL, and the
ClangExpressionDeclMap *DeclMap() override { return NULL; }
//------------------------------------------------------------------
- /// Return the object that the parser should allow to access ASTs.
- /// May be NULL if the ASTs do not need to be transformed.
+ /// 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
/// The ASTConsumer that the returned transformer should send
//----------------------------------------------------------------------
/// @class ClangPersistentVariables ClangPersistentVariables.h
-/// "lldb/Expression/ClangPersistentVariables.h"
-/// @brief Manages persistent values that need to be preserved between
-/// expression invocations.
+/// "lldb/Expression/ClangPersistentVariables.h" Manages persistent values
+/// that need to be preserved between expression invocations.
///
/// A list of variables that can be accessed and updated by any expression. See
/// ClangPersistentVariable for more discussion. Also provides an increasing,
//----------------------------------------------------------------------
/// @class ClangUserExpression ClangUserExpression.h
-/// "lldb/Expression/ClangUserExpression.h"
-/// @brief Encapsulates a single expression for use with Clang
+/// "lldb/Expression/ClangUserExpression.h" Encapsulates a single expression
+/// for use with Clang
///
/// LLDB uses expressions for various purposes, notably to call functions
/// and as a backend for the expr command. ClangUserExpression encapsulates
-/// the objects needed to parse and interpret or JIT an expression. It
-/// uses the Clang parser to produce LLVM IR from the expression.
+/// the objects needed to parse and interpret or JIT an expression. It uses
+/// the Clang parser to produce LLVM IR from the expression.
//----------------------------------------------------------------------
class ClangUserExpression : public LLVMUserExpression {
public:
bool keep_result_in_memory);
//------------------------------------------------------------------
- /// Return the object that the parser should allow to access ASTs.
- /// May be NULL if the ASTs do not need to be transformed.
+ /// 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
/// The ASTConsumer that the returned transformer should send
//----------------------------------------------------------------------
/// @class ClangUtilityFunction ClangUtilityFunction.h
-/// "lldb/Expression/ClangUtilityFunction.h"
-/// @brief Encapsulates a single expression for use with Clang
+/// "lldb/Expression/ClangUtilityFunction.h" Encapsulates a single expression
+/// for use with Clang
///
/// LLDB uses expressions for various purposes, notably to call functions
/// and as a backend for the expr command. ClangUtilityFunction encapsulates
/// a self-contained function meant to be used from other code. Utility
/// functions can perform error-checking for ClangUserExpressions, or can
-/// simply provide a way to push a function into the target for the debugger to
-/// call later on.
+/// simply provide a way to push a function into the target for the debugger
+/// to call later on.
//----------------------------------------------------------------------
class ClangUtilityFunction : public UtilityFunction {
public:
void ResetDeclMap(ExecutionContext &exe_ctx, bool keep_result_in_memory);
//------------------------------------------------------------------
- /// Return the object that the parser should allow to access ASTs.
- /// May be NULL if the ASTs do not need to be transformed.
+ /// 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
/// The ASTConsumer that the returned transformer should send
//----------------------------------------------------------------------
/// @class IRForTarget IRForTarget.h "lldb/Expression/IRForTarget.h"
-/// @brief Transforms the IR for a function to run in the target
+/// 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 contexts: interpreted by LLDB as a DWARF location expression,
-/// or compiled by the JIT and inserted into the target process for
-/// execution.
+/// Once an expression has been parsed and converted to IR, it can run in two
+/// contexts: interpreted by LLDB as a DWARF location expression, or compiled
+/// by the JIT and inserted into the target process for execution.
///
/// IRForTarget makes the second possible, by applying a series of
/// transformations to the IR which make it relocatable. These
//------------------------------------------------------------------
/// Interface stub
///
- /// Implementation of the llvm::ModulePass::assignPassManager()
- /// function.
+ /// Implementation of the llvm::ModulePass::assignPassManager() function.
//------------------------------------------------------------------
void assignPassManager(llvm::PMStack &pass_mgr_stack,
llvm::PassManagerType pass_mgr_type =
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// Get the address of a function, and a location to put the complete
- /// Value of the function if one is available.
+ /// Get the address of a function, and a location to put the complete Value
+ /// of the function if one is available.
///
/// @param[in] function
/// The function to find the location of.
//------------------------------------------------------------------
/// A function-level pass to take the generated global value
- /// $__lldb_expr_result and make it into a persistent variable.
- /// Also see ASTResultSynthesizer.
+ /// $__lldb_expr_result and make it into a persistent variable. Also see
+ /// ASTResultSynthesizer.
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// Find the NamedDecl corresponding to a Value. This interface is
- /// exposed for the IR interpreter.
+ /// Find the NamedDecl corresponding to a Value. This interface is exposed
+ /// for the IR interpreter.
///
/// @param[in] module
/// The module containing metadata to search
//------------------------------------------------------------------
/// Set the constant result variable m_const_result to the provided
- /// constant, assuming it can be evaluated. The result variable
- /// will be reset to NULL later if the expression has side effects.
+ /// constant, assuming it can be evaluated. The result variable will be
+ /// reset to NULL later if the expression has side effects.
///
/// @param[in] initializer
/// The constant initializer for the variable.
lldb_private::TypeFromParser type);
//------------------------------------------------------------------
- /// If the IR represents a cast of a variable, set m_const_result
- /// to the result of the cast. The result variable will be reset to
+ /// If the IR represents a cast of a variable, set m_const_result to the
+ /// result of the cast. The result variable will be reset to
/// NULL latger if the expression has side effects.
///
/// @param[in] type
/// rewrite them to use sel_registerName instead of statically allocated
/// selectors. The reason is that the selectors are created on the
/// assumption that the Objective-C runtime will scan the appropriate
- /// section and prepare them. This doesn't happen when code is copied
- /// into the target, though, and there's no easy way to induce the
- /// runtime to scan them. So instead we get our selectors from
- /// sel_registerName.
+ /// section and prepare them. This doesn't happen when code is copied into
+ /// the target, though, and there's no easy way to induce the runtime to
+ /// scan them. So instead we get our selectors from sel_registerName.
//------------------------------------------------------------------
//------------------------------------------------------------------
//------------------------------------------------------------------
/// A basic block-level pass to find all newly-declared persistent
- /// variables and register them with the ClangExprDeclMap. This
- /// allows them to be materialized and dematerialized like normal
- /// external variables. Before transformation, these persistent
- /// variables look like normal locals, so they have an allocation.
- /// This pass excises these allocations and makes references look
- /// like external references where they will be resolved -- like all
- /// other external references -- by ResolveExternals().
+ /// variables and register them with the ClangExprDeclMap. This allows them
+ /// to be materialized and dematerialized like normal external variables.
+ /// Before transformation, these persistent variables look like normal
+ /// locals, so they have an allocation. This pass excises these allocations
+ /// and makes references look like external references where they will be
+ /// resolved -- like all other external references -- by ResolveExternals().
//------------------------------------------------------------------
//------------------------------------------------------------------
//------------------------------------------------------------------
/// A function-level pass to find all external variables and functions
- /// used in the IR. Each found external variable is added to the
- /// struct, and each external function is resolved in place, its call
- /// replaced with a call to a function pointer whose value is the
- /// address of the function in the target process.
+ /// used in the IR. Each found external variable is added to the struct,
+ /// and each external function is resolved in place, its call replaced with
+ /// a call to a function pointer whose value is the address of the function
+ /// in the target process.
//------------------------------------------------------------------
//------------------------------------------------------------------
- /// Write an initializer to a memory array of assumed sufficient
- /// size.
+ /// Write an initializer to a memory array of assumed sufficient size.
///
/// @param[in] data
/// A pointer to the data to write to.
//------------------------------------------------------------------
/// A basic block-level pass to excise guard variables from the code.
/// The result for the function is passed through Clang as a static
- /// variable. Static variables normally have guard variables to
- /// ensure that they are only initialized once.
+ /// variable. Static variables normally have guard variables to ensure that
+ /// they are only initialized once.
//------------------------------------------------------------------
//------------------------------------------------------------------
//------------------------------------------------------------------
/// A function-level pass to make all external variable references
- /// point at the correct offsets from the void* passed into the
- /// function. ClangExpressionDeclMap::DoStructLayout() must be called
- /// beforehand, so that the offsets are valid.
+ /// point at the correct offsets from the void* passed into the function.
+ /// ClangExpressionDeclMap::DoStructLayout() must be called beforehand, so
+ /// that the offsets are valid.
//------------------------------------------------------------------
//------------------------------------------------------------------
llvm::StoreInst *m_result_store; ///< If non-NULL, the store instruction that
///writes to the result variable. If
- /// m_has_side_effects is true, this is NULL.
+ /// m_has_side_effects is true, this is
+ /// NULL.
bool m_result_is_pointer; ///< True if the function's result in the AST is a
///pointer (see comments in
/// ASTResultSynthesizer::SynthesizeBodyResult)
/// location of the static allocation.
//------------------------------------------------------------------
- /// UnfoldConstant operates on a constant [Old] which has just been
- /// replaced with a value [New]. We assume that new_value has
- /// been properly placed early in the function, in front of the
- /// first instruction in the entry basic block
- /// [FirstEntryInstruction].
+ /// UnfoldConstant operates on a constant [Old] which has just been replaced
+ /// with a value [New]. We assume that new_value has been properly placed
+ /// early in the function, in front of the first instruction in the entry
+ /// basic block [FirstEntryInstruction].
///
- /// UnfoldConstant reads through the uses of Old and replaces Old
- /// in those uses with New. Where those uses are constants, the
- /// function generates new instructions to compute the result of the
- /// new, non-constant expression and places them before
- /// FirstEntryInstruction. These instructions replace the constant
- /// uses, so UnfoldConstant calls itself recursively for those.
+ /// UnfoldConstant reads through the uses of Old and replaces Old in those
+ /// uses with New. Where those uses are constants, the function generates
+ /// new instructions to compute the result of the new, non-constant
+ /// expression and places them before FirstEntryInstruction. These
+ /// instructions replace the constant uses, so UnfoldConstant calls itself
+ /// recursively for those.
///
/// @param[in] llvm_function
/// The function currently being processed.
lldb_private::Stream &error_stream);
//------------------------------------------------------------------
- /// Construct a reference to m_reloc_placeholder with a given type
- /// and offset. This typically happens after inserting data into
+ /// Construct a reference to m_reloc_placeholder with a given type and
+ /// offset. This typically happens after inserting data into
/// m_data_allocator.
///
/// @param[in] type
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.
+ /// Commit the allocation in m_data_allocator and use its final location to
+ /// replace m_reloc_placeholder.
///
/// @param[in] module
/// The module that m_data_allocator resides in
//----------------------------------------------------------------------
/// @class GoUserExpression GoUserExpression.h
-/// "lldb/Expression/GoUserExpression.h"
-/// @brief Encapsulates a single expression for use with Go
+/// "lldb/Expression/GoUserExpression.h" Encapsulates a single expression for
+/// use with Go
///
/// LLDB uses expressions for various purposes, notably to call functions
-/// and as a backend for the expr command. GoUserExpression encapsulates
-/// the objects needed to parse and interpret an expression.
+/// and as a backend for the expr command. GoUserExpression encapsulates the
+/// objects needed to parse and interpret an expression.
//----------------------------------------------------------------------
class GoUserExpression : public UserExpression {
public:
//===----------------------------------------------------------------------===//
//
/// @file
-/// @brief Generic structures and typedefs for ELF files.
+/// Generic structures and typedefs for ELF files.
///
/// This file provides definitions for the various entities comprising an ELF
/// file. The structures are generic in the sense that they do not correspond
/// to the exact binary layout of an ELF, but can be used to hold the
/// information present in both 32 and 64 bit variants of the format. Each
-/// entity provides a \c Parse method which is capable of transparently reading
-/// both 32 and 64 bit instances of the object.
+/// entity provides a \c Parse method which is capable of transparently
+/// reading both 32 and 64 bit instances of the object.
//===----------------------------------------------------------------------===//
#ifndef liblldb_ELFHeader_h_
//------------------------------------------------------------------------------
/// @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 from both
+/// Types used to represent the various components of ELF structures. All
+/// types are signed or unsigned integral types wide enough to hold values
+/// from both
/// 32 and 64 bit ELF variants.
//@{
typedef uint64_t elf_addr;
//------------------------------------------------------------------------------
/// @class ELFHeader
-/// @brief Generic representation of an ELF file header.
+/// Generic representation of an ELF file header.
///
-/// This object is used to identify the general attributes on an ELF file and to
-/// locate additional sections within the file.
+/// This object is used to identify the general attributes on an ELF file and
+/// to locate additional sections within the file.
struct ELFHeader {
unsigned char e_ident[llvm::ELF::EI_NIDENT]; ///< ELF file identification.
elf_addr e_entry; ///< Virtual address program entry point.
bool HasHeaderExtension() const;
//--------------------------------------------------------------------------
- /// Parse an ELFHeader entry starting at position \p offset and
- /// update the data extractor with the address size and byte order
- /// attributes as defined by the header.
+ /// Parse an ELFHeader entry starting at position \p offset and update the
+ /// data extractor with the address size and byte order attributes as
+ /// defined by the header.
///
/// @param[in,out] data
/// The DataExtractor to read from. Updated with the address size and
private:
//--------------------------------------------------------------------------
- /// Parse an ELFHeader header extension entry. This method is called
- /// by Parse().
+ /// Parse an ELFHeader header extension entry. This method is called by
+ /// Parse().
///
/// @param[in] data
/// The DataExtractor to read from.
//------------------------------------------------------------------------------
/// @class ELFSectionHeader
-/// @brief Generic representation of an ELF section header.
+/// Generic representation of an ELF section header.
struct ELFSectionHeader {
elf_word sh_name; ///< Section name string index.
elf_word sh_type; ///< Section type.
//------------------------------------------------------------------------------
/// @class ELFProgramHeader
-/// @brief Generic representation of an ELF program header.
+/// Generic representation of an ELF program header.
struct ELFProgramHeader {
elf_word p_type; ///< Type of program segment.
elf_word p_flags; ///< Segment attributes.
//------------------------------------------------------------------------------
/// @class ELFSymbol
-/// @brief Represents a symbol within an ELF symbol table.
+/// Represents a symbol within an ELF symbol table.
struct ELFSymbol {
elf_addr st_value; ///< Absolute or relocatable address.
elf_xword st_size; ///< Size of the symbol or zero.
//------------------------------------------------------------------------------
/// @class ELFDynamic
-/// @brief Represents an entry in an ELF dynamic table.
+/// Represents an entry in an ELF dynamic table.
struct ELFDynamic {
elf_sxword d_tag; ///< Type of dynamic table entry.
union {
//------------------------------------------------------------------------------
/// @class ELFRel
-/// @brief Represents a relocation entry with an implicit addend.
+/// Represents a relocation entry with an implicit addend.
struct ELFRel {
elf_addr r_offset; ///< Address of reference.
elf_xword r_info; ///< symbol index and type of relocation.
//------------------------------------------------------------------------------
/// @class ELFRela
-/// @brief Represents a relocation entry with an explicit addend.
+/// Represents a relocation entry with an explicit addend.
struct ELFRela {
elf_addr r_offset; ///< Address of reference.
elf_xword r_info; ///< Symbol index and type of relocation.
//===----------------------------------------------------------------------===//
/// @class ELFRelocation
-/// @brief Generic wrapper for ELFRel and ELFRela.
+/// Generic wrapper for ELFRel and ELFRela.
///
/// This helper class allows us to parse both ELFRel and ELFRela relocation
/// entries in a generic manner.
//------------------------------------------------------------------------------
/// @class ObjectFileELF
-/// @brief Generic ELF object file reader.
+/// Generic ELF object file reader.
///
-/// This class provides a generic ELF (32/64 bit) reader plugin implementing the
-/// ObjectFile protocol.
+/// This class provides a generic ELF (32/64 bit) reader plugin implementing
+/// the ObjectFile protocol.
class ObjectFileELF : public lldb_private::ObjectFile {
public:
~ObjectFileELF() override;
uint64_t length,
lldb_private::ArchSpec &arch_spec);
- /// Parses the elf section headers and returns the uuid, debug link name, crc,
- /// archspec.
+ /// Parses the elf section headers and returns the uuid, debug link name,
+ /// crc, archspec.
static size_t GetSectionHeaderInfo(SectionHeaderColl §ion_headers,
lldb_private::DataExtractor &object_data,
const elf::ELFHeader &header,
namespace process_darwin {
/// @class NativeProcessDarwin
-/// @brief Manages communication with the inferior (debugee) process.
+/// Manages communication with the inferior (debugee) process.
///
-/// Upon construction, this class prepares and launches an inferior
-/// process for debugging.
+/// Upon construction, this class prepares and launches an inferior process
+/// for debugging.
///
/// Changes in the inferior process state are broadcasted.
class NativeProcessDarwin : public NativeProcessProtocol {
// -----------------------------------------------------------------
/// Finalize the launch.
///
- /// This method associates the NativeProcessDarwin instance with
- /// the host process that was just launched. It peforms actions
- /// like attaching a listener to the inferior exception port,
- /// ptracing the process, and the like.
+ /// This method associates the NativeProcessDarwin instance with the host
+ /// process that was just launched. It peforms actions like attaching a
+ /// listener to the inferior exception port, ptracing the process, and the
+ /// like.
///
/// @param[in] launch_flavor
/// The launch flavor that was used to launch the process.
task_t TaskPortForProcessID(Status &error, bool force = false) const;
- /// Attaches to an existing process. Forms the
- /// implementation of Process::DoAttach.
+ /// Attaches to an existing process. Forms the implementation of
+ /// Process::DoAttach.
void AttachToInferior(MainLoop &mainloop, lldb::pid_t pid, Status &error);
::pid_t Attach(lldb::pid_t pid, Status &error);
Status GetSignalInfo(lldb::tid_t tid, void *siginfo);
/// Writes the raw event message code (vis-a-vis PTRACE_GETEVENTMSG)
- /// corresponding to the given thread ID to the memory pointed to
- /// by @p message.
+ /// corresponding to the given thread ID to the memory pointed to by @p
+ /// message.
Status GetEventMessage(lldb::tid_t tid, unsigned long *message);
void NotifyThreadDeath(lldb::tid_t tid);
//------------------------------------------------------------------------------
// @class FreeBSDThread
-// @brief Abstraction of a FreeBSD thread.
+// Abstraction of a FreeBSD thread.
class FreeBSDThread : public lldb_private::Thread {
public:
//------------------------------------------------------------------
//===----------------------------------------------------------------------===//
/// @class POSIXStopInfo
-/// @brief Simple base class for all POSIX-specific StopInfo objects.
+/// Simple base class for all POSIX-specific StopInfo objects.
///
class POSIXStopInfo : public lldb_private::StopInfo {
public:
//===----------------------------------------------------------------------===//
/// @class POSIXLimboStopInfo
-/// @brief Represents the stop state of a process ready to exit.
+/// Represents the stop state of a process ready to exit.
///
class POSIXLimboStopInfo : public POSIXStopInfo {
public:
//===----------------------------------------------------------------------===//
/// @class POSIXNewThreadStopInfo
-/// @brief Represents the stop state of process when a new thread is spawned.
+/// Represents the stop state of process when a new thread is spawned.
///
class POSIXNewThreadStopInfo : public POSIXStopInfo {
//------------------------------------------------------------------------------
/// @class Operation
-/// @brief Represents a ProcessMonitor operation.
+/// Represents a ProcessMonitor operation.
///
-/// Under FreeBSD, it is not possible to ptrace() from any other thread but the
-/// one that spawned or attached to the process from the start. Therefore, when
-/// a ProcessMonitor is asked to deliver or change the state of an inferior
-/// process the operation must be "funneled" to a specific thread to perform the
-/// task. The Operation class provides an abstract base for all services the
-/// ProcessMonitor must perform via the single virtual function Execute, thus
-/// encapsulating the code that needs to run in the privileged context.
+/// Under FreeBSD, it is not possible to ptrace() from any other thread but
+/// the one that spawned or attached to the process from the start.
+/// Therefore, when a ProcessMonitor is asked to deliver or change the state
+/// of an inferior process the operation must be "funneled" to a specific
+/// thread to perform the task. The Operation class provides an abstract base
+/// for all services the ProcessMonitor must perform via the single virtual
+/// function Execute, thus encapsulating the code that needs to run in the
+/// privileged context.
class Operation {
public:
virtual ~Operation() {}
//------------------------------------------------------------------------------
/// @class ReadOperation
-/// @brief Implements ProcessMonitor::ReadMemory.
+/// Implements ProcessMonitor::ReadMemory.
class ReadOperation : public Operation {
public:
ReadOperation(lldb::addr_t addr, void *buff, size_t size, Status &error,
//------------------------------------------------------------------------------
/// @class WriteOperation
-/// @brief Implements ProcessMonitor::WriteMemory.
+/// Implements ProcessMonitor::WriteMemory.
class WriteOperation : public Operation {
public:
WriteOperation(lldb::addr_t addr, const void *buff, size_t size,
//------------------------------------------------------------------------------
/// @class ReadRegOperation
-/// @brief Implements ProcessMonitor::ReadRegisterValue.
+/// Implements ProcessMonitor::ReadRegisterValue.
class ReadRegOperation : public Operation {
public:
ReadRegOperation(lldb::tid_t tid, unsigned offset, unsigned size,
//------------------------------------------------------------------------------
/// @class WriteRegOperation
-/// @brief Implements ProcessMonitor::WriteRegisterValue.
+/// Implements ProcessMonitor::WriteRegisterValue.
class WriteRegOperation : public Operation {
public:
WriteRegOperation(lldb::tid_t tid, unsigned offset,
//------------------------------------------------------------------------------
/// @class ReadDebugRegOperation
-/// @brief Implements ProcessMonitor::ReadDebugRegisterValue.
+/// Implements ProcessMonitor::ReadDebugRegisterValue.
class ReadDebugRegOperation : public Operation {
public:
ReadDebugRegOperation(lldb::tid_t tid, unsigned offset, unsigned size,
//------------------------------------------------------------------------------
/// @class WriteDebugRegOperation
-/// @brief Implements ProcessMonitor::WriteDebugRegisterValue.
+/// Implements ProcessMonitor::WriteDebugRegisterValue.
class WriteDebugRegOperation : public Operation {
public:
WriteDebugRegOperation(lldb::tid_t tid, unsigned offset,
//------------------------------------------------------------------------------
/// @class ReadGPROperation
-/// @brief Implements ProcessMonitor::ReadGPR.
+/// Implements ProcessMonitor::ReadGPR.
class ReadGPROperation : public Operation {
public:
ReadGPROperation(lldb::tid_t tid, void *buf, bool &result)
//------------------------------------------------------------------------------
/// @class ReadFPROperation
-/// @brief Implements ProcessMonitor::ReadFPR.
+/// Implements ProcessMonitor::ReadFPR.
class ReadFPROperation : public Operation {
public:
ReadFPROperation(lldb::tid_t tid, void *buf, bool &result)
//------------------------------------------------------------------------------
/// @class WriteGPROperation
-/// @brief Implements ProcessMonitor::WriteGPR.
+/// Implements ProcessMonitor::WriteGPR.
class WriteGPROperation : public Operation {
public:
WriteGPROperation(lldb::tid_t tid, void *buf, bool &result)
//------------------------------------------------------------------------------
/// @class WriteFPROperation
-/// @brief Implements ProcessMonitor::WriteFPR.
+/// Implements ProcessMonitor::WriteFPR.
class WriteFPROperation : public Operation {
public:
WriteFPROperation(lldb::tid_t tid, void *buf, bool &result)
//------------------------------------------------------------------------------
/// @class ResumeOperation
-/// @brief Implements ProcessMonitor::Resume.
+/// Implements ProcessMonitor::Resume.
class ResumeOperation : public Operation {
public:
ResumeOperation(uint32_t signo, bool &result)
//------------------------------------------------------------------------------
/// @class SingleStepOperation
-/// @brief Implements ProcessMonitor::SingleStep.
+/// Implements ProcessMonitor::SingleStep.
class SingleStepOperation : public Operation {
public:
SingleStepOperation(uint32_t signo, bool &result)
//------------------------------------------------------------------------------
/// @class LwpInfoOperation
-/// @brief Implements ProcessMonitor::GetLwpInfo.
+/// Implements ProcessMonitor::GetLwpInfo.
class LwpInfoOperation : public Operation {
public:
LwpInfoOperation(lldb::tid_t tid, void *info, bool &result, int &ptrace_err)
//------------------------------------------------------------------------------
/// @class ThreadSuspendOperation
-/// @brief Implements ProcessMonitor::ThreadSuspend.
+/// Implements ProcessMonitor::ThreadSuspend.
class ThreadSuspendOperation : public Operation {
public:
ThreadSuspendOperation(lldb::tid_t tid, bool suspend, bool &result)
//------------------------------------------------------------------------------
/// @class EventMessageOperation
-/// @brief Implements ProcessMonitor::GetEventMessage.
+/// Implements ProcessMonitor::GetEventMessage.
class EventMessageOperation : public Operation {
public:
EventMessageOperation(lldb::tid_t tid, unsigned long *message, bool &result)
//------------------------------------------------------------------------------
/// @class KillOperation
-/// @brief Implements ProcessMonitor::Kill.
+/// Implements ProcessMonitor::Kill.
class KillOperation : public Operation {
public:
KillOperation(bool &result) : m_result(result) {}
//------------------------------------------------------------------------------
/// @class DetachOperation
-/// @brief Implements ProcessMonitor::Detach.
+/// Implements ProcessMonitor::Detach.
class DetachOperation : public Operation {
public:
DetachOperation(Status &result) : m_error(result) {}
//------------------------------------------------------------------------------
/// The basic design of the ProcessMonitor is built around two threads.
///
-/// One thread (@see SignalThread) simply blocks on a call to waitpid() looking
-/// for changes in the debugee state. When a change is detected a
+/// One thread (@see SignalThread) simply blocks on a call to waitpid()
+/// looking for changes in the debugee state. When a change is detected a
/// ProcessMessage is sent to the associated ProcessFreeBSD instance. This
-/// thread
-/// "drives" state changes in the debugger.
+/// thread "drives" state changes in the debugger.
///
/// The second thread (@see OperationThread) is responsible for two things 1)
/// launching or attaching to the inferior process, and then 2) servicing
class Operation;
/// @class ProcessMonitor
-/// @brief Manages communication with the inferior (debugee) process.
+/// Manages communication with the inferior (debugee) process.
///
-/// Upon construction, this class prepares and launches an inferior process for
-/// debugging.
+/// Upon construction, this class prepares and launches an inferior process
+/// for debugging.
///
/// Changes in the inferior process state are propagated to the associated
/// ProcessFreeBSD instance by calling ProcessFreeBSD::SendMessage with the
/// standard error of this debugee. Even if stderr and stdout were
/// redirected on launch it may still happen that data is available on this
/// descriptor (if the inferior process opens /dev/tty, for example). This
- /// descriptor is
- /// closed after a call to StopMonitor().
+ /// descriptor is closed after a call to StopMonitor().
///
/// If this monitor was attached to an existing process this method returns
/// -1.
size_t WriteMemory(lldb::addr_t vm_addr, const void *buf, size_t size,
lldb_private::Status &error);
- /// Reads the contents from the register identified by the given (architecture
- /// dependent) offset.
+ /// Reads the contents from the register identified by the given
+ /// (architecture dependent) offset.
///
/// This method is provided for use by RegisterContextFreeBSD derivatives.
bool ReadRegisterValue(lldb::tid_t tid, unsigned offset, const char *reg_name,
/// @class LauchArgs
///
- /// @brief Simple structure to pass data to the thread responsible for
- /// launching a child process.
+ /// Simple structure to pass data to the thread responsible for launching a
+ /// child process.
struct LaunchArgs : OperationArgs {
LaunchArgs(ProcessMonitor *monitor, lldb_private::Module *module,
char const **argv, lldb_private::Environment env,
//------------------------------------------------------------------------------
/// @class POSIXBreakpointProtocol
///
-/// @brief Extends RegisterClass with a few virtual operations useful on POSIX.
+/// Extends RegisterClass with a few virtual operations useful on POSIX.
class POSIXBreakpointProtocol {
public:
POSIXBreakpointProtocol() { m_watchpoints_initialized = false; }
namespace process_linux {
/// @class NativeProcessLinux
-/// @brief Manages communication with the inferior (debugee) process.
+/// Manages communication with the inferior (debugee) process.
///
-/// Upon construction, this class prepares and launches an inferior process for
-/// debugging.
+/// Upon construction, this class prepares and launches an inferior process
+/// for debugging.
///
/// Changes in the inferior process state are broadcasted.
class NativeProcessLinux : public NativeProcessProtocol {
namespace lldb_private {
namespace process_netbsd {
/// @class NativeProcessNetBSD
-/// @brief Manages communication with the inferior (debugee) process.
+/// Manages communication with the inferior (debugee) process.
///
-/// Upon construction, this class prepares and launches an inferior process for
-/// debugging.
+/// Upon construction, this class prepares and launches an inferior process
+/// for debugging.
///
/// Changes in the inferior process state are broadcasted.
class NativeProcessNetBSD : public NativeProcessProtocol {
//----------------------------------------------------------------------
/// @class HistoryThread HistoryThread.h "HistoryThread.h"
-/// @brief A thread object representing a backtrace from a previous point in the
+/// A thread object representing a backtrace from a previous point in the
/// process execution
///
/// This subclass of Thread is used to provide a backtrace from earlier in
/// process execution. It is given a backtrace list of pc addresses and
-/// optionally a stop_id of when those pc addresses were collected, and it will
-/// create stack frames for them.
+/// optionally a stop_id of when those pc addresses were collected, and it
+/// will create stack frames for them.
//----------------------------------------------------------------------
class HistoryThread : public lldb_private::Thread {
///------------------------------------------------------------------------------
/// @class RegisterInfoInterface
///
-/// @brief RegisterInfo interface to patch RegisterInfo structure for archs.
+/// RegisterInfo interface to patch RegisterInfo structure for archs.
///------------------------------------------------------------------------------
class RegisterInfoInterface {
public:
clang::FunctionTemplateDecl *ClangASTContext::CreateFunctionTemplateDecl(
clang::DeclContext *decl_ctx, clang::FunctionDecl *func_decl,
const char *name, const TemplateParameterInfos &template_param_infos) {
- // /// \brief Create a function template node.
+ // /// Create a function template node.
ASTContext *ast = getASTContext();
llvm::SmallVector<NamedDecl *, 8> template_param_decls;
namespace {
-/// @brief Represents the collection of qualifiers on a type
+/// Represents the collection of qualifiers on a type
enum Qualifiers {
QualifierNone = 0,
QualifierPointer = 32
};
-/// @brief Categorizes the recognized operators
+/// Categorizes the recognized operators
enum class OperatorKind {
Unary,
NoMatch
};
-/// @brief Represents one of the recognized two-character operator
-/// abbreviations used when parsing operators as names and expressions
+/// Represents one of the recognized two-character operator abbreviations used
+/// when parsing operators as names and expressions
struct Operator {
const char *name;
OperatorKind kind;
};
-/// @brief Represents a range of characters in the output buffer, typically for
-/// use with RewriteRange()
+/// Represents a range of characters in the output buffer, typically for use
+/// with RewriteRange()
struct BufferRange {
int offset;
int length;
};
-/// @brief Transient state required while parsing a name
+/// Transient state required while parsing a name
struct NameState {
bool parse_function_params;
BufferRange last_name_range;
};
-/// @brief LLDB's fast C++ demangler
+/// LLDB's fast C++ demangler
///
/// This is an incomplete implementation designed to speed up the demangling
/// process that is often a bottleneck when LLDB stops a process for the first
/// time. Where the implementation doesn't know how to demangle a symbol it
-/// fails gracefully to allow the caller to fall back to the existing demangler.
+/// fails gracefully to allow the caller to fall back to the existing
+/// demangler.
///
/// Over time the full mangling spec should be supported without compromising
/// performance for the most common cases.
// Public API
//----------------------------------------------------
- /// @brief Create a SymbolDemangler
+ /// Create a SymbolDemangler
///
/// The newly created demangler allocates and owns scratch memory sufficient
/// for demangling typical symbols. Additional memory will be allocated if
m_owns_m_rewrite_ranges = true;
}
- /// @brief Create a SymbolDemangler that uses provided scratch memory
+ /// Create a SymbolDemangler that uses provided scratch memory
///
/// The provided memory is not owned by the demangler. It will be
- /// overwritten during calls to GetDemangledCopy() but can be used for
- /// other purposes between calls. The provided memory will not be freed
- /// when this instance is destroyed.
+ /// overwritten during calls to GetDemangledCopy() but can be used for other
+ /// purposes between calls. The provided memory will not be freed when this
+ /// instance is destroyed.
///
/// If demangling a symbol requires additional space it will be allocated
/// and managed by the demangler instance.
///
- /// @param storage_ptr Valid pointer to at least storage_size bytes of
- /// space that the SymbolDemangler can use during demangling
+ /// @param storage_ptr Valid pointer to at least storage_size bytes of space
+ /// that the SymbolDemangler can use during demangling
///
/// @param storage_size Number of bytes of space available scratch memory
/// referenced by storage_ptr
m_owns_buffer = false;
}
- /// @brief Destroys the SymbolDemangler and deallocates any scratch
- /// memory that it owns
+ /// Destroys the SymbolDemangler and deallocates any scratch memory that it
+ /// owns
~SymbolDemangler() {
if (m_owns_buffer)
int highwater_buffer = 0;
#endif
- /// @brief Parses the provided mangled name and returns a newly allocated
+ /// Parses the provided mangled name and returns a newly allocated
/// demangling
///
- /// @param mangled_name Valid null-terminated C++ mangled name following
- /// the Itanium C++ ABI mangling specification as implemented by Clang
+ /// @param mangled_name Valid null-terminated C++ mangled name following the
+ /// Itanium C++ ABI mangling specification as implemented by Clang
///
/// @result Newly allocated null-terminated demangled name when demangling
/// is successful, and nullptr when demangling fails. The caller is
//----------------------------------------------------------------------
/// @class JSONGenerator JSONGenerator.h
-/// @brief A class which can construct structured data for the sole purpose
+/// A class which can construct structured data for the sole purpose
/// of printing it in JSON format.
///
/// A stripped down version of lldb's StructuredData objects which are much
namespace ptdecoder_private {
//----------------------------------------------------------------------
/// @class Instruction
-/// @brief Represents an assembly instruction containing raw
+/// Represents an assembly instruction containing raw
/// instruction bytes, instruction address along with information
/// regarding execution flow context and Intel(R) Processor Trace
/// context.
//---------------------------------------------------------------------------
/// @class InstructionList
-/// @brief Represents a list of assembly instructions. Each instruction is of
+/// Represents a list of assembly instructions. Each instruction is of
/// type Instruction.
//---------------------------------------------------------------------------
class InstructionList {
//----------------------------------------------------------------------
/// @class TraceOptions
-/// @brief Provides Intel(R) Processor Trace specific configuration options and
+/// 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
/// assembly instructions executed for an inferior.
//----------------------------------------------------------------------
/// @class Decoder
-/// @brief This class makes use of Intel(R) Processor Trace hardware feature
+/// 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.
///
//----------------------------------------------------------------------
/// @class PTInstruction
-/// @brief Represents an assembly instruction containing raw
+/// Represents an assembly instruction containing raw
/// instruction bytes, instruction address along with information
/// regarding execution flow context and Intel(R) Processor Trace
/// context.
//---------------------------------------------------------------------------
/// @class PTInstructionList
-/// @brief Represents a list of assembly instructions. Each instruction is of
+/// Represents a list of assembly instructions. Each instruction is of
/// type PTInstruction.
//---------------------------------------------------------------------------
class PTInstructionList {
//----------------------------------------------------------------------
/// @class PTTraceOptions
-/// @brief Provides configuration options like trace type, trace buffer size,
+/// Provides configuration options like trace type, trace buffer size,
/// meta data buffer size along with other Intel(R) Processor Trace
/// specific options.
//----------------------------------------------------------------------
//------------------------------------------------------------------
/// Get Intel(R) Processor Trace specific configuration options (apart from
- /// trace buffer size, meta data buffer size and TraceType) formatted as json
- /// text i.e. {"Name":Value,"Name":Value} pairs, where "Value" is a 64-bit
- /// unsigned integer in hex format. For "Name", please refer to
+ /// trace buffer size, meta data buffer size and TraceType) formatted as
+ /// json text i.e. {"Name":Value,"Name":Value} pairs, where "Value" is a
+ /// 64-bit unsigned integer in hex format. For "Name", please refer to
/// SBProcess::StartTrace API description for setting SBTraceOptions.
///
/// @return
//----------------------------------------------------------------------
/// @class PTDecoder
-/// @brief This class makes use of Intel(R) Processor Trace hardware feature
+/// 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.
///