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 /// Removes all invalid breakpoint locations.
318 /// Removes all breakpoint locations with architectures that aren't
319 /// compatible with \a arch. Also remove any breakpoint locations
320 /// with whose locations have address where the section has been
321 /// deleted (module and object files no longer exist).
323 /// This is typically used after the process calls exec, or anytime
324 /// the architecture of the target changes.
327 /// If valid, check the module in each breakpoint to make sure
328 /// they are compatible, otherwise, ignore architecture.
329 //------------------------------------------------------------------
331 RemoveInvalidLocations (const ArchSpec &arch);
333 //------------------------------------------------------------------
334 // The next section deals with various breakpoint options.
335 //------------------------------------------------------------------
337 //------------------------------------------------------------------
338 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
339 //------------------------------------------------------------------
341 SetEnabled (bool enable);
343 //------------------------------------------------------------------
344 /// Check the Enable/Disable state.
346 /// \b true if the breakpoint is enabled, \b false if disabled.
347 //------------------------------------------------------------------
351 //------------------------------------------------------------------
352 /// Set the breakpoint to ignore the next \a count breakpoint hits.
354 /// The number of breakpoint hits to ignore.
355 //------------------------------------------------------------------
357 SetIgnoreCount (uint32_t count);
359 //------------------------------------------------------------------
360 /// Return the current ignore count/
362 /// The number of breakpoint hits to be ignored.
363 //------------------------------------------------------------------
365 GetIgnoreCount () const;
367 //------------------------------------------------------------------
368 /// Return the current hit count for all locations.
370 /// The current hit count for all locations.
371 //------------------------------------------------------------------
373 GetHitCount () const;
376 //------------------------------------------------------------------
377 /// If \a one_shot is \b true, breakpoint will be deleted on first hit.
378 //------------------------------------------------------------------
380 SetOneShot (bool one_shot);
382 //------------------------------------------------------------------
383 /// Check the OneShot state.
385 /// \b true if the breakpoint is one shot, \b false otherwise.
386 //------------------------------------------------------------------
390 //------------------------------------------------------------------
391 /// Set the valid thread to be checked when the breakpoint is hit.
392 /// @param[in] thread_id
393 /// If this thread hits the breakpoint, we stop, otherwise not.
394 //------------------------------------------------------------------
396 SetThreadID (lldb::tid_t thread_id);
398 //------------------------------------------------------------------
399 /// Return the current stop thread value.
401 /// The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads.
402 //------------------------------------------------------------------
404 GetThreadID () const;
407 SetThreadIndex (uint32_t index);
410 GetThreadIndex() const;
413 SetThreadName (const char *thread_name);
416 GetThreadName () const;
419 SetQueueName (const char *queue_name);
422 GetQueueName () const;
424 //------------------------------------------------------------------
425 /// Set the callback action invoked when the breakpoint is hit.
427 /// @param[in] callback
428 /// The method that will get called when the breakpoint is hit.
430 /// A void * pointer that will get passed back to the callback function.
431 /// @param[in] is_synchronous
432 /// If \b true the callback will be run on the private event thread
433 /// before the stop event gets reported. If false, the callback will get
434 /// handled on the public event thead after the stop has been posted.
437 /// \b true if the process should stop when you hit the breakpoint.
438 /// \b false if it should continue.
439 //------------------------------------------------------------------
441 SetCallback (BreakpointHitCallback callback,
443 bool is_synchronous = false);
446 SetCallback (BreakpointHitCallback callback,
447 const lldb::BatonSP &callback_baton_sp,
448 bool is_synchronous = false);
453 //------------------------------------------------------------------
454 /// Set the breakpoint's condition.
456 /// @param[in] condition
457 /// The condition expression to evaluate when the breakpoint is hit.
458 /// Pass in NULL to clear the condition.
459 //------------------------------------------------------------------
460 void SetCondition (const char *condition);
462 //------------------------------------------------------------------
463 /// Return a pointer to the text of the condition expression.
466 /// A pointer to the condition expression text, or NULL if no
467 // condition has been set.
468 //------------------------------------------------------------------
469 const char *GetConditionText () const;
471 //------------------------------------------------------------------
472 // The next section are various utility functions.
473 //------------------------------------------------------------------
475 //------------------------------------------------------------------
476 /// Return the number of breakpoint locations that have resolved to
477 /// actual breakpoint sites.
480 /// The number locations resolved breakpoint sites.
481 //------------------------------------------------------------------
483 GetNumResolvedLocations() const;
485 //------------------------------------------------------------------
486 /// Return the number of breakpoint locations.
489 /// The number breakpoint locations.
490 //------------------------------------------------------------------
492 GetNumLocations() const;
494 //------------------------------------------------------------------
495 /// Put a description of this breakpoint into the stream \a s.
498 /// Stream into which to dump the description.
501 /// The description level that indicates the detail level to
504 /// @see lldb::DescriptionLevel
505 //------------------------------------------------------------------
507 GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false);
509 //------------------------------------------------------------------
510 /// Set the "kind" description for a breakpoint. If the breakpoint is hit
511 /// the stop info will show this "kind" description instead of the breakpoint
512 /// number. Mostly useful for internal breakpoints, where the breakpoint number
513 /// doesn't have meaning to the user.
516 /// New "kind" description.
517 //------------------------------------------------------------------
519 SetBreakpointKind (const char *kind)
521 m_kind_description.assign (kind);
524 //------------------------------------------------------------------
525 /// Return the "kind" description for a breakpoint.
528 /// The breakpoint kind, or NULL if none is set.
529 //------------------------------------------------------------------
530 const char *GetBreakpointKind () const
532 return m_kind_description.c_str();
535 //------------------------------------------------------------------
536 /// Accessor for the breakpoint Target.
538 /// This breakpoint's Target.
539 //------------------------------------------------------------------
547 GetResolverDescription (Stream *s);
549 //------------------------------------------------------------------
550 /// Find breakpoint locations which match the (filename, line_number) description.
551 /// The breakpoint location collection is to be filled with the matching locations.
552 /// It should be initialized with 0 size by the API client.
555 /// True if there is a match
557 /// The locations which match the filename and line_number in loc_coll. If its
558 /// size is 0 and true is returned, it means the breakpoint fully matches the
560 //------------------------------------------------------------------
561 bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number,
562 BreakpointLocationCollection &loc_coll);
565 GetFilterDescription (Stream *s);
567 //------------------------------------------------------------------
568 /// Returns the BreakpointOptions structure set at the breakpoint level.
570 /// Meant to be used by the BreakpointLocation class.
573 /// A pointer to this breakpoint's BreakpointOptions.
574 //------------------------------------------------------------------
579 //------------------------------------------------------------------
580 /// Invoke the callback action when the breakpoint is hit.
582 /// Meant to be used by the BreakpointLocation class.
584 /// @param[in] context
585 /// Described the breakpoint event.
587 /// @param[in] bp_loc_id
588 /// Which breakpoint location hit this breakpoint.
591 /// \b true if the target should stop at this breakpoint and \b false not.
592 //------------------------------------------------------------------
594 InvokeCallback (StoppointCallbackContext *context,
595 lldb::break_id_t bp_loc_id);
605 //------------------------------------------------------------------
607 //------------------------------------------------------------------
610 //------------------------------------------------------------------
611 /// Constructors and Destructors
612 /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans.
613 /// The constructor takes a filter and a resolver. Up in Target there are convenience
614 /// variants that make breakpoints for some common cases.
616 /// @param[in] target
617 /// The target in which the breakpoint will be set.
619 /// @param[in] filter_sp
620 /// Shared pointer to the search filter that restricts the search domain of the breakpoint.
622 /// @param[in] resolver_sp
623 /// Shared pointer to the resolver object that will determine breakpoint matches.
626 /// If true, request a hardware breakpoint to be used to implement the breakpoint locations.
628 /// @param resolve_indirect_symbols
629 /// If true, and the address of a given breakpoint location in this breakpoint is set on an
630 /// indirect symbol (i.e. Symbol::IsIndirect returns true) then the actual breakpoint site will
631 /// be set on the target of the indirect symbol.
632 //------------------------------------------------------------------
633 // This is the generic constructor
634 Breakpoint(Target &target,
635 lldb::SearchFilterSP &filter_sp,
636 lldb::BreakpointResolverSP &resolver_sp,
638 bool resolve_indirect_symbols = true);
640 friend class BreakpointLocation; // To call the following two when determining whether to stop.
643 DecrementIgnoreCount();
645 // BreakpointLocation::IgnoreCountShouldStop & Breakpoint::IgnoreCountShouldStop can only be called once per stop,
646 // and BreakpointLocation::IgnoreCountShouldStop should be tested first, and if it returns false we should
647 // continue, otherwise we should test Breakpoint::IgnoreCountShouldStop.
650 IgnoreCountShouldStop ();
653 //------------------------------------------------------------------
654 // For Breakpoint only
655 //------------------------------------------------------------------
656 bool m_being_created;
657 bool m_hardware; // If this breakpoint is required to use a hardware breakpoint
658 Target &m_target; // The target that holds this breakpoint.
659 lldb::SearchFilterSP m_filter_sp; // The filter that constrains the breakpoint's domain.
660 lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint.
661 BreakpointOptions m_options; // Settable breakpoint options
662 BreakpointLocationList m_locations; // The list of locations currently found for this breakpoint.
663 std::string m_kind_description;
664 bool m_resolve_indirect_symbols;
667 SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind);
670 SendBreakpointChangedEvent (BreakpointEventData *data);
672 DISALLOW_COPY_AND_ASSIGN(Breakpoint);
675 } // namespace lldb_private
677 #endif // liblldb_Breakpoint_h_