LLDB  mainline
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
lldb_private::DynamicLoader Class Referenceabstract

A plug-in interface definition class for dynamic loaders. More...

#include "lldb/Target/DynamicLoader.h"

Inheritance diagram for lldb_private::DynamicLoader:
Inheritance graph
[legend]
Collaboration diagram for lldb_private::DynamicLoader:
Collaboration graph
[legend]

Public Member Functions

 DynamicLoader (Process *process)
 Construct with a process. More...
 
 ~DynamicLoader () override
 Destructor. More...
 
virtual void DidAttach ()=0
 Called after attaching a process. More...
 
virtual void DidLaunch ()=0
 Called after launching a process. More...
 
virtual bool ProcessDidExec ()
 Helper function that can be used to detect when a process has called exec and is now a new and different process. More...
 
bool GetStopWhenImagesChange () const
 Get whether the process should stop when images change. More...
 
void SetStopWhenImagesChange (bool stop)
 Set whether the process should stop when images change. More...
 
virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan (Thread &thread, bool stop_others)=0
 Provides a plan to step through the dynamic loader trampoline for the current state of thread. More...
 
virtual size_t FindEquivalentSymbols (Symbol *original_symbol, ModuleList &module_list, SymbolContextList &equivalent_symbols)
 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. More...
 
virtual Status CanLoadImage ()=0
 Ask if it is ok to try and load or unload an shared library (image). More...
 
virtual bool AlwaysRelyOnEHUnwindInfo (SymbolContext &sym_ctx)
 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. More...
 
virtual lldb::addr_t GetThreadLocalData (const lldb::ModuleSP module, const lldb::ThreadSP thread, lldb::addr_t tls_file_addr)
 Retrieves the per-module TLS block for a given thread. More...
 
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)
 Locates or creates a module given by file and updates/loads the resulting module at the virtual base address base_addr. More...
 
virtual bool GetSharedCacheInformation (lldb::addr_t &base_address, UUID &uuid, LazyBool &using_shared_cache, LazyBool &private_shared_cache)
 Get information about the shared cache for a process, if possible. More...
 
- Public Member Functions inherited from lldb_private::PluginInterface
virtual ~PluginInterface ()
 
virtual ConstString GetPluginName ()=0
 
virtual uint32_t GetPluginVersion ()=0
 

Static Public Member Functions

static DynamicLoaderFindPlugin (Process *process, const char *plugin_name)
 Find a dynamic loader plugin for a given process. More...
 

Protected Member Functions

lldb::ModuleSP GetTargetExecutable ()
 Checks to see if the target module has changed, updates the target accordingly and returns the target executable module. More...
 
virtual void UpdateLoadedSections (lldb::ModuleSP module, lldb::addr_t link_map_addr, lldb::addr_t base_addr, bool base_addr_is_offset)
 Updates the load address of every allocatable section in module. More...
 
void UpdateLoadedSectionsCommon (lldb::ModuleSP module, lldb::addr_t base_addr, bool base_addr_is_offset)
 
virtual void UnloadSections (const lldb::ModuleSP module)
 Removes the loaded sections from the target in module. More...
 
void UnloadSectionsCommon (const lldb::ModuleSP module)
 
const lldb_private::SectionListGetSectionListFromModule (const lldb::ModuleSP module) const
 
int64_t ReadUnsignedIntWithSizeInBytes (lldb::addr_t addr, int size_in_bytes)
 
lldb::addr_t ReadPointer (lldb::addr_t addr)
 
void LoadOperatingSystemPlugin (bool flush)
 

Protected Attributes

Processm_process
 The process that this dynamic loader plug-in is tracking. More...
 

Detailed Description

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.

Definition at line 64 of file DynamicLoader.h.

Constructor & Destructor Documentation

◆ DynamicLoader()

DynamicLoader::DynamicLoader ( Process process)

Construct with a process.

Definition at line 61 of file DynamicLoader.cpp.

References ~DynamicLoader().

◆ ~DynamicLoader()

DynamicLoader::~DynamicLoader ( )
overridedefault

Destructor.

The destructor is virtual since this class is designed to be inherited from by the plug-in instance.

Referenced by DynamicLoader().

Member Function Documentation

◆ AlwaysRelyOnEHUnwindInfo()

virtual bool lldb_private::DynamicLoader::AlwaysRelyOnEHUnwindInfo ( SymbolContext sym_ctx)
inlinevirtual

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.

Returns
True if the symbol context should use eh_frame instructions unconditionally when unwinding from this frame. Else false, the normal lldb unwind behavior of only using eh_frame when the function appears in the middle of the stack.

Reimplemented in DynamicLoaderPOSIXDYLD, and lldb_private::DynamicLoaderDarwin.

Definition at line 203 of file DynamicLoader.h.

◆ CanLoadImage()

virtual Status lldb_private::DynamicLoader::CanLoadImage ( )
pure virtual

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.

Returns
true if it is currently ok to try and load a shared library into the process, false otherwise.

Implemented in DynamicLoaderMacOSXDYLD, DynamicLoaderDarwinKernel, DynamicLoaderMacOS, DynamicLoaderPOSIXDYLD, DynamicLoaderStatic, DynamicLoaderHexagonDYLD, and lldb_private::DynamicLoaderWindowsDYLD.

Referenced by PlatformPOSIX::EvaluateLibdlExpression(), and FindEquivalentSymbols().

◆ DidAttach()

virtual void lldb_private::DynamicLoader::DidAttach ( )
pure virtual

◆ DidLaunch()

virtual void lldb_private::DynamicLoader::DidLaunch ( )
pure virtual

Called after launching a process.

Allow DynamicLoader plug-ins to execute some code after the process has stopped for the first time on launch.

Implemented in DynamicLoaderDarwinKernel, DynamicLoaderPOSIXDYLD, DynamicLoaderStatic, lldb_private::DynamicLoaderDarwin, DynamicLoaderHexagonDYLD, and lldb_private::DynamicLoaderWindowsDYLD.

Referenced by lldb_private::Process::Launch().

◆ FindEquivalentSymbols()

virtual size_t lldb_private::DynamicLoader::FindEquivalentSymbols ( Symbol original_symbol,
ModuleList module_list,
SymbolContextList equivalent_symbols 
)
inlinevirtual

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.

Parameters
[in]original_symbolThe symbol for which we are finding equivalences.
[in]module_listThe set of modules in which to search.
[out]equivalent_symbolsThe equivalent symbol list - any equivalent symbols found are appended to this list.
Returns
Number of equivalent symbols found.

Reimplemented in lldb_private::DynamicLoaderDarwin.

Definition at line 165 of file DynamicLoader.h.

References CanLoadImage().

◆ FindPlugin()

DynamicLoader * DynamicLoader::FindPlugin ( Process process,
const char *  plugin_name 
)
static

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 process.

Parameters
[in]processThe process for which to try and locate a dynamic loader plug-in instance.
[in]plugin_nameAn optional name of a specific dynamic loader plug-in that should be used. If NULL, pick the best plug-in.

Definition at line 32 of file DynamicLoader.cpp.

Referenced by lldb_private::ProcessWindows::GetDynamicLoader(), lldb_private::process_gdb_remote::ProcessGDBRemote::GetDynamicLoader(), and lldb_private::Process::GetDynamicLoader().

◆ GetSectionListFromModule()

const SectionList * DynamicLoader::GetSectionListFromModule ( const lldb::ModuleSP  module) const
protected

◆ GetSharedCacheInformation()

virtual bool lldb_private::DynamicLoader::GetSharedCacheInformation ( lldb::addr_t base_address,
UUID uuid,
LazyBool using_shared_cache,
LazyBool private_shared_cache 
)
inlinevirtual

Get information about the shared cache for a process, if possible.

On some systems (e.g. Darwin based systems), a set of libraries that are common to most processes may be put in a single region of memory and mapped into every process, this is called the shared cache, as a performance optimization.

Many targets will not have the concept of a shared cache.

Depending on how the DynamicLoader gathers information about the shared cache, it may be able to only return basic information - like the UUID of the cache - or it may be able to return additional information about the cache.

Parameters
[out]base_addressThe base address (load address) of the shared cache. LLDB_INVALID_ADDRESS if it cannot be determined.
[out]uuidThe UUID of the shared cache, if it can be determined. If the UUID cannot be fetched, IsValid() will be false.
[out]using_shared_cacheIf this process is using a shared cache. If unknown, eLazyBoolCalculate is returned.
[out]private_shared_cacheA LazyBool indicating whether this process is using a private shared cache. If this information cannot be fetched, eLazyBoolCalculate.
Returns
Returns false if this DynamicLoader cannot gather information about the shared cache / has no concept of a shared cache.

Reimplemented in DynamicLoaderMacOSXDYLD, and DynamicLoaderMacOS.

Definition at line 266 of file DynamicLoader.h.

References lldb_private::UUID::Clear(), lldb_private::eLazyBoolCalculate, GetSectionListFromModule(), GetTargetExecutable(), LLDB_INVALID_ADDRESS, LoadOperatingSystemPlugin(), ReadPointer(), ReadUnsignedIntWithSizeInBytes(), UnloadSections(), UnloadSectionsCommon(), UpdateLoadedSections(), and UpdateLoadedSectionsCommon().

Referenced by ObjectFileMachO::GetProcessSharedCacheUUID().

◆ GetStepThroughTrampolinePlan()

virtual lldb::ThreadPlanSP lldb_private::DynamicLoader::GetStepThroughTrampolinePlan ( Thread thread,
bool  stop_others 
)
pure virtual

Provides a plan to step through the dynamic loader trampoline for the current state of thread.

Parameters
[in]stop_othersWhether the plan should be set to stop other threads.
Returns
A pointer to the plan (caller owned) or NULL if we are not at such a trampoline.

Implemented in DynamicLoaderDarwinKernel, DynamicLoaderPOSIXDYLD, DynamicLoaderStatic, lldb_private::DynamicLoaderDarwin, DynamicLoaderHexagonDYLD, and lldb_private::DynamicLoaderWindowsDYLD.

Referenced by lldb_private::ThreadPlanStepThrough::LookForPlanToStepThroughFromCurrentPC(), and ProcessDidExec().

◆ GetStopWhenImagesChange()

bool DynamicLoader::GetStopWhenImagesChange ( ) const

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.

Returns
Returns true if the process should stop when images change, false if the process should resume.

Definition at line 68 of file DynamicLoader.cpp.

References lldb_private::ProcessProperties::GetStopOnSharedLibraryEvents(), and m_process.

Referenced by DynamicLoaderDarwinKernel::BreakpointHit(), DynamicLoaderMacOS::NotifyBreakpointHit(), DynamicLoaderMacOSXDYLD::NotifyBreakpointHit(), ProcessDidExec(), DynamicLoaderHexagonDYLD::RendezvousBreakpointHit(), and DynamicLoaderPOSIXDYLD::RendezvousBreakpointHit().

◆ GetTargetExecutable()

ModuleSP DynamicLoader::GetTargetExecutable ( )
protected

◆ GetThreadLocalData()

virtual lldb::addr_t lldb_private::DynamicLoader::GetThreadLocalData ( const lldb::ModuleSP  module,
const lldb::ThreadSP  thread,
lldb::addr_t  tls_file_addr 
)
inlinevirtual

Retrieves the per-module TLS block for a given thread.

Parameters
[in]moduleThe module to query TLS data for.
[in]threadThe specific thread to query TLS data for.
Returns
If the given thread has TLS data allocated for the module, the address of the TLS block. Otherwise LLDB_INVALID_ADDRESS is returned.

Reimplemented in DynamicLoaderPOSIXDYLD, lldb_private::DynamicLoaderDarwin, and DynamicLoaderHexagonDYLD.

Definition at line 219 of file DynamicLoader.h.

References LLDB_INVALID_ADDRESS, and LoadModuleAtAddress().

Referenced by lldb_private::Thread::GetThreadLocalData().

◆ LoadModuleAtAddress()

ModuleSP DynamicLoader::LoadModuleAtAddress ( const lldb_private::FileSpec file,
lldb::addr_t  link_map_addr,
lldb::addr_t  base_addr,
bool  base_addr_is_offset 
)
virtual

◆ LoadOperatingSystemPlugin()

void DynamicLoader::LoadOperatingSystemPlugin ( bool  flush)
protected

◆ ProcessDidExec()

virtual bool lldb_private::DynamicLoader::ProcessDidExec ( )
inlinevirtual

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.

Reimplemented in DynamicLoaderMacOSXDYLD, and DynamicLoaderMacOS.

Definition at line 107 of file DynamicLoader.h.

References GetStepThroughTrampolinePlan(), GetStopWhenImagesChange(), and SetStopWhenImagesChange().

Referenced by lldb_private::StopInfoMachException::CreateStopReasonWithMachException().

◆ ReadPointer()

addr_t DynamicLoader::ReadPointer ( lldb::addr_t  addr)
protected

◆ ReadUnsignedIntWithSizeInBytes()

int64_t DynamicLoader::ReadUnsignedIntWithSizeInBytes ( lldb::addr_t  addr,
int  size_in_bytes 
)
protected

◆ SetStopWhenImagesChange()

void DynamicLoader::SetStopWhenImagesChange ( bool  stop)

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.

Parameters
[in]stopBoolean value that indicates whether the process should stop when images change.

Definition at line 72 of file DynamicLoader.cpp.

References m_process, and lldb_private::ProcessProperties::SetStopOnSharedLibraryEvents().

Referenced by ProcessDidExec().

◆ UnloadSections()

void DynamicLoader::UnloadSections ( const lldb::ModuleSP  module)
protectedvirtual

Removes the loaded sections from the target in module.

Parameters
moduleThe module to traverse.

Reimplemented in DynamicLoaderPOSIXDYLD, and DynamicLoaderHexagonDYLD.

Definition at line 123 of file DynamicLoader.cpp.

References UnloadSectionsCommon().

Referenced by GetSharedCacheInformation(), lldb_private::DynamicLoaderDarwin::UnloadAllImages(), and lldb_private::DynamicLoaderDarwin::UnloadImages().

◆ UnloadSectionsCommon()

void DynamicLoader::UnloadSectionsCommon ( const lldb::ModuleSP  module)
protected

◆ UpdateLoadedSections()

void DynamicLoader::UpdateLoadedSections ( lldb::ModuleSP  module,
lldb::addr_t  link_map_addr,
lldb::addr_t  base_addr,
bool  base_addr_is_offset 
)
protectedvirtual

Updates the load address of every allocatable section in module.

Parameters
moduleThe module to traverse.
link_map_addrThe virtual address of the link map for the module.
base_addrThe virtual base address module is loaded at.

Reimplemented in DynamicLoaderPOSIXDYLD, and DynamicLoaderHexagonDYLD.

Definition at line 109 of file DynamicLoader.cpp.

References UpdateLoadedSectionsCommon().

Referenced by lldb_private::DynamicLoaderWindowsDYLD::DidAttach(), lldb_private::DynamicLoaderWindowsDYLD::DidLaunch(), GetSharedCacheInformation(), and LoadModuleAtAddress().

◆ UpdateLoadedSectionsCommon()

void DynamicLoader::UpdateLoadedSectionsCommon ( lldb::ModuleSP  module,
lldb::addr_t  base_addr,
bool  base_addr_is_offset 
)
protected

Member Data Documentation

◆ m_process

Process* lldb_private::DynamicLoader::m_process
protected

The process that this dynamic loader plug-in is tracking.

Definition at line 326 of file DynamicLoader.h.

Referenced by DynamicLoaderMacOS::AddBinaries(), lldb_private::DynamicLoaderDarwin::AddModulesUsingImageInfos(), DynamicLoaderMacOSXDYLD::AddModulesUsingImageInfosAddress(), lldb_private::DynamicLoaderDarwin::AlwaysRelyOnEHUnwindInfo(), DynamicLoaderMacOS::CanLoadImage(), lldb_private::DynamicLoaderDarwin::Clear(), DynamicLoaderDarwinKernel::Clear(), DynamicLoaderMacOS::ClearNotificationBreakpoint(), DynamicLoaderMacOSXDYLD::ClearNotificationBreakpoint(), DynamicLoaderPOSIXDYLD::ComputeLoadOffset(), DynamicLoaderHexagonDYLD::DidAttach(), lldb_private::DynamicLoaderWindowsDYLD::DidAttach(), lldb_private::DynamicLoaderDarwin::DidAttach(), DynamicLoaderPOSIXDYLD::DidAttach(), DynamicLoaderDarwinKernel::DidAttach(), lldb_private::DynamicLoaderWindowsDYLD::DidLaunch(), lldb_private::DynamicLoaderDarwin::DidLaunch(), DynamicLoaderStatic::DidLaunch(), DynamicLoaderPOSIXDYLD::DidLaunch(), DynamicLoaderDarwinKernel::DidLaunch(), DynamicLoaderMacOS::DoClear(), DynamicLoaderMacOSXDYLD::DoClear(), DynamicLoaderMacOS::DoInitialImageFetch(), DynamicLoaderMacOSXDYLD::DoInitialImageFetch(), DynamicLoaderPOSIXDYLD::EntryBreakpointHit(), lldb_private::DynamicLoaderDarwin::FindTargetModuleForImageInfo(), DynamicLoaderMacOS::GetDyldLockVariableAddressFromModule(), DynamicLoaderHexagonDYLD::GetEntryPoint(), DynamicLoaderPOSIXDYLD::GetEntryPoint(), lldb_private::DynamicLoaderWindowsDYLD::GetLoadAddress(), lldb_private::DynamicLoaderDarwin::GetPThreadLibraryModule(), DynamicLoaderMacOS::GetSharedCacheInformation(), DynamicLoaderMacOSXDYLD::GetSharedCacheInformation(), lldb_private::DynamicLoaderWindowsDYLD::GetStepThroughTrampolinePlan(), GetStopWhenImagesChange(), DynamicLoaderHexagonDYLD::GetTargetExecutable(), GetTargetExecutable(), DynamicLoaderHexagonDYLD::GetThreadLocalData(), lldb_private::DynamicLoaderDarwin::GetThreadLocalData(), DynamicLoaderMacOSXDYLD::InitializeFromAllImageInfos(), DynamicLoaderHexagonDYLD::LoadAllCurrentModules(), DynamicLoaderPOSIXDYLD::LoadAllCurrentModules(), DynamicLoaderPOSIXDYLD::LoadInterpreterModule(), DynamicLoaderDarwinKernel::LoadKernelModuleIfNeeded(), LoadModuleAtAddress(), LoadOperatingSystemPlugin(), DynamicLoaderPOSIXDYLD::LoadVDSO(), DynamicLoaderMacOS::NotifyBreakpointHit(), DynamicLoaderMacOSXDYLD::NotifyBreakpointHit(), lldb_private::DynamicLoaderWindowsDYLD::OnLoadModule(), lldb_private::DynamicLoaderWindowsDYLD::OnUnloadModule(), DynamicLoaderDarwinKernel::ParseKextSummaries(), lldb_private::DynamicLoaderDarwin::PrivateInitialize(), DynamicLoaderDarwinKernel::PrivateInitialize(), lldb_private::DynamicLoaderDarwin::PrivateProcessStateChanged(), DynamicLoaderPOSIXDYLD::ProbeEntry(), DynamicLoaderMacOS::ProcessDidExec(), DynamicLoaderMacOSXDYLD::ProcessDidExec(), DynamicLoaderMacOSXDYLD::ReadAllImageInfosStructure(), DynamicLoaderMacOSXDYLD::ReadDYLDInfoFromMemoryAndSetNotificationCallback(), DynamicLoaderMacOSXDYLD::ReadImageInfos(), DynamicLoaderDarwinKernel::ReadKextSummaries(), DynamicLoaderDarwinKernel::ReadKextSummaryHeader(), DynamicLoaderMacOSXDYLD::ReadMachHeader(), ReadPointer(), ReadUnsignedIntWithSizeInBytes(), DynamicLoaderHexagonDYLD::RefreshModules(), DynamicLoaderPOSIXDYLD::RefreshModules(), DynamicLoaderMacOSXDYLD::RemoveModulesUsingImageInfosAddress(), DynamicLoaderHexagonDYLD::RendezvousBreakpointHit(), DynamicLoaderPOSIXDYLD::RendezvousBreakpointHit(), DynamicLoaderPOSIXDYLD::ResolveExecutableModule(), DynamicLoaderMacOS::SetNotificationBreakpoint(), DynamicLoaderMacOSXDYLD::SetNotificationBreakpoint(), DynamicLoaderDarwinKernel::SetNotificationBreakpointIfNeeded(), DynamicLoaderHexagonDYLD::SetRendezvousBreakpoint(), DynamicLoaderPOSIXDYLD::SetRendezvousBreakpoint(), SetStopWhenImagesChange(), lldb_private::DynamicLoaderDarwin::UnloadAllImages(), lldb_private::DynamicLoaderDarwin::UnloadImages(), lldb_private::DynamicLoaderDarwin::UnloadModuleSections(), DynamicLoaderHexagonDYLD::UnloadSections(), UnloadSectionsCommon(), lldb_private::DynamicLoaderDarwin::UpdateDYLDImageInfoFromNewImageInfo(), DynamicLoaderMacOSXDYLD::UpdateImageInfosHeaderAndLoadCommands(), lldb_private::DynamicLoaderDarwin::UpdateImageLoadAddress(), DynamicLoaderHexagonDYLD::UpdateLoadedSections(), UpdateLoadedSectionsCommon(), lldb_private::DynamicLoaderDarwin::UpdateSpecialBinariesFromNewImageInfos(), DynamicLoaderHexagonDYLD::~DynamicLoaderHexagonDYLD(), DynamicLoaderMacOS::~DynamicLoaderMacOS(), DynamicLoaderMacOSXDYLD::~DynamicLoaderMacOSXDYLD(), and DynamicLoaderPOSIXDYLD::~DynamicLoaderPOSIXDYLD().


The documentation for this class was generated from the following files: