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