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