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