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_
17 #include <unordered_set>
20 // Other libraries and framework includes
22 #include "lldb/Breakpoint/BreakpointID.h"
23 #include "lldb/Breakpoint/BreakpointLocationCollection.h"
24 #include "lldb/Breakpoint/BreakpointLocationList.h"
25 #include "lldb/Breakpoint/BreakpointOptions.h"
26 #include "lldb/Breakpoint/Stoppoint.h"
27 #include "lldb/Core/Event.h"
28 #include "lldb/Core/SearchFilter.h"
29 #include "lldb/Core/StringList.h"
30 #include "lldb/Core/StructuredData.h"
32 namespace lldb_private {
34 //----------------------------------------------------------------------
35 /// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h"
36 /// @brief Class that manages logical breakpoint setting.
37 //----------------------------------------------------------------------
39 //----------------------------------------------------------------------
41 /// A breakpoint has four main parts, a filter, a resolver, the list of
43 /// locations that have been determined for the filter/resolver pair, and
45 /// a set of options for the breakpoint.
48 /// This is an object derived from SearchFilter. It manages the search
49 /// for breakpoint location matches through the symbols in the module list of
51 /// that owns it. It also filters out locations based on whatever logic it
55 /// This is an object derived from BreakpointResolver. It provides a
56 /// callback to the filter that will find breakpoint locations. How it does
58 /// determined by what kind of resolver it is.
60 /// The Breakpoint class also provides constructors for the common breakpoint
62 /// which make the appropriate filter and resolver for you.
65 /// This stores the breakpoint locations that have been determined
66 /// to date. For a given breakpoint, there will be only one location with a
68 /// address. Adding a location at an already taken address will just return the
70 /// already at that address. Locations can be looked up by ID, or by address.
74 /// \b Enabled/Disabled
78 /// Note, these options can be set on the breakpoint, and they can also be set
80 /// individual locations. The options set on the breakpoint take precedence
82 /// options set on the individual location.
83 /// So for instance disabling the breakpoint will cause NONE of the locations to
85 /// But if the breakpoint is enabled, then the location's enabled state will be
87 /// to determine whether to insert that breakpoint location.
88 /// Similarly, if the breakpoint condition says "stop", we won't check the
89 /// location's condition.
90 /// But if the breakpoint condition says "continue", then we will check the
91 /// location for whether
92 /// to actually stop or not.
93 /// One subtle point worth observing here is that you don't actually stop at a
95 /// always stop at one of its locations. So the "should stop" tests are done by
97 /// not by the breakpoint.
98 //----------------------------------------------------------------------
99 class Breakpoint : public std::enable_shared_from_this<Breakpoint>,
102 static const ConstString &GetEventIdentifier();
104 //------------------------------------------------------------------
105 /// An enum specifying the match style for breakpoint settings. At
106 /// present only used for function name style breakpoints.
107 //------------------------------------------------------------------
108 typedef enum { Exact, Regexp, Glob } MatchType;
111 enum class OptionNames : uint32_t { Names = 0, Hardware, LastOptionName };
114 *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)];
116 static const char *GetKey(OptionNames enum_value) {
117 return g_option_names[static_cast<uint32_t>(enum_value)];
121 class BreakpointEventData : public EventData {
123 BreakpointEventData(lldb::BreakpointEventType sub_type,
124 const lldb::BreakpointSP &new_breakpoint_sp);
126 ~BreakpointEventData() override;
128 static const ConstString &GetFlavorString();
130 const ConstString &GetFlavor() const override;
132 lldb::BreakpointEventType GetBreakpointEventType() const;
134 lldb::BreakpointSP &GetBreakpoint();
136 BreakpointLocationCollection &GetBreakpointLocationCollection() {
140 void Dump(Stream *s) const override;
142 static lldb::BreakpointEventType
143 GetBreakpointEventTypeFromEvent(const lldb::EventSP &event_sp);
145 static lldb::BreakpointSP
146 GetBreakpointFromEvent(const lldb::EventSP &event_sp);
148 static lldb::BreakpointLocationSP
149 GetBreakpointLocationAtIndexFromEvent(const lldb::EventSP &event_sp,
153 GetNumBreakpointLocationsFromEvent(const lldb::EventSP &event_sp);
155 static const BreakpointEventData *
156 GetEventDataFromEvent(const Event *event_sp);
159 lldb::BreakpointEventType m_breakpoint_event;
160 lldb::BreakpointSP m_new_breakpoint_sp;
161 BreakpointLocationCollection m_locations;
163 DISALLOW_COPY_AND_ASSIGN(BreakpointEventData);
166 class BreakpointPrecondition {
168 virtual ~BreakpointPrecondition() = default;
170 virtual bool EvaluatePrecondition(StoppointCallbackContext &context);
172 virtual Error ConfigurePrecondition(Args &options);
174 virtual void GetDescription(Stream &stream, lldb::DescriptionLevel level);
177 typedef std::shared_ptr<BreakpointPrecondition> BreakpointPreconditionSP;
179 // Saving & restoring breakpoints:
180 static lldb::BreakpointSP CreateFromStructuredData(
181 Target &target, StructuredData::ObjectSP &data_object_sp, Error &error);
184 SerializedBreakpointMatchesNames(StructuredData::ObjectSP &bkpt_object_sp,
185 std::vector<std::string> &names);
187 virtual StructuredData::ObjectSP SerializeToStructuredData();
189 static const char *GetSerializationKey() { return "Breakpoint"; }
190 //------------------------------------------------------------------
193 /// The destructor is not virtual since there should be no reason to subclass
194 /// breakpoints. The varieties of breakpoints are specified instead by
195 /// providing different resolvers & filters.
196 //------------------------------------------------------------------
197 ~Breakpoint() override;
199 //------------------------------------------------------------------
201 //------------------------------------------------------------------
203 //------------------------------------------------------------------
204 /// Tell whether this breakpoint is an "internal" breakpoint.
206 /// Returns \b true if this is an internal breakpoint, \b false otherwise.
207 //------------------------------------------------------------------
208 bool IsInternal() const;
210 //------------------------------------------------------------------
211 /// Standard "Dump" method. At present it does nothing.
212 //------------------------------------------------------------------
213 void Dump(Stream *s) override;
215 //------------------------------------------------------------------
216 // The next set of methods provide ways to tell the breakpoint to update
217 // it's location list - usually done when modules appear or disappear.
218 //------------------------------------------------------------------
220 //------------------------------------------------------------------
221 /// Tell this breakpoint to clear all its breakpoint sites. Done
222 /// when the process holding the breakpoint sites is destroyed.
223 //------------------------------------------------------------------
224 void ClearAllBreakpointSites();
226 //------------------------------------------------------------------
227 /// Tell this breakpoint to scan it's target's module list and resolve any
228 /// new locations that match the breakpoint's specifications.
229 //------------------------------------------------------------------
230 void ResolveBreakpoint();
232 //------------------------------------------------------------------
233 /// Tell this breakpoint to scan a given module list and resolve any
234 /// new locations that match the breakpoint's specifications.
236 /// @param[in] module_list
237 /// The list of modules to look in for new locations.
239 /// @param[in] send_event
240 /// If \b true, send a breakpoint location added event for non-internal
242 //------------------------------------------------------------------
243 void ResolveBreakpointInModules(ModuleList &module_list,
244 bool send_event = true);
246 //------------------------------------------------------------------
247 /// Tell this breakpoint to scan a given module list and resolve any
248 /// new locations that match the breakpoint's specifications.
250 /// @param[in] changed_modules
251 /// The list of modules to look in for new locations.
253 /// @param[in] new_locations
254 /// Fills new_locations with the new locations that were made.
255 //------------------------------------------------------------------
256 void ResolveBreakpointInModules(ModuleList &module_list,
257 BreakpointLocationCollection &new_locations);
259 //------------------------------------------------------------------
260 /// Like ResolveBreakpointInModules, but allows for "unload" events, in
261 /// which case we will remove any locations that are in modules that got
264 /// @param[in] changedModules
265 /// The list of modules to look in for new locations.
266 /// @param[in] load_event
267 /// If \b true then the modules were loaded, if \b false, unloaded.
268 /// @param[in] delete_locations
269 /// If \b true then the modules were unloaded delete any locations in the
271 //------------------------------------------------------------------
272 void ModulesChanged(ModuleList &changed_modules, bool load_event,
273 bool delete_locations = false);
275 //------------------------------------------------------------------
276 /// Tells the breakpoint the old module \a old_module_sp has been
277 /// replaced by new_module_sp (usually because the underlying file has been
278 /// rebuilt, and the old version is gone.)
280 /// @param[in] old_module_sp
281 /// The old module that is going away.
282 /// @param[in] new_module_sp
283 /// The new module that is replacing it.
284 //------------------------------------------------------------------
285 void ModuleReplaced(lldb::ModuleSP old_module_sp,
286 lldb::ModuleSP new_module_sp);
288 //------------------------------------------------------------------
289 // The next set of methods provide access to the breakpoint locations
290 // for this breakpoint.
291 //------------------------------------------------------------------
293 //------------------------------------------------------------------
294 /// Add a location to the breakpoint's location list. This is only meant
295 /// to be called by the breakpoint's resolver. FIXME: how do I ensure that?
298 /// The Address specifying the new location.
299 /// @param[out] new_location
300 /// Set to \b true if a new location was created, to \b false if there
301 /// already was a location at this Address.
303 /// Returns a pointer to the new location.
304 //------------------------------------------------------------------
305 lldb::BreakpointLocationSP AddLocation(const Address &addr,
306 bool *new_location = nullptr);
308 //------------------------------------------------------------------
309 /// Find a breakpoint location by Address.
312 /// The Address specifying the location.
314 /// Returns a shared pointer to the location at \a addr. The pointer
315 /// in the shared pointer will be nullptr if there is no location at that
317 //------------------------------------------------------------------
318 lldb::BreakpointLocationSP FindLocationByAddress(const Address &addr);
320 //------------------------------------------------------------------
321 /// Find a breakpoint location ID by Address.
324 /// The Address specifying the location.
326 /// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if
327 /// there is no breakpoint location at that address.
328 //------------------------------------------------------------------
329 lldb::break_id_t FindLocationIDByAddress(const Address &addr);
331 //------------------------------------------------------------------
332 /// Find a breakpoint location for a given breakpoint location ID.
334 /// @param[in] bp_loc_id
335 /// The ID specifying the location.
337 /// Returns a shared pointer to the location with ID \a bp_loc_id. The
339 /// in the shared pointer will be nullptr if there is no location with that
341 //------------------------------------------------------------------
342 lldb::BreakpointLocationSP FindLocationByID(lldb::break_id_t bp_loc_id);
344 //------------------------------------------------------------------
345 /// Get breakpoint locations by index.
348 /// The location index.
351 /// Returns a shared pointer to the location with index \a
352 /// index. The shared pointer might contain nullptr if \a index is
353 /// greater than then number of actual locations.
354 //------------------------------------------------------------------
355 lldb::BreakpointLocationSP GetLocationAtIndex(size_t index);
357 //------------------------------------------------------------------
358 /// Removes all invalid breakpoint locations.
360 /// Removes all breakpoint locations with architectures that aren't
361 /// compatible with \a arch. Also remove any breakpoint locations
362 /// with whose locations have address where the section has been
363 /// deleted (module and object files no longer exist).
365 /// This is typically used after the process calls exec, or anytime
366 /// the architecture of the target changes.
369 /// If valid, check the module in each breakpoint to make sure
370 /// they are compatible, otherwise, ignore architecture.
371 //------------------------------------------------------------------
372 void RemoveInvalidLocations(const ArchSpec &arch);
374 //------------------------------------------------------------------
375 // The next section deals with various breakpoint options.
376 //------------------------------------------------------------------
378 //------------------------------------------------------------------
379 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
380 //------------------------------------------------------------------
381 void SetEnabled(bool enable) override;
383 //------------------------------------------------------------------
384 /// Check the Enable/Disable state.
386 /// \b true if the breakpoint is enabled, \b false if disabled.
387 //------------------------------------------------------------------
388 bool IsEnabled() override;
390 //------------------------------------------------------------------
391 /// Set the breakpoint to ignore the next \a count breakpoint hits.
393 /// The number of breakpoint hits to ignore.
394 //------------------------------------------------------------------
395 void SetIgnoreCount(uint32_t count);
397 //------------------------------------------------------------------
398 /// Return the current ignore count/
400 /// The number of breakpoint hits to be ignored.
401 //------------------------------------------------------------------
402 uint32_t GetIgnoreCount() const;
404 //------------------------------------------------------------------
405 /// Return the current hit count for all locations.
407 /// The current hit count for all locations.
408 //------------------------------------------------------------------
409 uint32_t GetHitCount() const;
411 //------------------------------------------------------------------
412 /// If \a one_shot is \b true, breakpoint will be deleted on first hit.
413 //------------------------------------------------------------------
414 void SetOneShot(bool one_shot);
416 //------------------------------------------------------------------
417 /// Check the OneShot state.
419 /// \b true if the breakpoint is one shot, \b false otherwise.
420 //------------------------------------------------------------------
421 bool IsOneShot() const;
423 //------------------------------------------------------------------
424 /// Set the valid thread to be checked when the breakpoint is hit.
425 /// @param[in] thread_id
426 /// If this thread hits the breakpoint, we stop, otherwise not.
427 //------------------------------------------------------------------
428 void SetThreadID(lldb::tid_t thread_id);
430 //------------------------------------------------------------------
431 /// Return the current stop thread value.
433 /// The thread id for which the breakpoint hit will stop,
434 /// LLDB_INVALID_THREAD_ID for all threads.
435 //------------------------------------------------------------------
436 lldb::tid_t GetThreadID() const;
438 void SetThreadIndex(uint32_t index);
440 uint32_t GetThreadIndex() const;
442 void SetThreadName(const char *thread_name);
444 const char *GetThreadName() const;
446 void SetQueueName(const char *queue_name);
448 const char *GetQueueName() const;
450 //------------------------------------------------------------------
451 /// Set the callback action invoked when the breakpoint is hit.
453 /// @param[in] callback
454 /// The method that will get called when the breakpoint is hit.
456 /// A void * pointer that will get passed back to the callback function.
457 /// @param[in] is_synchronous
458 /// If \b true the callback will be run on the private event thread
459 /// before the stop event gets reported. If false, the callback will get
460 /// handled on the public event thread after the stop has been posted.
463 /// \b true if the process should stop when you hit the breakpoint.
464 /// \b false if it should continue.
465 //------------------------------------------------------------------
466 void SetCallback(BreakpointHitCallback callback, void *baton,
467 bool is_synchronous = false);
469 void SetCallback(BreakpointHitCallback callback,
470 const lldb::BatonSP &callback_baton_sp,
471 bool is_synchronous = false);
473 void ClearCallback();
475 //------------------------------------------------------------------
476 /// Set the breakpoint's condition.
478 /// @param[in] condition
479 /// The condition expression to evaluate when the breakpoint is hit.
480 /// Pass in nullptr to clear the condition.
481 //------------------------------------------------------------------
482 void SetCondition(const char *condition);
484 //------------------------------------------------------------------
485 /// Return a pointer to the text of the condition expression.
488 /// A pointer to the condition expression text, or nullptr if no
489 // condition has been set.
490 //------------------------------------------------------------------
491 const char *GetConditionText() const;
493 //------------------------------------------------------------------
494 // The next section are various utility functions.
495 //------------------------------------------------------------------
497 //------------------------------------------------------------------
498 /// Return the number of breakpoint locations that have resolved to
499 /// actual breakpoint sites.
502 /// The number locations resolved breakpoint sites.
503 //------------------------------------------------------------------
504 size_t GetNumResolvedLocations() const;
506 //------------------------------------------------------------------
507 /// Return the number of breakpoint locations.
510 /// The number breakpoint locations.
511 //------------------------------------------------------------------
512 size_t GetNumLocations() const;
514 //------------------------------------------------------------------
515 /// Put a description of this breakpoint into the stream \a s.
518 /// Stream into which to dump the description.
521 /// The description level that indicates the detail level to
524 /// @see lldb::DescriptionLevel
525 //------------------------------------------------------------------
526 void GetDescription(Stream *s, lldb::DescriptionLevel level,
527 bool show_locations = false);
529 //------------------------------------------------------------------
530 /// Set the "kind" description for a breakpoint. If the breakpoint is hit
531 /// the stop info will show this "kind" description instead of the breakpoint
532 /// number. Mostly useful for internal breakpoints, where the breakpoint
534 /// doesn't have meaning to the user.
537 /// New "kind" description.
538 //------------------------------------------------------------------
539 void SetBreakpointKind(const char *kind) { m_kind_description.assign(kind); }
541 //------------------------------------------------------------------
542 /// Return the "kind" description for a breakpoint.
545 /// The breakpoint kind, or nullptr if none is set.
546 //------------------------------------------------------------------
547 const char *GetBreakpointKind() const { return m_kind_description.c_str(); }
549 //------------------------------------------------------------------
550 /// Accessor for the breakpoint Target.
552 /// This breakpoint's Target.
553 //------------------------------------------------------------------
554 Target &GetTarget() { return m_target; }
556 const Target &GetTarget() const { return m_target; }
558 const lldb::TargetSP GetTargetSP();
560 void GetResolverDescription(Stream *s);
562 //------------------------------------------------------------------
563 /// Find breakpoint locations which match the (filename, line_number)
565 /// The breakpoint location collection is to be filled with the matching
567 /// It should be initialized with 0 size by the API client.
570 /// True if there is a match
572 /// The locations which match the filename and line_number in loc_coll.
574 /// size is 0 and true is returned, it means the breakpoint fully matches
577 //------------------------------------------------------------------
578 bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number,
579 BreakpointLocationCollection &loc_coll);
581 void GetFilterDescription(Stream *s);
583 //------------------------------------------------------------------
584 /// Returns the BreakpointOptions structure set at the breakpoint level.
586 /// Meant to be used by the BreakpointLocation class.
589 /// A pointer to this breakpoint's BreakpointOptions.
590 //------------------------------------------------------------------
591 BreakpointOptions *GetOptions();
593 //------------------------------------------------------------------
594 /// Invoke the callback action when the breakpoint is hit.
596 /// Meant to be used by the BreakpointLocation class.
598 /// @param[in] context
599 /// Described the breakpoint event.
601 /// @param[in] bp_loc_id
602 /// Which breakpoint location hit this breakpoint.
605 /// \b true if the target should stop at this breakpoint and \b false not.
606 //------------------------------------------------------------------
607 bool InvokeCallback(StoppointCallbackContext *context,
608 lldb::break_id_t bp_loc_id);
610 bool IsHardware() const { return m_hardware; }
612 lldb::BreakpointResolverSP GetResolver() { return m_resolver_sp; }
614 lldb::SearchFilterSP GetSearchFilter() { return m_filter_sp; }
616 bool AddName(const char *new_name, Error &error);
618 void RemoveName(const char *name_to_remove) {
620 m_name_list.erase(name_to_remove);
623 bool MatchesName(const char *name) {
624 return m_name_list.find(name) != m_name_list.end();
627 void GetNames(std::vector<std::string> &names) {
629 for (auto name : m_name_list) {
630 names.push_back(name);
634 //------------------------------------------------------------------
635 /// Set a pre-condition filter that overrides all user provided
636 /// filters/callbacks etc.
638 /// Used to define fancy breakpoints that can do dynamic hit detection without
639 /// taking up the condition slot -
640 /// which really belongs to the user anyway...
642 /// The Precondition should not continue the target, it should return true if
643 /// the condition says to stop and
646 //------------------------------------------------------------------
647 void SetPrecondition(BreakpointPreconditionSP precondition_sp) {
648 m_precondition_sp = precondition_sp;
651 bool EvaluatePrecondition(StoppointCallbackContext &context);
653 BreakpointPreconditionSP GetPrecondition() { return m_precondition_sp; }
657 //------------------------------------------------------------------
659 //------------------------------------------------------------------
661 //------------------------------------------------------------------
662 /// Constructors and Destructors
663 /// Only the Target can make a breakpoint, and it owns the breakpoint
665 /// The constructor takes a filter and a resolver. Up in Target there are
667 /// variants that make breakpoints for some common cases.
669 /// @param[in] target
670 /// The target in which the breakpoint will be set.
672 /// @param[in] filter_sp
673 /// Shared pointer to the search filter that restricts the search domain of
676 /// @param[in] resolver_sp
677 /// Shared pointer to the resolver object that will determine breakpoint
681 /// If true, request a hardware breakpoint to be used to implement the
682 /// breakpoint locations.
684 /// @param resolve_indirect_symbols
685 /// If true, and the address of a given breakpoint location in this
686 /// breakpoint is set on an
687 /// indirect symbol (i.e. Symbol::IsIndirect returns true) then the actual
688 /// breakpoint site will
689 /// be set on the target of the indirect symbol.
690 //------------------------------------------------------------------
691 // This is the generic constructor
692 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp,
693 lldb::BreakpointResolverSP &resolver_sp, bool hardware,
694 bool resolve_indirect_symbols = true);
696 friend class BreakpointLocation; // To call the following two when determining
699 void DecrementIgnoreCount();
701 // BreakpointLocation::IgnoreCountShouldStop &
702 // Breakpoint::IgnoreCountShouldStop can only be called once per stop,
703 // and BreakpointLocation::IgnoreCountShouldStop should be tested first, and
704 // if it returns false we should
705 // continue, otherwise we should test Breakpoint::IgnoreCountShouldStop.
707 bool IgnoreCountShouldStop();
709 void IncrementHitCount() { m_hit_count++; }
711 void DecrementHitCount() {
712 assert(m_hit_count > 0);
717 // This one should only be used by Target to copy breakpoints from target to
718 // target - primarily from the dummy
719 // target to prime new targets.
720 Breakpoint(Target &new_target, Breakpoint &bp_to_copy_from);
722 //------------------------------------------------------------------
723 // For Breakpoint only
724 //------------------------------------------------------------------
725 bool m_being_created;
727 m_hardware; // If this breakpoint is required to use a hardware breakpoint
728 Target &m_target; // The target that holds this breakpoint.
729 std::unordered_set<std::string> m_name_list; // If not empty, this is the name
730 // of this breakpoint (many
731 // breakpoints can share the same
734 m_filter_sp; // The filter that constrains the breakpoint's domain.
735 lldb::BreakpointResolverSP
736 m_resolver_sp; // The resolver that defines this breakpoint.
737 BreakpointPreconditionSP m_precondition_sp; // The precondition is a
738 // breakpoint-level hit filter
740 // to skip certain breakpoint hits. For instance, exception breakpoints
741 // use this to limit the stop to certain exception classes, while leaving
742 // the condition & callback free for user specification.
743 std::unique_ptr<BreakpointOptions>
744 m_options_up; // Settable breakpoint options
745 BreakpointLocationList
746 m_locations; // The list of locations currently found for this breakpoint.
747 std::string m_kind_description;
748 bool m_resolve_indirect_symbols;
749 uint32_t m_hit_count; // Number of times this breakpoint/watchpoint has been
751 // separately from the locations hit counts, since locations can go away when
752 // their backing library gets unloaded, and we would lose hit counts.
754 void SendBreakpointChangedEvent(lldb::BreakpointEventType eventKind);
756 void SendBreakpointChangedEvent(BreakpointEventData *data);
758 DISALLOW_COPY_AND_ASSIGN(Breakpoint);
761 } // namespace lldb_private
763 #endif // liblldb_Breakpoint_h_