1//===-- BreakpointLocation.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_BREAKPOINTLOCATION_H
10#define LLDB_BREAKPOINT_BREAKPOINTLOCATION_H
11
12#include <memory>
13#include <mutex>
14
15#include "lldb/Breakpoint/BreakpointOptions.h"
16#include "lldb/Breakpoint/StoppointHitCounter.h"
17#include "lldb/Core/Address.h"
18#include "lldb/Utility/UserID.h"
19#include "lldb/lldb-private.h"
20
21namespace lldb_private {
22
23/// \class BreakpointLocation BreakpointLocation.h
24/// "lldb/Breakpoint/BreakpointLocation.h" Class that manages one unique (by
25/// address) instance of a logical breakpoint.
26
27/// General Outline:
28/// A breakpoint location is defined by the breakpoint that produces it,
29/// and the address that resulted in this particular instantiation. Each
30/// breakpoint location also may have a breakpoint site if its address has
31/// been loaded into the program. Finally it has a settable options object.
32///
33/// FIXME: Should we also store some fingerprint for the location, so
34/// we can map one location to the "equivalent location" on rerun? This would
35/// be useful if you've set options on the locations.
36
37class BreakpointLocation
38 : public std::enable_shared_from_this<BreakpointLocation> {
39public:
40 ~BreakpointLocation();
41
42 /// Gets the load address for this breakpoint location \return
43 /// Returns breakpoint location load address, \b
44 /// LLDB_INVALID_ADDRESS if not yet set.
45 lldb::addr_t GetLoadAddress() const;
46
47 /// Gets the Address for this breakpoint location \return
48 /// Returns breakpoint location Address.
49 Address &GetAddress();
50 /// Gets the Breakpoint that created this breakpoint location \return
51 /// Returns the owning breakpoint.
52 Breakpoint &GetBreakpoint();
53
54 Target &GetTarget();
55
56 /// Determines whether we should stop due to a hit at this breakpoint
57 /// location.
58 ///
59 /// Side Effects: This may evaluate the breakpoint condition, and run the
60 /// callback. So this command may do a considerable amount of work.
61 ///
62 /// \return
63 /// \b true if this breakpoint location thinks we should stop,
64 /// \b false otherwise.
65 bool ShouldStop(StoppointCallbackContext *context);
66
67 // The next section deals with various breakpoint options.
68
69 /// If \a enabled is \b true, enable the breakpoint, if \b false disable it.
70 void SetEnabled(bool enabled);
71
72 /// Check the Enable/Disable state.
73 ///
74 /// \return
75 /// \b true if the breakpoint is enabled, \b false if disabled.
76 bool IsEnabled() const;
77
78 /// If \a auto_continue is \b true, set the breakpoint to continue when hit.
79 void SetAutoContinue(bool auto_continue);
80
81 /// Check the AutoContinue state.
82 ///
83 /// \return
84 /// \b true if the breakpoint is set to auto-continue, \b false if not.
85 bool IsAutoContinue() const;
86
87 /// Return the current Hit Count.
88 uint32_t GetHitCount() const { return m_hit_counter.GetValue(); }
89
90 /// Resets the current Hit Count.
91 void ResetHitCount() { m_hit_counter.Reset(); }
92
93 /// Return the current Ignore Count.
94 ///
95 /// \return
96 /// The number of breakpoint hits to be ignored.
97 uint32_t GetIgnoreCount() const;
98
99 /// Set the breakpoint to ignore the next \a count breakpoint hits.
100 ///
101 /// \param[in] n
102 /// The number of breakpoint hits to ignore.
103 void SetIgnoreCount(uint32_t n);
104
105 /// Set the callback action invoked when the breakpoint is hit.
106 ///
107 /// The callback will return a bool indicating whether the target should
108 /// stop at this breakpoint or not.
109 ///
110 /// \param[in] callback
111 /// The method that will get called when the breakpoint is hit.
112 ///
113 /// \param[in] callback_baton_sp
114 /// A shared pointer to a Baton that provides the void * needed
115 /// for the callback.
116 ///
117 /// \see lldb_private::Baton
118 void SetCallback(BreakpointHitCallback callback,
119 const lldb::BatonSP &callback_baton_sp, bool is_synchronous);
120
121 void SetCallback(BreakpointHitCallback callback, void *baton,
122 bool is_synchronous);
123
124 void ClearCallback();
125
126 /// Set the breakpoint location's condition.
127 ///
128 /// \param[in] condition
129 /// The condition expression to evaluate when the breakpoint is hit.
130 void SetCondition(const char *condition);
131
132 /// Return a pointer to the text of the condition expression.
133 ///
134 /// \return
135 /// A pointer to the condition expression text, or nullptr if no
136 // condition has been set.
137 const char *GetConditionText(size_t *hash = nullptr) const;
138
139 bool ConditionSaysStop(ExecutionContext &exe_ctx, Status &error);
140
141 /// Set the valid thread to be checked when the breakpoint is hit.
142 ///
143 /// \param[in] thread_id
144 /// If this thread hits the breakpoint, we stop, otherwise not.
145 void SetThreadID(lldb::tid_t thread_id);
146
147 lldb::tid_t GetThreadID();
148
149 void SetThreadIndex(uint32_t index);
150
151 uint32_t GetThreadIndex() const;
152
153 void SetThreadName(const char *thread_name);
154
155 const char *GetThreadName() const;
156
157 void SetQueueName(const char *queue_name);
158
159 const char *GetQueueName() const;
160
161 // The next section deals with this location's breakpoint sites.
162
163 /// Try to resolve the breakpoint site for this location.
164 ///
165 /// \return
166 /// \b true if we were successful at setting a breakpoint site,
167 /// \b false otherwise.
168 bool ResolveBreakpointSite();
169
170 /// Clear this breakpoint location's breakpoint site - for instance when
171 /// disabling the breakpoint.
172 ///
173 /// \return
174 /// \b true if there was a breakpoint site to be cleared, \b false
175 /// otherwise.
176 bool ClearBreakpointSite();
177
178 /// Return whether this breakpoint location has a breakpoint site. \return
179 /// \b true if there was a breakpoint site for this breakpoint
180 /// location, \b false otherwise.
181 bool IsResolved() const;
182
183 lldb::BreakpointSiteSP GetBreakpointSite() const;
184
185 // The next section are generic report functions.
186
187 /// Print a description of this breakpoint location to the stream \a s.
188 ///
189 /// \param[in] s
190 /// The stream to which to print the description.
191 ///
192 /// \param[in] level
193 /// The description level that indicates the detail level to
194 /// provide.
195 ///
196 /// \see lldb::DescriptionLevel
197 void GetDescription(Stream *s, lldb::DescriptionLevel level);
198
199 /// Standard "Dump" method. At present it does nothing.
200 void Dump(Stream *s) const;
201
202 /// Use this to set location specific breakpoint options.
203 ///
204 /// It will create a copy of the containing breakpoint's options if that
205 /// hasn't been done already
206 ///
207 /// \return
208 /// A reference to the breakpoint options.
209 BreakpointOptions &GetLocationOptions();
210
211 /// Use this to access breakpoint options from this breakpoint location.
212 /// This will return the options that have a setting for the specified
213 /// BreakpointOptions kind.
214 ///
215 /// \param[in] kind
216 /// The particular option you are looking up.
217 /// \return
218 /// A pointer to the containing breakpoint's options if this
219 /// location doesn't have its own copy.
220 const BreakpointOptions &
221 GetOptionsSpecifyingKind(BreakpointOptions::OptionKind kind) const;
222
223 bool ValidForThisThread(Thread &thread);
224
225 /// Invoke the callback action when the breakpoint is hit.
226 ///
227 /// Meant to be used by the BreakpointLocation class.
228 ///
229 /// \param[in] context
230 /// Described the breakpoint event.
231 ///
232 /// \return
233 /// \b true if the target should stop at this breakpoint and \b
234 /// false not.
235 bool InvokeCallback(StoppointCallbackContext *context);
236
237 /// Report whether the callback for this location is synchronous or not.
238 ///
239 /// \return
240 /// \b true if the callback is synchronous and \b false if not.
241 bool IsCallbackSynchronous();
242
243 /// Returns whether we should resolve Indirect functions in setting the
244 /// breakpoint site for this location.
245 ///
246 /// \return
247 /// \b true if the breakpoint SITE for this location should be set on the
248 /// resolved location for Indirect functions.
249 bool ShouldResolveIndirectFunctions() {
250 return m_should_resolve_indirect_functions;
251 }
252
253 /// Returns whether the address set in the breakpoint site for this location
254 /// was found by resolving an indirect symbol.
255 ///
256 /// \return
257 /// \b true or \b false as given in the description above.
258 bool IsIndirect() { return m_is_indirect; }
259
260 void SetIsIndirect(bool is_indirect) { m_is_indirect = is_indirect; }
261
262 /// Returns whether the address set in the breakpoint location was re-routed
263 /// to the target of a re-exported symbol.
264 ///
265 /// \return
266 /// \b true or \b false as given in the description above.
267 bool IsReExported() { return m_is_reexported; }
268
269 void SetIsReExported(bool is_reexported) { m_is_reexported = is_reexported; }
270
271 /// Returns whether the two breakpoint locations might represent "equivalent
272 /// locations". This is used when modules changed to determine if a Location
273 /// in the old module might be the "same as" the input location.
274 ///
275 /// \param[in] location
276 /// The location to compare against.
277 ///
278 /// \return
279 /// \b true or \b false as given in the description above.
280 bool EquivalentToLocation(BreakpointLocation &location);
281
282 /// Returns the breakpoint location ID.
283 lldb::break_id_t GetID() const { return m_loc_id; }
284
285protected:
286 friend class BreakpointSite;
287 friend class BreakpointLocationList;
288 friend class Process;
289 friend class StopInfoBreakpoint;
290
291 /// Set the breakpoint site for this location to \a bp_site_sp.
292 ///
293 /// \param[in] bp_site_sp
294 /// The breakpoint site we are setting for this location.
295 ///
296 /// \return
297 /// \b true if we were successful at setting the breakpoint site,
298 /// \b false otherwise.
299 bool SetBreakpointSite(lldb::BreakpointSiteSP &bp_site_sp);
300
301 void DecrementIgnoreCount();
302
303 /// BreakpointLocation::IgnoreCountShouldStop can only be called once
304 /// per stop. This method checks first against the loc and then the owner.
305 /// It also takes care of decrementing the ignore counters.
306 /// If it returns false we should continue, otherwise stop.
307 bool IgnoreCountShouldStop();
308
309private:
310 void SwapLocation(lldb::BreakpointLocationSP swap_from);
311
312 void BumpHitCount();
313
314 void UndoBumpHitCount();
315
316 /// Updates the thread ID internally.
317 ///
318 /// This method was created to handle actually mutating the thread ID
319 /// internally because SetThreadID broadcasts an event in addition to mutating
320 /// state. The constructor calls this instead of SetThreadID to avoid the
321 /// broadcast.
322 ///
323 /// \param[in] thread_id
324 /// The new thread ID.
325 void SetThreadIDInternal(lldb::tid_t thread_id);
326
327 // Constructors and Destructors
328 //
329 // Only the Breakpoint can make breakpoint locations, and it owns them.
330
331 /// Constructor.
332 ///
333 /// \param[in] owner
334 /// A back pointer to the breakpoint that owns this location.
335 ///
336 /// \param[in] addr
337 /// The Address defining this location.
338 ///
339 /// \param[in] tid
340 /// The thread for which this breakpoint location is valid, or
341 /// LLDB_INVALID_THREAD_ID if it is valid for all threads.
342 ///
343 /// \param[in] hardware
344 /// \b true if a hardware breakpoint is requested.
345
346 BreakpointLocation(lldb::break_id_t bid, Breakpoint &owner,
347 const Address &addr, lldb::tid_t tid, bool hardware,
348 bool check_for_resolver = true);
349
350 // Data members:
351 bool m_should_resolve_indirect_functions;
352 bool m_is_reexported;
353 bool m_is_indirect;
354 Address m_address; ///< The address defining this location.
355 Breakpoint &m_owner; ///< The breakpoint that produced this object.
356 std::unique_ptr<BreakpointOptions> m_options_up; ///< Breakpoint options
357 /// pointer, nullptr if we're
358 /// using our breakpoint's
359 /// options.
360 lldb::BreakpointSiteSP m_bp_site_sp; ///< Our breakpoint site (it may be
361 ///shared by more than one location.)
362 lldb::UserExpressionSP m_user_expression_sp; ///< The compiled expression to
363 ///use in testing our condition.
364 std::mutex m_condition_mutex; ///< Guards parsing and evaluation of the
365 ///condition, which could be evaluated by
366 /// multiple processes.
367 size_t m_condition_hash; ///< For testing whether the condition source code
368 ///changed.
369 lldb::break_id_t m_loc_id; ///< Breakpoint location ID.
370 StoppointHitCounter m_hit_counter; ///< Number of times this breakpoint
371 /// location has been hit.
372
373 void SetShouldResolveIndirectFunctions(bool do_resolve) {
374 m_should_resolve_indirect_functions = do_resolve;
375 }
376
377 void SendBreakpointLocationChangedEvent(lldb::BreakpointEventType eventKind);
378
379 BreakpointLocation(const BreakpointLocation &) = delete;
380 const BreakpointLocation &operator=(const BreakpointLocation &) = delete;
381};
382
383} // namespace lldb_private
384
385#endif // LLDB_BREAKPOINT_BREAKPOINTLOCATION_H
386

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