1 //===-- DynamicLoader.h -----------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_DynamicLoader_h_
11 #define liblldb_DynamicLoader_h_
14 #include "lldb/lldb-private.h"
15 #include "lldb/Core/Error.h"
16 #include "lldb/Core/PluginInterface.h"
18 namespace lldb_private {
20 //----------------------------------------------------------------------
21 /// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
22 /// @brief A plug-in interface definition class for dynamic loaders.
24 /// Dynamic loader plug-ins track image (shared library) loading and
25 /// unloading. The class is initialized given a live process that is
26 /// halted at its entry point or just after attaching.
28 /// Dynamic loader plug-ins can track the process by registering
29 /// callbacks using the:
30 /// Process::RegisterNotificationCallbacks (const Notifications&)
33 /// Breakpoints can also be set in the process which can register
34 /// functions that get called using:
35 /// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void *).
36 /// These breakpoint callbacks return a boolean value that indicates if
37 /// the process should continue or halt and should return the global
38 /// setting for this using:
39 /// DynamicLoader::StopWhenImagesChange() const.
40 //----------------------------------------------------------------------
42 public PluginInterface
45 //------------------------------------------------------------------
46 /// Find a dynamic loader plugin for a given process.
48 /// Scans the installed DynamicLoader plug-ins and tries to find
49 /// an instance that can be used to track image changes in \a
52 /// @param[in] process
53 /// The process for which to try and locate a dynamic loader
56 /// @param[in] plugin_name
57 /// An optional name of a specific dynamic loader plug-in that
58 /// should be used. If NULL, pick the best plug-in.
59 //------------------------------------------------------------------
61 FindPlugin (Process *process, const char *plugin_name);
63 //------------------------------------------------------------------
64 /// Construct with a process.
65 //------------------------------------------------------------------
66 DynamicLoader (Process *process);
68 //------------------------------------------------------------------
71 /// The destructor is virtual since this class is designed to be
72 /// inherited from by the plug-in instance.
73 //------------------------------------------------------------------
77 //------------------------------------------------------------------
78 /// Called after attaching a process.
80 /// Allow DynamicLoader plug-ins to execute some code after
81 /// attaching to a process.
82 //------------------------------------------------------------------
86 //------------------------------------------------------------------
87 /// Called after launching a process.
89 /// Allow DynamicLoader plug-ins to execute some code after
90 /// the process has stopped for the first time on launch.
91 //------------------------------------------------------------------
96 //------------------------------------------------------------------
97 /// Helper function that can be used to detect when a process has
98 /// called exec and is now a new and different process. This can
99 /// be called when necessary to try and detect the exec. The process
100 /// might be able to answer this question, but sometimes it might
101 /// not be able and the dynamic loader often knows what the program
102 /// entry point is. So the process and the dynamic loader can work
103 /// together to detect this.
104 //------------------------------------------------------------------
110 //------------------------------------------------------------------
111 /// Get whether the process should stop when images change.
113 /// When images (executables and shared libraries) get loaded or
114 /// unloaded, often debug sessions will want to try and resolve or
115 /// unresolve breakpoints that are set in these images. Any
116 /// breakpoints set by DynamicLoader plug-in instances should
117 /// return this value to ensure consistent debug session behaviour.
120 /// Returns \b true if the process should stop when images
121 /// change, \b false if the process should resume.
122 //------------------------------------------------------------------
124 GetStopWhenImagesChange () const;
126 //------------------------------------------------------------------
127 /// Set whether the process should stop when images change.
129 /// When images (executables and shared libraries) get loaded or
130 /// unloaded, often debug sessions will want to try and resolve or
131 /// unresolve breakpoints that are set in these images. The default
132 /// is set so that the process stops when images change, but this
133 /// can be overridden using this function callback.
136 /// Boolean value that indicates whether the process should stop
137 /// when images change.
138 //------------------------------------------------------------------
140 SetStopWhenImagesChange (bool stop);
142 //------------------------------------------------------------------
143 /// Provides a plan to step through the dynamic loader trampoline
144 /// for the current state of \a thread.
147 /// @param[in] stop_others
148 /// Whether the plan should be set to stop other threads.
151 /// A pointer to the plan (caller owned) or NULL if we are not at such
153 //------------------------------------------------------------------
154 virtual lldb::ThreadPlanSP
155 GetStepThroughTrampolinePlan (Thread &thread, bool stop_others) = 0;
158 //------------------------------------------------------------------
159 /// Some dynamic loaders provide features where there are a group of symbols "equivalent to"
160 /// a given symbol one of which will be chosen when the symbol is bound. If you want to
161 /// set a breakpoint on one of these symbols, you really need to set it on all the
162 /// equivalent symbols.
165 /// @param[in] original_symbol
166 /// The symbol for which we are finding equivalences.
168 /// @param[in] module_list
169 /// The set of modules in which to search.
171 /// @param[out] equivalent_symbols
172 /// The equivalent symbol list - any equivalent symbols found are appended to this list.
175 /// Number of equivalent symbols found.
176 //------------------------------------------------------------------
178 FindEquivalentSymbols (Symbol *original_symbol, ModuleList &module_list, SymbolContextList &equivalent_symbols)
183 //------------------------------------------------------------------
184 /// Ask if it is ok to try and load or unload an shared library
187 /// The dynamic loader often knows when it would be ok to try and
188 /// load or unload a shared library. This function call allows the
189 /// dynamic loader plug-ins to check any current dyld state to make
190 /// sure it is an ok time to load a shared library.
193 /// \b true if it is currently ok to try and load a shared
194 /// library into the process, \b false otherwise.
195 //------------------------------------------------------------------
199 //------------------------------------------------------------------
200 /// Ask if the eh_frame information for the given SymbolContext should
201 /// be relied on even when it's the first frame in a stack unwind.
203 /// The CFI instructions from the eh_frame section are normally only
204 /// valid at call sites -- places where a program could throw an
205 /// exception and need to unwind out. But some Modules may be known
206 /// to the system as having reliable eh_frame information at all call
207 /// sites. This would be the case if the Module's contents are largely
208 /// hand-written assembly with hand-written eh_frame information.
209 /// Normally when unwinding from a function at the beginning of a stack
210 /// unwind lldb will examine the assembly instructions to understand
211 /// how the stack frame is set up and where saved registers are stored.
212 /// But with hand-written assembly this is not reliable enough -- we need
213 /// to consult those function's hand-written eh_frame information.
216 /// \b True if the symbol context should use eh_frame instructions
217 /// unconditionally when unwinding from this frame. Else \b false,
218 /// the normal lldb unwind behavior of only using eh_frame when the
219 /// function appears in the middle of the stack.
220 //------------------------------------------------------------------
222 AlwaysRelyOnEHUnwindInfo (SymbolContext &sym_ctx)
227 //------------------------------------------------------------------
228 /// Retrieves the per-module TLS block for a given thread.
230 /// @param[in] module
231 /// The module to query TLS data for.
233 /// @param[in] thread
234 /// The specific thread to query TLS data for.
237 /// If the given thread has TLS data allocated for the
238 /// module, the address of the TLS block. Otherwise
239 /// LLDB_INVALID_ADDRESS is returned.
240 //------------------------------------------------------------------
242 GetThreadLocalData (const lldb::ModuleSP module, const lldb::ThreadSP thread)
244 return LLDB_INVALID_ADDRESS;
248 //------------------------------------------------------------------
249 // Utility methods for derived classes
250 //------------------------------------------------------------------
252 /// Checks to see if the target module has changed, updates the target
253 /// accordingly and returns the target executable module.
255 GetTargetExecutable();
257 /// Updates the load address of every allocatable section in @p module.
259 /// @param module The module to traverse.
261 /// @param link_map_addr The virtual address of the link map for the @p module.
263 /// @param base_addr The virtual base address @p module is loaded at.
265 UpdateLoadedSections(lldb::ModuleSP module,
266 lldb::addr_t link_map_addr,
267 lldb::addr_t base_addr);
269 // Utility method so base classes can share implementation of UpdateLoadedSections
271 UpdateLoadedSectionsCommon(lldb::ModuleSP module,
272 lldb::addr_t base_addr);
274 /// Removes the loaded sections from the target in @p module.
276 /// @param module The module to traverse.
278 UnloadSections(const lldb::ModuleSP module);
280 // Utility method so base classes can share implementation of UnloadSections
282 UnloadSectionsCommon(const lldb::ModuleSP module);
284 /// Locates or creates a module given by @p file and updates/loads the
285 /// resulting module at the virtual base address @p base_addr.
287 LoadModuleAtAddress(const lldb_private::FileSpec &file, lldb::addr_t link_map_addr, lldb::addr_t base_addr);
289 const lldb_private::SectionList *
290 GetSectionListFromModule(const lldb::ModuleSP module) const;
292 // Read an unsigned int of the given size from memory at the given addr.
293 // Return -1 if the read fails, otherwise return the result as an int64_t.
295 ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes);
297 // Read a pointer from memory at the given addr.
298 // Return LLDB_INVALID_ADDRESS if the read fails.
300 ReadPointer(lldb::addr_t addr);
302 //------------------------------------------------------------------
304 //------------------------------------------------------------------
305 Process* m_process; ///< The process that this dynamic loader plug-in is tracking.
307 DISALLOW_COPY_AND_ASSIGN (DynamicLoader);
311 } // namespace lldb_private
313 #endif // liblldb_DynamicLoader_h_