1 //===-- Breakpoint.h --------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef LLDB_BREAKPOINT_BREAKPOINT_H
10 #define LLDB_BREAKPOINT_BREAKPOINT_H
14 #include <unordered_set>
17 #include "lldb/Breakpoint/BreakpointID.h"
18 #include "lldb/Breakpoint/BreakpointLocationCollection.h"
19 #include "lldb/Breakpoint/BreakpointLocationList.h"
20 #include "lldb/Breakpoint/BreakpointName.h"
21 #include "lldb/Breakpoint/BreakpointOptions.h"
22 #include "lldb/Breakpoint/Stoppoint.h"
23 #include "lldb/Core/SearchFilter.h"
24 #include "lldb/Utility/Event.h"
25 #include "lldb/Utility/StringList.h"
26 #include "lldb/Utility/StructuredData.h"
28 namespace lldb_private {
30 /// \class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" Class that
31 /// manages logical breakpoint setting.
34 /// A breakpoint has four main parts, a filter, a resolver, the list of
36 /// locations that have been determined for the filter/resolver pair, and
37 /// finally a set of options for the breakpoint.
40 /// This is an object derived from SearchFilter. It manages the search for
41 /// breakpoint location matches through the symbols in the module list of the
42 /// target that owns it. It also filters out locations based on whatever
46 /// This is an object derived from BreakpointResolver. It provides a callback
47 /// to the filter that will find breakpoint locations. How it does this is
48 /// determined by what kind of resolver it is.
50 /// The Breakpoint class also provides constructors for the common breakpoint
51 /// cases which make the appropriate filter and resolver for you.
54 /// This stores the breakpoint locations that have been determined to date.
55 /// For a given breakpoint, there will be only one location with a given
56 /// address. Adding a location at an already taken address will just return
57 /// the location already at that address. Locations can be looked up by ID,
62 /// \b Enabled/Disabled
66 /// Note, these options can be set on the breakpoint, and they can also be set
67 /// on the individual locations. The options set on the breakpoint take
68 /// precedence over the options set on the individual location. So for
69 /// instance disabling the breakpoint will cause NONE of the locations to get
70 /// hit. But if the breakpoint is enabled, then the location's enabled state
71 /// will be checked to determine whether to insert that breakpoint location.
72 /// Similarly, if the breakpoint condition says "stop", we won't check the
73 /// location's condition. But if the breakpoint condition says "continue",
74 /// then we will check the location for whether to actually stop or not. One
75 /// subtle point worth observing here is that you don't actually stop at a
76 /// Breakpoint, you always stop at one of its locations. So the "should stop"
77 /// tests are done by the location, not by the breakpoint.
78 class Breakpoint : public std::enable_shared_from_this<Breakpoint>,
81 static ConstString GetEventIdentifier();
83 /// An enum specifying the match style for breakpoint settings. At present
84 /// only used for function name style breakpoints.
85 enum MatchType { Exact, Regexp, Glob };
88 enum class OptionNames : uint32_t { Names = 0, Hardware, LastOptionName };
91 *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)];
93 static const char *GetKey(OptionNames enum_value) {
94 return g_option_names[static_cast<uint32_t>(enum_value)];
98 class BreakpointEventData : public EventData {
100 BreakpointEventData(lldb::BreakpointEventType sub_type,
101 const lldb::BreakpointSP &new_breakpoint_sp);
103 ~BreakpointEventData() override;
105 static ConstString GetFlavorString();
107 ConstString GetFlavor() const override;
109 lldb::BreakpointEventType GetBreakpointEventType() const;
111 lldb::BreakpointSP &GetBreakpoint();
113 BreakpointLocationCollection &GetBreakpointLocationCollection() {
117 void Dump(Stream *s) const override;
119 static lldb::BreakpointEventType
120 GetBreakpointEventTypeFromEvent(const lldb::EventSP &event_sp);
122 static lldb::BreakpointSP
123 GetBreakpointFromEvent(const lldb::EventSP &event_sp);
125 static lldb::BreakpointLocationSP
126 GetBreakpointLocationAtIndexFromEvent(const lldb::EventSP &event_sp,
130 GetNumBreakpointLocationsFromEvent(const lldb::EventSP &event_sp);
132 static const BreakpointEventData *
133 GetEventDataFromEvent(const Event *event_sp);
136 lldb::BreakpointEventType m_breakpoint_event;
137 lldb::BreakpointSP m_new_breakpoint_sp;
138 BreakpointLocationCollection m_locations;
140 BreakpointEventData(const BreakpointEventData &) = delete;
141 const BreakpointEventData &operator=(const BreakpointEventData &) = delete;
144 // Saving & restoring breakpoints:
145 static lldb::BreakpointSP CreateFromStructuredData(
146 lldb::TargetSP target_sp, StructuredData::ObjectSP &data_object_sp,
150 SerializedBreakpointMatchesNames(StructuredData::ObjectSP &bkpt_object_sp,
151 std::vector<std::string> &names);
153 virtual StructuredData::ObjectSP SerializeToStructuredData();
155 static const char *GetSerializationKey() { return "Breakpoint"; }
158 /// The destructor is not virtual since there should be no reason to
159 /// subclass breakpoints. The varieties of breakpoints are specified
160 /// instead by providing different resolvers & filters.
161 ~Breakpoint() override;
165 /// Tell whether this breakpoint is an "internal" breakpoint. \return
166 /// Returns \b true if this is an internal breakpoint, \b false otherwise.
167 bool IsInternal() const;
169 /// Standard "Dump" method. At present it does nothing.
170 void Dump(Stream *s) override;
172 // The next set of methods provide ways to tell the breakpoint to update it's
173 // location list - usually done when modules appear or disappear.
175 /// Tell this breakpoint to clear all its breakpoint sites. Done when the
176 /// process holding the breakpoint sites is destroyed.
177 void ClearAllBreakpointSites();
179 /// Tell this breakpoint to scan it's target's module list and resolve any
180 /// new locations that match the breakpoint's specifications.
181 void ResolveBreakpoint();
183 /// Tell this breakpoint to scan a given module list and resolve any new
184 /// locations that match the breakpoint's specifications.
186 /// \param[in] module_list
187 /// The list of modules to look in for new locations.
189 /// \param[in] send_event
190 /// If \b true, send a breakpoint location added event for non-internal
192 void ResolveBreakpointInModules(ModuleList &module_list,
193 bool send_event = true);
195 /// Tell this breakpoint to scan a given module list and resolve any new
196 /// locations that match the breakpoint's specifications.
198 /// \param[in] module_list
199 /// The list of modules to look in for new locations.
201 /// \param[in] new_locations
202 /// Fills new_locations with the new locations that were made.
203 void ResolveBreakpointInModules(ModuleList &module_list,
204 BreakpointLocationCollection &new_locations);
206 /// Like ResolveBreakpointInModules, but allows for "unload" events, in
207 /// which case we will remove any locations that are in modules that got
210 /// \param[in] changed_modules
211 /// The list of modules to look in for new locations.
212 /// \param[in] load_event
213 /// If \b true then the modules were loaded, if \b false, unloaded.
214 /// \param[in] delete_locations
215 /// If \b true then the modules were unloaded delete any locations in the
217 void ModulesChanged(ModuleList &changed_modules, bool load_event,
218 bool delete_locations = false);
220 /// Tells the breakpoint the old module \a old_module_sp has been replaced
221 /// by new_module_sp (usually because the underlying file has been rebuilt,
222 /// and the old version is gone.)
224 /// \param[in] old_module_sp
225 /// The old module that is going away.
226 /// \param[in] new_module_sp
227 /// The new module that is replacing it.
228 void ModuleReplaced(lldb::ModuleSP old_module_sp,
229 lldb::ModuleSP new_module_sp);
231 // The next set of methods provide access to the breakpoint locations for
234 /// Add a location to the breakpoint's location list. This is only meant to
235 /// be called by the breakpoint's resolver. FIXME: how do I ensure that?
238 /// The Address specifying the new location.
239 /// \param[out] new_location
240 /// Set to \b true if a new location was created, to \b false if there
241 /// already was a location at this Address.
243 /// Returns a pointer to the new location.
244 lldb::BreakpointLocationSP AddLocation(const Address &addr,
245 bool *new_location = nullptr);
247 /// Find a breakpoint location by Address.
250 /// The Address specifying the location.
252 /// Returns a shared pointer to the location at \a addr. The pointer
253 /// in the shared pointer will be nullptr if there is no location at that
255 lldb::BreakpointLocationSP FindLocationByAddress(const Address &addr);
257 /// Find a breakpoint location ID by Address.
260 /// The Address specifying the location.
262 /// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if
263 /// there is no breakpoint location at that address.
264 lldb::break_id_t FindLocationIDByAddress(const Address &addr);
266 /// Find a breakpoint location for a given breakpoint location ID.
268 /// \param[in] bp_loc_id
269 /// The ID specifying the location.
271 /// Returns a shared pointer to the location with ID \a bp_loc_id. The
273 /// in the shared pointer will be nullptr if there is no location with that
275 lldb::BreakpointLocationSP FindLocationByID(lldb::break_id_t bp_loc_id);
277 /// Get breakpoint locations by index.
280 /// The location index.
283 /// Returns a shared pointer to the location with index \a
284 /// index. The shared pointer might contain nullptr if \a index is
285 /// greater than then number of actual locations.
286 lldb::BreakpointLocationSP GetLocationAtIndex(size_t index);
288 /// Removes all invalid breakpoint locations.
290 /// Removes all breakpoint locations with architectures that aren't
291 /// compatible with \a arch. Also remove any breakpoint locations with whose
292 /// locations have address where the section has been deleted (module and
293 /// object files no longer exist).
295 /// This is typically used after the process calls exec, or anytime the
296 /// architecture of the target changes.
299 /// If valid, check the module in each breakpoint to make sure
300 /// they are compatible, otherwise, ignore architecture.
301 void RemoveInvalidLocations(const ArchSpec &arch);
303 // The next section deals with various breakpoint options.
305 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
306 void SetEnabled(bool enable) override;
308 /// Check the Enable/Disable state.
310 /// \b true if the breakpoint is enabled, \b false if disabled.
311 bool IsEnabled() override;
313 /// Set the breakpoint to ignore the next \a count breakpoint hits.
315 /// The number of breakpoint hits to ignore.
316 void SetIgnoreCount(uint32_t count);
318 /// Return the current ignore count/
320 /// The number of breakpoint hits to be ignored.
321 uint32_t GetIgnoreCount() const;
323 /// Return the current hit count for all locations. \return
324 /// The current hit count for all locations.
325 uint32_t GetHitCount() const;
327 /// If \a one_shot is \b true, breakpoint will be deleted on first hit.
328 void SetOneShot(bool one_shot);
330 /// Check the OneShot state.
332 /// \b true if the breakpoint is one shot, \b false otherwise.
333 bool IsOneShot() const;
335 /// If \a auto_continue is \b true, breakpoint will auto-continue when on
337 void SetAutoContinue(bool auto_continue);
339 /// Check the AutoContinue state.
341 /// \b true if the breakpoint is set to auto-continue, \b false otherwise.
342 bool IsAutoContinue() const;
344 /// Set the valid thread to be checked when the breakpoint is hit.
345 /// \param[in] thread_id
346 /// If this thread hits the breakpoint, we stop, otherwise not.
347 void SetThreadID(lldb::tid_t thread_id);
349 /// Return the current stop thread value.
351 /// The thread id for which the breakpoint hit will stop,
352 /// LLDB_INVALID_THREAD_ID for all threads.
353 lldb::tid_t GetThreadID() const;
355 void SetThreadIndex(uint32_t index);
357 uint32_t GetThreadIndex() const;
359 void SetThreadName(const char *thread_name);
361 const char *GetThreadName() const;
363 void SetQueueName(const char *queue_name);
365 const char *GetQueueName() const;
367 /// Set the callback action invoked when the breakpoint is hit.
369 /// \param[in] callback
370 /// The method that will get called when the breakpoint is hit.
372 /// A void * pointer that will get passed back to the callback function.
373 /// \param[in] is_synchronous
374 /// If \b true the callback will be run on the private event thread
375 /// before the stop event gets reported. If false, the callback will get
376 /// handled on the public event thread after the stop has been posted.
377 void SetCallback(BreakpointHitCallback callback, void *baton,
378 bool is_synchronous = false);
380 void SetCallback(BreakpointHitCallback callback,
381 const lldb::BatonSP &callback_baton_sp,
382 bool is_synchronous = false);
384 void ClearCallback();
386 /// Set the breakpoint's condition.
388 /// \param[in] condition
389 /// The condition expression to evaluate when the breakpoint is hit.
390 /// Pass in nullptr to clear the condition.
391 void SetCondition(const char *condition);
393 /// Return a pointer to the text of the condition expression.
396 /// A pointer to the condition expression text, or nullptr if no
397 // condition has been set.
398 const char *GetConditionText() const;
400 // The next section are various utility functions.
402 /// Return the number of breakpoint locations that have resolved to actual
403 /// breakpoint sites.
406 /// The number locations resolved breakpoint sites.
407 size_t GetNumResolvedLocations() const;
409 /// Return whether this breakpoint has any resolved locations.
412 /// True if GetNumResolvedLocations > 0
413 bool HasResolvedLocations() const;
415 /// Return the number of breakpoint locations.
418 /// The number breakpoint locations.
419 size_t GetNumLocations() const;
421 /// Put a description of this breakpoint into the stream \a s.
424 /// Stream into which to dump the description.
427 /// The description level that indicates the detail level to
430 /// \see lldb::DescriptionLevel
431 void GetDescription(Stream *s, lldb::DescriptionLevel level,
432 bool show_locations = false);
434 /// Set the "kind" description for a breakpoint. If the breakpoint is hit
435 /// the stop info will show this "kind" description instead of the
436 /// breakpoint number. Mostly useful for internal breakpoints, where the
437 /// breakpoint number doesn't have meaning to the user.
440 /// New "kind" description.
441 void SetBreakpointKind(const char *kind) { m_kind_description.assign(kind); }
443 /// Return the "kind" description for a breakpoint.
446 /// The breakpoint kind, or nullptr if none is set.
447 const char *GetBreakpointKind() const { return m_kind_description.c_str(); }
449 /// Accessor for the breakpoint Target.
451 /// This breakpoint's Target.
452 Target &GetTarget() { return m_target; }
454 const Target &GetTarget() const { return m_target; }
456 const lldb::TargetSP GetTargetSP();
458 void GetResolverDescription(Stream *s);
460 /// Find breakpoint locations which match the (filename, line_number)
461 /// description. The breakpoint location collection is to be filled with the
462 /// matching locations. It should be initialized with 0 size by the API
466 /// True if there is a match
468 /// The locations which match the filename and line_number in loc_coll.
470 /// size is 0 and true is returned, it means the breakpoint fully matches
473 bool GetMatchingFileLine(ConstString filename, uint32_t line_number,
474 BreakpointLocationCollection &loc_coll);
476 void GetFilterDescription(Stream *s);
478 /// Returns the BreakpointOptions structure set at the breakpoint level.
480 /// Meant to be used by the BreakpointLocation class.
483 /// A pointer to this breakpoint's BreakpointOptions.
484 BreakpointOptions *GetOptions();
486 /// Returns the BreakpointOptions structure set at the breakpoint level.
488 /// Meant to be used by the BreakpointLocation class.
491 /// A pointer to this breakpoint's BreakpointOptions.
492 const BreakpointOptions *GetOptions() const;
494 /// Invoke the callback action when the breakpoint is hit.
496 /// Meant to be used by the BreakpointLocation class.
498 /// \param[in] context
499 /// Described the breakpoint event.
501 /// \param[in] bp_loc_id
502 /// Which breakpoint location hit this breakpoint.
505 /// \b true if the target should stop at this breakpoint and \b false not.
506 bool InvokeCallback(StoppointCallbackContext *context,
507 lldb::break_id_t bp_loc_id);
509 bool IsHardware() const { return m_hardware; }
511 lldb::BreakpointResolverSP GetResolver() { return m_resolver_sp; }
513 lldb::SearchFilterSP GetSearchFilter() { return m_filter_sp; }
515 private: // The target needs to manage adding & removing names. It will do the
516 // checking for name validity as well.
517 bool AddName(llvm::StringRef new_name);
519 void RemoveName(const char *name_to_remove) {
521 m_name_list.erase(name_to_remove);
525 bool MatchesName(const char *name) {
526 return m_name_list.find(name) != m_name_list.end();
529 void GetNames(std::vector<std::string> &names) {
531 for (auto name : m_name_list) {
532 names.push_back(name);
536 /// Set a pre-condition filter that overrides all user provided
537 /// filters/callbacks etc.
539 /// Used to define fancy breakpoints that can do dynamic hit detection
540 /// without taking up the condition slot - which really belongs to the user
543 /// The Precondition should not continue the target, it should return true
544 /// if the condition says to stop and false otherwise.
546 void SetPrecondition(lldb::BreakpointPreconditionSP precondition_sp) {
547 m_precondition_sp = precondition_sp;
550 bool EvaluatePrecondition(StoppointCallbackContext &context);
552 lldb::BreakpointPreconditionSP GetPrecondition() { return m_precondition_sp; }
554 // Produces the OR'ed values for all the names assigned to this breakpoint.
555 const BreakpointName::Permissions &GetPermissions() const {
556 return m_permissions;
559 BreakpointName::Permissions &GetPermissions() {
560 return m_permissions;
563 bool AllowList() const {
564 return GetPermissions().GetAllowList();
566 bool AllowDisable() const {
567 return GetPermissions().GetAllowDisable();
569 bool AllowDelete() const {
570 return GetPermissions().GetAllowDelete();
573 // This one should only be used by Target to copy breakpoints from target to
574 // target - primarily from the dummy target to prime new targets.
575 static lldb::BreakpointSP CopyFromBreakpoint(lldb::TargetSP new_target,
576 const Breakpoint &bp_to_copy_from);
582 /// Constructors and Destructors
583 /// Only the Target can make a breakpoint, and it owns the breakpoint
584 /// lifespans. The constructor takes a filter and a resolver. Up in Target
585 /// there are convenience variants that make breakpoints for some common
588 /// \param[in] target
589 /// The target in which the breakpoint will be set.
591 /// \param[in] filter_sp
592 /// Shared pointer to the search filter that restricts the search domain of
595 /// \param[in] resolver_sp
596 /// Shared pointer to the resolver object that will determine breakpoint
600 /// If true, request a hardware breakpoint to be used to implement the
601 /// breakpoint locations.
603 /// \param resolve_indirect_symbols
604 /// If true, and the address of a given breakpoint location in this
605 /// breakpoint is set on an
606 /// indirect symbol (i.e. Symbol::IsIndirect returns true) then the actual
607 /// breakpoint site will
608 /// be set on the target of the indirect symbol.
609 // This is the generic constructor
610 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp,
611 lldb::BreakpointResolverSP &resolver_sp, bool hardware,
612 bool resolve_indirect_symbols = true);
614 friend class BreakpointLocation; // To call the following two when determining
617 void DecrementIgnoreCount();
619 // BreakpointLocation::IgnoreCountShouldStop &
620 // Breakpoint::IgnoreCountShouldStop can only be called once per stop, and
621 // BreakpointLocation::IgnoreCountShouldStop should be tested first, and if
622 // it returns false we should continue, otherwise we should test
623 // Breakpoint::IgnoreCountShouldStop.
625 bool IgnoreCountShouldStop();
627 void IncrementHitCount() { m_hit_count++; }
629 void DecrementHitCount() {
630 assert(m_hit_count > 0);
635 // To call from CopyFromBreakpoint.
636 Breakpoint(Target &new_target, const Breakpoint &bp_to_copy_from);
638 // For Breakpoint only
639 bool m_being_created;
641 m_hardware; // If this breakpoint is required to use a hardware breakpoint
642 Target &m_target; // The target that holds this breakpoint.
643 std::unordered_set<std::string> m_name_list; // If not empty, this is the name
644 // of this breakpoint (many
645 // breakpoints can share the same
648 m_filter_sp; // The filter that constrains the breakpoint's domain.
649 lldb::BreakpointResolverSP
650 m_resolver_sp; // The resolver that defines this breakpoint.
651 lldb::BreakpointPreconditionSP m_precondition_sp; // The precondition is a
652 // breakpoint-level hit
653 // filter that can be used
654 // to skip certain breakpoint hits. For instance, exception breakpoints use
655 // this to limit the stop to certain exception classes, while leaving the
656 // condition & callback free for user specification.
657 std::unique_ptr<BreakpointOptions>
658 m_options_up; // Settable breakpoint options
659 BreakpointLocationList
660 m_locations; // The list of locations currently found for this breakpoint.
661 std::string m_kind_description;
662 bool m_resolve_indirect_symbols;
663 uint32_t m_hit_count; // Number of times this breakpoint/watchpoint has been
665 // separately from the locations hit counts, since locations can go away when
666 // their backing library gets unloaded, and we would lose hit counts.
667 BreakpointName::Permissions m_permissions;
669 void SendBreakpointChangedEvent(lldb::BreakpointEventType eventKind);
671 void SendBreakpointChangedEvent(BreakpointEventData *data);
673 Breakpoint(const Breakpoint &) = delete;
674 const Breakpoint &operator=(const Breakpoint &) = delete;
677 } // namespace lldb_private
679 #endif // LLDB_BREAKPOINT_BREAKPOINT_H