contrib/llvm-project/lldb/include/lldb/Target/DynamicLoader.h

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