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