Here is a refinement of SBAddress. The patch also includes updates to classes referenced by SBAddress.
Does this read better? Thanks, John On Wed, Mar 9, 2016 at 11:56 AM, Jim Ingham <jing...@apple.com> wrote: > In the case of something like SBAddress, I think it would be better to > have a class header that explains file/load addresses and section offset > addresses. Then you can just use the terms in the function documentation, > and they can be shorter and more explicit. Trying to define terms inline > like this makes it harder both to define the term and to say what the > function does. It also means it is hard to avoid redundantly redefining > terms as they are used in different functions. > > Thanks for starting this process! > > Jim > > > > On Mar 9, 2016, at 11:47 AM, John Lindal via lldb-commits < > lldb-commits@lists.llvm.org> wrote: > > > > Having completed my C++ app on top of lldb, I would like to improve the > function-level documentation so others don't have to blunder around in the > dark the way I did :) > > > > Here is a patch for SBAddress.h > > > > If this is the right direction, I will work my way through the rest of > the SB*.h files. > > > > Thanks! > > John Lindal > > > > ----- > > > > diff --git a/include/lldb/API/SBAddress.h b/include/lldb/API/SBAddress.h > > index 4cbbee9..b324e90 100644 > > --- a/include/lldb/API/SBAddress.h > > +++ b/include/lldb/API/SBAddress.h > > @@ -33,27 +33,100 @@ public: > > 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. > > + /// > > + /// If an address comes from a file on disk that has section > > + /// relative addresses, then it has a virtual address that is > > + /// relative to a unique section in the object file. > > + /// > > + /// @return > > + /// The valid file virtual address, or LLDB_INVALID_ADDRESS if > > + /// the address doesn't have a file virtual address (image is > > + /// from memory only with no representation on disk). > > + //------------------------------------------------------------------ > > addr_t > > GetFileAddress () const; > > > > + //------------------------------------------------------------------ > > + /// Get the load address. > > + /// > > + /// If an address comes from a file on disk that has section > > + /// relative addresses, then it has a virtual address that is > > + /// relative to a unique section in the object file. Sections > > + /// get resolved at runtime by DynamicLoader plug-ins as images > > + /// (executables and shared libraries) get loaded/unloaded. If a > > + /// section is loaded, then the load address can be resolved. > > + /// > > + /// @param[in] target > > + /// The target in which to search. > > + /// > > + /// @return > > + /// The valid load virtual 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. If this fails, > > + /// assumes the address is absolute, e.g., on the stack or heap. > If it > > + /// succeeds, the object becomes valid. > > + /// > > + /// @param[in] load_addr > > + /// A new offset value for this object. > > + /// > > + /// @param[in] target > > + /// The target within which the offset is valid. > > + //------------------------------------------------------------------ > > void > > SetLoadAddress (lldb::addr_t load_addr, > > lldb::SBTarget &target); > > + > > + //------------------------------------------------------------------ > > + /// Set the offset for this address, relative to the current > section, > > + /// if any. > > + /// > > + /// @param[in] offset > > + /// A new offset value for this object. > > + //------------------------------------------------------------------ > > + // FIXME: Should this be SetOffsetAddress? > > 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); > > > > @@ -63,10 +136,25 @@ public: > > // 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 symbol information for this address. An address might > > + /// refer to code or data from an existing module, or it might > refer to > > + /// something on the stack or heap. This function 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 (...)". > > + /// > > + /// @param[in] resolve_scope > > + /// lldb::SymbolContextItem value specifying the scope in which > to > > + /// resolve this address. > > + /// > > + /// @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 > > @@ -76,30 +164,67 @@ public: > > // One or more bits from the SymbolContextItem enumerations can be > logically > > // OR'ed together to more efficiently retrieve multiple symbol > objects. > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The lldb::SBSection containing this address. > > + //------------------------------------------------------------------ > > lldb::SBSection > > GetSection (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The offset for this address, relative to the section. > > + //------------------------------------------------------------------ > > lldb::addr_t > > GetOffset (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The module containing this address. > > + //------------------------------------------------------------------ > > lldb::SBModule > > GetModule (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The compile unit containing this address. > > + //------------------------------------------------------------------ > > lldb::SBCompileUnit > > GetCompileUnit (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The function containing this address. > > + //------------------------------------------------------------------ > > lldb::SBFunction > > GetFunction (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The block containing this address. > > + //------------------------------------------------------------------ > > lldb::SBBlock > > GetBlock (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The symbol at this address. > > + //------------------------------------------------------------------ > > lldb::SBSymbol > > GetSymbol (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The lldb::SBLineEntry specifying the file location that > > + /// corresponds to this address. > > + //------------------------------------------------------------------ > > lldb::SBLineEntry > > GetLineEntry (); > > > > + //------------------------------------------------------------------ > > + /// @return section > > + /// The classification for this address. > > + //------------------------------------------------------------------ > > lldb::AddressClass > > GetAddressClass (); > > > > > > _______________________________________________ > > lldb-commits mailing list > > lldb-commits@lists.llvm.org > > http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits > >
diff
Description: Binary data
_______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
