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 <cstddef> |
22 | #include <cstdint> |
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. |
52 | class DynamicLoader : public PluginInterface { |
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 empty, pick the best plug-in. |
66 | static DynamicLoader *FindPlugin(Process *process, |
67 | llvm::StringRef plugin_name); |
68 | |
69 | /// Construct with a process. |
70 | DynamicLoader(Process *process); |
71 | |
72 | /// Called after attaching a process. |
73 | /// |
74 | /// Allow DynamicLoader plug-ins to execute some code after attaching to a |
75 | /// process. |
76 | virtual void DidAttach() = 0; |
77 | |
78 | /// Called after launching a process. |
79 | /// |
80 | /// Allow DynamicLoader plug-ins to execute some code after the process has |
81 | /// stopped for the first time on launch. |
82 | virtual void DidLaunch() = 0; |
83 | |
84 | /// Helper function that can be used to detect when a process has called |
85 | /// exec and is now a new and different process. This can be called when |
86 | /// necessary to try and detect the exec. The process might be able to |
87 | /// answer this question, but sometimes it might not be able and the dynamic |
88 | /// loader often knows what the program entry point is. So the process and |
89 | /// the dynamic loader can work together to detect this. |
90 | virtual bool ProcessDidExec() { return false; } |
91 | /// Get whether the process should stop when images change. |
92 | /// |
93 | /// When images (executables and shared libraries) get loaded or unloaded, |
94 | /// often debug sessions will want to try and resolve or unresolve |
95 | /// breakpoints that are set in these images. Any breakpoints set by |
96 | /// DynamicLoader plug-in instances should return this value to ensure |
97 | /// consistent debug session behaviour. |
98 | /// |
99 | /// \return |
100 | /// Returns \b true if the process should stop when images |
101 | /// change, \b false if the process should resume. |
102 | bool GetStopWhenImagesChange() const; |
103 | |
104 | /// Set whether the process should stop when images change. |
105 | /// |
106 | /// When images (executables and shared libraries) get loaded or unloaded, |
107 | /// often debug sessions will want to try and resolve or unresolve |
108 | /// breakpoints that are set in these images. The default is set so that the |
109 | /// process stops when images change, but this can be overridden using this |
110 | /// function callback. |
111 | /// |
112 | /// \param[in] stop |
113 | /// Boolean value that indicates whether the process should stop |
114 | /// when images change. |
115 | void SetStopWhenImagesChange(bool stop); |
116 | |
117 | /// Provides a plan to step through the dynamic loader trampoline for the |
118 | /// current state of \a thread. |
119 | /// |
120 | /// |
121 | /// \param[in] stop_others |
122 | /// Whether the plan should be set to stop other threads. |
123 | /// |
124 | /// \return |
125 | /// A pointer to the plan (caller owned) or NULL if we are not at such |
126 | /// a trampoline. |
127 | virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread, |
128 | bool stop_others) = 0; |
129 | |
130 | /// Some dynamic loaders provide features where there are a group of symbols |
131 | /// "equivalent to" a given symbol one of which will be chosen when the |
132 | /// symbol is bound. If you want to set a breakpoint on one of these |
133 | /// symbols, you really need to set it on all the equivalent symbols. |
134 | /// |
135 | /// |
136 | /// \param[in] original_symbol |
137 | /// The symbol for which we are finding equivalences. |
138 | /// |
139 | /// \param[in] module_list |
140 | /// The set of modules in which to search. |
141 | /// |
142 | /// \param[out] equivalent_symbols |
143 | /// The equivalent symbol list - any equivalent symbols found are appended |
144 | /// to this list. |
145 | /// |
146 | virtual void FindEquivalentSymbols(Symbol *original_symbol, |
147 | ModuleList &module_list, |
148 | SymbolContextList &equivalent_symbols) {} |
149 | |
150 | /// Ask if it is ok to try and load or unload an shared library (image). |
151 | /// |
152 | /// The dynamic loader often knows when it would be ok to try and load or |
153 | /// unload a shared library. This function call allows the dynamic loader |
154 | /// plug-ins to check any current dyld state to make sure it is an ok time |
155 | /// to load a shared library. |
156 | /// |
157 | /// \return |
158 | /// \b true if it is currently ok to try and load a shared |
159 | /// library into the process, \b false otherwise. |
160 | virtual Status CanLoadImage() = 0; |
161 | |
162 | /// Ask if the eh_frame information for the given SymbolContext should be |
163 | /// relied on even when it's the first frame in a stack unwind. |
164 | /// |
165 | /// The CFI instructions from the eh_frame section are normally only valid |
166 | /// at call sites -- places where a program could throw an exception and |
167 | /// need to unwind out. But some Modules may be known to the system as |
168 | /// having reliable eh_frame information at all call sites. This would be |
169 | /// the case if the Module's contents are largely hand-written assembly with |
170 | /// hand-written eh_frame information. Normally when unwinding from a |
171 | /// function at the beginning of a stack unwind lldb will examine the |
172 | /// assembly instructions to understand how the stack frame is set up and |
173 | /// where saved registers are stored. But with hand-written assembly this is |
174 | /// not reliable enough -- we need to consult those function's hand-written |
175 | /// eh_frame information. |
176 | /// |
177 | /// \return |
178 | /// \b True if the symbol context should use eh_frame instructions |
179 | /// unconditionally when unwinding from this frame. Else \b false, |
180 | /// the normal lldb unwind behavior of only using eh_frame when the |
181 | /// function appears in the middle of the stack. |
182 | virtual bool AlwaysRelyOnEHUnwindInfo(SymbolContext &sym_ctx) { |
183 | return false; |
184 | } |
185 | |
186 | /// Retrieves the per-module TLS block for a given thread. |
187 | /// |
188 | /// \param[in] module |
189 | /// The module to query TLS data for. |
190 | /// |
191 | /// \param[in] thread |
192 | /// The specific thread to query TLS data for. |
193 | /// |
194 | /// \return |
195 | /// If the given thread has TLS data allocated for the |
196 | /// module, the address of the TLS block. Otherwise |
197 | /// LLDB_INVALID_ADDRESS is returned. |
198 | virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module, |
199 | const lldb::ThreadSP thread, |
200 | lldb::addr_t tls_file_addr) { |
201 | return LLDB_INVALID_ADDRESS; |
202 | } |
203 | |
204 | /// Locates or creates a module given by \p file and updates/loads the |
205 | /// resulting module at the virtual base address \p base_addr. |
206 | /// Note that this calls Target::GetOrCreateModule with notify being false, |
207 | /// so it is necessary to call Target::ModulesDidLoad afterwards. |
208 | virtual lldb::ModuleSP LoadModuleAtAddress(const lldb_private::FileSpec &file, |
209 | lldb::addr_t link_map_addr, |
210 | lldb::addr_t base_addr, |
211 | bool base_addr_is_offset); |
212 | |
213 | /// Find/load a binary into lldb given a UUID and the address where it is |
214 | /// loaded in memory, or a slide to be applied to the file address. |
215 | /// May force an expensive search on the computer to find the binary by |
216 | /// UUID, should not be used for a large number of binaries - intended for |
217 | /// an environment where there may be one, or a few, binaries resident in |
218 | /// memory. |
219 | /// |
220 | /// Given a UUID, search for a binary and load it at the address provided, |
221 | /// or with the slide applied, or at the file address unslid. |
222 | /// |
223 | /// Given an address, try to read the binary out of memory, get the UUID, |
224 | /// find the file if possible and load it unslid, or add the memory module. |
225 | /// |
226 | /// \param[in] process |
227 | /// The process to add this binary to. |
228 | /// |
229 | /// \param[in] name |
230 | /// Name of the binary, if available. If this method cannot find a |
231 | /// matching binary on the debug host, it may create a memory module |
232 | /// out of live memory, and the provided name will be used. If an |
233 | /// empty StringRef is provided, a name will be constructed for the module |
234 | /// based on the address it is loaded at. |
235 | /// |
236 | /// \param[in] uuid |
237 | /// UUID of the binary to be loaded. UUID may be empty, and if a |
238 | /// load address is supplied, will read the binary from memory, get |
239 | /// a UUID and try to find a local binary. There is a performance |
240 | /// cost to doing this, it is not preferable. |
241 | /// |
242 | /// \param[in] value |
243 | /// Address where the binary should be loaded, or read out of memory. |
244 | /// Or a slide value, to be applied to the file addresses of the binary. |
245 | /// |
246 | /// \param[in] value_is_offset |
247 | /// A flag indicating that \p value is an address, or an offset to |
248 | /// be applied to the file addresses. |
249 | /// |
250 | /// \param[in] force_symbol_search |
251 | /// Allow the search to do a possibly expensive external search for |
252 | /// the ObjectFile and/or SymbolFile. |
253 | /// |
254 | /// \param[in] notify |
255 | /// Whether ModulesDidLoad should be called when a binary has been added |
256 | /// to the Target. The caller may prefer to batch up these when loading |
257 | /// multiple binaries. |
258 | /// |
259 | /// \param[in] set_address_in_target |
260 | /// Whether the address of the binary should be set in the Target if it |
261 | /// is added. The caller may want to set the section addresses |
262 | /// individually, instead of loading the binary the entire based on the |
263 | /// start address or slide. The caller is responsible for setting the |
264 | /// load address for the binary or its segments in the Target if it passes |
265 | /// true. |
266 | /// |
267 | /// \param[in] allow_memory_image_last_resort |
268 | /// If no better binary image can be found, allow reading the binary |
269 | /// out of memory, if possible, and create the Module based on that. |
270 | /// May be slow to read a binary out of memory, and for unusual |
271 | /// environments, may be no symbols mapped in memory at all. |
272 | /// |
273 | /// \return |
274 | /// Returns a shared pointer for the Module that has been added. |
275 | static lldb::ModuleSP LoadBinaryWithUUIDAndAddress( |
276 | Process *process, llvm::StringRef name, UUID uuid, lldb::addr_t value, |
277 | bool value_is_offset, bool force_symbol_search, bool notify, |
278 | bool set_address_in_target, bool allow_memory_image_last_resort); |
279 | |
280 | /// Get information about the shared cache for a process, if possible. |
281 | /// |
282 | /// On some systems (e.g. Darwin based systems), a set of libraries that are |
283 | /// common to most processes may be put in a single region of memory and |
284 | /// mapped into every process, this is called the shared cache, as a |
285 | /// performance optimization. |
286 | /// |
287 | /// Many targets will not have the concept of a shared cache. |
288 | /// |
289 | /// Depending on how the DynamicLoader gathers information about the shared |
290 | /// cache, it may be able to only return basic information - like the UUID |
291 | /// of the cache - or it may be able to return additional information about |
292 | /// the cache. |
293 | /// |
294 | /// \param[out] base_address |
295 | /// The base address (load address) of the shared cache. |
296 | /// LLDB_INVALID_ADDRESS if it cannot be determined. |
297 | /// |
298 | /// \param[out] uuid |
299 | /// The UUID of the shared cache, if it can be determined. |
300 | /// If the UUID cannot be fetched, IsValid() will be false. |
301 | /// |
302 | /// \param[out] using_shared_cache |
303 | /// If this process is using a shared cache. |
304 | /// If unknown, eLazyBoolCalculate is returned. |
305 | /// |
306 | /// \param[out] private_shared_cache |
307 | /// A LazyBool indicating whether this process is using a |
308 | /// private shared cache. |
309 | /// If this information cannot be fetched, eLazyBoolCalculate. |
310 | /// |
311 | /// \return |
312 | /// Returns false if this DynamicLoader cannot gather information |
313 | /// about the shared cache / has no concept of a shared cache. |
314 | virtual bool GetSharedCacheInformation(lldb::addr_t &base_address, UUID &uuid, |
315 | LazyBool &using_shared_cache, |
316 | LazyBool &private_shared_cache) { |
317 | base_address = LLDB_INVALID_ADDRESS; |
318 | uuid.Clear(); |
319 | using_shared_cache = eLazyBoolCalculate; |
320 | private_shared_cache = eLazyBoolCalculate; |
321 | return false; |
322 | } |
323 | |
324 | /// Return whether the dynamic loader is fully initialized and it's safe to |
325 | /// call its APIs. |
326 | /// |
327 | /// On some systems (e.g. Darwin based systems), lldb will get notified by |
328 | /// the dynamic loader before it itself finished initializing and it's not |
329 | /// safe to call certain APIs or SPIs. |
330 | virtual bool IsFullyInitialized() { return true; } |
331 | |
332 | protected: |
333 | // Utility methods for derived classes |
334 | |
335 | lldb::ModuleSP FindModuleViaTarget(const FileSpec &file); |
336 | |
337 | /// Checks to see if the target module has changed, updates the target |
338 | /// accordingly and returns the target executable module. |
339 | lldb::ModuleSP GetTargetExecutable(); |
340 | |
341 | /// Updates the load address of every allocatable section in \p module. |
342 | /// |
343 | /// \param module The module to traverse. |
344 | /// |
345 | /// \param link_map_addr The virtual address of the link map for the @p |
346 | /// module. |
347 | /// |
348 | /// \param base_addr The virtual base address \p module is loaded at. |
349 | virtual void UpdateLoadedSections(lldb::ModuleSP module, |
350 | lldb::addr_t link_map_addr, |
351 | lldb::addr_t base_addr, |
352 | bool base_addr_is_offset); |
353 | |
354 | // Utility method so base classes can share implementation of |
355 | // UpdateLoadedSections |
356 | void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr, |
357 | bool base_addr_is_offset); |
358 | |
359 | /// Removes the loaded sections from the target in \p module. |
360 | /// |
361 | /// \param module The module to traverse. |
362 | virtual void UnloadSections(const lldb::ModuleSP module); |
363 | |
364 | // Utility method so base classes can share implementation of UnloadSections |
365 | void UnloadSectionsCommon(const lldb::ModuleSP module); |
366 | |
367 | const lldb_private::SectionList * |
368 | GetSectionListFromModule(const lldb::ModuleSP module) const; |
369 | |
370 | // Read an unsigned int of the given size from memory at the given addr. |
371 | // Return -1 if the read fails, otherwise return the result as an int64_t. |
372 | int64_t ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes); |
373 | |
374 | // Read a pointer from memory at the given addr. Return LLDB_INVALID_ADDRESS |
375 | // if the read fails. |
376 | lldb::addr_t ReadPointer(lldb::addr_t addr); |
377 | |
378 | // Calls into the Process protected method LoadOperatingSystemPlugin: |
379 | void LoadOperatingSystemPlugin(bool flush); |
380 | |
381 | |
382 | // Member variables. |
383 | Process |
384 | *m_process; ///< The process that this dynamic loader plug-in is tracking. |
385 | }; |
386 | |
387 | } // namespace lldb_private |
388 | |
389 | #endif // LLDB_TARGET_DYNAMICLOADER_H |
390 | |