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