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