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

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


================
Comment at: include/lldb/API/SBAddress.h:25-26
@@ +24,4 @@
+///
+/// SBAddress objects can represent two types of addresses: file address
+/// and load address.
+///
----------------
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.

================
Comment at: include/lldb/API/SBAddress.h:37
@@ +36,3 @@
+/// virtual addresses start at 0x0.
+///
+/// Load addresses represent a unique location within a process' address
----------------
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.
```

================
Comment at: include/lldb/API/SBAddress.h:50
@@ +49,3 @@
+/// address.
+///
+/// If an address has a valid section, the address might refer to things
----------------
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).
```


Repository:
  rL LLVM

https://reviews.llvm.org/D22831