Having completed my C++ app on top of lldb, I would like to improve the
function-level documentation so others don't have to blunder around in the
dark the way I did :)
Here is a patch for SBAddress.h
If this is the right direction, I will work my way through the rest of the
SB*.h files.
Thanks!
John Lindal
-----
diff --git a/include/lldb/API/SBAddress.h b/include/lldb/API/SBAddress.h
index 4cbbee9..b324e90 100644
--- a/include/lldb/API/SBAddress.h
+++ b/include/lldb/API/SBAddress.h
@@ -33,27 +33,100 @@ public:
const lldb::SBAddress &
operator = (const lldb::SBAddress &rhs);
+ //------------------------------------------------------------------
+ /// @return
+ /// true if the object is valid. If the object is invalid, it is
+ /// not safe to call any other methods.
+ //------------------------------------------------------------------
bool
IsValid () const;
+ //------------------------------------------------------------------
+ /// Clears the address. The object is no longer valid.
+ //------------------------------------------------------------------
void
Clear ();
+ //------------------------------------------------------------------
+ /// 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 a unique section in the object file.
+ ///
+ /// @return
+ /// The valid file virtual address, or LLDB_INVALID_ADDRESS if
+ /// the address doesn't have a file virtual address (image is
+ /// from memory only with no representation on disk).
+ //------------------------------------------------------------------
addr_t
GetFileAddress () const;
+ //------------------------------------------------------------------
+ /// 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 a 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.
+ ///
+ /// @param[in] target
+ /// The target in which to search.
+ ///
+ /// @return
+ /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
+ /// the address is currently not loaded.
+ //------------------------------------------------------------------
addr_t
GetLoadAddress (const lldb::SBTarget &target) const;
+ //------------------------------------------------------------------
+ /// Set the section and address within the section. If it succeeds,
+ /// the object becomes valid.
+ ///
+ /// @param[in] section
+ /// A lldb::SBSection object to use as the section base.
+ ///
+ /// @param[in] offset
+ /// A new offset value for this object.
+ //------------------------------------------------------------------
void
SetAddress (lldb::SBSection section, lldb::addr_t offset);
+ //------------------------------------------------------------------
+ /// Tries to resolve the address within the target. If this fails,
+ /// assumes the address is absolute, e.g., on the stack or heap. If it
+ /// succeeds, the object becomes valid.
+ ///
+ /// @param[in] load_addr
+ /// A new offset value for this object.
+ ///
+ /// @param[in] target
+ /// The target within which the offset is valid.
+ //------------------------------------------------------------------
void
SetLoadAddress (lldb::addr_t load_addr,
lldb::SBTarget &target);
+
+ //------------------------------------------------------------------
+ /// Set the offset for this address, relative to the current section,
+ /// if any.
+ ///
+ /// @param[in] offset
+ /// A new offset value for this object.
+ //------------------------------------------------------------------
+ // FIXME: Should this be SetOffsetAddress?
bool
OffsetAddress (addr_t offset);
+ //------------------------------------------------------------------
+ /// Dump a description of this object to the given lldb::SBStream.
+ ///
+ /// @param[in] description
+ /// The stream to which to dump the object description.
+ //------------------------------------------------------------------
bool
GetDescription (lldb::SBStream &description);
@@ -63,10 +136,25 @@ public:
// will only return valid values if the address has been resolved to a
code
// or data address using "void SBAddress::SetLoadAddress(...)" or
// "lldb::SBAddress SBTarget::ResolveLoadAddress (...)".
+
+ //------------------------------------------------------------------
+ /// Lookup symbol information for this address. An address might
+ /// refer to code or data from an existing module, or it might refer to
+ /// something on the stack or heap. This function will only return
+ /// valid values if the address has been resolved to a code or data
+ /// address using "void SBAddress::SetLoadAddress(...)" or
+ /// "lldb::SBAddress SBTarget::ResolveLoadAddress (...)".
+ ///
+ /// @param[in] resolve_scope
+ /// lldb::SymbolContextItem value specifying the scope in which to
+ /// resolve this address.
+ ///
+ /// @return
+ /// lldb::SBSymbolContext with the result.
+ //------------------------------------------------------------------
lldb::SBSymbolContext
GetSymbolContext (uint32_t resolve_scope);
-
// The following functions grab individual objects for a given address
and
// are less efficient if you want more than one symbol related
objects.
// Use one of the following when you want multiple debug symbol
related
@@ -76,30 +164,67 @@ public:
// One or more bits from the SymbolContextItem enumerations can be
logically
// OR'ed together to more efficiently retrieve multiple symbol objects.
+ //------------------------------------------------------------------
+ /// @return section
+ /// The lldb::SBSection containing this address.
+ //------------------------------------------------------------------
lldb::SBSection
GetSection ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The offset for this address, relative to the section.
+ //------------------------------------------------------------------
lldb::addr_t
GetOffset ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The module containing this address.
+ //------------------------------------------------------------------
lldb::SBModule
GetModule ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The compile unit containing this address.
+ //------------------------------------------------------------------
lldb::SBCompileUnit
GetCompileUnit ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The function containing this address.
+ //------------------------------------------------------------------
lldb::SBFunction
GetFunction ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The block containing this address.
+ //------------------------------------------------------------------
lldb::SBBlock
GetBlock ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The symbol at this address.
+ //------------------------------------------------------------------
lldb::SBSymbol
GetSymbol ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The lldb::SBLineEntry specifying the file location that
+ /// corresponds to this address.
+ //------------------------------------------------------------------
lldb::SBLineEntry
GetLineEntry ();
+ //------------------------------------------------------------------
+ /// @return section
+ /// The classification for this address.
+ //------------------------------------------------------------------
lldb::AddressClass
GetAddressClass ();
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
