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. |
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 | |
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 | /// 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 | |