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 empty, pick the best plug-in.
66  static DynamicLoader *FindPlugin(Process *process,
67  llvm::StringRef plugin_name);
68 
69  /// Construct with a process.
70  DynamicLoader(Process *process);
71 
72  /// Called after attaching a process.
73  ///
74  /// Allow DynamicLoader plug-ins to execute some code after attaching to a
75  /// process.
76  virtual void DidAttach() = 0;
77 
78  /// Called after launching a process.
79  ///
80  /// Allow DynamicLoader plug-ins to execute some code after the process has
81  /// stopped for the first time on launch.
82  virtual void DidLaunch() = 0;
83 
84  /// Helper function that can be used to detect when a process has called
85  /// exec and is now a new and different process. This can be called when
86  /// necessary to try and detect the exec. The process might be able to
87  /// answer this question, but sometimes it might not be able and the dynamic
88  /// loader often knows what the program entry point is. So the process and
89  /// the dynamic loader can work together to detect this.
90  virtual bool ProcessDidExec() { return false; }
91  /// Get whether the process should stop when images change.
92  ///
93  /// When images (executables and shared libraries) get loaded or unloaded,
94  /// often debug sessions will want to try and resolve or unresolve
95  /// breakpoints that are set in these images. Any breakpoints set by
96  /// DynamicLoader plug-in instances should return this value to ensure
97  /// consistent debug session behaviour.
98  ///
99  /// \return
100  /// Returns \b true if the process should stop when images
101  /// change, \b false if the process should resume.
102  bool GetStopWhenImagesChange() const;
103 
104  /// Set whether the process should stop when images change.
105  ///
106  /// When images (executables and shared libraries) get loaded or unloaded,
107  /// often debug sessions will want to try and resolve or unresolve
108  /// breakpoints that are set in these images. The default is set so that the
109  /// process stops when images change, but this can be overridden using this
110  /// function callback.
111  ///
112  /// \param[in] stop
113  /// Boolean value that indicates whether the process should stop
114  /// when images change.
115  void SetStopWhenImagesChange(bool stop);
116 
117  /// Provides a plan to step through the dynamic loader trampoline for the
118  /// current state of \a thread.
119  ///
120  ///
121  /// \param[in] stop_others
122  /// Whether the plan should be set to stop other threads.
123  ///
124  /// \return
125  /// A pointer to the plan (caller owned) or NULL if we are not at such
126  /// a trampoline.
127  virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread,
128  bool stop_others) = 0;
129 
130  /// Some dynamic loaders provide features where there are a group of symbols
131  /// "equivalent to" a given symbol one of which will be chosen when the
132  /// symbol is bound. If you want to set a breakpoint on one of these
133  /// symbols, you really need to set it on all the equivalent symbols.
134  ///
135  ///
136  /// \param[in] original_symbol
137  /// The symbol for which we are finding equivalences.
138  ///
139  /// \param[in] module_list
140  /// The set of modules in which to search.
141  ///
142  /// \param[out] equivalent_symbols
143  /// The equivalent symbol list - any equivalent symbols found are appended
144  /// to this list.
145  ///
146  virtual void FindEquivalentSymbols(Symbol *original_symbol,
147  ModuleList &module_list,
148  SymbolContextList &equivalent_symbols) {}
149 
150  /// Ask if it is ok to try and load or unload an shared library (image).
151  ///
152  /// The dynamic loader often knows when it would be ok to try and load or
153  /// unload a shared library. This function call allows the dynamic loader
154  /// plug-ins to check any current dyld state to make sure it is an ok time
155  /// to load a shared library.
156  ///
157  /// \return
158  /// \b true if it is currently ok to try and load a shared
159  /// library into the process, \b false otherwise.
160  virtual Status CanLoadImage() = 0;
161 
162  /// Ask if the eh_frame information for the given SymbolContext should be
163  /// relied on even when it's the first frame in a stack unwind.
164  ///
165  /// The CFI instructions from the eh_frame section are normally only valid
166  /// at call sites -- places where a program could throw an exception and
167  /// need to unwind out. But some Modules may be known to the system as
168  /// having reliable eh_frame information at all call sites. This would be
169  /// the case if the Module's contents are largely hand-written assembly with
170  /// hand-written eh_frame information. Normally when unwinding from a
171  /// function at the beginning of a stack unwind lldb will examine the
172  /// assembly instructions to understand how the stack frame is set up and
173  /// where saved registers are stored. But with hand-written assembly this is
174  /// not reliable enough -- we need to consult those function's hand-written
175  /// eh_frame information.
176  ///
177  /// \return
178  /// \b True if the symbol context should use eh_frame instructions
179  /// unconditionally when unwinding from this frame. Else \b false,
180  /// the normal lldb unwind behavior of only using eh_frame when the
181  /// function appears in the middle of the stack.
182  virtual bool AlwaysRelyOnEHUnwindInfo(SymbolContext &sym_ctx) {
183  return false;
184  }
185 
186  /// Retrieves the per-module TLS block for a given thread.
187  ///
188  /// \param[in] module
189  /// The module to query TLS data for.
190  ///
191  /// \param[in] thread
192  /// The specific thread to query TLS data for.
193  ///
194  /// \return
195  /// If the given thread has TLS data allocated for the
196  /// module, the address of the TLS block. Otherwise
197  /// LLDB_INVALID_ADDRESS is returned.
198  virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module,
199  const lldb::ThreadSP thread,
200  lldb::addr_t tls_file_addr) {
201  return LLDB_INVALID_ADDRESS;
202  }
203 
204  /// Locates or creates a module given by \p file and updates/loads the
205  /// resulting module at the virtual base address \p base_addr.
206  /// Note that this calls Target::GetOrCreateModule with notify being false,
207  /// so it is necessary to call Target::ModulesDidLoad afterwards.
208  virtual lldb::ModuleSP LoadModuleAtAddress(const lldb_private::FileSpec &file,
209  lldb::addr_t link_map_addr,
210  lldb::addr_t base_addr,
211  bool base_addr_is_offset);
212 
213  /// Find/load a binary into lldb given a UUID and the address where it is
214  /// loaded in memory, or a slide to be applied to the file address.
215  /// May force an expensive search on the computer to find the binary by
216  /// UUID, should not be used for a large number of binaries - intended for
217  /// an environment where there may be one, or a few, binaries resident in
218  /// memory.
219  ///
220  /// Given a UUID, search for a binary and load it at the address provided,
221  /// or with the slide applied, or at the file address unslid.
222  ///
223  /// Given an address, try to read the binary out of memory, get the UUID,
224  /// find the file if possible and load it unslid, or add the memory module.
225  ///
226  /// \param[in] process
227  /// The process to add this binary to.
228  ///
229  /// \param[in] name
230  /// Name of the binary, if available. If this method cannot find a
231  /// matching binary on the debug host, it may create a memory module
232  /// out of live memory, and the provided name will be used. If an
233  /// empty StringRef is provided, a name will be constructed for the module
234  /// based on the address it is loaded at.
235  ///
236  /// \param[in] uuid
237  /// UUID of the binary to be loaded. UUID may be empty, and if a
238  /// load address is supplied, will read the binary from memory, get
239  /// a UUID and try to find a local binary. There is a performance
240  /// cost to doing this, it is not preferable.
241  ///
242  /// \param[in] value
243  /// Address where the binary should be loaded, or read out of memory.
244  /// Or a slide value, to be applied to the file addresses of the binary.
245  ///
246  /// \param[in] value_is_offset
247  /// A flag indicating that \p value is an address, or an offset to
248  /// be applied to the file addresses.
249  ///
250  /// \param[in] force_symbol_search
251  /// Allow the search to do a possibly expensive external search for
252  /// the ObjectFile and/or SymbolFile.
253  ///
254  /// \param[in] notify
255  /// Whether ModulesDidLoad should be called when a binary has been added
256  /// to the Target. The caller may prefer to batch up these when loading
257  /// multiple binaries.
258  ///
259  /// \return
260  /// Returns a shared pointer for the Module that has been added.
261  static lldb::ModuleSP LoadBinaryWithUUIDAndAddress(
262  Process *process, llvm::StringRef name, UUID uuid, lldb::addr_t value,
263  bool value_is_offset, bool force_symbol_search, bool notify);
264 
265  /// Get information about the shared cache for a process, if possible.
266  ///
267  /// On some systems (e.g. Darwin based systems), a set of libraries that are
268  /// common to most processes may be put in a single region of memory and
269  /// mapped into every process, this is called the shared cache, as a
270  /// performance optimization.
271  ///
272  /// Many targets will not have the concept of a shared cache.
273  ///
274  /// Depending on how the DynamicLoader gathers information about the shared
275  /// cache, it may be able to only return basic information - like the UUID
276  /// of the cache - or it may be able to return additional information about
277  /// the cache.
278  ///
279  /// \param[out] base_address
280  /// The base address (load address) of the shared cache.
281  /// LLDB_INVALID_ADDRESS if it cannot be determined.
282  ///
283  /// \param[out] uuid
284  /// The UUID of the shared cache, if it can be determined.
285  /// If the UUID cannot be fetched, IsValid() will be false.
286  ///
287  /// \param[out] using_shared_cache
288  /// If this process is using a shared cache.
289  /// If unknown, eLazyBoolCalculate is returned.
290  ///
291  /// \param[out] private_shared_cache
292  /// A LazyBool indicating whether this process is using a
293  /// private shared cache.
294  /// If this information cannot be fetched, eLazyBoolCalculate.
295  ///
296  /// \return
297  /// Returns false if this DynamicLoader cannot gather information
298  /// about the shared cache / has no concept of a shared cache.
299  virtual bool GetSharedCacheInformation(lldb::addr_t &base_address, UUID &uuid,
300  LazyBool &using_shared_cache,
301  LazyBool &private_shared_cache) {
302  base_address = LLDB_INVALID_ADDRESS;
303  uuid.Clear();
304  using_shared_cache = eLazyBoolCalculate;
305  private_shared_cache = eLazyBoolCalculate;
306  return false;
307  }
308 
309  /// Return whether the dynamic loader is fully initialized and it's safe to
310  /// call its APIs.
311  ///
312  /// On some systems (e.g. Darwin based systems), lldb will get notified by
313  /// the dynamic loader before it itself finished initializing and it's not
314  /// safe to call certain APIs or SPIs.
315  virtual bool IsFullyInitialized() { return true; }
316 
317 protected:
318  // Utility methods for derived classes
319 
320  lldb::ModuleSP FindModuleViaTarget(const FileSpec &file);
321 
322  /// Checks to see if the target module has changed, updates the target
323  /// accordingly and returns the target executable module.
324  lldb::ModuleSP GetTargetExecutable();
325 
326  /// Updates the load address of every allocatable section in \p module.
327  ///
328  /// \param module The module to traverse.
329  ///
330  /// \param link_map_addr The virtual address of the link map for the @p
331  /// module.
332  ///
333  /// \param base_addr The virtual base address \p module is loaded at.
334  virtual void UpdateLoadedSections(lldb::ModuleSP module,
335  lldb::addr_t link_map_addr,
336  lldb::addr_t base_addr,
337  bool base_addr_is_offset);
338 
339  // Utility method so base classes can share implementation of
340  // UpdateLoadedSections
341  void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr,
342  bool base_addr_is_offset);
343 
344  /// Removes the loaded sections from the target in \p module.
345  ///
346  /// \param module The module to traverse.
347  virtual void UnloadSections(const lldb::ModuleSP module);
348 
349  // Utility method so base classes can share implementation of UnloadSections
350  void UnloadSectionsCommon(const lldb::ModuleSP module);
351 
353  GetSectionListFromModule(const lldb::ModuleSP module) const;
354 
355  // Read an unsigned int of the given size from memory at the given addr.
356  // Return -1 if the read fails, otherwise return the result as an int64_t.
357  int64_t ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes);
358 
359  // Read a pointer from memory at the given addr. Return LLDB_INVALID_ADDRESS
360  // if the read fails.
362 
363  // Calls into the Process protected method LoadOperatingSystemPlugin:
364  void LoadOperatingSystemPlugin(bool flush);
365 
366 
367  // Member variables.
368  Process
369  *m_process; ///< The process that this dynamic loader plug-in is tracking.
370 };
371 
372 } // namespace lldb_private
373 
374 #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:299
lldb_private::DynamicLoader::SetStopWhenImagesChange
void SetStopWhenImagesChange(bool stop)
Set whether the process should stop when images change.
Definition: DynamicLoader.cpp:72
lldb_private::UUID
Definition: UUID.h:23
lldb_private::DynamicLoader::DynamicLoader
DynamicLoader(Process *process)
Construct with a process.
Definition: DynamicLoader.cpp:63
lldb_private::Symbol
Definition: Symbol.h:20
UUID.h
lldb_private::PluginInterface
Definition: PluginInterface.h:16
lldb-defines.h
lldb_private::DynamicLoader::FindPlugin
static DynamicLoader * FindPlugin(Process *process, llvm::StringRef plugin_name)
Find a dynamic loader plugin for a given process.
Definition: DynamicLoader.cpp:36
lldb_private::Process
Definition: Process.h:338
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:127
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:298
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:146
lldb_private::FileSpec
Definition: FileSpec.h:55
lldb_private::DynamicLoader::DidLaunch
virtual void DidLaunch()=0
Called after launching a process.
lldb_private::ModuleList
Definition: ModuleList.h:82
lldb_private::Thread
Definition: Thread.h:61
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:90
lldb_private::DynamicLoader::ReadUnsignedIntWithSizeInBytes
int64_t ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes)
Definition: DynamicLoader.cpp:278
lldb_private::LLDBLog::Process
@ Process
lldb_private::LLDBLog::Thread
@ Thread
lldb_private::DynamicLoader::FindModuleViaTarget
lldb::ModuleSP FindModuleViaTarget(const FileSpec &file)
Definition: DynamicLoader.cpp:152
lldb_private::DynamicLoader::ReadPointer
lldb::addr_t ReadPointer(lldb::addr_t addr)
Definition: DynamicLoader.cpp:289
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:109
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:369
lldb_private::DynamicLoader::UpdateLoadedSectionsCommon
void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr, bool base_addr_is_offset)
Definition: DynamicLoader.cpp:115
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:198
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:62
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:165
lldb_private::DynamicLoader::GetStopWhenImagesChange
bool GetStopWhenImagesChange() const
Get whether the process should stop when images change.
Definition: DynamicLoader.cpp:68
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:76
lldb_private::DynamicLoader::LoadBinaryWithUUIDAndAddress
static lldb::ModuleSP LoadBinaryWithUUIDAndAddress(Process *process, llvm::StringRef name, UUID uuid, lldb::addr_t value, bool value_is_offset, bool force_symbol_search, bool notify)
Find/load a binary into lldb given a UUID and the address where it is loaded in memory,...
Definition: DynamicLoader.cpp:188
LLDB_INVALID_ADDRESS
#define LLDB_INVALID_ADDRESS
Definition: lldb-defines.h:74
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:315
lldb_private::DynamicLoader::UnloadSections
virtual void UnloadSections(const lldb::ModuleSP module)
Removes the loaded sections from the target in module.
Definition: DynamicLoader.cpp:123
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:182
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:141