mirror of
https://github.com/opnsense/src.git
synced 2026-02-28 12:20:54 -05:00
318 lines
13 KiB
C++
318 lines
13 KiB
C++
//===-- 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.
|
|
//------------------------------------------------------------------
|
|
~DynamicLoader() override;
|
|
|
|
//------------------------------------------------------------------
|
|
/// 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,
|
|
bool base_addr_is_offset);
|
|
|
|
// Utility method so base classes can share implementation of UpdateLoadedSections
|
|
void
|
|
UpdateLoadedSectionsCommon(lldb::ModuleSP module,
|
|
lldb::addr_t base_addr,
|
|
bool base_addr_is_offset);
|
|
|
|
/// 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.
|
|
virtual lldb::ModuleSP
|
|
LoadModuleAtAddress(const lldb_private::FileSpec &file,
|
|
lldb::addr_t link_map_addr,
|
|
lldb::addr_t base_addr,
|
|
bool base_addr_is_offset);
|
|
|
|
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_
|