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