LLDB  mainline
DynamicLoader.h
Go to the documentation of this file.
1 //===-- DynamicLoader.h -----------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLDB_TARGET_DYNAMICLOADER_H
10 #define LLDB_TARGET_DYNAMICLOADER_H
11 
13 #include "lldb/Utility/FileSpec.h"
14 #include "lldb/Utility/Status.h"
15 #include "lldb/Utility/UUID.h"
16 #include "lldb/lldb-defines.h"
17 #include "lldb/lldb-forward.h"
19 #include "lldb/lldb-types.h"
20 
21 #include <cstddef>
22 #include <cstdint>
23 namespace lldb_private {
24 class ModuleList;
25 class Process;
26 class SectionList;
27 class Symbol;
28 class SymbolContext;
29 class SymbolContextList;
30 class Thread;
31 }
32 
33 namespace lldb_private {
34 
35 /// \class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
36 /// A plug-in interface definition class for dynamic loaders.
37 ///
38 /// Dynamic loader plug-ins track image (shared library) loading and
39 /// unloading. The class is initialized given a live process that is halted at
40 /// its entry point or just after attaching.
41 ///
42 /// Dynamic loader plug-ins can track the process by registering callbacks
43 /// using the: Process::RegisterNotificationCallbacks (const Notifications&)
44 /// function.
45 ///
46 /// Breakpoints can also be set in the process which can register functions
47 /// that get called using: Process::BreakpointSetCallback (lldb::user_id_t,
48 /// BreakpointHitCallback, void *). These breakpoint callbacks return a
49 /// boolean value that indicates if the process should continue or halt and
50 /// should return the global setting for this using:
51 /// DynamicLoader::StopWhenImagesChange() const.
53 public:
54  /// Find a dynamic loader plugin for a given process.
55  ///
56  /// Scans the installed DynamicLoader plug-ins and tries to find an instance
57  /// that can be used to track image changes in \a process.
58  ///
59  /// \param[in] process
60  /// The process for which to try and locate a dynamic loader
61  /// plug-in instance.
62  ///
63  /// \param[in] plugin_name
64  /// An optional name of a specific dynamic loader plug-in that
65  /// should be used. If NULL, pick the best plug-in.
66  static DynamicLoader *FindPlugin(Process *process, const char *plugin_name);
67 
68  /// Construct with a process.
69  DynamicLoader(Process *process);
70 
71  /// Called after attaching a process.
72  ///
73  /// Allow DynamicLoader plug-ins to execute some code after attaching to a
74  /// process.
75  virtual void DidAttach() = 0;
76 
77  /// Called after launching a process.
78  ///
79  /// Allow DynamicLoader plug-ins to execute some code after the process has
80  /// stopped for the first time on launch.
81  virtual void DidLaunch() = 0;
82 
83  /// Helper function that can be used to detect when a process has called
84  /// exec and is now a new and different process. This can be called when
85  /// necessary to try and detect the exec. The process might be able to
86  /// answer this question, but sometimes it might not be able and the dynamic
87  /// loader often knows what the program entry point is. So the process and
88  /// the dynamic loader can work together to detect this.
89  virtual bool ProcessDidExec() { return false; }
90  /// Get whether the process should stop when images change.
91  ///
92  /// When images (executables and shared libraries) get loaded or unloaded,
93  /// often debug sessions will want to try and resolve or unresolve
94  /// breakpoints that are set in these images. Any breakpoints set by
95  /// DynamicLoader plug-in instances should return this value to ensure
96  /// consistent debug session behaviour.
97  ///
98  /// \return
99  /// Returns \b true if the process should stop when images
100  /// change, \b false if the process should resume.
101  bool GetStopWhenImagesChange() const;
102 
103  /// Set whether the process should stop when images change.
104  ///
105  /// When images (executables and shared libraries) get loaded or unloaded,
106  /// often debug sessions will want to try and resolve or unresolve
107  /// breakpoints that are set in these images. The default is set so that the
108  /// process stops when images change, but this can be overridden using this
109  /// function callback.
110  ///
111  /// \param[in] stop
112  /// Boolean value that indicates whether the process should stop
113  /// when images change.
114  void SetStopWhenImagesChange(bool stop);
115 
116  /// Provides a plan to step through the dynamic loader trampoline for the
117  /// current state of \a thread.
118  ///
119  ///
120  /// \param[in] stop_others
121  /// Whether the plan should be set to stop other threads.
122  ///
123  /// \return
124  /// A pointer to the plan (caller owned) or NULL if we are not at such
125  /// a trampoline.
126  virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread,
127  bool stop_others) = 0;
128 
129  /// Some dynamic loaders provide features where there are a group of symbols
130  /// "equivalent to" a given symbol one of which will be chosen when the
131  /// symbol is bound. If you want to set a breakpoint on one of these
132  /// symbols, you really need to set it on all the equivalent symbols.
133  ///
134  ///
135  /// \param[in] original_symbol
136  /// The symbol for which we are finding equivalences.
137  ///
138  /// \param[in] module_list
139  /// The set of modules in which to search.
140  ///
141  /// \param[out] equivalent_symbols
142  /// The equivalent symbol list - any equivalent symbols found are appended
143  /// to this list.
144  ///
145  virtual void FindEquivalentSymbols(Symbol *original_symbol,
146  ModuleList &module_list,
147  SymbolContextList &equivalent_symbols) {}
148 
149  /// Ask if it is ok to try and load or unload an shared library (image).
150  ///
151  /// The dynamic loader often knows when it would be ok to try and load or
152  /// unload a shared library. This function call allows the dynamic loader
153  /// plug-ins to check any current dyld state to make sure it is an ok time
154  /// to load a shared library.
155  ///
156  /// \return
157  /// \b true if it is currently ok to try and load a shared
158  /// library into the process, \b false otherwise.
159  virtual Status CanLoadImage() = 0;
160 
161  /// Ask if the eh_frame information for the given SymbolContext should be
162  /// relied on even when it's the first frame in a stack unwind.
163  ///
164  /// The CFI instructions from the eh_frame section are normally only valid
165  /// at call sites -- places where a program could throw an exception and
166  /// need to unwind out. But some Modules may be known to the system as
167  /// having reliable eh_frame information at all call sites. This would be
168  /// the case if the Module's contents are largely hand-written assembly with
169  /// hand-written eh_frame information. Normally when unwinding from a
170  /// function at the beginning of a stack unwind lldb will examine the
171  /// assembly instructions to understand how the stack frame is set up and
172  /// where saved registers are stored. But with hand-written assembly this is
173  /// not reliable enough -- we need to consult those function's hand-written
174  /// eh_frame information.
175  ///
176  /// \return
177  /// \b True if the symbol context should use eh_frame instructions
178  /// unconditionally when unwinding from this frame. Else \b false,
179  /// the normal lldb unwind behavior of only using eh_frame when the
180  /// function appears in the middle of the stack.
181  virtual bool AlwaysRelyOnEHUnwindInfo(SymbolContext &sym_ctx) {
182  return false;
183  }
184 
185  /// Retrieves the per-module TLS block for a given thread.
186  ///
187  /// \param[in] module
188  /// The module to query TLS data for.
189  ///
190  /// \param[in] thread
191  /// The specific thread to query TLS data for.
192  ///
193  /// \return
194  /// If the given thread has TLS data allocated for the
195  /// module, the address of the TLS block. Otherwise
196  /// LLDB_INVALID_ADDRESS is returned.
197  virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module,
198  const lldb::ThreadSP thread,
199  lldb::addr_t tls_file_addr) {
200  return LLDB_INVALID_ADDRESS;
201  }
202 
203  /// Locates or creates a module given by \p file and updates/loads the
204  /// resulting module at the virtual base address \p base_addr.
205  virtual lldb::ModuleSP LoadModuleAtAddress(const lldb_private::FileSpec &file,
206  lldb::addr_t link_map_addr,
207  lldb::addr_t base_addr,
208  bool base_addr_is_offset);
209 
210  /// Get information about the shared cache for a process, if possible.
211  ///
212  /// On some systems (e.g. Darwin based systems), a set of libraries that are
213  /// common to most processes may be put in a single region of memory and
214  /// mapped into every process, this is called the shared cache, as a
215  /// performance optimization.
216  ///
217  /// Many targets will not have the concept of a shared cache.
218  ///
219  /// Depending on how the DynamicLoader gathers information about the shared
220  /// cache, it may be able to only return basic information - like the UUID
221  /// of the cache - or it may be able to return additional information about
222  /// the cache.
223  ///
224  /// \param[out] base_address
225  /// The base address (load address) of the shared cache.
226  /// LLDB_INVALID_ADDRESS if it cannot be determined.
227  ///
228  /// \param[out] uuid
229  /// The UUID of the shared cache, if it can be determined.
230  /// If the UUID cannot be fetched, IsValid() will be false.
231  ///
232  /// \param[out] using_shared_cache
233  /// If this process is using a shared cache.
234  /// If unknown, eLazyBoolCalculate is returned.
235  ///
236  /// \param[out] private_shared_cache
237  /// A LazyBool indicating whether this process is using a
238  /// private shared cache.
239  /// If this information cannot be fetched, eLazyBoolCalculate.
240  ///
241  /// \return
242  /// Returns false if this DynamicLoader cannot gather information
243  /// about the shared cache / has no concept of a shared cache.
244  virtual bool GetSharedCacheInformation(lldb::addr_t &base_address, UUID &uuid,
245  LazyBool &using_shared_cache,
246  LazyBool &private_shared_cache) {
247  base_address = LLDB_INVALID_ADDRESS;
248  uuid.Clear();
249  using_shared_cache = eLazyBoolCalculate;
250  private_shared_cache = eLazyBoolCalculate;
251  return false;
252  }
253 
254  /// Return whether the dynamic loader is fully initialized and it's safe to
255  /// call its APIs.
256  ///
257  /// On some systems (e.g. Darwin based systems), lldb will get notified by
258  /// the dynamic loader before it itself finished initializing and it's not
259  /// safe to call certain APIs or SPIs.
260  virtual bool IsFullyInitialized() { return true; }
261 
262 protected:
263  // Utility methods for derived classes
264 
265  /// Checks to see if the target module has changed, updates the target
266  /// accordingly and returns the target executable module.
267  lldb::ModuleSP GetTargetExecutable();
268 
269  /// Updates the load address of every allocatable section in \p module.
270  ///
271  /// \param module The module to traverse.
272  ///
273  /// \param link_map_addr The virtual address of the link map for the @p
274  /// module.
275  ///
276  /// \param base_addr The virtual base address \p module is loaded at.
277  virtual void UpdateLoadedSections(lldb::ModuleSP module,
278  lldb::addr_t link_map_addr,
279  lldb::addr_t base_addr,
280  bool base_addr_is_offset);
281 
282  // Utility method so base classes can share implementation of
283  // UpdateLoadedSections
284  void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr,
285  bool base_addr_is_offset);
286 
287  /// Removes the loaded sections from the target in \p module.
288  ///
289  /// \param module The module to traverse.
290  virtual void UnloadSections(const lldb::ModuleSP module);
291 
292  // Utility method so base classes can share implementation of UnloadSections
293  void UnloadSectionsCommon(const lldb::ModuleSP module);
294 
296  GetSectionListFromModule(const lldb::ModuleSP module) const;
297 
298  // Read an unsigned int of the given size from memory at the given addr.
299  // Return -1 if the read fails, otherwise return the result as an int64_t.
300  int64_t ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes);
301 
302  // Read a pointer from memory at the given addr. Return LLDB_INVALID_ADDRESS
303  // if the read fails.
305 
306  // Calls into the Process protected method LoadOperatingSystemPlugin:
307  void LoadOperatingSystemPlugin(bool flush);
308 
309 
310  // Member variables.
311  Process
312  *m_process; ///< The process that this dynamic loader plug-in is tracking.
313 };
314 
315 } // namespace lldb_private
316 
317 #endif // LLDB_TARGET_DYNAMICLOADER_H
lldb_private::DynamicLoader::GetSharedCacheInformation
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.
Definition: DynamicLoader.h:244
lldb_private::DynamicLoader::SetStopWhenImagesChange
void SetStopWhenImagesChange(bool stop)
Set whether the process should stop when images change.
Definition: DynamicLoader.cpp:70
lldb_private::UUID
Definition: UUID.h:23
lldb_private::DynamicLoader::DynamicLoader
DynamicLoader(Process *process)
Construct with a process.
Definition: DynamicLoader.cpp:61
lldb_private::Symbol
Definition: Symbol.h:20
UUID.h
lldb_private::PluginInterface
Definition: PluginInterface.h:16
lldb-defines.h
lldb_private::Process
Definition: Process.h:341
lldb_private::DynamicLoader::CanLoadImage
virtual Status CanLoadImage()=0
Ask if it is ok to try and load or unload an shared library (image).
lldb_private::SymbolContextList
Definition: SymbolContext.h:379
lldb_private::DynamicLoader::UnloadSectionsCommon
void UnloadSectionsCommon(const lldb::ModuleSP module)
Definition: DynamicLoader.cpp:125
lldb_private::SectionList
Definition: Section.h:34
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb_private::LazyBool
LazyBool
Definition: lldb-private-enumerations.h:115
lldb-private-enumerations.h
lldb_private::SymbolContext
Definition: SymbolContext.h:33
lldb_private::DynamicLoader::LoadOperatingSystemPlugin
void LoadOperatingSystemPlugin(bool flush)
Definition: DynamicLoader.cpp:238
lldb_private::DynamicLoader::FindEquivalentSymbols
virtual void 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 symb...
Definition: DynamicLoader.h:145
lldb_private::FileSpec
Definition: FileSpec.h:56
lldb_private::DynamicLoader::DidLaunch
virtual void DidLaunch()=0
Called after launching a process.
lldb_private::ModuleList
Definition: ModuleList.h:71
lldb_private::Thread
Definition: Thread.h:62
lldb_private::DynamicLoader::ProcessDidExec
virtual bool ProcessDidExec()
Helper function that can be used to detect when a process has called exec and is now a new and differ...
Definition: DynamicLoader.h:89
lldb_private::DynamicLoader::ReadUnsignedIntWithSizeInBytes
int64_t ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes)
Definition: DynamicLoader.cpp:218
lldb_private::DynamicLoader::ReadPointer
lldb::addr_t ReadPointer(lldb::addr_t addr)
Definition: DynamicLoader.cpp:229
lldb_private::DynamicLoader::UpdateLoadedSections
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.
Definition: DynamicLoader.cpp:107
PluginInterface.h
lldb_private::DynamicLoader
Definition: DynamicLoader.h:52
lldb_private::DynamicLoader::m_process
Process * m_process
The process that this dynamic loader plug-in is tracking.
Definition: DynamicLoader.h:312
lldb_private::DynamicLoader::UpdateLoadedSectionsCommon
void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr, bool base_addr_is_offset)
Definition: DynamicLoader.cpp:113
lldb_private::DynamicLoader::GetThreadLocalData
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.
Definition: DynamicLoader.h:197
lldb_private::DynamicLoader::GetStepThroughTrampolinePlan
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.
lldb-types.h
lldb_private::UUID::Clear
void Clear()
Definition: UUID.h:72
lldb_private::Status
Definition: Status.h:44
lldb_private::DynamicLoader::LoadModuleAtAddress
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 ...
Definition: DynamicLoader.cpp:150
lldb_private::DynamicLoader::GetStopWhenImagesChange
bool GetStopWhenImagesChange() const
Get whether the process should stop when images change.
Definition: DynamicLoader.cpp:66
lldb_private::DynamicLoader::FindPlugin
static DynamicLoader * FindPlugin(Process *process, const char *plugin_name)
Find a dynamic loader plugin for a given process.
Definition: DynamicLoader.cpp:32
lldb_private::DynamicLoader::GetTargetExecutable
lldb::ModuleSP GetTargetExecutable()
Checks to see if the target module has changed, updates the target accordingly and returns the target...
Definition: DynamicLoader.cpp:74
LLDB_INVALID_ADDRESS
#define LLDB_INVALID_ADDRESS
Definition: lldb-defines.h:86
lldb-forward.h
Status.h
lldb_private::DynamicLoader::IsFullyInitialized
virtual bool IsFullyInitialized()
Return whether the dynamic loader is fully initialized and it's safe to call its APIs.
Definition: DynamicLoader.h:260
lldb_private::DynamicLoader::UnloadSections
virtual void UnloadSections(const lldb::ModuleSP module)
Removes the loaded sections from the target in module.
Definition: DynamicLoader.cpp:121
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::eLazyBoolCalculate
@ eLazyBoolCalculate
Definition: lldb-private-enumerations.h:115
FileSpec.h
lldb_private::DynamicLoader::AlwaysRelyOnEHUnwindInfo
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 fi...
Definition: DynamicLoader.h:181
lldb_private::DynamicLoader::DidAttach
virtual void DidAttach()=0
Called after attaching a process.
lldb_private::DynamicLoader::GetSectionListFromModule
const lldb_private::SectionList * GetSectionListFromModule(const lldb::ModuleSP module) const
Definition: DynamicLoader.cpp:139