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