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