Coverage Report

Created: 2022-01-25 06:29

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Target/DynamicLoader.h
Line
Count
Source (jump to first uncovered line)
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
0
  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
0
                                     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
2
  virtual bool AlwaysRelyOnEHUnwindInfo(SymbolContext &sym_ctx) {
183
2
    return false;
184
2
  }
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
0
                                          lldb::addr_t tls_file_addr) {
201
0
    return LLDB_INVALID_ADDRESS;
202
0
  }
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
  virtual lldb::ModuleSP LoadModuleAtAddress(const lldb_private::FileSpec &file,
207
                                             lldb::addr_t link_map_addr,
208
                                             lldb::addr_t base_addr,
209
                                             bool base_addr_is_offset);
210
211
  /// Get information about the shared cache for a process, if possible.
212
  ///
213
  /// On some systems (e.g. Darwin based systems), a set of libraries that are
214
  /// common to most processes may be put in a single region of memory and
215
  /// mapped into every process, this is called the shared cache, as a
216
  /// performance optimization.
217
  ///
218
  /// Many targets will not have the concept of a shared cache.
219
  ///
220
  /// Depending on how the DynamicLoader gathers information about the shared
221
  /// cache, it may be able to only return basic information - like the UUID
222
  /// of the cache - or it may be able to return additional information about
223
  /// the cache.
224
  ///
225
  /// \param[out] base_address
226
  ///     The base address (load address) of the shared cache.
227
  ///     LLDB_INVALID_ADDRESS if it cannot be determined.
228
  ///
229
  /// \param[out] uuid
230
  ///     The UUID of the shared cache, if it can be determined.
231
  ///     If the UUID cannot be fetched, IsValid() will be false.
232
  ///
233
  /// \param[out] using_shared_cache
234
  ///     If this process is using a shared cache.
235
  ///     If unknown, eLazyBoolCalculate is returned.
236
  ///
237
  /// \param[out] private_shared_cache
238
  ///     A LazyBool indicating whether this process is using a
239
  ///     private shared cache.
240
  ///     If this information cannot be fetched, eLazyBoolCalculate.
241
  ///
242
  /// \return
243
  ///     Returns false if this DynamicLoader cannot gather information
244
  ///     about the shared cache / has no concept of a shared cache.
245
  virtual bool GetSharedCacheInformation(lldb::addr_t &base_address, UUID &uuid,
246
                                         LazyBool &using_shared_cache,
247
0
                                         LazyBool &private_shared_cache) {
248
0
    base_address = LLDB_INVALID_ADDRESS;
249
0
    uuid.Clear();
250
0
    using_shared_cache = eLazyBoolCalculate;
251
0
    private_shared_cache = eLazyBoolCalculate;
252
0
    return false;
253
0
  }
254
255
  /// Return whether the dynamic loader is fully initialized and it's safe to
256
  /// call its APIs.
257
  ///
258
  /// On some systems (e.g. Darwin based systems), lldb will get notified by
259
  /// the dynamic loader before it itself finished initializing and it's not
260
  /// safe to call certain APIs or SPIs.
261
1.22k
  virtual bool IsFullyInitialized() { return true; }
262
263
protected:
264
  // Utility methods for derived classes
265
266
  /// Checks to see if the target module has changed, updates the target
267
  /// accordingly and returns the target executable module.
268
  lldb::ModuleSP GetTargetExecutable();
269
270
  /// Updates the load address of every allocatable section in \p module.
271
  ///
272
  /// \param module The module to traverse.
273
  ///
274
  /// \param link_map_addr The virtual address of the link map for the @p
275
  /// module.
276
  ///
277
  /// \param base_addr The virtual base address \p module is loaded at.
278
  virtual void UpdateLoadedSections(lldb::ModuleSP module,
279
                                    lldb::addr_t link_map_addr,
280
                                    lldb::addr_t base_addr,
281
                                    bool base_addr_is_offset);
282
283
  // Utility method so base classes can share implementation of
284
  // UpdateLoadedSections
285
  void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr,
286
                                  bool base_addr_is_offset);
287
288
  /// Removes the loaded sections from the target in \p module.
289
  ///
290
  /// \param module The module to traverse.
291
  virtual void UnloadSections(const lldb::ModuleSP module);
292
293
  // Utility method so base classes can share implementation of UnloadSections
294
  void UnloadSectionsCommon(const lldb::ModuleSP module);
295
296
  const lldb_private::SectionList *
297
  GetSectionListFromModule(const lldb::ModuleSP module) const;
298
299
  // Read an unsigned int of the given size from memory at the given addr.
300
  // Return -1 if the read fails, otherwise return the result as an int64_t.
301
  int64_t ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes);
302
303
  // Read a pointer from memory at the given addr. Return LLDB_INVALID_ADDRESS
304
  // if the read fails.
305
  lldb::addr_t ReadPointer(lldb::addr_t addr);
306
307
  // Calls into the Process protected method LoadOperatingSystemPlugin:
308
  void LoadOperatingSystemPlugin(bool flush);
309
310
311
  // Member variables.
312
  Process
313
      *m_process; ///< The process that this dynamic loader plug-in is tracking.
314
};
315
316
} // namespace lldb_private
317
318
#endif // LLDB_TARGET_DYNAMICLOADER_H