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 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 
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.
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 
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 protected:
146   std::chrono::seconds m_packet_timeout;
147   uint32_t m_echo_number;
148   LazyBool m_supports_qEcho;
149   GDBRemoteCommunicationHistory m_history;
150   bool m_send_acks;
151   bool m_is_platform; // Set to true if this class represents a platform,
152                       // false if this class represents a debug session for
153                       // a single process
154 
155   CompressionType m_compression_type;
156 
157   PacketResult SendPacketNoLock(llvm::StringRef payload);
158   PacketResult SendRawPacketNoLock(llvm::StringRef payload,
159                                    bool skip_ack = false);
160 
161   PacketResult ReadPacket(StringExtractorGDBRemote &response,
162                           Timeout<std::micro> timeout, bool sync_on_timeout);
163 
164   PacketResult ReadPacketWithOutputSupport(
165       StringExtractorGDBRemote &response, Timeout<std::micro> timeout,
166       bool sync_on_timeout,
167       llvm::function_ref<void(llvm::StringRef)> output_callback);
168 
169   // Pop a packet from the queue in a thread safe manner
170   PacketResult PopPacketFromQueue(StringExtractorGDBRemote &response,
171                                   Timeout<std::micro> timeout);
172 
173   PacketResult WaitForPacketNoLock(StringExtractorGDBRemote &response,
174                                    Timeout<std::micro> timeout,
175                                    bool sync_on_timeout);
176 
177   bool CompressionIsEnabled() {
178     return m_compression_type != CompressionType::None;
179   }
180 
181   // If compression is enabled, decompress the packet in m_bytes and update
182   // m_bytes with the uncompressed version.
183   // Returns 'true' packet was decompressed and m_bytes is the now-decompressed
184   // text.
185   // Returns 'false' if unable to decompress or if the checksum was invalid.
186   //
187   // NB: Once the packet has been decompressed, checksum cannot be computed
188   // based
189   // on m_bytes.  The checksum was for the compressed packet.
190   bool DecompressPacket();
191 
192   Status StartListenThread(const char *hostname = "127.0.0.1",
193                            uint16_t port = 0);
194 
195   bool JoinListenThread();
196 
197   static lldb::thread_result_t ListenThread(lldb::thread_arg_t arg);
198 
199   // GDB-Remote read thread
200   //  . this thread constantly tries to read from the communication
201   //    class and stores all packets received in a queue.  The usual
202   //    threads read requests simply pop packets off the queue in the
203   //    usual order.
204   //    This setup allows us to intercept and handle async packets, such
205   //    as the notify packet.
206 
207   // This method is defined as part of communication.h
208   // when the read thread gets any bytes it will pass them on to this function
209   void AppendBytesToCache(const uint8_t *bytes, size_t len, bool broadcast,
210                           lldb::ConnectionStatus status) override;
211 
212 private:
213   std::queue<StringExtractorGDBRemote> m_packet_queue; // The packet queue
214   std::mutex m_packet_queue_mutex; // Mutex for accessing queue
215   std::condition_variable
216       m_condition_queue_not_empty; // Condition variable to wait for packets
217 
218   HostThread m_listen_thread;
219   std::string m_listen_url;
220 
221 #if defined(HAVE_LIBCOMPRESSION)
222   CompressionType m_decompression_scratch_type = CompressionType::None;
223   void *m_decompression_scratch = nullptr;
224 #endif
225 
226   DISALLOW_COPY_AND_ASSIGN(GDBRemoteCommunication);
227 };
228 
229 } // namespace process_gdb_remote
230 } // namespace lldb_private
231 
232 namespace llvm {
233 template <>
234 struct format_provider<
235     lldb_private::process_gdb_remote::GDBRemoteCommunication::PacketResult> {
236   static void format(const lldb_private::process_gdb_remote::
237                          GDBRemoteCommunication::PacketResult &state,
238                      raw_ostream &Stream, StringRef Style);
239 };
240 } // namespace llvm
241 
242 #endif // liblldb_GDBRemoteCommunication_h_
243