contrib/llvm/tools/lldb/include/lldb/Target/SystemRuntime.h

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