Index: include/lldb/API/SBAddress.h =================================================================== --- include/lldb/API/SBAddress.h +++ include/lldb/API/SBAddress.h @@ -15,6 +15,97 @@ 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 &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: SBAddress(); @@ -30,56 +121,185 @@ 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_INVALID_ADDRESS if the address + /// doesn't have a file address (image is from memory only with no + /// representation on disk). + //------------------------------------------------------------------ addr_t GetFileAddress() const; + //------------------------------------------------------------------ + /// Get the load address. + /// + /// @param[in] target + /// The target in which to search. + /// + /// @return + /// The valid load address, or LLDB_INVALID_ADDRESS if the address + /// is currently not loaded. + //------------------------------------------------------------------ addr_t GetLoadAddress(const lldb::SBTarget &target) const; + //------------------------------------------------------------------ + /// Set the section and address within the section. If it succeeds, + /// the object becomes valid. + /// + /// @param[in] section + /// A lldb::SBSection object to use as the section base. + /// + /// @param[in] offset + /// A new offset value for this object. + //------------------------------------------------------------------ void SetAddress(lldb::SBSection section, lldb::addr_t offset); + //------------------------------------------------------------------ + /// Tries to resolve the address within the target's modules. If this + /// fails, assumes the address is absolute, e.g., on the stack or heap. + /// The object becomes valid, but will contain no section, and the + /// offset will match the load address. + /// + /// @param[in] load_addr + /// A new load address for this object. + /// + /// @param[in] target + /// The target within which the load address will be resolved. + //------------------------------------------------------------------ void SetLoadAddress(lldb::addr_t load_addr, lldb::SBTarget &target); + + //------------------------------------------------------------------ + /// Shift the address relative to its current position. + /// + /// @param[in] offset + /// The offset by which the address should be shifted. + //------------------------------------------------------------------ bool OffsetAddress(addr_t offset); + //------------------------------------------------------------------ + /// Dump a description of this object to the given lldb::SBStream. + /// + /// @param[in] description + /// The stream to which to dump the object description. + //------------------------------------------------------------------ bool GetDescription(lldb::SBStream &description); - // The following queries can lookup symbol information for a given address. - // An address might refer to code or data from an existing module, or it - // might refer to something on the stack or heap. The following functions - // will only return valid values if the address has been resolved to a code - // or data address using "void SBAddress::SetLoadAddress(...)" or - // "lldb::SBAddress SBTarget::ResolveLoadAddress (...)". + //------------------------------------------------------------------ + /// Lookup debug and symbol information that contains this address. + /// + /// @param[in] resolve_scope + /// lldb::SymbolContextItem bitmap specifying what to retrieve. + /// + /// @return + /// lldb::SBSymbolContext with the result. + //------------------------------------------------------------------ lldb::SBSymbolContext GetSymbolContext(uint32_t resolve_scope); - // 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. - + //------------------------------------------------------------------ + /// Get the section, if any, to which this address refers. + /// + /// @return + /// The lldb::SBSection (within a module) containing this address. + //------------------------------------------------------------------ lldb::SBSection GetSection(); + //------------------------------------------------------------------ + /// 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. + /// + /// @return + /// The offset for this address, relative to the section. + //------------------------------------------------------------------ lldb::addr_t GetOffset(); + //------------------------------------------------------------------ + /// Get the module that contains this address + /// + /// The returned module will only be valid if this address has a valid + /// section. + /// + /// @return + /// The lldb::SBModule containing this address. + //------------------------------------------------------------------ lldb::SBModule GetModule(); + //------------------------------------------------------------------ + /// 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. + /// + /// @return + /// The lldb::SBCompileUnit (within a module) containing this address. + //------------------------------------------------------------------ lldb::SBCompileUnit GetCompileUnit(); + //------------------------------------------------------------------ + /// 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. + /// + /// @return + /// The lldb::SBFunction containing this address. + //------------------------------------------------------------------ lldb::SBFunction GetFunction(); + //------------------------------------------------------------------ + /// 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. + /// + /// @return + /// The lldb::SBBlock containing this address. + //------------------------------------------------------------------ lldb::SBBlock GetBlock(); + //------------------------------------------------------------------ + /// Get the symbol that contains this address + /// + /// The returned object will only be valid if this address has a valid + /// section. + /// + /// @return + /// The lldb::SBSymbol at this address. + //------------------------------------------------------------------ lldb::SBSymbol GetSymbol(); + //------------------------------------------------------------------ + /// 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. + /// + /// @return + /// The lldb::SBLineEntry specifying the file location that + /// corresponds to this address. + //------------------------------------------------------------------ lldb::SBLineEntry GetLineEntry(); + //------------------------------------------------------------------ + /// @return + /// The classification for this address, e.g., code or data. + //------------------------------------------------------------------ lldb::AddressClass GetAddressClass(); protected: