include/lldb/Target/DynamicLoader.h

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