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/Core/StructuredData.h" 24 #include "lldb/Target/QueueList.h" 25 #include "lldb/Target/QueueItem.h" 26 #include "lldb/lldb-private.h" 27 28 namespace lldb_private { 29 30 //---------------------------------------------------------------------- 31 /// @class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h" 32 /// @brief A plug-in interface definition class for system runtimes. 33 /// 34 /// The system runtime plugins can collect information from the system 35 /// libraries during a Process' lifetime and provide information about 36 /// how objects/threads were originated. 37 /// 38 /// For instance, a system runtime plugin use a breakpoint when threads 39 /// are created to record the backtrace of where that thread was created. 40 /// Later, when backtracing the created thread, it could extend the backtrace 41 /// to show where it was originally created from. 42 /// 43 /// The plugin will insert its own breakpoint when Created and start collecting 44 /// information. Later when it comes time to augment a Thread, it can be 45 /// asked to provide that information. 46 /// 47 //---------------------------------------------------------------------- 48 49 class SystemRuntime : 50 public PluginInterface 51 { 52 public: 53 //------------------------------------------------------------------ 54 /// Find a system runtime plugin for a given process. 55 /// 56 /// Scans the installed SystemRuntime plugins and tries to find 57 /// an instance that can be used to track image changes in \a 58 /// process. 59 /// 60 /// @param[in] process 61 /// The process for which to try and locate a system runtime 62 /// plugin instance. 63 //------------------------------------------------------------------ 64 static SystemRuntime* 65 FindPlugin (Process *process); 66 67 //------------------------------------------------------------------ 68 /// Construct with a process. 69 // ----------------------------------------------------------------- 70 SystemRuntime(lldb_private::Process *process); 71 72 //------------------------------------------------------------------ 73 /// Destructor. 74 /// 75 /// The destructor is virtual since this class is designed to be 76 /// inherited by the plug-in instance. 77 //------------------------------------------------------------------ 78 virtual 79 ~SystemRuntime(); 80 81 //------------------------------------------------------------------ 82 /// Called after attaching to a process. 83 /// 84 /// Allow the SystemRuntime plugin to execute some code after attaching 85 /// to a process. 86 //------------------------------------------------------------------ 87 virtual void 88 DidAttach (); 89 90 //------------------------------------------------------------------ 91 /// Called after launching a process. 92 /// 93 /// Allow the SystemRuntime plugin to execute some code after launching 94 /// a process. 95 //------------------------------------------------------------------ 96 virtual void 97 DidLaunch(); 98 99 //------------------------------------------------------------------ 100 /// Called when modules have been loaded in the process. 101 /// 102 /// Allow the SystemRuntime plugin to enable logging features in the 103 /// system runtime libraries. 104 //------------------------------------------------------------------ 105 virtual void 106 ModulesDidLoad(lldb_private::ModuleList &module_list); 107 108 //------------------------------------------------------------------ 109 /// Called before detaching from a process. 110 /// 111 /// This will give a SystemRuntime plugin a chance to free any resources 112 /// in the inferior process before we detach. 113 //------------------------------------------------------------------ 114 virtual void 115 Detach (); 116 117 //------------------------------------------------------------------ 118 /// Return a list of thread origin extended backtraces that may 119 /// be available. 120 /// 121 /// A System Runtime may be able to provide a backtrace of when this 122 /// thread was originally created. Furthermore, it may be able to 123 /// provide that extended backtrace for different styles of creation. 124 /// On a system with both pthreads and libdispatch, aka Grand Central 125 /// Dispatch, queues, the system runtime may be able to provide the 126 /// pthread creation of the thread and it may also be able to provide 127 /// the backtrace of when this GCD queue work block was enqueued. 128 /// The caller may request these different origins by name. 129 /// 130 /// The names will be provided in the order that they are most likely 131 /// to be requested. For instance, a most natural order may be to 132 /// request the GCD libdispatch queue origin. If there is none, then 133 /// request the pthread origin. 134 /// 135 /// @return 136 /// A vector of ConstStrings with names like "pthread" or "libdispatch". 137 /// An empty vector may be returned if no thread origin extended 138 /// backtrace capabilities are available. 139 //------------------------------------------------------------------ 140 virtual const std::vector<ConstString> & 141 GetExtendedBacktraceTypes (); 142 143 //------------------------------------------------------------------ 144 /// Return a Thread which shows the origin of this thread's creation. 145 /// 146 /// This likely returns a HistoryThread which shows how thread was 147 /// originally created (e.g. "pthread" type), or how the work that 148 /// is currently executing on it was originally enqueued (e.g. 149 /// "libdispatch" type). 150 /// 151 /// There may be a chain of thread-origins; it may be informative to 152 /// the end user to query the returned ThreadSP for its origins as 153 /// well. 154 /// 155 /// @param [in] thread 156 /// The thread to examine. 157 /// 158 /// @param [in] type 159 /// The type of thread origin being requested. The types supported 160 /// are returned from SystemRuntime::GetExtendedBacktraceTypes. 161 /// 162 /// @return 163 /// A ThreadSP which will have a StackList of frames. This Thread will 164 /// not appear in the Process' list of current threads. Normal thread 165 /// operations like stepping will not be available. This is a historical 166 /// view thread and may be only useful for showing a backtrace. 167 /// 168 /// An empty ThreadSP will be returned if no thread origin is available. 169 //------------------------------------------------------------------ 170 virtual lldb::ThreadSP 171 GetExtendedBacktraceThread (lldb::ThreadSP thread, ConstString type); 172 173 //------------------------------------------------------------------ 174 /// Get the extended backtrace thread for a QueueItem 175 /// 176 /// A QueueItem represents a function/block that will be executed on 177 /// a libdispatch queue in the future, or it represents a function/block 178 /// that is currently executing on a thread. 179 /// 180 /// This method will report a thread backtrace of the function that 181 /// enqueued it originally, if possible. 182 /// 183 /// @param [in] queue_item_sp 184 /// The QueueItem that we are getting an extended backtrace for. 185 /// 186 /// @param [in] type 187 /// The type of extended backtrace to fetch. The types supported 188 /// are returned from SystemRuntime::GetExtendedBacktraceTypes. 189 /// 190 /// @return 191 /// If an extended backtrace is available, it is returned. Else 192 /// an empty ThreadSP is returned. 193 //------------------------------------------------------------------ 194 virtual lldb::ThreadSP GetExtendedBacktraceForQueueItem(lldb::QueueItemSP queue_item_sp,ConstString type)195 GetExtendedBacktraceForQueueItem (lldb::QueueItemSP queue_item_sp, ConstString type) 196 { 197 return lldb::ThreadSP(); 198 } 199 200 //------------------------------------------------------------------ 201 /// Populate the Process' QueueList with libdispatch / GCD queues that exist. 202 /// 203 /// When process execution is paused, the SystemRuntime may be called to fill 204 /// in the list of Queues that currently exist. 205 /// 206 /// @param [out] queue_list 207 /// This QueueList will be cleared, and any queues that currently exist 208 /// will be added. An empty QueueList will be returned if no queues 209 /// exist or if this Systemruntime does not support libdispatch queues. 210 //------------------------------------------------------------------ 211 virtual void PopulateQueueList(lldb_private::QueueList & queue_list)212 PopulateQueueList (lldb_private::QueueList &queue_list) 213 { 214 } 215 216 //------------------------------------------------------------------ 217 /// Get the queue name for a thread given a thread's dispatch_qaddr. 218 /// 219 /// On systems using libdispatch queues, a thread may be associated with a queue. 220 /// There will be a call to get the thread's dispatch_qaddr. At the dispatch_qaddr 221 /// we will find the address of this thread's dispatch_queue_t structure. 222 /// Given the address of the dispatch_queue_t structure for a thread, 223 /// get the queue name and return it. 224 /// 225 /// @param [in] dispatch_qaddr 226 /// The address of the dispatch_qaddr pointer for this thread. 227 /// 228 /// @return 229 /// The string of this queue's name. An empty string is returned if the 230 /// name could not be found. 231 //------------------------------------------------------------------ 232 virtual std::string GetQueueNameFromThreadQAddress(lldb::addr_t dispatch_qaddr)233 GetQueueNameFromThreadQAddress (lldb::addr_t dispatch_qaddr) 234 { 235 return ""; 236 } 237 238 //------------------------------------------------------------------ 239 /// Get the QueueID for the libdispatch queue given the thread's dispatch_qaddr. 240 /// 241 /// On systems using libdispatch queues, a thread may be associated with a queue. 242 /// There will be a call to get the thread's dispatch_qaddr. At the dispatch_qaddr 243 /// we will find the address of this thread's dispatch_queue_t structure. 244 /// Given the address of the dispatch_queue_t structure for a thread, 245 /// get the queue ID and return it. 246 /// 247 /// @param [in] dispatch_qaddr 248 /// The address of the dispatch_qaddr pointer for this thread. 249 /// 250 /// @return 251 /// The queue ID, or if it could not be retrieved, LLDB_INVALID_QUEUE_ID. 252 //------------------------------------------------------------------ 253 virtual lldb::queue_id_t GetQueueIDFromThreadQAddress(lldb::addr_t dispatch_qaddr)254 GetQueueIDFromThreadQAddress (lldb::addr_t dispatch_qaddr) 255 { 256 return LLDB_INVALID_QUEUE_ID; 257 } 258 259 //------------------------------------------------------------------ 260 /// Get the libdispatch_queue_t address for the queue given the thread's dispatch_qaddr. 261 /// 262 /// On systems using libdispatch queues, a thread may be associated with a queue. 263 /// There will be a call to get the thread's dispatch_qaddr. 264 /// Given the thread's dispatch_qaddr, find the libdispatch_queue_t address and 265 /// return it. 266 /// 267 /// @param [in] dispatch_qaddr 268 /// The address of the dispatch_qaddr pointer for this thread. 269 /// 270 /// @return 271 /// The libdispatch_queue_t address, or LLDB_INVALID_ADDRESS if unavailable/not found. 272 //------------------------------------------------------------------ 273 virtual lldb::addr_t GetLibdispatchQueueAddressFromThreadQAddress(lldb::addr_t dispatch_qaddr)274 GetLibdispatchQueueAddressFromThreadQAddress (lldb::addr_t dispatch_qaddr) 275 { 276 return LLDB_INVALID_ADDRESS; 277 } 278 279 //------------------------------------------------------------------ 280 /// Get the pending work items for a libdispatch Queue 281 /// 282 /// If this system/process is using libdispatch and the runtime can do so, 283 /// retrieve the list of pending work items for the specified Queue and 284 /// add it to the Queue. 285 /// 286 /// @param [in] queue 287 /// The queue of interest. 288 //------------------------------------------------------------------ 289 virtual void PopulatePendingItemsForQueue(lldb_private::Queue * queue)290 PopulatePendingItemsForQueue (lldb_private::Queue *queue) 291 { 292 } 293 294 //------------------------------------------------------------------ 295 /// Complete the fields in a QueueItem 296 /// 297 /// PopulatePendingItemsForQueue() may not fill in all of the QueueItem 298 /// details; when the remaining fields are needed, they will be 299 /// fetched by call this method. 300 /// 301 /// @param [in] queue_item 302 /// The QueueItem that we will be completing. 303 /// 304 /// @param [in] item_ref 305 /// The item_ref token that is needed to retrieve the rest of the 306 /// information about the QueueItem. 307 //------------------------------------------------------------------ 308 virtual void CompleteQueueItem(lldb_private::QueueItem * queue_item,lldb::addr_t item_ref)309 CompleteQueueItem (lldb_private::QueueItem *queue_item, lldb::addr_t item_ref) 310 { 311 } 312 313 //------------------------------------------------------------------ 314 /// Add key-value pairs to the StructuredData dictionary object with 315 /// information debugserver may need when constructing the jThreadExtendedInfo 316 /// packet. 317 /// 318 /// @param [out] dict 319 /// Dictionary to which key-value pairs should be added; they will 320 /// be sent to the remote gdb server stub as arguments in the 321 /// jThreadExtendedInfo request. 322 //------------------------------------------------------------------ 323 virtual void AddThreadExtendedInfoPacketHints(lldb_private::StructuredData::ObjectSP dict)324 AddThreadExtendedInfoPacketHints (lldb_private::StructuredData::ObjectSP dict) 325 { 326 } 327 328 /// Determine whether it is safe to run an expression on a given thread 329 /// 330 /// If a system must not run functions on a thread in some particular state, 331 /// this method gives a way for it to flag that the expression should not be 332 /// run. 333 /// 334 /// @param [in] thread_sp 335 /// The thread we want to run the expression on. 336 /// 337 /// @return 338 /// True will be returned if there are no known problems with running an 339 /// expression on this thread. False means that the inferior function 340 /// call should not be made on this thread. 341 //------------------------------------------------------------------ 342 virtual bool SafeToCallFunctionsOnThisThread(lldb::ThreadSP thread_sp)343 SafeToCallFunctionsOnThisThread (lldb::ThreadSP thread_sp) 344 { 345 return true; 346 } 347 348 protected: 349 //------------------------------------------------------------------ 350 // Member variables. 351 //------------------------------------------------------------------ 352 Process *m_process; 353 354 std::vector<ConstString> m_types; 355 356 private: 357 DISALLOW_COPY_AND_ASSIGN (SystemRuntime); 358 }; 359 360 } // namespace lldb_private 361 362 #endif // liblldb_SystemRuntime_h_ 363