LLDB  mainline
GDBRemoteCommunication.h
Go to the documentation of this file.
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 
13 
14 #include <condition_variable>
15 #include <mutex>
16 #include <queue>
17 #include <string>
18 #include <vector>
19 
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"
27 #include "lldb/lldb-public.h"
28 
29 namespace lldb_private {
30 namespace process_gdb_remote {
31 
32 typedef enum {
40 
41 enum class CompressionType {
42  None = 0, // no compression
43  ZlibDeflate, // zlib's deflate compression scheme, requires zlib or Apple's
44  // libcompression
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
49 };
50 
51 class ProcessGDBRemote;
52 
54 public:
55  enum {
56  eBroadcastBitRunPacketSent = kLoUserBroadcastBit,
57  eBroadcastBitGdbReadThreadGotNotify =
58  kLoUserBroadcastBit << 1 // Sent when we received a notify packet.
59  };
60 
61  enum class PacketType { Invalid = 0, Standard, Notify };
62 
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
70  // was sent
71  ErrorReplyAck, // Sending reply ack failed
72  ErrorDisconnected, // We were disconnected
73  ErrorNoSequenceLock // We couldn't get the sequence lock for a multi-packet
74  // request
75  };
76 
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
80  class ScopedTimeout {
81  public:
83  std::chrono::seconds timeout);
84  ~ScopedTimeout();
85 
86  private:
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;
93  };
94 
95  GDBRemoteCommunication(const char *comm_name, const char *listener_name);
96 
97  ~GDBRemoteCommunication() override;
98 
99  PacketResult GetAck();
100 
101  size_t SendAck();
102 
103  size_t SendNack();
104 
105  char CalculcateChecksum(llvm::StringRef payload);
106 
107  PacketType CheckForPacket(const uint8_t *src, size_t src_len,
108  StringExtractorGDBRemote &packet);
109 
110  bool GetSendAcks() { return m_send_acks; }
111 
112  // Set the global packet timeout.
113  //
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
116  // for ACKs.
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;
121  }
122 
123  std::chrono::seconds GetPacketTimeout() const { return m_packet_timeout; }
124 
125  // Start a debugserver instance on the current host using the
126  // supplied connection URL.
127  Status StartDebugserverProcess(
128  const char *url,
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
134 
135  void DumpHistory(Stream &strm);
136  void SetHistoryStream(llvm::raw_ostream *strm);
137 
138  static llvm::Error ConnectLocally(GDBRemoteCommunication &client,
139  GDBRemoteCommunication &server);
140 
141 protected:
142  std::chrono::seconds m_packet_timeout;
147  bool m_is_platform; // Set to true if this class represents a platform,
148  // false if this class represents a debug session for
149  // a single process
150 
152 
153  PacketResult SendPacketNoLock(llvm::StringRef payload);
154  PacketResult SendRawPacketNoLock(llvm::StringRef payload,
155  bool skip_ack = false);
156 
157  PacketResult ReadPacket(StringExtractorGDBRemote &response,
158  Timeout<std::micro> timeout, bool sync_on_timeout);
159 
160  PacketResult ReadPacketWithOutputSupport(
162  bool sync_on_timeout,
163  llvm::function_ref<void(llvm::StringRef)> output_callback);
164 
165  // Pop a packet from the queue in a thread safe manner
166  PacketResult PopPacketFromQueue(StringExtractorGDBRemote &response,
167  Timeout<std::micro> timeout);
168 
169  PacketResult WaitForPacketNoLock(StringExtractorGDBRemote &response,
170  Timeout<std::micro> timeout,
171  bool sync_on_timeout);
172 
174  return m_compression_type != CompressionType::None;
175  }
176 
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
180  // text.
181  // Returns 'false' if unable to decompress or if the checksum was invalid.
182  //
183  // NB: Once the packet has been decompressed, checksum cannot be computed
184  // based
185  // on m_bytes. The checksum was for the compressed packet.
186  bool DecompressPacket();
187 
188  Status StartListenThread(const char *hostname = "127.0.0.1",
189  uint16_t port = 0);
190 
191  bool JoinListenThread();
192 
193  static lldb::thread_result_t ListenThread(lldb::thread_arg_t arg);
194 
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
199  // usual order.
200  // This setup allows us to intercept and handle async packets, such
201  // as the notify packet.
202 
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;
207 
208 private:
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
213 
214  HostThread m_listen_thread;
215  std::string m_listen_url;
216 
217 #if defined(HAVE_LIBCOMPRESSION)
218  CompressionType m_decompression_scratch_type = CompressionType::None;
219  void *m_decompression_scratch = nullptr;
220 #endif
221 
222  DISALLOW_COPY_AND_ASSIGN(GDBRemoteCommunication);
223 };
224 
225 } // namespace process_gdb_remote
226 } // namespace lldb_private
227 
228 namespace llvm {
229 template <>
230 struct format_provider<
232  static void format(const lldb_private::process_gdb_remote::
234  raw_ostream &Stream, StringRef Style);
235 };
236 } // namespace llvm
237 
238 #endif // liblldb_GDBRemoteCommunication_h_
void * thread_arg_t
Definition: lldb-types.h:61
A command line argument class.
Definition: Args.h:32
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
Definition: Debugger.h:71
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
llvm::Error Error
The history keeps a circular buffer of GDB remote packets.
A plug-in interface definition class for debug platform that includes many platform abilities such as...
Definition: Platform.h:67
An abstract communications class.
Definition: Communication.h:91
std::chrono::seconds SetPacketTimeout(std::chrono::seconds packet_timeout)
An error handling class.
Definition: Status.h:44
void * thread_result_t
Definition: lldb-types.h:62