1 //===-- GDBRemoteCommunication.h --------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_GDBRemoteCommunication_h_
10 #define liblldb_GDBRemoteCommunication_h_
12 #include "GDBRemoteCommunicationHistory.h"
14 #include <condition_variable>
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"
29 namespace lldb_private {
30 namespace process_gdb_remote {
32 enum GDBStoppointType {
33 eStoppointInvalid = -1,
34 eBreakpointSoftware = 0,
41 enum class CompressionType {
42 None = 0, // no compression
43 ZlibDeflate, // zlib's deflate compression scheme, requires zlib or Apple's
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
51 class ProcessGDBRemote;
53 class GDBRemoteCommunication : public Communication {
56 eBroadcastBitRunPacketSent = kLoUserBroadcastBit,
57 eBroadcastBitGdbReadThreadGotNotify =
58 kLoUserBroadcastBit << 1 // Sent when we received a notify packet.
61 enum class PacketType { Invalid = 0, Standard, Notify };
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
71 ErrorReplyAck, // Sending reply ack failed
72 ErrorDisconnected, // We were disconnected
73 ErrorNoSequenceLock // We couldn't get the sequence lock for a multi-packet
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
82 ScopedTimeout(GDBRemoteCommunication &gdb_comm,
83 std::chrono::seconds timeout);
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;
95 GDBRemoteCommunication(const char *comm_name, const char *listener_name);
97 ~GDBRemoteCommunication() override;
99 PacketResult GetAck();
105 char CalculcateChecksum(llvm::StringRef payload);
107 PacketType CheckForPacket(const uint8_t *src, size_t src_len,
108 StringExtractorGDBRemote &packet);
110 bool GetSendAcks() { return m_send_acks; }
112 // Set the global packet timeout.
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
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;
123 std::chrono::seconds GetPacketTimeout() const { return m_packet_timeout; }
125 // Start a debugserver instance on the current host using the
126 // supplied connection URL.
127 Status StartDebugserverProcess(
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
135 void DumpHistory(Stream &strm);
136 void SetHistoryStream(llvm::raw_ostream *strm);
138 static llvm::Error ConnectLocally(GDBRemoteCommunication &client,
139 GDBRemoteCommunication &server);
142 std::chrono::seconds m_packet_timeout;
143 uint32_t m_echo_number;
144 LazyBool m_supports_qEcho;
145 GDBRemoteCommunicationHistory m_history;
147 bool m_is_platform; // Set to true if this class represents a platform,
148 // false if this class represents a debug session for
151 CompressionType m_compression_type;
153 PacketResult SendPacketNoLock(llvm::StringRef payload);
154 PacketResult SendRawPacketNoLock(llvm::StringRef payload,
155 bool skip_ack = false);
157 PacketResult ReadPacket(StringExtractorGDBRemote &response,
158 Timeout<std::micro> timeout, bool sync_on_timeout);
160 PacketResult ReadPacketWithOutputSupport(
161 StringExtractorGDBRemote &response, Timeout<std::micro> timeout,
162 bool sync_on_timeout,
163 llvm::function_ref<void(llvm::StringRef)> output_callback);
165 // Pop a packet from the queue in a thread safe manner
166 PacketResult PopPacketFromQueue(StringExtractorGDBRemote &response,
167 Timeout<std::micro> timeout);
169 PacketResult WaitForPacketNoLock(StringExtractorGDBRemote &response,
170 Timeout<std::micro> timeout,
171 bool sync_on_timeout);
173 bool CompressionIsEnabled() {
174 return m_compression_type != CompressionType::None;
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
181 // Returns 'false' if unable to decompress or if the checksum was invalid.
183 // NB: Once the packet has been decompressed, checksum cannot be computed
185 // on m_bytes. The checksum was for the compressed packet.
186 bool DecompressPacket();
188 Status StartListenThread(const char *hostname = "127.0.0.1",
191 bool JoinListenThread();
193 static lldb::thread_result_t ListenThread(lldb::thread_arg_t arg);
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
200 // This setup allows us to intercept and handle async packets, such
201 // as the notify packet.
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;
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
214 HostThread m_listen_thread;
215 std::string m_listen_url;
217 #if defined(HAVE_LIBCOMPRESSION)
218 CompressionType m_decompression_scratch_type = CompressionType::None;
219 void *m_decompression_scratch = nullptr;
222 DISALLOW_COPY_AND_ASSIGN(GDBRemoteCommunication);
225 } // namespace process_gdb_remote
226 } // namespace lldb_private
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);
238 #endif // liblldb_GDBRemoteCommunication_h_