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/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
  27 namespace 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
  48 class SystemRuntime :
  49     public PluginInterface
  50 {
  51 public:
  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
 273 protected:
 274     //------------------------------------------------------------------
 275     // Member variables.
 276     //------------------------------------------------------------------
 277     Process *m_process;
 278
 279     std::vector<ConstString> m_types;
 280
 281 private:
 282     DISALLOW_COPY_AND_ASSIGN (SystemRuntime);
 283 };
 284
 285 } // namespace lldb_private
 286
 287 #endif  // liblldb_SystemRuntime_h_