EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-05-10 08:42:55
0001 //===-- SystemRuntime.h -----------------------------------------*- C++ -*-===// 0002 // 0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 0004 // See https://llvm.org/LICENSE.txt for license information. 0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 0006 // 0007 //===----------------------------------------------------------------------===// 0008 0009 #ifndef LLDB_TARGET_SYSTEMRUNTIME_H 0010 #define LLDB_TARGET_SYSTEMRUNTIME_H 0011 0012 #include <vector> 0013 0014 #include "lldb/Core/ModuleList.h" 0015 #include "lldb/Core/PluginInterface.h" 0016 #include "lldb/Target/QueueItem.h" 0017 #include "lldb/Target/QueueList.h" 0018 #include "lldb/Target/Runtime.h" 0019 #include "lldb/Utility/ConstString.h" 0020 #include "lldb/Utility/StructuredData.h" 0021 #include "lldb/lldb-private.h" 0022 #include "lldb/lldb-public.h" 0023 0024 namespace lldb_private { 0025 0026 /// \class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h" 0027 /// A plug-in interface definition class for system runtimes. 0028 /// 0029 /// The system runtime plugins can collect information from the system 0030 /// libraries during a Process' lifetime and provide information about how 0031 /// objects/threads were originated. 0032 /// 0033 /// For instance, a system runtime plugin use a breakpoint when threads are 0034 /// created to record the backtrace of where that thread was created. Later, 0035 /// when backtracing the created thread, it could extend the backtrace to show 0036 /// where it was originally created from. 0037 /// 0038 /// The plugin will insert its own breakpoint when Created and start 0039 /// collecting information. Later when it comes time to augment a Thread, it 0040 /// can be asked to provide that information. 0041 /// 0042 0043 class SystemRuntime : public Runtime, public PluginInterface { 0044 public: 0045 /// Find a system runtime plugin for a given process. 0046 /// 0047 /// Scans the installed SystemRuntime plugins and tries to find an instance 0048 /// that can be used to track image changes in \a process. 0049 /// 0050 /// \param[in] process 0051 /// The process for which to try and locate a system runtime 0052 /// plugin instance. 0053 static SystemRuntime *FindPlugin(Process *process); 0054 0055 /// Construct with a process. 0056 SystemRuntime(Process *process); 0057 0058 /// Destructor. 0059 /// 0060 /// The destructor is virtual since this class is designed to be inherited 0061 /// by the plug-in instance. 0062 ~SystemRuntime() override; 0063 0064 /// Called after attaching to a process. 0065 /// 0066 /// Allow the SystemRuntime plugin to execute some code after attaching to a 0067 /// process. 0068 virtual void DidAttach(); 0069 0070 /// Called after launching a process. 0071 /// 0072 /// Allow the SystemRuntime plugin to execute some code after launching a 0073 /// process. 0074 virtual void DidLaunch(); 0075 0076 /// Called when modules have been loaded in the process. 0077 /// 0078 /// Allow the SystemRuntime plugin to enable logging features in the system 0079 /// runtime libraries. 0080 void ModulesDidLoad(const ModuleList &module_list) override; 0081 0082 /// Called before detaching from a process. 0083 /// 0084 /// This will give a SystemRuntime plugin a chance to free any resources in 0085 /// the inferior process before we detach. 0086 virtual void Detach(); 0087 0088 /// Return a list of thread origin extended backtraces that may be 0089 /// available. 0090 /// 0091 /// A System Runtime may be able to provide a backtrace of when this 0092 /// thread was originally created. Furthermore, it may be able to provide 0093 /// that extended backtrace for different styles of creation. On a system 0094 /// with both pthreads and libdispatch, aka Grand Central Dispatch, queues, 0095 /// the system runtime may be able to provide the pthread creation of the 0096 /// thread and it may also be able to provide the backtrace of when this GCD 0097 /// queue work block was enqueued. The caller may request these different 0098 /// origins by name. 0099 /// 0100 /// The names will be provided in the order that they are most likely to be 0101 /// requested. For instance, a most natural order may be to request the GCD 0102 /// libdispatch queue origin. If there is none, then request the pthread 0103 /// origin. 0104 /// 0105 /// \return 0106 /// A vector of ConstStrings with names like "pthread" or "libdispatch". 0107 /// An empty vector may be returned if no thread origin extended 0108 /// backtrace capabilities are available. 0109 virtual const std::vector<ConstString> &GetExtendedBacktraceTypes(); 0110 0111 /// Return a Thread which shows the origin of this thread's creation. 0112 /// 0113 /// This likely returns a HistoryThread which shows how thread was 0114 /// originally created (e.g. "pthread" type), or how the work that is 0115 /// currently executing on it was originally enqueued (e.g. "libdispatch" 0116 /// type). 0117 /// 0118 /// There may be a chain of thread-origins; it may be informative to the end 0119 /// user to query the returned ThreadSP for its origins as well. 0120 /// 0121 /// \param [in] thread 0122 /// The thread to examine. 0123 /// 0124 /// \param [in] type 0125 /// The type of thread origin being requested. The types supported 0126 /// are returned from SystemRuntime::GetExtendedBacktraceTypes. 0127 /// 0128 /// \return 0129 /// A ThreadSP which will have a StackList of frames. This Thread will 0130 /// not appear in the Process' list of current threads. Normal thread 0131 /// operations like stepping will not be available. This is a historical 0132 /// view thread and may be only useful for showing a backtrace. 0133 /// 0134 /// An empty ThreadSP will be returned if no thread origin is available. 0135 virtual lldb::ThreadSP GetExtendedBacktraceThread(lldb::ThreadSP thread, 0136 ConstString type); 0137 0138 /// Get the extended backtrace thread for a QueueItem 0139 /// 0140 /// A QueueItem represents a function/block that will be executed on 0141 /// a libdispatch queue in the future, or it represents a function/block 0142 /// that is currently executing on a thread. 0143 /// 0144 /// This method will report a thread backtrace of the function that enqueued 0145 /// it originally, if possible. 0146 /// 0147 /// \param [in] queue_item_sp 0148 /// The QueueItem that we are getting an extended backtrace for. 0149 /// 0150 /// \param [in] type 0151 /// The type of extended backtrace to fetch. The types supported 0152 /// are returned from SystemRuntime::GetExtendedBacktraceTypes. 0153 /// 0154 /// \return 0155 /// If an extended backtrace is available, it is returned. Else 0156 /// an empty ThreadSP is returned. 0157 virtual lldb::ThreadSP 0158 GetExtendedBacktraceForQueueItem(lldb::QueueItemSP queue_item_sp, 0159 ConstString type) { 0160 return lldb::ThreadSP(); 0161 } 0162 0163 /// Populate the Process' QueueList with libdispatch / GCD queues that 0164 /// exist. 0165 /// 0166 /// When process execution is paused, the SystemRuntime may be called to 0167 /// fill in the list of Queues that currently exist. 0168 /// 0169 /// \param [out] queue_list 0170 /// This QueueList will be cleared, and any queues that currently exist 0171 /// will be added. An empty QueueList will be returned if no queues 0172 /// exist or if this Systemruntime does not support libdispatch queues. 0173 virtual void PopulateQueueList(lldb_private::QueueList &queue_list) {} 0174 0175 /// Get the queue name for a thread given a thread's dispatch_qaddr. 0176 /// 0177 /// On systems using libdispatch queues, a thread may be associated with a 0178 /// queue. There will be a call to get the thread's dispatch_qaddr. At the 0179 /// dispatch_qaddr we will find the address of this thread's 0180 /// dispatch_queue_t structure. Given the address of the dispatch_queue_t 0181 /// structure for a thread, get the queue name and return it. 0182 /// 0183 /// \param [in] dispatch_qaddr 0184 /// The address of the dispatch_qaddr pointer for this thread. 0185 /// 0186 /// \return 0187 /// The string of this queue's name. An empty string is returned if the 0188 /// name could not be found. 0189 virtual std::string 0190 GetQueueNameFromThreadQAddress(lldb::addr_t dispatch_qaddr) { 0191 return ""; 0192 } 0193 0194 /// Get the QueueID for the libdispatch queue given the thread's 0195 /// dispatch_qaddr. 0196 /// 0197 /// On systems using libdispatch queues, a thread may be associated with a 0198 /// queue. There will be a call to get the thread's dispatch_qaddr. At the 0199 /// dispatch_qaddr we will find the address of this thread's 0200 /// dispatch_queue_t structure. Given the address of the dispatch_queue_t 0201 /// structure for a thread, get the queue ID and return it. 0202 /// 0203 /// \param [in] dispatch_qaddr 0204 /// The address of the dispatch_qaddr pointer for this thread. 0205 /// 0206 /// \return 0207 /// The queue ID, or if it could not be retrieved, LLDB_INVALID_QUEUE_ID. 0208 virtual lldb::queue_id_t 0209 GetQueueIDFromThreadQAddress(lldb::addr_t dispatch_qaddr) { 0210 return LLDB_INVALID_QUEUE_ID; 0211 } 0212 0213 /// Get the libdispatch_queue_t address for the queue given the thread's 0214 /// dispatch_qaddr. 0215 /// 0216 /// On systems using libdispatch queues, a thread may be associated with a 0217 /// queue. There will be a call to get the thread's dispatch_qaddr. Given 0218 /// the thread's dispatch_qaddr, find the libdispatch_queue_t address and 0219 /// return it. 0220 /// 0221 /// \param [in] dispatch_qaddr 0222 /// The address of the dispatch_qaddr pointer for this thread. 0223 /// 0224 /// \return 0225 /// The libdispatch_queue_t address, or LLDB_INVALID_ADDRESS if 0226 /// unavailable/not found. 0227 virtual lldb::addr_t 0228 GetLibdispatchQueueAddressFromThreadQAddress(lldb::addr_t dispatch_qaddr) { 0229 return LLDB_INVALID_ADDRESS; 0230 } 0231 0232 /// Retrieve the Queue kind for the queue at a thread's dispatch_qaddr. 0233 /// 0234 /// Retrieve the Queue kind - either eQueueKindSerial or 0235 /// eQueueKindConcurrent, indicating that this queue processes work items 0236 /// serially or concurrently. 0237 /// 0238 /// \return 0239 /// The Queue kind, if it could be read, else eQueueKindUnknown. 0240 virtual lldb::QueueKind GetQueueKind(lldb::addr_t dispatch_qaddr) { 0241 return lldb::eQueueKindUnknown; 0242 } 0243 0244 /// Get the pending work items for a libdispatch Queue 0245 /// 0246 /// If this system/process is using libdispatch and the runtime can do so, 0247 /// retrieve the list of pending work items for the specified Queue and add 0248 /// it to the Queue. 0249 /// 0250 /// \param [in] queue 0251 /// The queue of interest. 0252 virtual void PopulatePendingItemsForQueue(lldb_private::Queue *queue) {} 0253 0254 /// Complete the fields in a QueueItem 0255 /// 0256 /// PopulatePendingItemsForQueue() may not fill in all of the QueueItem 0257 /// details; when the remaining fields are needed, they will be fetched by 0258 /// call this method. 0259 /// 0260 /// \param [in] queue_item 0261 /// The QueueItem that we will be completing. 0262 /// 0263 /// \param [in] item_ref 0264 /// The item_ref token that is needed to retrieve the rest of the 0265 /// information about the QueueItem. 0266 virtual void CompleteQueueItem(lldb_private::QueueItem *queue_item, 0267 lldb::addr_t item_ref) {} 0268 0269 /// Add key-value pairs to the StructuredData dictionary object with 0270 /// information debugserver may need when constructing the 0271 /// jThreadExtendedInfo packet. 0272 /// 0273 /// \param [out] dict 0274 /// Dictionary to which key-value pairs should be added; they will 0275 /// be sent to the remote gdb server stub as arguments in the 0276 /// jThreadExtendedInfo request. 0277 virtual void AddThreadExtendedInfoPacketHints( 0278 lldb_private::StructuredData::ObjectSP dict) {} 0279 0280 /// Determine whether it is safe to run an expression on a given thread 0281 /// 0282 /// If a system must not run functions on a thread in some particular state, 0283 /// this method gives a way for it to flag that the expression should not be 0284 /// run. 0285 /// 0286 /// \param [in] thread_sp 0287 /// The thread we want to run the expression on. 0288 /// 0289 /// \return 0290 /// True will be returned if there are no known problems with running an 0291 /// expression on this thread. False means that the inferior function 0292 /// call should not be made on this thread. 0293 virtual bool SafeToCallFunctionsOnThisThread(lldb::ThreadSP thread_sp) { 0294 return true; 0295 } 0296 0297 protected: 0298 std::vector<ConstString> m_types; 0299 0300 private: 0301 SystemRuntime(const SystemRuntime &) = delete; 0302 const SystemRuntime &operator=(const SystemRuntime &) = delete; 0303 }; 0304 0305 } // namespace lldb_private 0306 0307 #endif // LLDB_TARGET_SYSTEMRUNTIME_H
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|