jafl updated this revision to Diff 67405.
jafl added a comment.
Incorporate additional feedback from Greg Clayton.
Repository:
rL LLVM
https://reviews.llvm.org/D22831
Files:
include/lldb/API/SBAddress.h
Index: include/lldb/API/SBAddress.h
===================================================================
--- include/lldb/API/SBAddress.h
+++ include/lldb/API/SBAddress.h
@@ -15,6 +15,93 @@
namespace lldb {
+//------------------------------------------------------------------
+/// \class SBAddress
+///
+/// Represents an address. An address may refer to code or data from an
+/// existing module (SBModule), or it may refer to something on the stack
+/// or heap.
+///
+/// SBAddress objects use two different kinds of addresses: file addresses
+/// and load addresses.
+///
+/// File addresses refer to the raw address as it is known in the object
+/// file that the module is using. File addresses will match the virtual
+/// addresses that are found in the object file, such as the address values
+/// in the symbols in the native symbol tables, unwind tables and any other
+/// data structures in the object file format (ELF, mach-o, COFF). File
+/// addresses are not unique across multiple modules as many modules might
+/// contain a file address of 0x0 (possibly the first function in the .text
+/// section) since many object files, like shared libraries, have their
+/// virtual addresses start at 0x0. Since file addresses are only unique
+/// within an SBModule, you must use a valid module object to resolve a
+/// file address into an SBAddress:
+///
+/// lldb::SBAddress SBModule::ResolveFileAddress (lldb::addr_t vm_addr);
+///
+/// File addresses are also useful in case you want to use other command
+/// line tools that know how to extract data from an object file, like
+/// objdump or many other tools that dump mach-o, ELF and COFF files.
+///
+/// Load addresses represent a unique location within a process' address
+/// space. A load address might represent a section/offset address within a
+/// process. In this case the SBAddress will have a valid section
+/// (lldb::SBAddress::GetSection() will return a SBSection that is valid),
+/// and a valid offset (lldb::addr_t lldb::SBAddress::GetOffset()) into
+/// that section. Or a load address might represent a unique location in
+/// the process' memory space that doesn't resolve to a section within an
+/// object file, like a location on the stack or heap. In this case the
+/// address will not have a valid section (lldb::SBSection
+/// lldb::SBAddress::GetSection() will return an SBSection that is *not*
+/// valid), and lldb::SBAddress::GetOffset() will return the value load
+/// address. You can resolve a load address back into a SBAddress by using
+/// either of:
+///
+/// SBAddress (lldb::addr_t load_addr, lldb::SBTarget &target);
+/// void SBAddress::SetLoadAddress (lldb::addr_t load_addr, lldb::SBTarget &target);
+///
+/// This will take the "load_addr" and figure out which section, if any,
+/// that the load address belongs to within the specified target. If
+/// "load_addr" belongs to a section, the resulting SBAddress objects will
+/// contain a valid section and offset (address that matches data in an
+/// object file's sections), otherwise it will have no section and the
+/// offset will match "load_addr" (stack or heap address).
+///
+/// If an address has a valid section, the address might refer to things
+/// found in the debug information:
+///
+/// SBModule - the module that contains the section
+/// SBCompileUnit - the source file that was compiled to create this code
+/// SBFunction - the function that contains this address
+/// SBBlock - the deepest lexical block that contains the address within the SBFucntion
+/// SBLineEntry - the file and line and column that contains the address
+/// SBVariable - the static/global variable that contains the address
+///
+/// If there is no debug information, then the address might also refer to
+/// a symbol from the symbol table:
+///
+/// SBSymbol - the symbol that contains the address
+///
+/// If an address comes from an existing module, then it will be resolved
+/// into an offset from its containing section in that module. That way it
+/// can refer to the same logical location in the module that holds it even
+/// if the module is unloaded and loaded at different addresses. Module
+/// based SBAddresses are not bound to a particular target or process, but
+/// you can ask the SBAddress where/if it has been loaded in a particular
+/// target.
+///
+/// The individual Get*() 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 objects for an address:
+/// ~~~
+/// * lldb::SBSymbolContext SBAddress::GetSymbolContext (uint32_t resolve_scope);
+/// * lldb::SBSymbolContext SBTarget::ResolveSymbolContextForAddress (const SBAddress &addr, uint32_t resolve_scope);
+/// ~~~
+/// One or more bits from the SymbolContextItem enumerations can be
+/// logically OR'ed together to more efficiently retrieve multiple symbol
+/// objects.
+//------------------------------------------------------------------
class LLDB_API SBAddress
{
public:
@@ -33,73 +120,203 @@
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.
+ ///
+ /// @return
+ /// The valid file address, or LLDB_INVALID_ADDRESS if the address
+ /// doesn't have a file address (image is from memory only with no
+ /// representation on disk).
+ //------------------------------------------------------------------
addr_t
GetFileAddress () const;
+ //------------------------------------------------------------------
+ /// Get the load address.
+ ///
+ /// @param[in] target
+ /// The target in which to search.
+ ///
+ /// @return
+ /// The valid load 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's modules. If this
+ /// fails, assumes the address is absolute, e.g., on the stack or heap.
+ /// The object becomes valid, but will contain no section, and the
+ /// offset will match the load address.
+ ///
+ /// @param[in] load_addr
+ /// A new load address for this object.
+ ///
+ /// @param[in] target
+ /// The target within which the load address will be resolved.
+ //------------------------------------------------------------------
void
SetLoadAddress (lldb::addr_t load_addr,
lldb::SBTarget &target);
+
+ //------------------------------------------------------------------
+ /// Shift the address relative to its current position.
+ ///
+ /// @param[in] offset
+ /// The offset by which the address should be shifted.
+ //------------------------------------------------------------------
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);
- // The following queries can lookup symbol information for a given address.
- // An address might refer to code or data from an existing module, or it
- // might refer to something on the stack or heap. The following functions
- // 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 debug and symbol information that contains this address.
+ ///
+ /// @param[in] resolve_scope
+ /// lldb::SymbolContextItem bitmap specifying what to retrieve.
+ ///
+ /// @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
- // objects for an address:
- // lldb::SBSymbolContext SBAddress::GetSymbolContext (uint32_t resolve_scope);
- // lldb::SBSymbolContext SBTarget::ResolveSymbolContextForAddress (const SBAddress &addr, uint32_t resolve_scope);
- // One or more bits from the SymbolContextItem enumerations can be logically
- // OR'ed together to more efficiently retrieve multiple symbol objects.
-
+ //------------------------------------------------------------------
+ /// Get the section, if any, to which this address refers.
+ ///
+ /// @return
+ /// The lldb::SBSection (within a module) containing this address.
+ //------------------------------------------------------------------
lldb::SBSection
GetSection ();
+ //------------------------------------------------------------------
+ /// Get the offset for this address.
+ ///
+ /// If this address contains a section, this value is the offset within
+ /// that section. If the address doesn't have a valid section, then
+ /// this address refers to an absolute address.
+ ///
+ /// @return
+ /// The offset for this address, relative to the section.
+ //------------------------------------------------------------------
lldb::addr_t
GetOffset ();
+ //------------------------------------------------------------------
+ /// Get the module that contains this address
+ ///
+ /// The returned module will only be valid if this address has a valid
+ /// section.
+ ///
+ /// @return
+ /// The lldb::SBModule containing this address.
+ //------------------------------------------------------------------
lldb::SBModule
GetModule ();
+ //------------------------------------------------------------------
+ /// Get the compile unit that contains this address
+ ///
+ /// The returned module will only be valid if this address has a valid
+ /// section and if the module has debug information available.
+ ///
+ /// @return
+ /// The lldb::SBCompileUnit (within a module) containing this address.
+ //------------------------------------------------------------------
lldb::SBCompileUnit
GetCompileUnit ();
+ //------------------------------------------------------------------
+ /// Get the function that contains this address
+ ///
+ /// The returned object will only be valid if this address has a valid
+ /// section and if the module has debug information available.
+ ///
+ /// @return
+ /// The lldb::SBFunction containing this address.
+ //------------------------------------------------------------------
lldb::SBFunction
GetFunction ();
+ //------------------------------------------------------------------
+ /// Get the deepest lexical block within a function that contains this
+ /// address.
+ ///
+ /// The returned object will only be valid if this address has a valid
+ /// section and if the module has debug information available.
+ ///
+ /// @return
+ /// The lldb::SBBlock containing this address.
+ //------------------------------------------------------------------
lldb::SBBlock
GetBlock ();
+ //------------------------------------------------------------------
+ /// Get the symbol that contains this address
+ ///
+ /// The returned object will only be valid if this address has a valid
+ /// section.
+ ///
+ /// @return
+ /// The lldb::SBSymbol at this address.
+ //------------------------------------------------------------------
lldb::SBSymbol
GetSymbol ();
+ //------------------------------------------------------------------
+ /// Get the source file and line that contains this address
+ ///
+ /// The returned object will only be valid if this address has a valid
+ /// section and if the module has debug information available.
+ ///
+ /// @return
+ /// The lldb::SBLineEntry specifying the file location that
+ /// corresponds to this address.
+ //------------------------------------------------------------------
lldb::SBLineEntry
GetLineEntry ();
+ //------------------------------------------------------------------
+ /// @return
+ /// The classification for this address, e.g., code or data.
+ //------------------------------------------------------------------
lldb::AddressClass
GetAddressClass ();
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
