[Lldb-commits] Improving the documentation
John Lindal via lldb-commits
lldb-commits at lists.llvm.org
Wed Mar 9 14:24:00 PST 2016
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 <jingham at 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 at 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 at lists.llvm.org
> > http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20160309/a7d5de56/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: diff
Type: application/octet-stream
Size: 20087 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20160309/a7d5de56/attachment-0001.obj>
More information about the lldb-commits
mailing list