1 //===-- GDBRemoteCommunication.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 liblldb_GDBRemoteCommunication_h_ 10 #define liblldb_GDBRemoteCommunication_h_ 11 12 #include "GDBRemoteCommunicationHistory.h" 13 14 #include <condition_variable> 15 #include <mutex> 16 #include <queue> 17 #include <string> 18 #include <vector> 19 20 #include "lldb/Core/Communication.h" 21 #include "lldb/Host/Config.h" 22 #include "lldb/Host/HostThread.h" 23 #include "lldb/Utility/Args.h" 24 #include "lldb/Utility/Listener.h" 25 #include "lldb/Utility/Predicate.h" 26 #include "lldb/Utility/StringExtractorGDBRemote.h" 27 #include "lldb/lldb-public.h" 28 29 namespace lldb_private { 30 namespace process_gdb_remote { 31 32 enum GDBStoppointType { 33 eStoppointInvalid = -1, 34 eBreakpointSoftware = 0, 35 eBreakpointHardware, 36 eWatchpointWrite, 37 eWatchpointRead, 38 eWatchpointReadWrite 39 }; 40 41 enum class CompressionType { 42 None = 0, // no compression 43 ZlibDeflate, // zlib's deflate compression scheme, requires zlib or Apple's 44 // libcompression 45 LZFSE, // an Apple compression scheme, requires Apple's libcompression 46 LZ4, // lz compression - called "lz4 raw" in libcompression terms, compat with 47 // https://code.google.com/p/lz4/ 48 LZMA, // Lempel–Ziv–Markov chain algorithm 49 }; 50 51 class ProcessGDBRemote; 52 53 class GDBRemoteCommunication : public Communication { 54 public: 55 enum { 56 eBroadcastBitRunPacketSent = kLoUserBroadcastBit, 57 eBroadcastBitGdbReadThreadGotNotify = 58 kLoUserBroadcastBit << 1 // Sent when we received a notify packet. 59 }; 60 61 enum class PacketType { Invalid = 0, Standard, Notify }; 62 63 enum class PacketResult { 64 Success = 0, // Success 65 ErrorSendFailed, // Status sending the packet 66 ErrorSendAck, // Didn't get an ack back after sending a packet 67 ErrorReplyFailed, // Status getting the reply 68 ErrorReplyTimeout, // Timed out waiting for reply 69 ErrorReplyInvalid, // Got a reply but it wasn't valid for the packet that 70 // was sent 71 ErrorReplyAck, // Sending reply ack failed 72 ErrorDisconnected, // We were disconnected 73 ErrorNoSequenceLock // We couldn't get the sequence lock for a multi-packet 74 // request 75 }; 76 77 // Class to change the timeout for a given scope and restore it to the 78 // original value when the 79 // created ScopedTimeout object got out of scope 80 class ScopedTimeout { 81 public: 82 ScopedTimeout(GDBRemoteCommunication &gdb_comm, 83 std::chrono::seconds timeout); 84 ~ScopedTimeout(); 85 86 private: 87 GDBRemoteCommunication &m_gdb_comm; 88 std::chrono::seconds m_saved_timeout; 89 // Don't ever reduce the timeout for a packet, only increase it. If the 90 // requested timeout if less than the current timeout, we don't set it 91 // and won't need to restore it. 92 bool m_timeout_modified; 93 }; 94 95 GDBRemoteCommunication(const char *comm_name, const char *listener_name); 96 97 ~GDBRemoteCommunication() override; 98 99 PacketResult GetAck(); 100 101 size_t SendAck(); 102 103 size_t SendNack(); 104 105 char CalculcateChecksum(llvm::StringRef payload); 106 107 PacketType CheckForPacket(const uint8_t *src, size_t src_len, 108 StringExtractorGDBRemote &packet); 109 110 bool GetSendAcks() { return m_send_acks; } 111 112 // Set the global packet timeout. 113 // 114 // For clients, this is the timeout that gets used when sending 115 // packets and waiting for responses. For servers, this is used when waiting 116 // for ACKs. 117 std::chrono::seconds SetPacketTimeout(std::chrono::seconds packet_timeout) { 118 const auto old_packet_timeout = m_packet_timeout; 119 m_packet_timeout = packet_timeout; 120 return old_packet_timeout; 121 } 122 123 std::chrono::seconds GetPacketTimeout() const { return m_packet_timeout; } 124 125 // Start a debugserver instance on the current host using the 126 // supplied connection URL. 127 Status StartDebugserverProcess( 128 const char *url, 129 Platform *platform, // If non nullptr, then check with the platform for 130 // the GDB server binary if it can't be located 131 ProcessLaunchInfo &launch_info, uint16_t *port, const Args *inferior_args, 132 int pass_comm_fd); // Communication file descriptor to pass during 133 // fork/exec to avoid having to connect/accept 134 135 void DumpHistory(Stream &strm); 136 void SetHistoryStream(llvm::raw_ostream *strm); 137 138 static llvm::Error ConnectLocally(GDBRemoteCommunication &client, 139 GDBRemoteCommunication &server); 140 141 protected: 142 std::chrono::seconds m_packet_timeout; 143 uint32_t m_echo_number; 144 LazyBool m_supports_qEcho; 145 GDBRemoteCommunicationHistory m_history; 146 bool m_send_acks; 147 bool m_is_platform; // Set to true if this class represents a platform, 148 // false if this class represents a debug session for 149 // a single process 150 151 CompressionType m_compression_type; 152 153 PacketResult SendPacketNoLock(llvm::StringRef payload); 154 PacketResult SendRawPacketNoLock(llvm::StringRef payload, 155 bool skip_ack = false); 156 157 PacketResult ReadPacket(StringExtractorGDBRemote &response, 158 Timeout<std::micro> timeout, bool sync_on_timeout); 159 160 PacketResult ReadPacketWithOutputSupport( 161 StringExtractorGDBRemote &response, Timeout<std::micro> timeout, 162 bool sync_on_timeout, 163 llvm::function_ref<void(llvm::StringRef)> output_callback); 164 165 // Pop a packet from the queue in a thread safe manner 166 PacketResult PopPacketFromQueue(StringExtractorGDBRemote &response, 167 Timeout<std::micro> timeout); 168 169 PacketResult WaitForPacketNoLock(StringExtractorGDBRemote &response, 170 Timeout<std::micro> timeout, 171 bool sync_on_timeout); 172 173 bool CompressionIsEnabled() { 174 return m_compression_type != CompressionType::None; 175 } 176 177 // If compression is enabled, decompress the packet in m_bytes and update 178 // m_bytes with the uncompressed version. 179 // Returns 'true' packet was decompressed and m_bytes is the now-decompressed 180 // text. 181 // Returns 'false' if unable to decompress or if the checksum was invalid. 182 // 183 // NB: Once the packet has been decompressed, checksum cannot be computed 184 // based 185 // on m_bytes. The checksum was for the compressed packet. 186 bool DecompressPacket(); 187 188 Status StartListenThread(const char *hostname = "127.0.0.1", 189 uint16_t port = 0); 190 191 bool JoinListenThread(); 192 193 static lldb::thread_result_t ListenThread(lldb::thread_arg_t arg); 194 195 // GDB-Remote read thread 196 // . this thread constantly tries to read from the communication 197 // class and stores all packets received in a queue. The usual 198 // threads read requests simply pop packets off the queue in the 199 // usual order. 200 // This setup allows us to intercept and handle async packets, such 201 // as the notify packet. 202 203 // This method is defined as part of communication.h 204 // when the read thread gets any bytes it will pass them on to this function 205 void AppendBytesToCache(const uint8_t *bytes, size_t len, bool broadcast, 206 lldb::ConnectionStatus status) override; 207 208 private: 209 std::queue<StringExtractorGDBRemote> m_packet_queue; // The packet queue 210 std::mutex m_packet_queue_mutex; // Mutex for accessing queue 211 std::condition_variable 212 m_condition_queue_not_empty; // Condition variable to wait for packets 213 214 HostThread m_listen_thread; 215 std::string m_listen_url; 216 217 #if defined(HAVE_LIBCOMPRESSION) 218 CompressionType m_decompression_scratch_type = CompressionType::None; 219 void *m_decompression_scratch = nullptr; 220 #endif 221 222 DISALLOW_COPY_AND_ASSIGN(GDBRemoteCommunication); 223 }; 224 225 } // namespace process_gdb_remote 226 } // namespace lldb_private 227 228 namespace llvm { 229 template <> 230 struct format_provider< 231 lldb_private::process_gdb_remote::GDBRemoteCommunication::PacketResult> { 232 static void format(const lldb_private::process_gdb_remote:: 233 GDBRemoteCommunication::PacketResult &state, 234 raw_ostream &Stream, StringRef Style); 235 }; 236 } // namespace llvm 237 238 #endif // liblldb_GDBRemoteCommunication_h_ 239