Re: [Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class
Sorry for missing this! What options should I use when running it? On Mon, Sep 19, 2016 at 2:31 PM, Eugene Zelenko wrote: > Eugene.Zelenko added a subscriber: Eugene.Zelenko. > Eugene.Zelenko added a comment. > > Please rebase from trunk and run Clang-format. > > > 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
Re: [Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class
Eugene.Zelenko added a subscriber: Eugene.Zelenko. Eugene.Zelenko added a comment. Please rebase from trunk and run Clang-format. 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
Re: [Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class
clayborg accepted this revision. clayborg added a comment. This revision is now accepted and ready to land. Looks good, thanks for the changes and the documentation. 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
Re: [Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class
jafl updated this revision to Diff 67405.
jafl added a comment.
Incorporate additional feedback from Greg Clayton.
Repository:
rL LLVM
https://reviews.llvm.org/D22831
Files:
include/lldb/API/SBAddress.h
Index: include/lldb/API/SBAddress.h
===
--- include/lldb/API/SBAddress.h
+++ include/lldb/API/SBAddress.h
@@ -15,6 +15,93 @@
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 &a
Re: [Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class
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 ___ lldb-commits mailing list lldb-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
Re: [Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class
jafl updated this revision to Diff 66678.
jafl added a comment.
Incorporated feedback
Repository:
rL LLVM
https://reviews.llvm.org/D22831
Files:
include/lldb/API/SBAddress.h
Index: include/lldb/API/SBAddress.h
===
--- include/lldb/API/SBAddress.h
+++ include/lldb/API/SBAddress.h
@@ -15,6 +15,74 @@
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 can represent 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.
+///
+/// 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:
@@ -33,73 +101,203 @@
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_INVALI
Re: [Lldb-commits] [PATCH] D22831: [LLDB] Documentation for SBAddress class
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
