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