clayborg requested changes to this revision.
clayborg added a comment.
This revision now requires changes to proceed.
A few modifications to the SBAddress info
================
Comment at: include/lldb/API/SBAddress.h:32
@@ +31,3 @@
+/// target.
+///
+/// The individual Get*() functions grab individual objects for a given
----------------
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
```
================
Comment at: include/lldb/API/SBAddress.h:44
@@ -18,1 +43,3 @@
+/// objects.
+//------------------------------------------------------------------
class LLDB_API SBAddress
----------------
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.
```
================
Comment at: include/lldb/API/SBAddress.h:117
@@ +116,3 @@
+ /// fails, assumes the address is absolute, e.g., on the stack or heap.
+ /// The object becomes valid.
+ ///
----------------
This is incorrect. The object will be valid, but will contain no section, and
the offset will match the load address.
================
Comment at: include/lldb/API/SBAddress.h:148
@@ +147,3 @@
+ //------------------------------------------------------------------
+ /// Lookup symbol information for this address.
+ ///
----------------
// Lookup debug and symbol information that contains this address
================
Comment at: include/lldb/API/SBAddress.h:159
@@ -68,11 +158,3 @@
-
- // 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.
-
+ //------------------------------------------------------------------
+ /// @return
----------------
// Get the section, if any, that this address refers to
================
Comment at: include/lldb/API/SBAddress.h:166
@@ -81,1 +165,3 @@
+ //------------------------------------------------------------------
+ /// @return
----------------
// 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
================
Comment at: include/lldb/API/SBAddress.h:173
@@ -84,1 +172,3 @@
+ //------------------------------------------------------------------
+ /// @return
----------------
// Get the module that contains this address
//
// The returned module will only be valid if this address has a valid section
================
Comment at: include/lldb/API/SBAddress.h:180
@@ -87,1 +179,3 @@
+ //------------------------------------------------------------------
+ /// @return
----------------
// 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
================
Comment at: include/lldb/API/SBAddress.h:187
@@ -90,1 +186,3 @@
+ //------------------------------------------------------------------
+ /// @return
----------------
// 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
================
Comment at: include/lldb/API/SBAddress.h:194
@@ -93,1 +193,3 @@
+ //------------------------------------------------------------------
+ /// @return
----------------
// 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
================
Comment at: include/lldb/API/SBAddress.h:201
@@ -96,1 +200,3 @@
+ //------------------------------------------------------------------
+ /// @return
----------------
Get the symbol that contains this address
The returned object will only be valid if this address has a valid section
================
Comment at: include/lldb/API/SBAddress.h:208
@@ -99,1 +207,3 @@
+ //------------------------------------------------------------------
+ /// @return
----------------
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
Repository:
rL LLVM
https://reviews.llvm.org/D22831
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
