1 //===-- GDBRemoteCommunication.h --------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_GDBRemoteCommunication_h_
11 #define liblldb_GDBRemoteCommunication_h_
15 #include <condition_variable>
21 // Other libraries and framework includes
23 #include "lldb/Core/Communication.h"
24 #include "lldb/Core/Listener.h"
25 #include "lldb/Host/HostThread.h"
26 #include "lldb/Host/Predicate.h"
27 #include "lldb/Interpreter/Args.h"
28 #include "lldb/lldb-public.h"
30 #include "Utility/StringExtractorGDBRemote.h"
32 namespace lldb_private {
33 namespace process_gdb_remote {
36 eStoppointInvalid = -1,
37 eBreakpointSoftware = 0,
44 enum class CompressionType {
45 None = 0, // no compression
46 ZlibDeflate, // zlib's deflate compression scheme, requires zlib or Apple's
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
54 class ProcessGDBRemote;
56 class GDBRemoteCommunication : public Communication {
59 eBroadcastBitRunPacketSent = kLoUserBroadcastBit,
60 eBroadcastBitGdbReadThreadGotNotify =
61 kLoUserBroadcastBit << 1 // Sent when we received a notify packet.
64 enum class PacketType { Invalid = 0, Standard, Notify };
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
74 ErrorReplyAck, // Sending reply ack failed
75 ErrorDisconnected, // We were disconnected
76 ErrorNoSequenceLock // We couldn't get the sequence lock for a multi-packet
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
85 ScopedTimeout(GDBRemoteCommunication &gdb_comm,
86 std::chrono::seconds timeout);
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;
98 GDBRemoteCommunication(const char *comm_name, const char *listener_name);
100 ~GDBRemoteCommunication() override;
102 PacketResult GetAck();
108 char CalculcateChecksum(llvm::StringRef payload);
110 PacketType CheckForPacket(const uint8_t *src, size_t src_len,
111 StringExtractorGDBRemote &packet);
113 bool GetSendAcks() { return m_send_acks; }
115 //------------------------------------------------------------------
116 // Set the global packet timeout.
118 // For clients, this is the timeout that gets used when sending
119 // packets and waiting for responses. For servers, this is used when waiting
121 //------------------------------------------------------------------
122 std::chrono::seconds SetPacketTimeout(std::chrono::seconds packet_timeout) {
123 const auto old_packet_timeout = m_packet_timeout;
124 m_packet_timeout = packet_timeout;
125 return old_packet_timeout;
128 std::chrono::seconds GetPacketTimeout() const { return m_packet_timeout; }
130 //------------------------------------------------------------------
131 // Start a debugserver instance on the current host using the
132 // supplied connection URL.
133 //------------------------------------------------------------------
134 Status StartDebugserverProcess(
136 Platform *platform, // If non nullptr, then check with the platform for
137 // the GDB server binary if it can't be located
138 ProcessLaunchInfo &launch_info, uint16_t *port, const Args *inferior_args,
139 int pass_comm_fd); // Communication file descriptor to pass during
140 // fork/exec to avoid having to connect/accept
142 void DumpHistory(Stream &strm);
148 ePacketTypeInvalid = 0,
155 : packet(), type(ePacketTypeInvalid), bytes_transmitted(0),
156 packet_idx(0), tid(LLDB_INVALID_THREAD_ID) {}
160 type = ePacketTypeInvalid;
161 bytes_transmitted = 0;
163 tid = LLDB_INVALID_THREAD_ID;
167 uint32_t bytes_transmitted;
172 History(uint32_t size);
176 // For single char packets for ack, nack and /x03
177 void AddPacket(char packet_char, PacketType type,
178 uint32_t bytes_transmitted);
180 void AddPacket(const std::string &src, uint32_t src_len, PacketType type,
181 uint32_t bytes_transmitted);
183 void Dump(Stream &strm) const;
185 void Dump(Log *log) const;
187 bool DidDumpToLog() const { return m_dumped_to_log; }
190 uint32_t GetFirstSavedPacketIndex() const {
191 if (m_total_packet_count < m_packets.size())
194 return m_curr_idx + 1;
197 uint32_t GetNumPacketsInHistory() const {
198 if (m_total_packet_count < m_packets.size())
199 return m_total_packet_count;
201 return (uint32_t)m_packets.size();
204 uint32_t GetNextIndex() {
205 ++m_total_packet_count;
206 const uint32_t idx = m_curr_idx;
207 m_curr_idx = NormalizeIndex(idx + 1);
211 uint32_t NormalizeIndex(uint32_t i) const { return i % m_packets.size(); }
213 std::vector<Entry> m_packets;
215 uint32_t m_total_packet_count;
216 mutable bool m_dumped_to_log;
219 std::chrono::seconds m_packet_timeout;
220 uint32_t m_echo_number;
221 LazyBool m_supports_qEcho;
224 bool m_is_platform; // Set to true if this class represents a platform,
225 // false if this class represents a debug session for
228 CompressionType m_compression_type;
230 PacketResult SendPacketNoLock(llvm::StringRef payload);
232 PacketResult ReadPacket(StringExtractorGDBRemote &response,
233 Timeout<std::micro> timeout, bool sync_on_timeout);
235 // Pop a packet from the queue in a thread safe manner
236 PacketResult PopPacketFromQueue(StringExtractorGDBRemote &response,
237 Timeout<std::micro> timeout);
239 PacketResult WaitForPacketNoLock(StringExtractorGDBRemote &response,
240 Timeout<std::micro> timeout,
241 bool sync_on_timeout);
243 bool CompressionIsEnabled() {
244 return m_compression_type != CompressionType::None;
247 // If compression is enabled, decompress the packet in m_bytes and update
248 // m_bytes with the uncompressed version.
249 // Returns 'true' packet was decompressed and m_bytes is the now-decompressed
251 // Returns 'false' if unable to decompress or if the checksum was invalid.
253 // NB: Once the packet has been decompressed, checksum cannot be computed
255 // on m_bytes. The checksum was for the compressed packet.
256 bool DecompressPacket();
258 Status StartListenThread(const char *hostname = "127.0.0.1",
261 bool JoinListenThread();
263 static lldb::thread_result_t ListenThread(lldb::thread_arg_t arg);
265 // GDB-Remote read thread
266 // . this thread constantly tries to read from the communication
267 // class and stores all packets received in a queue. The usual
268 // threads read requests simply pop packets off the queue in the
270 // This setup allows us to intercept and handle async packets, such
271 // as the notify packet.
273 // This method is defined as part of communication.h
274 // when the read thread gets any bytes it will pass them on to this function
275 void AppendBytesToCache(const uint8_t *bytes, size_t len, bool broadcast,
276 lldb::ConnectionStatus status) override;
279 std::queue<StringExtractorGDBRemote> m_packet_queue; // The packet queue
280 std::mutex m_packet_queue_mutex; // Mutex for accessing queue
281 std::condition_variable
282 m_condition_queue_not_empty; // Condition variable to wait for packets
284 HostThread m_listen_thread;
285 std::string m_listen_url;
287 DISALLOW_COPY_AND_ASSIGN(GDBRemoteCommunication);
290 } // namespace process_gdb_remote
291 } // namespace lldb_private
293 #endif // liblldb_GDBRemoteCommunication_h_