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