[Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class

[Greg Clayton via lldb-commits]

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