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
16namespace lldb_private {
17namespace process_gdb_remote {
18
19class GDBRemoteClientBase : public GDBRemoteCommunication, public Broadcaster {
20public:
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
99protected:
100  PacketResult
101  SendPacketAndWaitForResponseNoLock(llvm::StringRef payload,
102                                     StringExtractorGDBRemote &response);
103
104  virtual void OnRunPacketSent(bool first);
105
106private:
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
176