1 //===-- Breakpoint.h --------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Breakpoint_h_
11 #define liblldb_Breakpoint_h_
15 // Other libraries and framework includes
17 #include "lldb/Breakpoint/BreakpointLocationList.h"
18 #include "lldb/Breakpoint/BreakpointOptions.h"
19 #include "lldb/Breakpoint/BreakpointLocationCollection.h"
20 #include "lldb/Breakpoint/Stoppoint.h"
21 #include "lldb/Core/SearchFilter.h"
22 #include "lldb/Core/Event.h"
23 #include "lldb/Core/StringList.h"
25 namespace lldb_private {
27 //----------------------------------------------------------------------
28 /// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h"
29 /// @brief Class that manages logical breakpoint setting.
30 //----------------------------------------------------------------------
32 //----------------------------------------------------------------------
34 /// A breakpoint has four main parts, a filter, a resolver, the list of breakpoint
35 /// locations that have been determined for the filter/resolver pair, and finally
36 /// a set of options for the breakpoint.
39 /// This is an object derived from SearchFilter. It manages the search
40 /// for breakpoint location matches through the symbols in the module list of the target
41 /// that owns it. It also filters out locations based on whatever logic it wants.
44 /// This is an object derived from BreakpointResolver. It provides a
45 /// callback to the filter that will find breakpoint locations. How it does this is
46 /// determined by what kind of resolver it is.
48 /// The Breakpoint class also provides constructors for the common breakpoint cases
49 /// which make the appropriate filter and resolver for you.
52 /// This stores the breakpoint locations that have been determined
53 /// to date. For a given breakpoint, there will be only one location with a given
54 /// address. Adding a location at an already taken address will just return the location
55 /// already at that address. Locations can be looked up by ID, or by address.
59 /// \b Enabled/Disabled
63 /// Note, these options can be set on the breakpoint, and they can also be set on the
64 /// individual locations. The options set on the breakpoint take precedence over the
65 /// options set on the individual location.
66 /// So for instance disabling the breakpoint will cause NONE of the locations to get hit.
67 /// But if the breakpoint is enabled, then the location's enabled state will be checked
68 /// to determine whether to insert that breakpoint location.
69 /// Similarly, if the breakpoint condition says "stop", we won't check the location's condition.
70 /// But if the breakpoint condition says "continue", then we will check the location for whether
71 /// to actually stop or not.
72 /// One subtle point worth observing here is that you don't actually stop at a Breakpoint, you
73 /// always stop at one of its locations. So the "should stop" tests are done by the location,
74 /// not by the breakpoint.
75 //----------------------------------------------------------------------
77 public std::enable_shared_from_this<Breakpoint>,
82 static const ConstString &
83 GetEventIdentifier ();
86 //------------------------------------------------------------------
87 /// An enum specifying the match style for breakpoint settings. At
88 /// present only used for function name style breakpoints.
89 //------------------------------------------------------------------
97 class BreakpointEventData :
102 static const ConstString &
105 virtual const ConstString &
108 BreakpointEventData (lldb::BreakpointEventType sub_type,
109 const lldb::BreakpointSP &new_breakpoint_sp);
112 ~BreakpointEventData();
114 lldb::BreakpointEventType
115 GetBreakpointEventType () const;
120 BreakpointLocationCollection &
121 GetBreakpointLocationCollection()
128 Dump (Stream *s) const;
130 static lldb::BreakpointEventType
131 GetBreakpointEventTypeFromEvent (const lldb::EventSP &event_sp);
133 static lldb::BreakpointSP
134 GetBreakpointFromEvent (const lldb::EventSP &event_sp);
136 static lldb::BreakpointLocationSP
137 GetBreakpointLocationAtIndexFromEvent (const lldb::EventSP &event_sp, uint32_t loc_idx);
140 GetNumBreakpointLocationsFromEvent (const lldb::EventSP &event_sp);
142 static const BreakpointEventData *
143 GetEventDataFromEvent (const Event *event_sp);
147 lldb::BreakpointEventType m_breakpoint_event;
148 lldb::BreakpointSP m_new_breakpoint_sp;
149 BreakpointLocationCollection m_locations;
151 DISALLOW_COPY_AND_ASSIGN (BreakpointEventData);
155 //------------------------------------------------------------------
158 /// The destructor is not virtual since there should be no reason to subclass
159 /// breakpoints. The varieties of breakpoints are specified instead by
160 /// providing different resolvers & filters.
161 //------------------------------------------------------------------
164 //------------------------------------------------------------------
166 //------------------------------------------------------------------
168 //------------------------------------------------------------------
169 /// Tell whether this breakpoint is an "internal" breakpoint.
171 /// Returns \b true if this is an internal breakpoint, \b false otherwise.
172 //------------------------------------------------------------------
176 //------------------------------------------------------------------
177 /// Standard "Dump" method. At present it does nothing.
178 //------------------------------------------------------------------
182 //------------------------------------------------------------------
183 // The next set of methods provide ways to tell the breakpoint to update
184 // it's location list - usually done when modules appear or disappear.
185 //------------------------------------------------------------------
188 //------------------------------------------------------------------
189 /// Tell this breakpoint to clear all its breakpoint sites. Done
190 /// when the process holding the breakpoint sites is destroyed.
191 //------------------------------------------------------------------
193 ClearAllBreakpointSites ();
195 //------------------------------------------------------------------
196 /// Tell this breakpoint to scan it's target's module list and resolve any
197 /// new locations that match the breakpoint's specifications.
198 //------------------------------------------------------------------
200 ResolveBreakpoint ();
202 //------------------------------------------------------------------
203 /// Tell this breakpoint to scan a given module list and resolve any
204 /// new locations that match the breakpoint's specifications.
206 /// @param[in] changed_modules
207 /// The list of modules to look in for new locations.
208 //------------------------------------------------------------------
210 ResolveBreakpointInModules (ModuleList &changed_modules);
213 //------------------------------------------------------------------
214 /// Like ResolveBreakpointInModules, but allows for "unload" events, in
215 /// which case we will remove any locations that are in modules that got
218 /// @param[in] changedModules
219 /// The list of modules to look in for new locations.
220 /// @param[in] load_event
221 /// If \b true then the modules were loaded, if \b false, unloaded.
222 /// @param[in] delete_locations
223 /// If \b true then the modules were unloaded delete any locations in the changed modules.
224 //------------------------------------------------------------------
226 ModulesChanged (ModuleList &changed_modules,
228 bool delete_locations = false);
231 //------------------------------------------------------------------
232 /// Tells the breakpoint the old module \a old_module_sp has been
233 /// replaced by new_module_sp (usually because the underlying file has been
234 /// rebuilt, and the old version is gone.)
236 /// @param[in] old_module_sp
237 /// The old module that is going away.
238 /// @param[in] new_module_sp
239 /// The new module that is replacing it.
240 //------------------------------------------------------------------
242 ModuleReplaced (lldb::ModuleSP old_module_sp, lldb::ModuleSP new_module_sp);
244 //------------------------------------------------------------------
245 // The next set of methods provide access to the breakpoint locations
246 // for this breakpoint.
247 //------------------------------------------------------------------
249 //------------------------------------------------------------------
250 /// Add a location to the breakpoint's location list. This is only meant
251 /// to be called by the breakpoint's resolver. FIXME: how do I ensure that?
254 /// The Address specifying the new location.
255 /// @param[out] new_location
256 /// Set to \b true if a new location was created, to \b false if there
257 /// already was a location at this Address.
259 /// Returns a pointer to the new location.
260 //------------------------------------------------------------------
261 lldb::BreakpointLocationSP
262 AddLocation (const Address &addr,
263 bool *new_location = NULL);
265 //------------------------------------------------------------------
266 /// Find a breakpoint location by Address.
269 /// The Address specifying the location.
271 /// Returns a shared pointer to the location at \a addr. The pointer
272 /// in the shared pointer will be NULL if there is no location at that address.
273 //------------------------------------------------------------------
274 lldb::BreakpointLocationSP
275 FindLocationByAddress (const Address &addr);
277 //------------------------------------------------------------------
278 /// Find a breakpoint location ID by Address.
281 /// The Address specifying the location.
283 /// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if
284 /// there is no breakpoint location at that address.
285 //------------------------------------------------------------------
287 FindLocationIDByAddress (const Address &addr);
289 //------------------------------------------------------------------
290 /// Find a breakpoint location for a given breakpoint location ID.
292 /// @param[in] bp_loc_id
293 /// The ID specifying the location.
295 /// Returns a shared pointer to the location with ID \a bp_loc_id. The pointer
296 /// in the shared pointer will be NULL if there is no location with that ID.
297 //------------------------------------------------------------------
298 lldb::BreakpointLocationSP
299 FindLocationByID (lldb::break_id_t bp_loc_id);
301 //------------------------------------------------------------------
302 /// Get breakpoint locations by index.
305 /// The location index.
308 /// Returns a shared pointer to the location with index \a
309 /// index. The shared pointer might contain NULL if \a index is
310 /// greater than then number of actual locations.
311 //------------------------------------------------------------------
312 lldb::BreakpointLocationSP
313 GetLocationAtIndex (size_t index);
315 //------------------------------------------------------------------
316 // The next section deals with various breakpoint options.
317 //------------------------------------------------------------------
319 //------------------------------------------------------------------
320 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
321 //------------------------------------------------------------------
323 SetEnabled (bool enable);
325 //------------------------------------------------------------------
326 /// Check the Enable/Disable state.
328 /// \b true if the breakpoint is enabled, \b false if disabled.
329 //------------------------------------------------------------------
333 //------------------------------------------------------------------
334 /// Set the breakpoint to ignore the next \a count breakpoint hits.
336 /// The number of breakpoint hits to ignore.
337 //------------------------------------------------------------------
339 SetIgnoreCount (uint32_t count);
341 //------------------------------------------------------------------
342 /// Return the current ignore count/
344 /// The number of breakpoint hits to be ignored.
345 //------------------------------------------------------------------
347 GetIgnoreCount () const;
349 //------------------------------------------------------------------
350 /// Return the current hit count for all locations.
352 /// The current hit count for all locations.
353 //------------------------------------------------------------------
355 GetHitCount () const;
358 //------------------------------------------------------------------
359 /// If \a one_shot is \b true, breakpoint will be deleted on first hit.
360 //------------------------------------------------------------------
362 SetOneShot (bool one_shot);
364 //------------------------------------------------------------------
365 /// Check the OneShot state.
367 /// \b true if the breakpoint is one shot, \b false otherwise.
368 //------------------------------------------------------------------
372 //------------------------------------------------------------------
373 /// Set the valid thread to be checked when the breakpoint is hit.
374 /// @param[in] thread_id
375 /// If this thread hits the breakpoint, we stop, otherwise not.
376 //------------------------------------------------------------------
378 SetThreadID (lldb::tid_t thread_id);
380 //------------------------------------------------------------------
381 /// Return the current stop thread value.
383 /// The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads.
384 //------------------------------------------------------------------
386 GetThreadID () const;
389 SetThreadIndex (uint32_t index);
392 GetThreadIndex() const;
395 SetThreadName (const char *thread_name);
398 GetThreadName () const;
401 SetQueueName (const char *queue_name);
404 GetQueueName () const;
406 //------------------------------------------------------------------
407 /// Set the callback action invoked when the breakpoint is hit.
409 /// @param[in] callback
410 /// The method that will get called when the breakpoint is hit.
412 /// A void * pointer that will get passed back to the callback function.
413 /// @param[in] is_synchronous
414 /// If \b true the callback will be run on the private event thread
415 /// before the stop event gets reported. If false, the callback will get
416 /// handled on the public event thead after the stop has been posted.
419 /// \b true if the process should stop when you hit the breakpoint.
420 /// \b false if it should continue.
421 //------------------------------------------------------------------
423 SetCallback (BreakpointHitCallback callback,
425 bool is_synchronous = false);
428 SetCallback (BreakpointHitCallback callback,
429 const lldb::BatonSP &callback_baton_sp,
430 bool is_synchronous = false);
435 //------------------------------------------------------------------
436 /// Set the breakpoint's condition.
438 /// @param[in] condition
439 /// The condition expression to evaluate when the breakpoint is hit.
440 /// Pass in NULL to clear the condition.
441 //------------------------------------------------------------------
442 void SetCondition (const char *condition);
444 //------------------------------------------------------------------
445 /// Return a pointer to the text of the condition expression.
448 /// A pointer to the condition expression text, or NULL if no
449 // condition has been set.
450 //------------------------------------------------------------------
451 const char *GetConditionText () const;
453 //------------------------------------------------------------------
454 // The next section are various utility functions.
455 //------------------------------------------------------------------
457 //------------------------------------------------------------------
458 /// Return the number of breakpoint locations that have resolved to
459 /// actual breakpoint sites.
462 /// The number locations resolved breakpoint sites.
463 //------------------------------------------------------------------
465 GetNumResolvedLocations() const;
467 //------------------------------------------------------------------
468 /// Return the number of breakpoint locations.
471 /// The number breakpoint locations.
472 //------------------------------------------------------------------
474 GetNumLocations() const;
476 //------------------------------------------------------------------
477 /// Put a description of this breakpoint into the stream \a s.
480 /// Stream into which to dump the description.
483 /// The description level that indicates the detail level to
486 /// @see lldb::DescriptionLevel
487 //------------------------------------------------------------------
489 GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false);
491 //------------------------------------------------------------------
492 /// Set the "kind" description for a breakpoint. If the breakpoint is hit
493 /// the stop info will show this "kind" description instead of the breakpoint
494 /// number. Mostly useful for internal breakpoints, where the breakpoint number
495 /// doesn't have meaning to the user.
498 /// New "kind" description.
499 //------------------------------------------------------------------
501 SetBreakpointKind (const char *kind)
503 m_kind_description.assign (kind);
506 //------------------------------------------------------------------
507 /// Return the "kind" description for a breakpoint.
510 /// The breakpoint kind, or NULL if none is set.
511 //------------------------------------------------------------------
512 const char *GetBreakpointKind () const
514 return m_kind_description.c_str();
517 //------------------------------------------------------------------
518 /// Accessor for the breakpoint Target.
520 /// This breakpoint's Target.
521 //------------------------------------------------------------------
529 GetResolverDescription (Stream *s);
531 //------------------------------------------------------------------
532 /// Find breakpoint locations which match the (filename, line_number) description.
533 /// The breakpoint location collection is to be filled with the matching locations.
534 /// It should be initialized with 0 size by the API client.
537 /// True if there is a match
539 /// The locations which match the filename and line_number in loc_coll. If its
540 /// size is 0 and true is returned, it means the breakpoint fully matches the
542 //------------------------------------------------------------------
543 bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number,
544 BreakpointLocationCollection &loc_coll);
547 GetFilterDescription (Stream *s);
549 //------------------------------------------------------------------
550 /// Returns the BreakpointOptions structure set at the breakpoint level.
552 /// Meant to be used by the BreakpointLocation class.
555 /// A pointer to this breakpoint's BreakpointOptions.
556 //------------------------------------------------------------------
561 //------------------------------------------------------------------
562 /// Invoke the callback action when the breakpoint is hit.
564 /// Meant to be used by the BreakpointLocation class.
566 /// @param[in] context
567 /// Described the breakpoint event.
569 /// @param[in] bp_loc_id
570 /// Which breakpoint location hit this breakpoint.
573 /// \b true if the target should stop at this breakpoint and \b false not.
574 //------------------------------------------------------------------
576 InvokeCallback (StoppointCallbackContext *context,
577 lldb::break_id_t bp_loc_id);
581 //------------------------------------------------------------------
583 //------------------------------------------------------------------
586 //------------------------------------------------------------------
587 /// Constructors and Destructors
588 /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans.
589 /// The constructor takes a filter and a resolver. Up in Target there are convenience
590 /// variants that make breakpoints for some common cases.
591 //------------------------------------------------------------------
592 // This is the generic constructor
593 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp, lldb::BreakpointResolverSP &resolver_sp);
595 friend class BreakpointLocation; // To call the following two when determining whether to stop.
598 DecrementIgnoreCount();
600 // BreakpointLocation::IgnoreCountShouldStop & Breakpoint::IgnoreCountShouldStop can only be called once per stop,
601 // and BreakpointLocation::IgnoreCountShouldStop should be tested first, and if it returns false we should
602 // continue, otherwise we should test Breakpoint::IgnoreCountShouldStop.
605 IgnoreCountShouldStop ();
608 //------------------------------------------------------------------
609 // For Breakpoint only
610 //------------------------------------------------------------------
611 bool m_being_created;
612 Target &m_target; // The target that holds this breakpoint.
613 lldb::SearchFilterSP m_filter_sp; // The filter that constrains the breakpoint's domain.
614 lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint.
615 BreakpointOptions m_options; // Settable breakpoint options
616 BreakpointLocationList m_locations; // The list of locations currently found for this breakpoint.
617 std::string m_kind_description;
620 SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind);
623 SendBreakpointChangedEvent (BreakpointEventData *data);
625 DISALLOW_COPY_AND_ASSIGN(Breakpoint);
628 } // namespace lldb_private
630 #endif // liblldb_Breakpoint_h_