1 //===-- GDBRemoteClientBase.h -----------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_SOURCE_PLUGINS_PROCESS_GDB_REMOTE_GDBREMOTECLIENTBASE_H 10 #define LLDB_SOURCE_PLUGINS_PROCESS_GDB_REMOTE_GDBREMOTECLIENTBASE_H 11 12 #include "GDBRemoteCommunication.h" 13 #include "lldb/Utility/Broadcaster.h" 14 #include "llvm/ADT/STLFunctionalExtras.h" 15 #include "llvm/ADT/StringRef.h" 16 #include <chrono> 17 #include <condition_variable> 18 #include <cstdint> 19 #include <mutex> 20 21 namespace lldb_private { 22 namespace process_gdb_remote { 23 24 class GDBRemoteClientBase : public GDBRemoteCommunication, public Broadcaster { 25 public: 26 enum { 27 eBroadcastBitRunPacketSent = (1u << 0), 28 }; 29 30 struct ContinueDelegate { 31 virtual ~ContinueDelegate(); 32 virtual void HandleAsyncStdout(llvm::StringRef out) = 0; 33 virtual void HandleAsyncMisc(llvm::StringRef data) = 0; 34 virtual void HandleStopReply() = 0; 35 36 /// Process asynchronously-received structured data. 37 /// 38 /// \param[in] data 39 /// The complete data packet, expected to start with JSON-async. 40 virtual void HandleAsyncStructuredDataPacket(llvm::StringRef data) = 0; 41 }; 42 43 GDBRemoteClientBase(const char *comm_name); 44 45 bool SendAsyncSignal(int signo, std::chrono::seconds interrupt_timeout); 46 47 bool Interrupt(std::chrono::seconds interrupt_timeout); 48 49 lldb::StateType SendContinuePacketAndWaitForResponse( 50 ContinueDelegate &delegate, const UnixSignals &signals, 51 llvm::StringRef payload, std::chrono::seconds interrupt_timeout, 52 StringExtractorGDBRemote &response); 53 54 // If interrupt_timeout == 0 seconds, don't interrupt the target. 55 // Only send the packet if the target is stopped. 56 // If you want to use this mode, use the fact that the timeout is defaulted 57 // so it's clear from the call-site that you are using no-interrupt. 58 // If it is non-zero, interrupt the target if it is running, and 59 // send the packet. 60 // It the target doesn't respond within the given timeout, it returns 61 // ErrorReplyTimeout. 62 PacketResult SendPacketAndWaitForResponse( 63 llvm::StringRef payload, StringExtractorGDBRemote &response, 64 std::chrono::seconds interrupt_timeout = std::chrono::seconds(0), 65 bool sync_on_timeout = true); 66 67 PacketResult ReadPacketWithOutputSupport( 68 StringExtractorGDBRemote &response, Timeout<std::micro> timeout, 69 bool sync_on_timeout, 70 llvm::function_ref<void(llvm::StringRef)> output_callback); 71 72 PacketResult SendPacketAndReceiveResponseWithOutputSupport( 73 llvm::StringRef payload, StringExtractorGDBRemote &response, 74 std::chrono::seconds interrupt_timeout, 75 llvm::function_ref<void(llvm::StringRef)> output_callback); 76 77 class Lock { 78 public: 79 // If interrupt_timeout == 0 seconds, only take the lock if the target is 80 // not running. If using this option, use the fact that the 81 // interrupt_timeout is defaulted so it will be obvious at the call site 82 // that you are choosing this mode. If it is non-zero, interrupt the target 83 // if it is running, waiting for the given timeout for the interrupt to 84 // succeed. 85 Lock(GDBRemoteClientBase &comm, 86 std::chrono::seconds interrupt_timeout = std::chrono::seconds(0)); 87 ~Lock(); 88 89 explicit operator bool() { return m_acquired; } 90 91 // Whether we had to interrupt the continue thread to acquire the 92 // connection. DidInterrupt()93 bool DidInterrupt() const { return m_did_interrupt; } 94 95 private: 96 std::unique_lock<std::recursive_mutex> m_async_lock; 97 GDBRemoteClientBase &m_comm; 98 std::chrono::seconds m_interrupt_timeout; 99 bool m_acquired; 100 bool m_did_interrupt; 101 102 void SyncWithContinueThread(); 103 }; 104 105 protected: 106 PacketResult 107 SendPacketAndWaitForResponseNoLock(llvm::StringRef payload, 108 StringExtractorGDBRemote &response, 109 bool sync_on_timeout = true); 110 111 virtual void OnRunPacketSent(bool first); 112 113 private: 114 /// Variables handling synchronization between the Continue thread and any 115 /// other threads wishing to send packets over the connection. Either the 116 /// continue thread has control over the connection (m_is_running == true) or 117 /// the connection is free for an arbitrary number of other senders to take 118 /// which indicate their interest by incrementing m_async_count. 119 /// 120 /// Semantics of individual states: 121 /// 122 /// - m_continue_packet == false, m_async_count == 0: 123 /// connection is free 124 /// - m_continue_packet == true, m_async_count == 0: 125 /// only continue thread is present 126 /// - m_continue_packet == true, m_async_count > 0: 127 /// continue thread has control, async threads should interrupt it and wait 128 /// for it to set m_continue_packet to false 129 /// - m_continue_packet == false, m_async_count > 0: 130 /// async threads have control, continue thread needs to wait for them to 131 /// finish (m_async_count goes down to 0). 132 /// @{ 133 std::mutex m_mutex; 134 std::condition_variable m_cv; 135 136 /// Packet with which to resume after an async interrupt. Can be changed by 137 /// an async thread e.g. to inject a signal. 138 std::string m_continue_packet; 139 140 /// When was the interrupt packet sent. Used to make sure we time out if the 141 /// stub does not respond to interrupt requests. 142 std::chrono::time_point<std::chrono::steady_clock> m_interrupt_endpoint; 143 144 /// Number of threads interested in sending. 145 uint32_t m_async_count; 146 147 /// Whether the continue thread has control. 148 bool m_is_running; 149 150 /// Whether we should resume after a stop. 151 bool m_should_stop; 152 /// @} 153 154 /// This handles the synchronization between individual async threads. For 155 /// now they just use a simple mutex. 156 std::recursive_mutex m_async_mutex; 157 158 bool ShouldStop(const UnixSignals &signals, 159 StringExtractorGDBRemote &response); 160 161 class ContinueLock { 162 public: 163 enum class LockResult { Success, Cancelled, Failed }; 164 165 explicit ContinueLock(GDBRemoteClientBase &comm); 166 ~ContinueLock(); 167 explicit operator bool() { return m_acquired; } 168 169 LockResult lock(); 170 171 void unlock(); 172 173 private: 174 GDBRemoteClientBase &m_comm; 175 bool m_acquired; 176 }; 177 }; 178 179 } // namespace process_gdb_remote 180 } // namespace lldb_private 181 182 #endif // LLDB_SOURCE_PLUGINS_PROCESS_GDB_REMOTE_GDBREMOTECLIENTBASE_H 183