GDBRemoteCommunication.h revision 360784 
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
29namespace lldb_private {
30namespace repro {
31class PacketRecorder;
32}
33namespace process_gdb_remote {
34
35enum GDBStoppointType {
36  eStoppointInvalid = -1,
37  eBreakpointSoftware = 0,
38  eBreakpointHardware,
39  eWatchpointWrite,
40  eWatchpointRead,
41  eWatchpointReadWrite
42};
43
44enum 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
54class ProcessGDBRemote;
55
56class GDBRemoteCommunication : public Communication {
57public:
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
145protected:
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
212private:
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
232namespace llvm {
233template <>
234struct 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