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 
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 
37 class BreakpointLocation
38     : public std::enable_shared_from_this<BreakpointLocation> {
39 public:
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.
GetHitCount()88   uint32_t GetHitCount() const { return m_hit_counter.GetValue(); }
89 
90   /// Resets the current Hit Count.
ResetHitCount()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.
ShouldResolveIndirectFunctions()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.
IsIndirect()258   bool IsIndirect() { return m_is_indirect; }
259 
SetIsIndirect(bool is_indirect)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.
IsReExported()267   bool IsReExported() { return m_is_reexported; }
268 
SetIsReExported(bool is_reexported)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.
GetID()283   lldb::break_id_t GetID() const { return m_loc_id; }
284 
285 protected:
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 
309 private:
310   void SwapLocation(lldb::BreakpointLocationSP swap_from);
311 
312   void BumpHitCount();
313 
314   void UndoBumpHitCount();
315 
316   // Constructors and Destructors
317   //
318   // Only the Breakpoint can make breakpoint locations, and it owns them.
319 
320   /// Constructor.
321   ///
322   /// \param[in] owner
323   ///     A back pointer to the breakpoint that owns this location.
324   ///
325   /// \param[in] addr
326   ///     The Address defining this location.
327   ///
328   /// \param[in] tid
329   ///     The thread for which this breakpoint location is valid, or
330   ///     LLDB_INVALID_THREAD_ID if it is valid for all threads.
331   ///
332   /// \param[in] hardware
333   ///     \b true if a hardware breakpoint is requested.
334 
335   BreakpointLocation(lldb::break_id_t bid, Breakpoint &owner,
336                      const Address &addr, lldb::tid_t tid, bool hardware,
337                      bool check_for_resolver = true);
338 
339   // Data members:
340   bool m_being_created;
341   bool m_should_resolve_indirect_functions;
342   bool m_is_reexported;
343   bool m_is_indirect;
344   Address m_address;   ///< The address defining this location.
345   Breakpoint &m_owner; ///< The breakpoint that produced this object.
346   std::unique_ptr<BreakpointOptions> m_options_up; ///< Breakpoint options
347                                                    /// pointer, nullptr if we're
348                                                    /// using our breakpoint's
349                                                    /// options.
350   lldb::BreakpointSiteSP m_bp_site_sp; ///< Our breakpoint site (it may be
351                                        ///shared by more than one location.)
352   lldb::UserExpressionSP m_user_expression_sp; ///< The compiled expression to
353                                                ///use in testing our condition.
354   std::mutex m_condition_mutex; ///< Guards parsing and evaluation of the
355                                 ///condition, which could be evaluated by
356                                 /// multiple processes.
357   size_t m_condition_hash; ///< For testing whether the condition source code
358                            ///changed.
359   lldb::break_id_t m_loc_id; ///< Breakpoint location ID.
360   StoppointHitCounter m_hit_counter; ///< Number of times this breakpoint
361                                      /// location has been hit.
362 
SetShouldResolveIndirectFunctions(bool do_resolve)363   void SetShouldResolveIndirectFunctions(bool do_resolve) {
364     m_should_resolve_indirect_functions = do_resolve;
365   }
366 
367   void SendBreakpointLocationChangedEvent(lldb::BreakpointEventType eventKind);
368 
369   BreakpointLocation(const BreakpointLocation &) = delete;
370   const BreakpointLocation &operator=(const BreakpointLocation &) = delete;
371 };
372 
373 } // namespace lldb_private
374 
375 #endif // LLDB_BREAKPOINT_BREAKPOINTLOCATION_H
376