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>
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 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
332protected:
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

source code of lldb/include/lldb/Target/DynamicLoader.h