DynamicLoader.h revision e6bd142d9fa7ed149bd37efd8a75637375f165b7
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 18namespace 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//---------------------------------------------------------------------- 41class DynamicLoader : 42 public PluginInterface 43{ 44public: 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 //------------------------------------------------------------------ 98 /// Get whether the process should stop when images change. 99 /// 100 /// When images (executables and shared libraries) get loaded or 101 /// unloaded, often debug sessions will want to try and resolve or 102 /// unresolve breakpoints that are set in these images. Any 103 /// breakpoints set by DynamicLoader plug-in instances should 104 /// return this value to ensure consistent debug session behaviour. 105 /// 106 /// @return 107 /// Returns \b true if the process should stop when images 108 /// change, \b false if the process should resume. 109 //------------------------------------------------------------------ 110 bool 111 GetStopWhenImagesChange () const; 112 113 //------------------------------------------------------------------ 114 /// Set whether the process should stop when images change. 115 /// 116 /// When images (executables and shared libraries) get loaded or 117 /// unloaded, often debug sessions will want to try and resolve or 118 /// unresolve breakpoints that are set in these images. The default 119 /// is set so that the process stops when images change, but this 120 /// can be overridden using this function callback. 121 /// 122 /// @param[in] stop 123 /// Boolean value that indicates whether the process should stop 124 /// when images change. 125 //------------------------------------------------------------------ 126 void 127 SetStopWhenImagesChange (bool stop); 128 129 //------------------------------------------------------------------ 130 /// Provides a plan to step through the dynamic loader trampoline 131 /// for the current state of \a thread. 132 /// 133 /// 134 /// @param[in] stop_others 135 /// Whether the plan should be set to stop other threads. 136 /// 137 /// @return 138 /// A pointer to the plan (caller owned) or NULL if we are not at such 139 /// a trampoline. 140 //------------------------------------------------------------------ 141 virtual lldb::ThreadPlanSP 142 GetStepThroughTrampolinePlan (Thread &thread, bool stop_others) = 0; 143 144 145 //------------------------------------------------------------------ 146 /// Ask if it is ok to try and load or unload an shared library 147 /// (image). 148 /// 149 /// The dynamic loader often knows when it would be ok to try and 150 /// load or unload a shared library. This function call allows the 151 /// dynamic loader plug-ins to check any current dyld state to make 152 /// sure it is an ok time to load a shared library. 153 /// 154 /// @return 155 /// \b True if it is currently ok to try and load a shared 156 /// library into the process, \b false otherwise. 157 //------------------------------------------------------------------ 158 virtual Error 159 CanLoadImage () = 0; 160 161protected: 162 //------------------------------------------------------------------ 163 // Member variables. 164 //------------------------------------------------------------------ 165 Process* m_process; ///< The process that this dynamic loader plug-in is tracking. 166 bool m_stop_when_images_change; ///< Boolean value that indicates if the process should stop when imamges change. 167private: 168 DISALLOW_COPY_AND_ASSIGN (DynamicLoader); 169 170}; 171 172} // namespace lldb_private 173 174#endif // liblldb_DynamicLoader_h_ 175