diff --git a/include/lldb/API/SBAddress.h b/include/lldb/API/SBAddress.h index 4cbbee9..5217a5b 100644 --- a/include/lldb/API/SBAddress.h +++ b/include/lldb/API/SBAddress.h @@ -15,6 +15,33 @@ 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. +/// +/// 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 +60,163 @@ 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. + /// + /// @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. + /// + /// @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 symbol information for 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. - + //------------------------------------------------------------------ + /// @return + /// The lldb::SBSection (within a module) containing this address. + //------------------------------------------------------------------ lldb::SBSection GetSection (); + //------------------------------------------------------------------ + /// @return + /// The offset for this address, relative to the section. + //------------------------------------------------------------------ lldb::addr_t GetOffset (); + //------------------------------------------------------------------ + /// @return + /// The lldb::SBModule containing this address. + //------------------------------------------------------------------ lldb::SBModule GetModule (); + //------------------------------------------------------------------ + /// @return + /// The lldb::SBCompileUnit (within a module) containing this address. + //------------------------------------------------------------------ lldb::SBCompileUnit GetCompileUnit (); + //------------------------------------------------------------------ + /// @return + /// The lldb::SBFunction containing this address. + //------------------------------------------------------------------ lldb::SBFunction GetFunction (); + //------------------------------------------------------------------ + /// @return + /// The lldb::SBBlock containing this address. + //------------------------------------------------------------------ lldb::SBBlock GetBlock (); + //------------------------------------------------------------------ + /// @return + /// The lldb::SBSymbol at this address. + //------------------------------------------------------------------ lldb::SBSymbol GetSymbol (); + //------------------------------------------------------------------ + /// @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 (); diff --git a/include/lldb/API/SBBlock.h b/include/lldb/API/SBBlock.h index a18eab02..c31e0b4 100644 --- a/include/lldb/API/SBBlock.h +++ b/include/lldb/API/SBBlock.h @@ -17,6 +17,11 @@ namespace lldb { +//------------------------------------------------------------------ +/// \class SBBlock +/// +/// Represents a block scope within the executable being debugged. +//------------------------------------------------------------------ class LLDB_API SBBlock { public: @@ -33,6 +38,11 @@ public: bool IsInlined () const; + //------------------------------------------------------------------ + /// @return + /// true if the object is valid. If the object is invalid, it is + /// not safe to call any other methods. + //------------------------------------------------------------------ bool IsValid () const; diff --git a/include/lldb/API/SBBroadcaster.h b/include/lldb/API/SBBroadcaster.h index 28b6686..91b1914 100644 --- a/include/lldb/API/SBBroadcaster.h +++ b/include/lldb/API/SBBroadcaster.h @@ -40,9 +40,37 @@ public: void BroadcastEvent (const lldb::SBEvent &event, bool unique = false); + //------------------------------------------------------------------ + /// Adds existing events to a newly registered listener. + /// Automatically called by AddListener(). + //------------------------------------------------------------------ + // + // FIXME: Should this be exposed in the API layer? void AddInitialEventsToListener (const lldb::SBListener &listener, uint32_t requested_events); + //------------------------------------------------------------------ + /// Listen for any events specified by \a event_mask. + /// + /// Only one listener can listen to each event bit in a given + /// Broadcaster. Once a listener has acquired an event bit, no + /// other broadcaster will have access to it until it is + /// relinquished by the first listener that gets it. The actual + /// event bits that get acquired by \a listener may be different + /// from what is requested in \a event_mask, and to track this the + /// actual event bits that are acquired get returned. + /// + /// @param[in] listener + /// The Listener object that wants to monitor the events that + /// get broadcast by this object. + /// + /// @param[in] event_mask + /// A bit mask that indicates which events the listener is + /// asking to monitor. + /// + /// @return + /// The actual event bits that were acquired by \a listener. + //------------------------------------------------------------------ uint32_t AddListener (const lldb::SBListener &listener, uint32_t event_mask); diff --git a/include/lldb/API/SBCompileUnit.h b/include/lldb/API/SBCompileUnit.h index a53d556..fff6d4b 100644 --- a/include/lldb/API/SBCompileUnit.h +++ b/include/lldb/API/SBCompileUnit.h @@ -15,6 +15,11 @@ namespace lldb { +//------------------------------------------------------------------ +/// \class SBCompileUnit +/// +/// Represents a compilation unit, i.e., a source file. +//------------------------------------------------------------------ class LLDB_API SBCompileUnit { public: @@ -28,9 +33,18 @@ public: const lldb::SBCompileUnit & operator = (const lldb::SBCompileUnit &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; + //------------------------------------------------------------------ + /// @return + /// The lldb::SBFileSpec for the source file. + //------------------------------------------------------------------ lldb::SBFileSpec GetFileSpec () const; @@ -51,9 +65,24 @@ public: lldb::SBFileSpec *inline_file_spec, bool exact) const; + //------------------------------------------------------------------ + /// Get the specified header file, by index. + /// + /// @param[in] idx + /// The index of the requested support file. + /// + /// @return + /// The lldb::SBFileSpec for the requested support file. + //------------------------------------------------------------------ SBFileSpec GetSupportFileAtIndex (uint32_t idx) const; + //------------------------------------------------------------------ + /// Get the number of header files used during compilation. + /// + /// @return + /// The number of support files. + //------------------------------------------------------------------ uint32_t GetNumSupportFiles () const; diff --git a/include/lldb/API/SBModule.h b/include/lldb/API/SBModule.h index 4030d2b..3065660 100644 --- a/include/lldb/API/SBModule.h +++ b/include/lldb/API/SBModule.h @@ -18,6 +18,13 @@ namespace lldb { +//------------------------------------------------------------------ +/// \class SBModule +/// +/// Represents a module within the executable being debugged. Each module +/// is constructed from multiple compilation units (lldb::SBCompileUnit) +/// and contains multiple sections (lldb::SBSection). +//------------------------------------------------------------------ class LLDB_API SBModule { public: @@ -36,6 +43,11 @@ public: ~SBModule (); + //------------------------------------------------------------------ + /// @return + /// true if the object is valid. If the object is invalid, it is + /// not safe to call any other methods. + //------------------------------------------------------------------ bool IsValid () const; @@ -43,20 +55,20 @@ public: Clear(); //------------------------------------------------------------------ - /// Get const accessor for the module file specification. + /// Get the module file specification. /// /// This function returns the file for the module on the host system /// that is running LLDB. This can differ from the path on the /// platform since we might be doing remote debugging. /// /// @return - /// A const reference to the file specification object. + /// The lldb::SBFileSpec. //------------------------------------------------------------------ lldb::SBFileSpec GetFileSpec () const; //------------------------------------------------------------------ - /// Get accessor for the module platform file specification. + /// Get the module platform file specification. /// /// Platform file refers to the path of the module as it is known on /// the remote system on which it is being debugged. For local @@ -68,7 +80,7 @@ public: /// The file could also be cached in a local developer kit directory. /// /// @return - /// A const reference to the file specification object. + /// The lldb::SBFileSpec. //------------------------------------------------------------------ lldb::SBFileSpec GetPlatformFileSpec () const; @@ -77,7 +89,7 @@ public: SetPlatformFileSpec (const lldb::SBFileSpec &platform_file); //------------------------------------------------------------------ - /// Get accessor for the remote install path for a module. + /// Get the remote install path for a module. /// /// When debugging to a remote platform by connecting to a remote /// platform, the install path of the module can be set. If the @@ -86,13 +98,13 @@ public: /// to launching. /// /// @return - /// A file specification object. + /// The lldb::SBFileSpec. //------------------------------------------------------------------ lldb::SBFileSpec GetRemoteInstallFileSpec (); //------------------------------------------------------------------ - /// Set accessor for the remote install path for a module. + /// Set the remote install path for a module. /// /// When debugging to a remote platform by connecting to a remote /// platform, the install path of the module can be set. If the @@ -108,6 +120,9 @@ public: /// /// @param[in] file /// A file specification object. + /// + /// @return + /// true if successful, i.e., this module object is valid. //------------------------------------------------------------------ bool SetRemoteInstallFileSpec (lldb::SBFileSpec &file); @@ -185,7 +200,7 @@ public: /// See FunctionNameType for more details. /// /// @return - /// A lldb::SBSymbolContextList that gets filled in with all of + /// lldb::SBSymbolContextList that gets filled in with all of /// the symbol contexts for all the matches. //------------------------------------------------------------------ lldb::SBSymbolContextList @@ -206,7 +221,7 @@ public: /// Allow the number of matches to be limited to \a max_matches. /// /// @return - /// A list of matched variables in an SBValueList. + /// A list of matched variables in an lldb::SBValueList. //------------------------------------------------------------------ lldb::SBValueList FindGlobalVariables (lldb::SBTarget &target, @@ -224,7 +239,7 @@ public: /// for. /// /// @return - /// An SBValue that gets filled in with the found variable (if any). + /// lldb::SBValue that gets filled in with the found variable (if any). //------------------------------------------------------------------ lldb::SBValue FindFirstGlobalVariable (lldb::SBTarget &target, const char *name); @@ -319,7 +334,7 @@ public: uint32_t num_versions); //------------------------------------------------------------------ - /// Get accessor for the symbol file specification. + /// Get the symbol file. /// /// When debugging an object file an additional debug information can /// be provided in separate file. Therefore if you debugging something @@ -327,7 +342,7 @@ public: /// in folder like '/usr/lib/liba.dylib.dSYM/'. /// /// @return - /// A const reference to the file specification object. + /// The lldb::SBFileSpec. //------------------------------------------------------------------ lldb::SBFileSpec GetSymbolFileSpec() const; diff --git a/include/lldb/Core/Broadcaster.h b/include/lldb/Core/Broadcaster.h index 8a61432..56b8edc 100644 --- a/include/lldb/Core/Broadcaster.h +++ b/include/lldb/Core/Broadcaster.h @@ -348,6 +348,10 @@ public: m_broadcaster_sp->Clear(); } + //------------------------------------------------------------------ + /// Hook for derived classes to add existing events to a newly + /// registered listener. + //------------------------------------------------------------------ virtual void AddInitialEventsToListener (lldb::ListenerSP listener_sp, uint32_t requested_events); diff --git a/include/lldb/Core/Section.h b/include/lldb/Core/Section.h index 8c92f1b..0f563fc 100644 --- a/include/lldb/Core/Section.h +++ b/include/lldb/Core/Section.h @@ -310,7 +310,7 @@ public: //------------------------------------------------------------------ /// Get the shared reference to the section data from the object /// file that the section resides in. No copies of the data will be - /// make unless the object file has been read from memory. If the + /// made unless the object file has been read from memory. If the /// object file is on disk, it will shared the mmap data for the /// entire object file. /// diff --git a/include/lldb/lldb-enumerations.h b/include/lldb/lldb-enumerations.h index 89dbeb3..f1f89d8 100644 --- a/include/lldb/lldb-enumerations.h +++ b/include/lldb/lldb-enumerations.h @@ -774,7 +774,7 @@ namespace lldb { //---------------------------------------------------------------------- // Address Class // - // A way of classifying an address used for disassembling and setting + // A way of classifying an address used for disassembling and setting // breakpoints. Many object files can track exactly what parts of their // object files are code, data and other information. This is of course // above and beyond just looking at the section types. For example, code