SystemRuntime.h revision 269024
1//===-- SystemRuntime.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_SystemRuntime_h_ 11#define liblldb_SystemRuntime_h_ 12 13// C Includes 14// C++ Includes 15// Other libraries and framework includes 16// Project includes 17#include <vector> 18 19#include "lldb/lldb-public.h" 20#include "lldb/Core/ConstString.h" 21#include "lldb/Core/ModuleList.h" 22#include "lldb/Core/PluginInterface.h" 23#include "lldb/Target/QueueList.h" 24#include "lldb/Target/QueueItem.h" 25#include "lldb/lldb-private.h" 26 27namespace lldb_private { 28 29//---------------------------------------------------------------------- 30/// @class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h" 31/// @brief A plug-in interface definition class for system runtimes. 32/// 33/// The system runtime plugins can collect information from the system 34/// libraries during a Process' lifetime and provide information about 35/// how objects/threads were originated. 36/// 37/// For instance, a system runtime plugin use a breakpoint when threads 38/// are created to record the backtrace of where that thread was created. 39/// Later, when backtracing the created thread, it could extend the backtrace 40/// to show where it was originally created from. 41/// 42/// The plugin will insert its own breakpoint when Created and start collecting 43/// information. Later when it comes time to augment a Thread, it can be 44/// asked to provide that information. 45/// 46//---------------------------------------------------------------------- 47 48class SystemRuntime : 49 public PluginInterface 50{ 51public: 52 //------------------------------------------------------------------ 53 /// Find a system runtime plugin for a given process. 54 /// 55 /// Scans the installed SystemRuntime plugins and tries to find 56 /// an instance that can be used to track image changes in \a 57 /// process. 58 /// 59 /// @param[in] process 60 /// The process for which to try and locate a system runtime 61 /// plugin instance. 62 //------------------------------------------------------------------ 63 static SystemRuntime* 64 FindPlugin (Process *process); 65 66 //------------------------------------------------------------------ 67 /// Construct with a process. 68 // ----------------------------------------------------------------- 69 SystemRuntime(lldb_private::Process *process); 70 71 //------------------------------------------------------------------ 72 /// Destructor. 73 /// 74 /// The destructor is virtual since this class is designed to be 75 /// inherited by the plug-in instance. 76 //------------------------------------------------------------------ 77 virtual 78 ~SystemRuntime(); 79 80 //------------------------------------------------------------------ 81 /// Called after attaching to a process. 82 /// 83 /// Allow the SystemRuntime plugin to execute some code after attaching 84 /// to a process. 85 //------------------------------------------------------------------ 86 virtual void 87 DidAttach (); 88 89 //------------------------------------------------------------------ 90 /// Called after launching a process. 91 /// 92 /// Allow the SystemRuntime plugin to execute some code after launching 93 /// a process. 94 //------------------------------------------------------------------ 95 virtual void 96 DidLaunch(); 97 98 //------------------------------------------------------------------ 99 /// Called when modules have been loaded in the process. 100 /// 101 /// Allow the SystemRuntime plugin to enable logging features in the 102 /// system runtime libraries. 103 //------------------------------------------------------------------ 104 virtual void 105 ModulesDidLoad(lldb_private::ModuleList &module_list); 106 107 //------------------------------------------------------------------ 108 /// Called before detaching from a process. 109 /// 110 /// This will give a SystemRuntime plugin a chance to free any resources 111 /// in the inferior process before we detach. 112 //------------------------------------------------------------------ 113 virtual void 114 Detach (); 115 116 //------------------------------------------------------------------ 117 /// Return a list of thread origin extended backtraces that may 118 /// be available. 119 /// 120 /// A System Runtime may be able to provide a backtrace of when this 121 /// thread was originally created. Furthermore, it may be able to 122 /// provide that extended backtrace for different styles of creation. 123 /// On a system with both pthreads and libdispatch, aka Grand Central 124 /// Dispatch, queues, the system runtime may be able to provide the 125 /// pthread creation of the thread and it may also be able to provide 126 /// the backtrace of when this GCD queue work block was enqueued. 127 /// The caller may request these different origins by name. 128 /// 129 /// The names will be provided in the order that they are most likely 130 /// to be requested. For instance, a most natural order may be to 131 /// request the GCD libdispatch queue origin. If there is none, then 132 /// request the pthread origin. 133 /// 134 /// @return 135 /// A vector of ConstStrings with names like "pthread" or "libdispatch". 136 /// An empty vector may be returned if no thread origin extended 137 /// backtrace capabilities are available. 138 //------------------------------------------------------------------ 139 virtual const std::vector<ConstString> & 140 GetExtendedBacktraceTypes (); 141 142 //------------------------------------------------------------------ 143 /// Return a Thread which shows the origin of this thread's creation. 144 /// 145 /// This likely returns a HistoryThread which shows how thread was 146 /// originally created (e.g. "pthread" type), or how the work that 147 /// is currently executing on it was originally enqueued (e.g. 148 /// "libdispatch" type). 149 /// 150 /// There may be a chain of thread-origins; it may be informative to 151 /// the end user to query the returned ThreadSP for its origins as 152 /// well. 153 /// 154 /// @param [in] thread 155 /// The thread to examine. 156 /// 157 /// @param [in] type 158 /// The type of thread origin being requested. The types supported 159 /// are returned from SystemRuntime::GetExtendedBacktraceTypes. 160 /// 161 /// @return 162 /// A ThreadSP which will have a StackList of frames. This Thread will 163 /// not appear in the Process' list of current threads. Normal thread 164 /// operations like stepping will not be available. This is a historical 165 /// view thread and may be only useful for showing a backtrace. 166 /// 167 /// An empty ThreadSP will be returned if no thread origin is available. 168 //------------------------------------------------------------------ 169 virtual lldb::ThreadSP 170 GetExtendedBacktraceThread (lldb::ThreadSP thread, ConstString type); 171 172 //------------------------------------------------------------------ 173 /// Get the extended backtrace thread for a QueueItem 174 /// 175 /// A QueueItem represents a function/block that will be executed on 176 /// a libdispatch queue in the future, or it represents a function/block 177 /// that is currently executing on a thread. 178 /// 179 /// This method will report a thread backtrace of the function that 180 /// enqueued it originally, if possible. 181 /// 182 /// @param [in] queue_item_sp 183 /// The QueueItem that we are getting an extended backtrace for. 184 /// 185 /// @param [in] type 186 /// The type of extended backtrace to fetch. The types supported 187 /// are returned from SystemRuntime::GetExtendedBacktraceTypes. 188 /// 189 /// @return 190 /// If an extended backtrace is available, it is returned. Else 191 /// an empty ThreadSP is returned. 192 //------------------------------------------------------------------ 193 virtual lldb::ThreadSP 194 GetExtendedBacktraceForQueueItem (lldb::QueueItemSP queue_item_sp, ConstString type) 195 { 196 return lldb::ThreadSP(); 197 } 198 199 //------------------------------------------------------------------ 200 /// Populate the Process' QueueList with libdispatch / GCD queues that exist. 201 /// 202 /// When process execution is paused, the SystemRuntime may be called to fill 203 /// in the list of Queues that currently exist. 204 /// 205 /// @param [out] queue_list 206 /// This QueueList will be cleared, and any queues that currently exist 207 /// will be added. An empty QueueList will be returned if no queues 208 /// exist or if this Systemruntime does not support libdispatch queues. 209 //------------------------------------------------------------------ 210 virtual void 211 PopulateQueueList (lldb_private::QueueList &queue_list) 212 { 213 } 214 215 //------------------------------------------------------------------ 216 /// Get the queue name for a thread given a thread's dispatch_qaddr. 217 /// 218 /// On systems using libdispatch queues, a thread may be associated with a queue. 219 /// There will be a call to get the thread's dispatch_qaddr. At the dispatch_qaddr 220 /// we will find the address of this thread's dispatch_queue_t structure. 221 /// Given the address of the dispatch_queue_t structure for a thread, 222 /// get the queue name and return it. 223 /// 224 /// @param [in] dispatch_qaddr 225 /// The address of the dispatch_queue_t structure for this thread. 226 /// 227 /// @return 228 /// The string of this queue's name. An empty string is returned if the 229 /// name could not be found. 230 //------------------------------------------------------------------ 231 virtual std::string 232 GetQueueNameFromThreadQAddress (lldb::addr_t dispatch_qaddr) 233 { 234 return ""; 235 } 236 237 //------------------------------------------------------------------ 238 /// Get the QueueID for the libdispatch queue given the thread's dispatch_qaddr. 239 /// 240 /// On systems using libdispatch queues, a thread may be associated with a queue. 241 /// There will be a call to get the thread's dispatch_qaddr. At the dispatch_qaddr 242 /// we will find the address of this thread's dispatch_queue_t structure. 243 /// Given the address of the dispatch_queue_t structure for a thread, 244 /// get the queue ID and return it. 245 /// 246 /// @param [in] dispatch_qaddr 247 /// The address of the dispatch_queue_t structure for this thread. 248 /// 249 /// @return 250 /// The queue ID, or if it could not be retrieved, LLDB_INVALID_QUEUE_ID. 251 //------------------------------------------------------------------ 252 virtual lldb::queue_id_t 253 GetQueueIDFromThreadQAddress (lldb::addr_t dispatch_qaddr) 254 { 255 return LLDB_INVALID_QUEUE_ID; 256 } 257 258 //------------------------------------------------------------------ 259 /// Get the pending work items for a libdispatch Queue 260 /// 261 /// If this system/process is using libdispatch and the runtime can do so, 262 /// retrieve the list of pending work items for the specified Queue and 263 /// add it to the Queue. 264 /// 265 /// @param [in] queue 266 /// The queue of interest. 267 //------------------------------------------------------------------ 268 virtual void 269 PopulatePendingItemsForQueue (lldb_private::Queue *queue) 270 { 271 } 272 273protected: 274 //------------------------------------------------------------------ 275 // Member variables. 276 //------------------------------------------------------------------ 277 Process *m_process; 278 279 std::vector<ConstString> m_types; 280 281private: 282 DISALLOW_COPY_AND_ASSIGN (SystemRuntime); 283}; 284 285} // namespace lldb_private 286 287#endif // liblldb_SystemRuntime_h_ 288