contrib/llvm-project/lldb/source/Plugins/Process/gdb-remote/GDBRemoteCommunication.h

   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 <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   /// Expand GDB run-length encoding.
 146   static std::string ExpandRLE(std::string);
 147
 148 protected:
 149   std::chrono::seconds m_packet_timeout;
 150   uint32_t m_echo_number;
 151   LazyBool m_supports_qEcho;
 152   GDBRemoteCommunicationHistory m_history;
 153   bool m_send_acks;
 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
 158   CompressionType m_compression_type;
 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(
 168       StringExtractorGDBRemote &response, Timeout<std::micro> timeout,
 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
 180   bool CompressionIsEnabled() {
 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
 221   HostThread m_listen_thread;
 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
 229   GDBRemoteCommunication(const GDBRemoteCommunication &) = delete;
 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<
 240     lldb_private::process_gdb_remote::GDBRemoteCommunication::PacketResult> {
 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