This is an archive of the discontinued LLVM Phabricator instance.

[LLDB] Documentation for SBAddress class
AcceptedPublic

Authored by jafl on Jul 26 2016, 1:07 PM.

Details

Reviewers
zturner
clayborg
Summary

"javadoc" documentation for SBAddress class

Diff Detail

Repository
rL LLVM

Event Timeline

jafl updated this revision to Diff 65578.Jul 26 2016, 1:07 PM
jafl retitled this revision from to Documentation for SBAddress class.
jafl updated this object.
jafl set the repository for this revision to rL LLVM.
jafl added a project: Restricted Project.
Eugene.Zelenko retitled this revision from Documentation for SBAddress class to [LLDB] Documentation for SBAddress class.Jul 26 2016, 4:22 PM
Eugene.Zelenko added reviewers: clayborg, zturner.
Eugene.Zelenko added a subscriber: lldb-commits.
clayborg requested changes to this revision.Jul 27 2016, 12:32 PM
clayborg edited edge metadata.

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

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

148

// Lookup debug and symbol information that contains this address

159

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

166

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

173

Get the module that contains this address

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

180

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

187

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

194

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

201

Get the symbol that contains this address

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

208

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

This revision now requires changes to proceed.Jul 27 2016, 12:32 PM
jafl updated this revision to Diff 66678.Aug 3 2016, 10:47 AM
jafl edited edge metadata.

Incorporated feedback

clayborg requested changes to this revision.Aug 8 2016, 11:12 AM
clayborg edited edge metadata.

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).
This revision now requires changes to proceed.Aug 8 2016, 11:12 AM
jafl updated this revision to Diff 67405.Aug 9 2016, 1:16 PM
jafl edited edge metadata.

Incorporate additional feedback from Greg Clayton.

clayborg accepted this revision.Aug 9 2016, 2:24 PM
clayborg edited edge metadata.

Looks good, thanks for the changes and the documentation.

This revision is now accepted and ready to land.Aug 9 2016, 2:24 PM

Please rebase from trunk and run Clang-format.

jafl updated this revision to Diff 94112.Apr 4 2017, 1:42 PM

Merged from master and ran clang-format