lldb/source/Plugins/Process/gdb-remote/GDBRemoteClientBase.h

   1 //===-- GDBRemoteClientBase.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_GDBREMOTECLIENTBASE_H
  10 #define LLDB_SOURCE_PLUGINS_PROCESS_GDB_REMOTE_GDBREMOTECLIENTBASE_H
  11
  12 #include "GDBRemoteCommunication.h"
  13
  14 #include <condition_variable>
  15
  16 namespace lldb_private {
  17 namespace process_gdb_remote {
  18
  19 class GDBRemoteClientBase : public GDBRemoteCommunication, public Broadcaster {
  20 public:
  21   enum {
  22     eBroadcastBitRunPacketSent = (1u << 0),
  23   };
  24
  25   struct ContinueDelegate {
  26     virtual ~ContinueDelegate();
  27     virtual void HandleAsyncStdout(llvm::StringRef out) = 0;
  28     virtual void HandleAsyncMisc(llvm::StringRef data) = 0;
  29     virtual void HandleStopReply() = 0;
  30
  31     /// Process asynchronously-received structured data.
  32     ///
  33     /// \param[in] data
  34     ///   The complete data packet, expected to start with JSON-async.
  35     virtual void HandleAsyncStructuredDataPacket(llvm::StringRef data) = 0;
  36   };
  37
  38   GDBRemoteClientBase(const char *comm_name);
  39
  40   bool SendAsyncSignal(int signo, std::chrono::seconds interrupt_timeout);
  41
  42   bool Interrupt(std::chrono::seconds interrupt_timeout);
  43
  44   lldb::StateType SendContinuePacketAndWaitForResponse(
  45       ContinueDelegate &delegate, const UnixSignals &signals,
  46       llvm::StringRef payload, std::chrono::seconds interrupt_timeout,
  47       StringExtractorGDBRemote &response);
  48
  49   // If interrupt_timeout == 0 seconds, don't interrupt the target.
  50   // Only send the packet if the target is stopped.
  51   // If you want to use this mode, use the fact that the timeout is defaulted
  52   // so it's clear from the call-site that you are using no-interrupt.
  53   // If it is non-zero, interrupt the target if it is running, and
  54   // send the packet.
  55   // It the target doesn't respond within the given timeout, it returns
  56   // ErrorReplyTimeout.
  57   PacketResult SendPacketAndWaitForResponse(
  58       llvm::StringRef payload, StringExtractorGDBRemote &response,
  59       std::chrono::seconds interrupt_timeout = std::chrono::seconds(0));
  60
  61   PacketResult ReadPacketWithOutputSupport(
  62       StringExtractorGDBRemote &response, Timeout<std::micro> timeout,
  63       bool sync_on_timeout,
  64       llvm::function_ref<void(llvm::StringRef)> output_callback);
  65
  66   PacketResult SendPacketAndReceiveResponseWithOutputSupport(
  67       llvm::StringRef payload, StringExtractorGDBRemote &response,
  68       std::chrono::seconds interrupt_timeout,
  69       llvm::function_ref<void(llvm::StringRef)> output_callback);
  70
  71   class Lock {
  72   public:
  73     // If interrupt_timeout == 0 seconds, only take the lock if the target is
  74     // not running. If using this option, use the fact that the
  75     // interrupt_timeout is defaulted so it will be obvious at the call site
  76     // that you are choosing this mode. If it is non-zero, interrupt the target
  77     // if it is running, waiting for the given timeout for the interrupt to
  78     // succeed.
  79     Lock(GDBRemoteClientBase &comm,
  80          std::chrono::seconds interrupt_timeout = std::chrono::seconds(0));
  81     ~Lock();
  82
  83     explicit operator bool() { return m_acquired; }
  84
  85     // Whether we had to interrupt the continue thread to acquire the
  86     // connection.
  87     bool DidInterrupt() const { return m_did_interrupt; }
  88
  89   private:
  90     std::unique_lock<std::recursive_mutex> m_async_lock;
  91     GDBRemoteClientBase &m_comm;
  92     std::chrono::seconds m_interrupt_timeout;
  93     bool m_acquired;
  94     bool m_did_interrupt;
  95
  96     void SyncWithContinueThread();
  97   };
  98
  99 protected:
 100   PacketResult
 101   SendPacketAndWaitForResponseNoLock(llvm::StringRef payload,
 102                                      StringExtractorGDBRemote &response);
 103
 104   virtual void OnRunPacketSent(bool first);
 105
 106 private:
 107   /// Variables handling synchronization between the Continue thread and any
 108   /// other threads wishing to send packets over the connection. Either the
 109   /// continue thread has control over the connection (m_is_running == true) or
 110   /// the connection is free for an arbitrary number of other senders to take
 111   /// which indicate their interest by incrementing m_async_count.
 112   ///
 113   /// Semantics of individual states:
 114   ///
 115   /// - m_continue_packet == false, m_async_count == 0:
 116   ///   connection is free
 117   /// - m_continue_packet == true, m_async_count == 0:
 118   ///   only continue thread is present
 119   /// - m_continue_packet == true, m_async_count > 0:
 120   ///   continue thread has control, async threads should interrupt it and wait
 121   ///   for it to set m_continue_packet to false
 122   /// - m_continue_packet == false, m_async_count > 0:
 123   ///   async threads have control, continue thread needs to wait for them to
 124   ///   finish (m_async_count goes down to 0).
 125   /// @{
 126   std::mutex m_mutex;
 127   std::condition_variable m_cv;
 128
 129   /// Packet with which to resume after an async interrupt. Can be changed by
 130   /// an async thread e.g. to inject a signal.
 131   std::string m_continue_packet;
 132
 133   /// When was the interrupt packet sent. Used to make sure we time out if the
 134   /// stub does not respond to interrupt requests.
 135   std::chrono::time_point<std::chrono::steady_clock> m_interrupt_endpoint;
 136
 137   /// Number of threads interested in sending.
 138   uint32_t m_async_count;
 139
 140   /// Whether the continue thread has control.
 141   bool m_is_running;
 142
 143   /// Whether we should resume after a stop.
 144   bool m_should_stop;
 145   /// @}
 146
 147   /// This handles the synchronization between individual async threads. For
 148   /// now they just use a simple mutex.
 149   std::recursive_mutex m_async_mutex;
 150
 151   bool ShouldStop(const UnixSignals &signals,
 152                   StringExtractorGDBRemote &response);
 153
 154   class ContinueLock {
 155   public:
 156     enum class LockResult { Success, Cancelled, Failed };
 157
 158     explicit ContinueLock(GDBRemoteClientBase &comm);
 159     ~ContinueLock();
 160     explicit operator bool() { return m_acquired; }
 161
 162     LockResult lock();
 163
 164     void unlock();
 165
 166   private:
 167     GDBRemoteClientBase &m_comm;
 168     bool m_acquired;
 169   };
 170 };
 171
 172 } // namespace process_gdb_remote
 173 } // namespace lldb_private
 174
 175 #endif // LLDB_SOURCE_PLUGINS_PROCESS_GDB_REMOTE_GDBREMOTECLIENTBASE_H