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