[LLDB] Documentation for SBAddress class

[jafl]

Summary

"javadoc" documentation for SBAddress class

[clayborg]

A few modifications to the SBAddress info

include/lldb/API/SBAddress.h

32

Maybe start off with something like:

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

44

We should add a blurb about "file addresses" and "load addresses" to explain what they are. Maybe something like:

SBAddress objects can vend two types of addresses: file address and load address. 

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. 

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 a SBSection that is *not* valid), and lldb::SBAddress::GetOffset() will return the value load address.

177

This is incorrect. The object will be valid, but will contain no section, and the offset will match the load address.

209

// Lookup debug and symbol information that contains this address

220–225

// Get the section, if any, that this address refers to

229

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

242

Get the module that contains this address

// The returned module will only be valid if this address has a valid section

254

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

266

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

278

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

291

Get the symbol that contains this address

The returned object will only be valid if this address has a valid section

303

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

[jafl]

Incorporated feedback

[clayborg]

Just a quick clarifications on file and load addresses to make things a bit clearer.

include/lldb/API/SBAddress.h

25–26

This should be reworded a bit as SBAddress objects don't represent file and load addresses, but file and load addresses can be extracted from a SBAddress object as lldb::addr_t values. So maybe:

SBAddress objects use two different kinds of addresses: file addresses and load addresses.

This keeps it simple, and then we will define both type of addresses below.

37

Add something like this:

Since file addresses are only unique within a 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.

50

Now to clarify the file and load address stuff we might say this here:

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).

[jafl]

Incorporate additional feedback from Greg Clayton.

[clayborg]

Looks good, thanks for the changes and the documentation.

[Eugene.Zelenko]

Please rebase from trunk and run Clang-format.

[jafl]

Merged from master and ran clang-format

include/lldb/API/SBAddress.h

 
 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:

     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 ();