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