DynamicLoader.h revision 355940
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 liblldb_DynamicLoader_h_ 10#define liblldb_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 <stddef.h> 22#include <stdint.h> 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 NULL, pick the best plug-in. 66 static DynamicLoader *FindPlugin(Process *process, const char *plugin_name); 67 68 /// Construct with a process. 69 DynamicLoader(Process *process); 70 71 /// Destructor. 72 /// 73 /// The destructor is virtual since this class is designed to be inherited 74 /// from by the plug-in instance. 75 ~DynamicLoader() override; 76 77 /// Called after attaching a process. 78 /// 79 /// Allow DynamicLoader plug-ins to execute some code after attaching to a 80 /// process. 81 virtual void DidAttach() = 0; 82 83 /// Called after launching a process. 84 /// 85 /// Allow DynamicLoader plug-ins to execute some code after the process has 86 /// stopped for the first time on launch. 87 virtual void DidLaunch() = 0; 88 89 /// Helper function that can be used to detect when a process has called 90 /// exec and is now a new and different process. This can be called when 91 /// necessary to try and detect the exec. The process might be able to 92 /// answer this question, but sometimes it might not be able and the dynamic 93 /// loader often knows what the program entry point is. So the process and 94 /// the dynamic loader can work together to detect this. 95 virtual bool ProcessDidExec() { return false; } 96 /// Get whether the process should stop when images change. 97 /// 98 /// When images (executables and shared libraries) get loaded or unloaded, 99 /// often debug sessions will want to try and resolve or unresolve 100 /// breakpoints that are set in these images. Any breakpoints set by 101 /// DynamicLoader plug-in instances should return this value to ensure 102 /// consistent debug session behaviour. 103 /// 104 /// \return 105 /// Returns \b true if the process should stop when images 106 /// change, \b false if the process should resume. 107 bool GetStopWhenImagesChange() const; 108 109 /// Set whether the process should stop when images change. 110 /// 111 /// When images (executables and shared libraries) get loaded or unloaded, 112 /// often debug sessions will want to try and resolve or unresolve 113 /// breakpoints that are set in these images. The default is set so that the 114 /// process stops when images change, but this can be overridden using this 115 /// function callback. 116 /// 117 /// \param[in] stop 118 /// Boolean value that indicates whether the process should stop 119 /// when images change. 120 void SetStopWhenImagesChange(bool stop); 121 122 /// Provides a plan to step through the dynamic loader trampoline for the 123 /// current state of \a thread. 124 /// 125 /// 126 /// \param[in] stop_others 127 /// Whether the plan should be set to stop other threads. 128 /// 129 /// \return 130 /// A pointer to the plan (caller owned) or NULL if we are not at such 131 /// a trampoline. 132 virtual lldb::ThreadPlanSP GetStepThroughTrampolinePlan(Thread &thread, 133 bool stop_others) = 0; 134 135 /// Some dynamic loaders provide features where there are a group of symbols 136 /// "equivalent to" a given symbol one of which will be chosen when the 137 /// symbol is bound. If you want to set a breakpoint on one of these 138 /// symbols, you really need to set it on all the equivalent symbols. 139 /// 140 /// 141 /// \param[in] original_symbol 142 /// The symbol for which we are finding equivalences. 143 /// 144 /// \param[in] module_list 145 /// The set of modules in which to search. 146 /// 147 /// \param[out] equivalent_symbols 148 /// The equivalent symbol list - any equivalent symbols found are appended 149 /// to this list. 150 /// 151 /// \return 152 /// Number of equivalent symbols found. 153 virtual size_t FindEquivalentSymbols(Symbol *original_symbol, 154 ModuleList &module_list, 155 SymbolContextList &equivalent_symbols) { 156 return 0; 157 } 158 159 /// Ask if it is ok to try and load or unload an shared library (image). 160 /// 161 /// The dynamic loader often knows when it would be ok to try and load or 162 /// unload a shared library. This function call allows the dynamic loader 163 /// plug-ins to check any current dyld state to make sure it is an ok time 164 /// to load a shared library. 165 /// 166 /// \return 167 /// \b true if it is currently ok to try and load a shared 168 /// library into the process, \b false otherwise. 169 virtual Status CanLoadImage() = 0; 170 171 /// Ask if the eh_frame information for the given SymbolContext should be 172 /// relied on even when it's the first frame in a stack unwind. 173 /// 174 /// The CFI instructions from the eh_frame section are normally only valid 175 /// at call sites -- places where a program could throw an exception and 176 /// need to unwind out. But some Modules may be known to the system as 177 /// having reliable eh_frame information at all call sites. This would be 178 /// the case if the Module's contents are largely hand-written assembly with 179 /// hand-written eh_frame information. Normally when unwinding from a 180 /// function at the beginning of a stack unwind lldb will examine the 181 /// assembly instructions to understand how the stack frame is set up and 182 /// where saved registers are stored. But with hand-written assembly this is 183 /// not reliable enough -- we need to consult those function's hand-written 184 /// eh_frame information. 185 /// 186 /// \return 187 /// \b True if the symbol context should use eh_frame instructions 188 /// unconditionally when unwinding from this frame. Else \b false, 189 /// the normal lldb unwind behavior of only using eh_frame when the 190 /// function appears in the middle of the stack. 191 virtual bool AlwaysRelyOnEHUnwindInfo(SymbolContext &sym_ctx) { 192 return false; 193 } 194 195 /// Retrieves the per-module TLS block for a given thread. 196 /// 197 /// \param[in] module 198 /// The module to query TLS data for. 199 /// 200 /// \param[in] thread 201 /// The specific thread to query TLS data for. 202 /// 203 /// \return 204 /// If the given thread has TLS data allocated for the 205 /// module, the address of the TLS block. Otherwise 206 /// LLDB_INVALID_ADDRESS is returned. 207 virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module, 208 const lldb::ThreadSP thread, 209 lldb::addr_t tls_file_addr) { 210 return LLDB_INVALID_ADDRESS; 211 } 212 213 /// Locates or creates a module given by \p file and updates/loads the 214 /// resulting module at the virtual base address \p base_addr. 215 virtual lldb::ModuleSP LoadModuleAtAddress(const lldb_private::FileSpec &file, 216 lldb::addr_t link_map_addr, 217 lldb::addr_t base_addr, 218 bool base_addr_is_offset); 219 220 /// Get information about the shared cache for a process, if possible. 221 /// 222 /// On some systems (e.g. Darwin based systems), a set of libraries that are 223 /// common to most processes may be put in a single region of memory and 224 /// mapped into every process, this is called the shared cache, as a 225 /// performance optimization. 226 /// 227 /// Many targets will not have the concept of a shared cache. 228 /// 229 /// Depending on how the DynamicLoader gathers information about the shared 230 /// cache, it may be able to only return basic information - like the UUID 231 /// of the cache - or it may be able to return additional information about 232 /// the cache. 233 /// 234 /// \param[out] base_address 235 /// The base address (load address) of the shared cache. 236 /// LLDB_INVALID_ADDRESS if it cannot be determined. 237 /// 238 /// \param[out] uuid 239 /// The UUID of the shared cache, if it can be determined. 240 /// If the UUID cannot be fetched, IsValid() will be false. 241 /// 242 /// \param[out] using_shared_cache 243 /// If this process is using a shared cache. 244 /// If unknown, eLazyBoolCalculate is returned. 245 /// 246 /// \param[out] private_shared_cache 247 /// A LazyBool indicating whether this process is using a 248 /// private shared cache. 249 /// If this information cannot be fetched, eLazyBoolCalculate. 250 /// 251 /// \return 252 /// Returns false if this DynamicLoader cannot gather information 253 /// about the shared cache / has no concept of a shared cache. 254 virtual bool GetSharedCacheInformation(lldb::addr_t &base_address, UUID &uuid, 255 LazyBool &using_shared_cache, 256 LazyBool &private_shared_cache) { 257 base_address = LLDB_INVALID_ADDRESS; 258 uuid.Clear(); 259 using_shared_cache = eLazyBoolCalculate; 260 private_shared_cache = eLazyBoolCalculate; 261 return false; 262 } 263 264protected: 265 // Utility methods for derived classes 266 267 /// Checks to see if the target module has changed, updates the target 268 /// accordingly and returns the target executable module. 269 lldb::ModuleSP GetTargetExecutable(); 270 271 /// Updates the load address of every allocatable section in \p module. 272 /// 273 /// \param module The module to traverse. 274 /// 275 /// \param link_map_addr The virtual address of the link map for the @p 276 /// module. 277 /// 278 /// \param base_addr The virtual base address \p module is loaded at. 279 virtual void UpdateLoadedSections(lldb::ModuleSP module, 280 lldb::addr_t link_map_addr, 281 lldb::addr_t base_addr, 282 bool base_addr_is_offset); 283 284 // Utility method so base classes can share implementation of 285 // UpdateLoadedSections 286 void UpdateLoadedSectionsCommon(lldb::ModuleSP module, lldb::addr_t base_addr, 287 bool base_addr_is_offset); 288 289 /// Removes the loaded sections from the target in \p module. 290 /// 291 /// \param module The module to traverse. 292 virtual void UnloadSections(const lldb::ModuleSP module); 293 294 // Utility method so base classes can share implementation of UnloadSections 295 void UnloadSectionsCommon(const lldb::ModuleSP module); 296 297 const lldb_private::SectionList * 298 GetSectionListFromModule(const lldb::ModuleSP module) const; 299 300 // Read an unsigned int of the given size from memory at the given addr. 301 // Return -1 if the read fails, otherwise return the result as an int64_t. 302 int64_t ReadUnsignedIntWithSizeInBytes(lldb::addr_t addr, int size_in_bytes); 303 304 // Read a pointer from memory at the given addr. Return LLDB_INVALID_ADDRESS 305 // if the read fails. 306 lldb::addr_t ReadPointer(lldb::addr_t addr); 307 308 // Calls into the Process protected method LoadOperatingSystemPlugin: 309 void LoadOperatingSystemPlugin(bool flush); 310 311 312 // Member variables. 313 Process 314 *m_process; ///< The process that this dynamic loader plug-in is tracking. 315 316private: 317 DISALLOW_COPY_AND_ASSIGN(DynamicLoader); 318}; 319 320} // namespace lldb_private 321 322#endif // liblldb_DynamicLoader_h_ 323