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