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