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