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