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