1//===-- Watchpoint.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_BREAKPOINT_WATCHPOINT_H
10#define LLDB_BREAKPOINT_WATCHPOINT_H
11
12#include <memory>
13#include <string>
14
15#include "lldb/Breakpoint/StoppointSite.h"
16#include "lldb/Breakpoint/WatchpointOptions.h"
17#include "lldb/Symbol/CompilerType.h"
18#include "lldb/Target/Target.h"
19#include "lldb/Utility/UserID.h"
20#include "lldb/lldb-private.h"
21
22namespace lldb_private {
23
24class Watchpoint : public std::enable_shared_from_this<Watchpoint>,
25 public StoppointSite {
26public:
27 class WatchpointEventData : public EventData {
28 public:
29 WatchpointEventData(lldb::WatchpointEventType sub_type,
30 const lldb::WatchpointSP &new_watchpoint_sp);
31
32 ~WatchpointEventData() override;
33
34 static llvm::StringRef GetFlavorString();
35
36 llvm::StringRef GetFlavor() const override;
37
38 lldb::WatchpointEventType GetWatchpointEventType() const;
39
40 lldb::WatchpointSP &GetWatchpoint();
41
42 void Dump(Stream *s) const override;
43
44 static lldb::WatchpointEventType
45 GetWatchpointEventTypeFromEvent(const lldb::EventSP &event_sp);
46
47 static lldb::WatchpointSP
48 GetWatchpointFromEvent(const lldb::EventSP &event_sp);
49
50 static const WatchpointEventData *
51 GetEventDataFromEvent(const Event *event_sp);
52
53 private:
54 lldb::WatchpointEventType m_watchpoint_event;
55 lldb::WatchpointSP m_new_watchpoint_sp;
56
57 WatchpointEventData(const WatchpointEventData &) = delete;
58 const WatchpointEventData &operator=(const WatchpointEventData &) = delete;
59 };
60
61 Watchpoint(Target &target, lldb::addr_t addr, uint32_t size,
62 const CompilerType *type, bool hardware = true);
63
64 ~Watchpoint() override;
65
66 bool IsEnabled() const;
67
68 // This doesn't really enable/disable the watchpoint. It is currently just
69 // for use in the Process plugin's {Enable,Disable}Watchpoint, which should
70 // be used instead.
71 void SetEnabled(bool enabled, bool notify = true);
72
73 bool IsHardware() const override;
74
75 bool ShouldStop(StoppointCallbackContext *context) override;
76
77 bool WatchpointRead() const;
78 bool WatchpointWrite() const;
79 bool WatchpointModify() const;
80 uint32_t GetIgnoreCount() const;
81 void SetIgnoreCount(uint32_t n);
82 void SetWatchpointType(uint32_t type, bool notify = true);
83 void SetDeclInfo(const std::string &str);
84 std::string GetWatchSpec();
85 void SetWatchSpec(const std::string &str);
86 bool WatchedValueReportable(const ExecutionContext &exe_ctx);
87
88 // Snapshot management interface.
89 bool IsWatchVariable() const;
90 void SetWatchVariable(bool val);
91 bool CaptureWatchedValue(const ExecutionContext &exe_ctx);
92
93 /// \struct WatchpointVariableContext
94 /// \brief Represents the context of a watchpoint variable.
95 ///
96 /// This struct encapsulates the information related to a watchpoint variable,
97 /// including the watch ID and the execution context in which it is being
98 /// used. This struct is passed as a Baton to the \b
99 /// VariableWatchpointDisabler breakpoint callback.
100 struct WatchpointVariableContext {
101 /// \brief Constructor for WatchpointVariableContext.
102 /// \param watch_id The ID of the watchpoint.
103 /// \param exe_ctx The execution context associated with the watchpoint.
104 WatchpointVariableContext(lldb::watch_id_t watch_id,
105 ExecutionContext exe_ctx)
106 : watch_id(watch_id), exe_ctx(exe_ctx) {}
107
108 lldb::watch_id_t watch_id; ///< The ID of the watchpoint.
109 ExecutionContext
110 exe_ctx; ///< The execution context associated with the watchpoint.
111 };
112
113 class WatchpointVariableBaton : public TypedBaton<WatchpointVariableContext> {
114 public:
115 WatchpointVariableBaton(std::unique_ptr<WatchpointVariableContext> Data)
116 : TypedBaton(std::move(Data)) {}
117 };
118
119 bool SetupVariableWatchpointDisabler(lldb::StackFrameSP frame_sp) const;
120
121 /// Callback routine to disable the watchpoint set on a local variable when
122 /// it goes out of scope.
123 static bool VariableWatchpointDisabler(
124 void *baton, lldb_private::StoppointCallbackContext *context,
125 lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
126
127 void GetDescription(Stream *s, lldb::DescriptionLevel level);
128 void Dump(Stream *s) const override;
129 bool DumpSnapshots(Stream *s, const char *prefix = nullptr) const;
130 void DumpWithLevel(Stream *s, lldb::DescriptionLevel description_level) const;
131 Target &GetTarget() { return m_target; }
132 const Status &GetError() { return m_error; }
133
134 /// Returns the WatchpointOptions structure set for this watchpoint.
135 ///
136 /// \return
137 /// A pointer to this watchpoint's WatchpointOptions.
138 WatchpointOptions *GetOptions() { return &m_options; }
139
140 /// Set the callback action invoked when the watchpoint is hit.
141 ///
142 /// \param[in] callback
143 /// The method that will get called when the watchpoint is hit.
144 /// \param[in] callback_baton
145 /// A void * pointer that will get passed back to the callback function.
146 /// \param[in] is_synchronous
147 /// If \b true the callback will be run on the private event thread
148 /// before the stop event gets reported. If false, the callback will get
149 /// handled on the public event thread after the stop has been posted.
150 void SetCallback(WatchpointHitCallback callback, void *callback_baton,
151 bool is_synchronous = false);
152
153 void SetCallback(WatchpointHitCallback callback,
154 const lldb::BatonSP &callback_baton_sp,
155 bool is_synchronous = false);
156
157 void ClearCallback();
158
159 /// Invoke the callback action when the watchpoint is hit.
160 ///
161 /// \param[in] context
162 /// Described the watchpoint event.
163 ///
164 /// \return
165 /// \b true if the target should stop at this watchpoint and \b false not.
166 bool InvokeCallback(StoppointCallbackContext *context);
167
168 // Condition
169 /// Set the watchpoint's condition.
170 ///
171 /// \param[in] condition
172 /// The condition expression to evaluate when the watchpoint is hit.
173 /// Pass in nullptr to clear the condition.
174 void SetCondition(const char *condition);
175
176 /// Return a pointer to the text of the condition expression.
177 ///
178 /// \return
179 /// A pointer to the condition expression text, or nullptr if no
180 // condition has been set.
181 const char *GetConditionText() const;
182
183 void TurnOnEphemeralMode();
184
185 void TurnOffEphemeralMode();
186
187 bool IsDisabledDuringEphemeralMode();
188
189 const CompilerType &GetCompilerType() { return m_type; }
190
191private:
192 friend class Target;
193 friend class WatchpointList;
194 friend class StopInfoWatchpoint; // This needs to call UndoHitCount()
195
196 void ResetHistoricValues() {
197 m_old_value_sp.reset();
198 m_new_value_sp.reset();
199 }
200
201 void UndoHitCount() { m_hit_counter.Decrement(); }
202
203 Target &m_target;
204 bool m_enabled; // Is this watchpoint enabled
205 bool m_is_hardware; // Is this a hardware watchpoint
206 bool m_is_watch_variable; // True if set via 'watchpoint set variable'.
207 bool m_is_ephemeral; // True if the watchpoint is in the ephemeral mode,
208 // meaning that it is
209 // undergoing a pair of temporary disable/enable actions to avoid recursively
210 // triggering further watchpoint events.
211 uint32_t m_disabled_count; // Keep track of the count that the watchpoint is
212 // disabled while in ephemeral mode.
213 // At the end of the ephemeral mode when the watchpoint is to be enabled
214 // again, we check the count, if it is more than 1, it means the user-
215 // supplied actions actually want the watchpoint to be disabled!
216 uint32_t m_watch_read : 1, // 1 if we stop when the watched data is read from
217 m_watch_write : 1, // 1 if we stop when the watched data is written to
218 m_watch_modify : 1; // 1 if we stop when the watched data is changed
219 uint32_t m_ignore_count; // Number of times to ignore this watchpoint
220 std::string m_decl_str; // Declaration information, if any.
221 std::string m_watch_spec_str; // Spec for the watchpoint.
222 lldb::ValueObjectSP m_old_value_sp;
223 lldb::ValueObjectSP m_new_value_sp;
224 CompilerType m_type;
225 Status m_error; // An error object describing errors associated with this
226 // watchpoint.
227 WatchpointOptions m_options; // Settable watchpoint options, which is a
228 // delegate to handle the callback machinery.
229 std::unique_ptr<UserExpression> m_condition_up; // The condition to test.
230
231 void SetID(lldb::watch_id_t id) { m_id = id; }
232
233 void SendWatchpointChangedEvent(lldb::WatchpointEventType eventKind);
234
235 Watchpoint(const Watchpoint &) = delete;
236 const Watchpoint &operator=(const Watchpoint &) = delete;
237};
238
239} // namespace lldb_private
240
241#endif // LLDB_BREAKPOINT_WATCHPOINT_H
242

source code of lldb/include/lldb/Breakpoint/Watchpoint.h