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 /// @brief 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
55 /// halted at its entry point or just after attaching.
57 /// Dynamic loader plug-ins can track the process by registering
58 /// callbacks using the:
59 /// Process::RegisterNotificationCallbacks (const Notifications&)
62 /// Breakpoints can also be set in the process which can register
63 /// functions that get called using:
64 /// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void
66 /// These breakpoint callbacks return a boolean value that indicates if
67 /// the process should continue or halt and should return the global
68 /// setting for this using:
69 /// DynamicLoader::StopWhenImagesChange() const.
70 //----------------------------------------------------------------------
71 class DynamicLoader : public PluginInterface {
73 //------------------------------------------------------------------
74 /// Find a dynamic loader plugin for a given process.
76 /// Scans the installed DynamicLoader plug-ins and tries to find
77 /// an instance that can be used to track image changes in \a
80 /// @param[in] process
81 /// The process for which to try and locate a dynamic loader
84 /// @param[in] plugin_name
85 /// An optional name of a specific dynamic loader plug-in that
86 /// should be used. If NULL, pick the best plug-in.
87 //------------------------------------------------------------------
88 static DynamicLoader *FindPlugin(Process *process, const char *plugin_name);
90 //------------------------------------------------------------------
91 /// Construct with a process.
92 //------------------------------------------------------------------
93 DynamicLoader(Process *process);
95 //------------------------------------------------------------------
98 /// The destructor is virtual since this class is designed to be
99 /// inherited from by the plug-in instance.
100 //------------------------------------------------------------------
101 virtual ~DynamicLoader() override;
103 //------------------------------------------------------------------
104 /// Called after attaching a process.
106 /// Allow DynamicLoader plug-ins to execute some code after
107 /// attaching to a process.
108 //------------------------------------------------------------------
109 virtual void DidAttach() = 0;
111 //------------------------------------------------------------------
112 /// Called after launching a process.
114 /// Allow DynamicLoader plug-ins to execute some code after
115 /// the process has stopped for the first time on launch.
116 //------------------------------------------------------------------
117 virtual void DidLaunch() = 0;
119 //------------------------------------------------------------------
120 /// Helper function that can be used to detect when a process has
121 /// called exec and is now a new and different process. This can
122 /// be called when necessary to try and detect the exec. The process
123 /// might be able to answer this question, but sometimes it might
124 /// not be able and the dynamic loader often knows what the program
125 /// entry point is. So the process and the dynamic loader can work
126 /// together to detect this.
127 //------------------------------------------------------------------
128 virtual bool ProcessDidExec() { return false; }
129 //------------------------------------------------------------------
130 /// Get whether the process should stop when images change.
132 /// When images (executables and shared libraries) get loaded or
133 /// unloaded, often debug sessions will want to try and resolve or
134 /// unresolve breakpoints that are set in these images. Any
135 /// breakpoints set by DynamicLoader plug-in instances should
136 /// return this value to ensure consistent debug session behaviour.
139 /// Returns \b true if the process should stop when images
140 /// change, \b false if the process should resume.
141 //------------------------------------------------------------------
142 bool GetStopWhenImagesChange() const;
144 //------------------------------------------------------------------
145 /// Set whether the process should stop when images change.
147 /// When images (executables and shared libraries) get loaded or
148 /// unloaded, often debug sessions will want to try and resolve or
149 /// unresolve breakpoints that are set in these images. The default
150 /// is set so that the process stops when images change, but this
151 /// can be overridden using this function callback.
154 /// Boolean value that indicates whether the process should stop
155 /// when images change.
156 //------------------------------------------------------------------
157 void SetStopWhenImagesChange(bool stop);
159 //------------------------------------------------------------------
160 /// Provides a plan to step through the dynamic loader trampoline
161 /// for the current state of \a thread.
164 /// @param[in] stop_others
165 /// Whether the plan should be set to stop other threads.
168 /// A pointer to the plan (caller owned) or NULL if we are not at such
170 //------------------------------------------------------------------
171 virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread,
172 bool stop_others) = 0;
174 //------------------------------------------------------------------
175 /// Some dynamic loaders provide features where there are a group of symbols
177 /// a given symbol one of which will be chosen when the symbol is bound. If
179 /// set a breakpoint on one of these symbols, you really need to set it on all
181 /// equivalent symbols.
184 /// @param[in] original_symbol
185 /// The symbol for which we are finding equivalences.
187 /// @param[in] module_list
188 /// The set of modules in which to search.
190 /// @param[out] equivalent_symbols
191 /// The equivalent symbol list - any equivalent symbols found are appended
195 /// Number of equivalent symbols found.
196 //------------------------------------------------------------------
197 virtual size_t FindEquivalentSymbols(Symbol *original_symbol,
198 ModuleList &module_list,
199 SymbolContextList &equivalent_symbols) {
203 //------------------------------------------------------------------
204 /// Ask if it is ok to try and load or unload an shared library
207 /// The dynamic loader often knows when it would be ok to try and
208 /// load or unload a shared library. This function call allows the
209 /// dynamic loader plug-ins to check any current dyld state to make
210 /// sure it is an ok time to load a shared library.
213 /// \b true if it is currently ok to try and load a shared
214 /// library into the process, \b false otherwise.
215 //------------------------------------------------------------------
216 virtual Status CanLoadImage() = 0;
218 //------------------------------------------------------------------
219 /// Ask if the eh_frame information for the given SymbolContext should
220 /// be relied on even when it's the first frame in a stack unwind.
222 /// The CFI instructions from the eh_frame section are normally only
223 /// valid at call sites -- places where a program could throw an
224 /// exception and need to unwind out. But some Modules may be known
225 /// to the system as having reliable eh_frame information at all call
226 /// sites. This would be the case if the Module's contents are largely
227 /// hand-written assembly with hand-written eh_frame information.
228 /// Normally when unwinding from a function at the beginning of a stack
229 /// unwind lldb will examine the assembly instructions to understand
230 /// how the stack frame is set up and where saved registers are stored.
231 /// But with hand-written assembly this is not reliable enough -- we need
232 /// to consult those function's hand-written eh_frame information.
235 /// \b True if the symbol context should use eh_frame instructions
236 /// unconditionally when unwinding from this frame. Else \b false,
237 /// the normal lldb unwind behavior of only using eh_frame when the
238 /// function appears in the middle of the stack.
239 //------------------------------------------------------------------
240 virtual bool AlwaysRelyOnEHUnwindInfo(SymbolContext &sym_ctx) {
244 //------------------------------------------------------------------
245 /// Retrieves the per-module TLS block for a given thread.
247 /// @param[in] module
248 /// The module to query TLS data for.
250 /// @param[in] thread
251 /// The specific thread to query TLS data for.
254 /// If the given thread has TLS data allocated for the
255 /// module, the address of the TLS block. Otherwise
256 /// LLDB_INVALID_ADDRESS is returned.
257 //------------------------------------------------------------------
258 virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module,
259 const lldb::ThreadSP thread,
260 lldb::addr_t tls_file_addr) {
261 return LLDB_INVALID_ADDRESS;
264 /// Locates or creates a module given by @p file and updates/loads the
265 /// resulting module at the virtual base address @p base_addr.
266 virtual lldb::ModuleSP LoadModuleAtAddress(const lldb_private::FileSpec &file,
267 lldb::addr_t link_map_addr,
268 lldb::addr_t base_addr,
269 bool base_addr_is_offset);
271 //------------------------------------------------------------------
272 /// Get information about the shared cache for a process, if possible.
274 /// On some systems (e.g. Darwin based systems), a set of libraries
275 /// that are common to most processes may be put in a single region
276 /// of memory and mapped into every process, this is called the
277 /// shared cache, as a performance optimization.
279 /// Many targets will not have the concept of a shared cache.
281 /// Depending on how the DynamicLoader gathers information about the
282 /// shared cache, it may be able to only return basic information -
283 /// like the UUID of the cache - or it may be able to return additional
284 /// information about the cache.
286 /// @param[out] base_address
287 /// The base address (load address) of the shared cache.
288 /// LLDB_INVALID_ADDRESS if it cannot be determined.
291 /// The UUID of the shared cache, if it can be determined.
292 /// If the UUID cannot be fetched, IsValid() will be false.
294 /// @param[out] using_shared_cache
295 /// If this process is using a shared cache.
296 /// If unknown, eLazyBoolCalculate is returned.
298 /// @param[out] private_shared_cache
299 /// A LazyBool indicating whether this process is using a
300 /// private shared cache.
301 /// If this information cannot be fetched, eLazyBoolCalculate.
304 /// Returns false if this DynamicLoader cannot gather information
305 /// about the shared cache / has no concept of a shared cache.
306 //------------------------------------------------------------------
307 virtual bool GetSharedCacheInformation(lldb::addr_t &base_address, UUID &uuid,
308 LazyBool &using_shared_cache,
309 LazyBool &private_shared_cache) {
310 base_address = LLDB_INVALID_ADDRESS;
312 using_shared_cache = eLazyBoolCalculate;
313 private_shared_cache = eLazyBoolCalculate;
318 //------------------------------------------------------------------
319 // Utility methods for derived classes
320 //------------------------------------------------------------------
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();
326 /// Updates the load address of every allocatable section in @p module.
328 /// @param module The module to traverse.
330 /// @param link_map_addr The virtual address of the link map for the @p
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);
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);
344 /// Removes the loaded sections from the target in @p module.
346 /// @param module The module to traverse.
347 virtual void UnloadSections(const lldb::ModuleSP module);
349 // Utility method so base classes can share implementation of UnloadSections
350 void UnloadSectionsCommon(const lldb::ModuleSP module);
352 const lldb_private::SectionList *
353 GetSectionListFromModule(const lldb::ModuleSP module) const;
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);
359 // Read a pointer from memory at the given addr.
360 // Return LLDB_INVALID_ADDRESS if the read fails.
361 lldb::addr_t ReadPointer(lldb::addr_t addr);
363 // Calls into the Process protected method LoadOperatingSystemPlugin:
364 void LoadOperatingSystemPlugin(bool flush);
367 //------------------------------------------------------------------
369 //------------------------------------------------------------------
371 *m_process; ///< The process that this dynamic loader plug-in is tracking.
374 DISALLOW_COPY_AND_ASSIGN(DynamicLoader);
377 } // namespace lldb_private
379 #endif // liblldb_DynamicLoader_h_