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

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