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