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