include/lldb/Target/DynamicLoader.h - lldb - Git at Google

 //===-- DynamicLoader.h -----------------------------------------*- C++ -*-===//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//

 #ifndef liblldb_DynamicLoader_h_
 #define liblldb_DynamicLoader_h_

 // Project includes
 #include "lldb/lldb-private.h"
 #include "lldb/Core/Error.h"
 #include "lldb/Core/PluginInterface.h"

 namespace lldb_private {

 //----------------------------------------------------------------------
 /// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
 /// @brief A plug-in interface definition class for dynamic loaders.
 ///
 /// Dynamic loader plug-ins track image (shared library) loading and
 /// unloading. The class is initialized given a live process that is
 /// halted at its entry point or just after attaching.
 ///
 /// Dynamic loader plug-ins can track the process by registering
 /// callbacks using the:
 /// Process::RegisterNotificationCallbacks (const Notifications&)
 /// function.
 ///
 /// Breakpoints can also be set in the process which can register
 /// functions that get called using:
 /// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void *).
 /// These breakpoint callbacks return a boolean value that indicates if
 /// the process should continue or halt and should return the global
 /// setting for this using:
 /// DynamicLoader::StopWhenImagesChange() const.
 //----------------------------------------------------------------------
 class DynamicLoader :
     public PluginInterface
 {
 public:
     //------------------------------------------------------------------
     /// Find a dynamic loader plugin for a given process.
     ///
     /// Scans the installed DynamicLoader plug-ins and tries to find
     /// an instance that can be used to track image changes in \a
     /// process.
     ///
     /// @param[in] process
     ///     The process for which to try and locate a dynamic loader
     ///     plug-in instance.
     ///
     /// @param[in] plugin_name
     ///     An optional name of a specific dynamic loader plug-in that
     ///     should be used. If NULL, pick the best plug-in.
     //------------------------------------------------------------------
     static DynamicLoader*
     FindPlugin (Process *process, const char *plugin_name);

     //------------------------------------------------------------------
     /// Construct with a process.
     //------------------------------------------------------------------
     DynamicLoader (Process *process);

     //------------------------------------------------------------------
     /// Destructor.
     ///
     /// The destructor is virtual since this class is designed to be
     /// inherited from by the plug-in instance.
     //------------------------------------------------------------------
     virtual
     ~DynamicLoader ();

     //------------------------------------------------------------------
     /// Called after attaching a process.
     ///
     /// Allow DynamicLoader plug-ins to execute some code after
     /// attaching to a process.
     //------------------------------------------------------------------
     virtual void
     DidAttach () = 0;

     //------------------------------------------------------------------
     /// Called after launching a process.
     ///
     /// Allow DynamicLoader plug-ins to execute some code after
     /// the process has stopped for the first time on launch.
     //------------------------------------------------------------------
     virtual void
     DidLaunch () = 0;


     //------------------------------------------------------------------
     /// Helper function that can be used to detect when a process has
     /// called exec and is now a new and different process. This can
     /// be called when necessary to try and detect the exec. The process
     /// might be able to answer this question, but sometimes it might
     /// not be able and the dynamic loader often knows what the program
     /// entry point is. So the process and the dynamic loader can work
     /// together to detect this.
     //------------------------------------------------------------------
     virtual bool
     ProcessDidExec ()
     {
         return false;
     }
     //------------------------------------------------------------------
     /// Get whether the process should stop when images change.
     ///
     /// When images (executables and shared libraries) get loaded or
     /// unloaded, often debug sessions will want to try and resolve or
     /// unresolve breakpoints that are set in these images. Any
     /// breakpoints set by DynamicLoader plug-in instances should
     /// return this value to ensure consistent debug session behaviour.
     ///
     /// @return
     ///     Returns \b true if the process should stop when images
     ///     change, \b false if the process should resume.
     //------------------------------------------------------------------
     bool
     GetStopWhenImagesChange () const;

     //------------------------------------------------------------------
     /// Set whether the process should stop when images change.
     ///
     /// When images (executables and shared libraries) get loaded or
     /// unloaded, often debug sessions will want to try and resolve or
     /// unresolve breakpoints that are set in these images. The default
     /// is set so that the process stops when images change, but this
     /// can be overridden using this function callback.
     ///
     /// @param[in] stop
     ///     Boolean value that indicates whether the process should stop
     ///     when images change.
     //------------------------------------------------------------------
     void
     SetStopWhenImagesChange (bool stop);

     //------------------------------------------------------------------
     /// Provides a plan to step through the dynamic loader trampoline
     /// for the current state of \a thread.
     ///
     ///
     /// @param[in] stop_others
     ///     Whether the plan should be set to stop other threads.
     ///
     /// @return
     ///    A pointer to the plan (caller owned) or NULL if we are not at such
     ///    a trampoline.
     //------------------------------------------------------------------
     virtual lldb::ThreadPlanSP
     GetStepThroughTrampolinePlan (Thread &thread, bool stop_others) = 0;


     //------------------------------------------------------------------
     /// Some dynamic loaders provide features where there are a group of symbols "equivalent to"
     /// a given symbol one of which will be chosen when the symbol is bound.  If you want to
     /// set a breakpoint on one of these symbols, you really need to set it on all the
     /// equivalent symbols.
     ///
     ///
     /// @param[in] original_symbol
     ///     The symbol for which we are finding equivalences.
     ///
     /// @param[in] module_list
     ///     The set of modules in which to search.
     ///
     /// @param[out] equivalent_symbols
     ///     The equivalent symbol list - any equivalent symbols found are appended to this list.
     ///
     /// @return
     ///    Number of equivalent symbols found.
     //------------------------------------------------------------------
     virtual size_t
     FindEquivalentSymbols (Symbol *original_symbol, ModuleList &module_list, SymbolContextList &equivalent_symbols)
     {
         return 0;
     }

     //------------------------------------------------------------------
     /// Ask if it is ok to try and load or unload an shared library
     /// (image).
     ///
     /// The dynamic loader often knows when it would be ok to try and
     /// load or unload a shared library. This function call allows the
     /// dynamic loader plug-ins to check any current dyld state to make
     /// sure it is an ok time to load a shared library.
     ///
     /// @return
     ///     \b true if it is currently ok to try and load a shared
     ///     library into the process, \b false otherwise.
     //------------------------------------------------------------------
     virtual Error
     CanLoadImage () = 0;

     //------------------------------------------------------------------
     /// Ask if the eh_frame information for the given SymbolContext should
     /// be relied on even when it's the first frame in a stack unwind.
     ///
     /// The CFI instructions from the eh_frame section are normally only
     /// valid at call sites -- places where a program could throw an
     /// exception and need to unwind out.  But some Modules may be known
     /// to the system as having reliable eh_frame information at all call
     /// sites.  This would be the case if the Module's contents are largely
     /// hand-written assembly with hand-written eh_frame information.
     /// Normally when unwinding from a function at the beginning of a stack
     /// unwind lldb will examine the assembly instructions to understand
     /// how the stack frame is set up and where saved registers are stored.
     /// But with hand-written assembly this is not reliable enough -- we need
     /// to consult those function's hand-written eh_frame information.
     ///
     /// @return
     ///     \b True if the symbol context should use eh_frame instructions
     ///     unconditionally when unwinding from this frame.  Else \b false,
     ///     the normal lldb unwind behavior of only using eh_frame when the
     ///     function appears in the middle of the stack.
     //------------------------------------------------------------------
     virtual bool
     AlwaysRelyOnEHUnwindInfo (SymbolContext &sym_ctx)
     {
        return false;
     }

     //------------------------------------------------------------------
     /// Retrieves the per-module TLS block for a given thread.
     ///
     /// @param[in] module
     ///     The module to query TLS data for.
     ///
     /// @param[in] thread
     ///     The specific thread to query TLS data for.
     ///
     /// @return
     ///     If the given thread has TLS data allocated for the
     ///     module, the address of the TLS block. Otherwise
     ///     LLDB_INVALID_ADDRESS is returned.
     //------------------------------------------------------------------
     virtual lldb::addr_t
     GetThreadLocalData (const lldb::ModuleSP module, const lldb::ThreadSP thread)
     {
         return LLDB_INVALID_ADDRESS;
     }

 protected:
     //------------------------------------------------------------------
     // Utility methods for derived classes
     //------------------------------------------------------------------

     /// Checks to see if the target module has changed, updates the target
     /// accordingly and returns the target executable module.
     lldb::ModuleSP
     GetTargetExecutable();

     /// Updates the load address of every allocatable section in @p module.
     ///
     /// @param module The module to traverse.
     ///
     /// @param link_map_addr The virtual address of the link map for the @p module.
     ///
     /// @param base_addr The virtual base address @p module is loaded at.
     virtual void
     UpdateLoadedSections(lldb::ModuleSP module,
                          lldb::addr_t link_map_addr,
                          lldb::addr_t base_addr);

     // Utility method so base classes can share implementation of UpdateLoadedSections
     void
     UpdateLoadedSectionsCommon(lldb::ModuleSP module,
                                lldb::addr_t base_addr);

     /// Removes the loaded sections from the target in @p module.
     ///
     /// @param module The module to traverse.
     virtual void
     UnloadSections(const lldb::ModuleSP module);

     // Utility method so base classes can share implementation of UnloadSections
     void
     UnloadSectionsCommon(const lldb::ModuleSP module);

     /// Locates or creates a module given by @p file and updates/loads the
     /// resulting module at the virtual base address @p base_addr.
     lldb::ModuleSP
     LoadModuleAtAddress(const lldb_private::FileSpec &file, lldb::addr_t link_map_addr, lldb::addr_t base_addr);

     const lldb_private::SectionList *
     GetSectionListFromModule(const lldb::ModuleSP module) const;

     // Read an unsigned int of the given size from memory at the given addr.
     // Return -1 if the read fails, otherwise return the result as an int64_t.
     int64_t
     ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes);

     // Read a pointer from memory at the given addr.
     // Return LLDB_INVALID_ADDRESS if the read fails.
     lldb::addr_t
     ReadPointer(lldb::addr_t addr);

     //------------------------------------------------------------------
     // Member variables.
     //------------------------------------------------------------------
     Process* m_process; ///< The process that this dynamic loader plug-in is tracking.
 private:
     DISALLOW_COPY_AND_ASSIGN (DynamicLoader);

 };

 } // namespace lldb_private

 #endif  // liblldb_DynamicLoader_h_
	//===-- DynamicLoader.h ------------------------------------------ C++ --===//
	//
	// The LLVM Compiler Infrastructure
	//
	// This file is distributed under the University of Illinois Open Source
	// License. See LICENSE.TXT for details.
	//
	//===----------------------------------------------------------------------===//

	#ifndef liblldb_DynamicLoader_h_
	#define liblldb_DynamicLoader_h_

	// Project includes
	#include "lldb/lldb-private.h"
	#include "lldb/Core/Error.h"
	#include "lldb/Core/PluginInterface.h"

	namespace lldb_private {

	//----------------------------------------------------------------------
	/// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
	/// @brief A plug-in interface definition class for dynamic loaders.
	///
	/// Dynamic loader plug-ins track image (shared library) loading and
	/// unloading. The class is initialized given a live process that is
	/// halted at its entry point or just after attaching.
	///
	/// Dynamic loader plug-ins can track the process by registering
	/// callbacks using the:
	/// Process::RegisterNotificationCallbacks (const Notifications&)
	/// function.
	///
	/// Breakpoints can also be set in the process which can register
	/// functions that get called using:
	/// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void *).
	/// These breakpoint callbacks return a boolean value that indicates if
	/// the process should continue or halt and should return the global
	/// setting for this using:
	/// DynamicLoader::StopWhenImagesChange() const.
	//----------------------------------------------------------------------
	class DynamicLoader :
	public PluginInterface
	{
	public:
	//------------------------------------------------------------------
	/// Find a dynamic loader plugin for a given process.
	///
	/// Scans the installed DynamicLoader plug-ins and tries to find
	/// an instance that can be used to track image changes in \a
	/// process.
	///
	/// @param[in] process
	/// The process for which to try and locate a dynamic loader
	/// plug-in instance.
	///
	/// @param[in] plugin_name
	/// An optional name of a specific dynamic loader plug-in that
	/// should be used. If NULL, pick the best plug-in.
	//------------------------------------------------------------------
	static DynamicLoader*
	FindPlugin (Process process, const char plugin_name);

	//------------------------------------------------------------------
	/// Construct with a process.
	//------------------------------------------------------------------
	DynamicLoader (Process *process);

	//------------------------------------------------------------------
	/// Destructor.
	///
	/// The destructor is virtual since this class is designed to be
	/// inherited from by the plug-in instance.
	//------------------------------------------------------------------
	virtual
	~DynamicLoader ();

	//------------------------------------------------------------------
	/// Called after attaching a process.
	///
	/// Allow DynamicLoader plug-ins to execute some code after
	/// attaching to a process.
	//------------------------------------------------------------------
	virtual void
	DidAttach () = 0;

	//------------------------------------------------------------------
	/// Called after launching a process.
	///
	/// Allow DynamicLoader plug-ins to execute some code after
	/// the process has stopped for the first time on launch.
	//------------------------------------------------------------------
	virtual void
	DidLaunch () = 0;


	//------------------------------------------------------------------
	/// Helper function that can be used to detect when a process has
	/// called exec and is now a new and different process. This can
	/// be called when necessary to try and detect the exec. The process
	/// might be able to answer this question, but sometimes it might
	/// not be able and the dynamic loader often knows what the program
	/// entry point is. So the process and the dynamic loader can work
	/// together to detect this.
	//------------------------------------------------------------------
	virtual bool
	ProcessDidExec ()
	{
	return false;
	}
	//------------------------------------------------------------------
	/// Get whether the process should stop when images change.
	///
	/// When images (executables and shared libraries) get loaded or
	/// unloaded, often debug sessions will want to try and resolve or
	/// unresolve breakpoints that are set in these images. Any
	/// breakpoints set by DynamicLoader plug-in instances should
	/// return this value to ensure consistent debug session behaviour.
	///
	/// @return
	/// Returns \b true if the process should stop when images
	/// change, \b false if the process should resume.
	//------------------------------------------------------------------
	bool
	GetStopWhenImagesChange () const;

	//------------------------------------------------------------------
	/// Set whether the process should stop when images change.
	///
	/// When images (executables and shared libraries) get loaded or
	/// unloaded, often debug sessions will want to try and resolve or
	/// unresolve breakpoints that are set in these images. The default
	/// is set so that the process stops when images change, but this
	/// can be overridden using this function callback.
	///
	/// @param[in] stop
	/// Boolean value that indicates whether the process should stop
	/// when images change.
	//------------------------------------------------------------------
	void
	SetStopWhenImagesChange (bool stop);

	//------------------------------------------------------------------
	/// Provides a plan to step through the dynamic loader trampoline
	/// for the current state of \a thread.
	///
	///
	/// @param[in] stop_others
	/// Whether the plan should be set to stop other threads.
	///
	/// @return
	/// A pointer to the plan (caller owned) or NULL if we are not at such
	/// a trampoline.
	//------------------------------------------------------------------
	virtual lldb::ThreadPlanSP
	GetStepThroughTrampolinePlan (Thread &thread, bool stop_others) = 0;


	//------------------------------------------------------------------
	/// Some dynamic loaders provide features where there are a group of symbols "equivalent to"
	/// a given symbol one of which will be chosen when the symbol is bound. If you want to
	/// set a breakpoint on one of these symbols, you really need to set it on all the
	/// equivalent symbols.
	///
	///
	/// @param[in] original_symbol
	/// The symbol for which we are finding equivalences.
	///
	/// @param[in] module_list
	/// The set of modules in which to search.
	///
	/// @param[out] equivalent_symbols
	/// The equivalent symbol list - any equivalent symbols found are appended to this list.
	///
	/// @return
	/// Number of equivalent symbols found.
	//------------------------------------------------------------------
	virtual size_t
	FindEquivalentSymbols (Symbol *original_symbol, ModuleList &module_list, SymbolContextList &equivalent_symbols)
	{
	return 0;
	}

	//------------------------------------------------------------------
	/// Ask if it is ok to try and load or unload an shared library
	/// (image).
	///
	/// The dynamic loader often knows when it would be ok to try and
	/// load or unload a shared library. This function call allows the
	/// dynamic loader plug-ins to check any current dyld state to make
	/// sure it is an ok time to load a shared library.
	///
	/// @return
	/// \b true if it is currently ok to try and load a shared
	/// library into the process, \b false otherwise.
	//------------------------------------------------------------------
	virtual Error
	CanLoadImage () = 0;

	//------------------------------------------------------------------
	/// Ask if the eh_frame information for the given SymbolContext should
	/// be relied on even when it's the first frame in a stack unwind.
	///
	/// The CFI instructions from the eh_frame section are normally only
	/// valid at call sites -- places where a program could throw an
	/// exception and need to unwind out. But some Modules may be known
	/// to the system as having reliable eh_frame information at all call
	/// sites. This would be the case if the Module's contents are largely
	/// hand-written assembly with hand-written eh_frame information.
	/// Normally when unwinding from a function at the beginning of a stack
	/// unwind lldb will examine the assembly instructions to understand
	/// how the stack frame is set up and where saved registers are stored.
	/// But with hand-written assembly this is not reliable enough -- we need
	/// to consult those function's hand-written eh_frame information.
	///
	/// @return
	/// \b True if the symbol context should use eh_frame instructions
	/// unconditionally when unwinding from this frame. Else \b false,
	/// the normal lldb unwind behavior of only using eh_frame when the
	/// function appears in the middle of the stack.
	//------------------------------------------------------------------
	virtual bool
	AlwaysRelyOnEHUnwindInfo (SymbolContext &sym_ctx)
	{
	return false;
	}

	//------------------------------------------------------------------
	/// Retrieves the per-module TLS block for a given thread.
	///
	/// @param[in] module
	/// The module to query TLS data for.
	///
	/// @param[in] thread
	/// The specific thread to query TLS data for.
	///
	/// @return
	/// If the given thread has TLS data allocated for the
	/// module, the address of the TLS block. Otherwise
	/// LLDB_INVALID_ADDRESS is returned.
	//------------------------------------------------------------------
	virtual lldb::addr_t
	GetThreadLocalData (const lldb::ModuleSP module, const lldb::ThreadSP thread)
	{
	return LLDB_INVALID_ADDRESS;
	}

	protected:
	//------------------------------------------------------------------
	// Utility methods for derived classes
	//------------------------------------------------------------------

	/// Checks to see if the target module has changed, updates the target
	/// accordingly and returns the target executable module.
	lldb::ModuleSP
	GetTargetExecutable();

	/// Updates the load address of every allocatable section in @p module.
	///
	/// @param module The module to traverse.
	///
	/// @param link_map_addr The virtual address of the link map for the @p module.
	///
	/// @param base_addr The virtual base address @p module is loaded at.
	virtual void
	UpdateLoadedSections(lldb::ModuleSP module,
	lldb::addr_t link_map_addr,
	lldb::addr_t base_addr);

	// Utility method so base classes can share implementation of UpdateLoadedSections
	void
	UpdateLoadedSectionsCommon(lldb::ModuleSP module,
	lldb::addr_t base_addr);

	/// Removes the loaded sections from the target in @p module.
	///
	/// @param module The module to traverse.
	virtual void
	UnloadSections(const lldb::ModuleSP module);

	// Utility method so base classes can share implementation of UnloadSections
	void
	UnloadSectionsCommon(const lldb::ModuleSP module);

	/// Locates or creates a module given by @p file and updates/loads the
	/// resulting module at the virtual base address @p base_addr.
	lldb::ModuleSP
	LoadModuleAtAddress(const lldb_private::FileSpec &file, lldb::addr_t link_map_addr, lldb::addr_t base_addr);

	const lldb_private::SectionList *
	GetSectionListFromModule(const lldb::ModuleSP module) const;

	// Read an unsigned int of the given size from memory at the given addr.
	// Return -1 if the read fails, otherwise return the result as an int64_t.
	int64_t
	ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes);

	// Read a pointer from memory at the given addr.
	// Return LLDB_INVALID_ADDRESS if the read fails.
	lldb::addr_t
	ReadPointer(lldb::addr_t addr);

	//------------------------------------------------------------------
	// Member variables.
	//------------------------------------------------------------------
	Process* m_process; ///< The process that this dynamic loader plug-in is tracking.
	private:
	DISALLOW_COPY_AND_ASSIGN (DynamicLoader);

	};

	} // namespace lldb_private

	#endif // liblldb_DynamicLoader_h_