Breakpoint.h revision 360784
1//===-- Breakpoint.h --------------------------------------------*- C++ -*-===// 2// 3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4// See https://llvm.org/LICENSE.txt for license information. 5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6// 7//===----------------------------------------------------------------------===// 8 9#ifndef liblldb_Breakpoint_h_ 10#define liblldb_Breakpoint_h_ 11 12#include <memory> 13#include <string> 14#include <unordered_set> 15#include <vector> 16 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" 27 28namespace lldb_private { 29 30/// \class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" Class that 31/// manages logical breakpoint setting. 32 33/// General Outline: 34/// A breakpoint has four main parts, a filter, a resolver, the list of 35/// breakpoint 36/// locations that have been determined for the filter/resolver pair, and 37/// finally a set of options for the breakpoint. 38/// 39/// \b Filter: 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 43/// logic it wants. 44/// 45/// \b Resolver: 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. 49/// 50/// The Breakpoint class also provides constructors for the common breakpoint 51/// cases which make the appropriate filter and resolver for you. 52/// 53/// \b Location List: 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, 58/// or by address. 59/// 60/// \b Options: 61/// This includes: 62/// \b Enabled/Disabled 63/// \b Ignore Count 64/// \b Callback 65/// \b Condition 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. 78class Breakpoint : public std::enable_shared_from_this<Breakpoint>, 79 public Stoppoint { 80public: 81 static ConstString GetEventIdentifier(); 82 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 }; 86 87private: 88 enum class OptionNames : uint32_t { Names = 0, Hardware, LastOptionName }; 89 90 static const char 91 *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)]; 92 93 static const char *GetKey(OptionNames enum_value) { 94 return g_option_names[static_cast<uint32_t>(enum_value)]; 95 } 96 97public: 98 class BreakpointEventData : public EventData { 99 public: 100 BreakpointEventData(lldb::BreakpointEventType sub_type, 101 const lldb::BreakpointSP &new_breakpoint_sp); 102 103 ~BreakpointEventData() override; 104 105 static ConstString GetFlavorString(); 106 107 ConstString GetFlavor() const override; 108 109 lldb::BreakpointEventType GetBreakpointEventType() const; 110 111 lldb::BreakpointSP &GetBreakpoint(); 112 113 BreakpointLocationCollection &GetBreakpointLocationCollection() { 114 return m_locations; 115 } 116 117 void Dump(Stream *s) const override; 118 119 static lldb::BreakpointEventType 120 GetBreakpointEventTypeFromEvent(const lldb::EventSP &event_sp); 121 122 static lldb::BreakpointSP 123 GetBreakpointFromEvent(const lldb::EventSP &event_sp); 124 125 static lldb::BreakpointLocationSP 126 GetBreakpointLocationAtIndexFromEvent(const lldb::EventSP &event_sp, 127 uint32_t loc_idx); 128 129 static size_t 130 GetNumBreakpointLocationsFromEvent(const lldb::EventSP &event_sp); 131 132 static const BreakpointEventData * 133 GetEventDataFromEvent(const Event *event_sp); 134 135 private: 136 lldb::BreakpointEventType m_breakpoint_event; 137 lldb::BreakpointSP m_new_breakpoint_sp; 138 BreakpointLocationCollection m_locations; 139 140 DISALLOW_COPY_AND_ASSIGN(BreakpointEventData); 141 }; 142 143 // Saving & restoring breakpoints: 144 static lldb::BreakpointSP CreateFromStructuredData( 145 Target &target, StructuredData::ObjectSP &data_object_sp, Status &error); 146 147 static bool 148 SerializedBreakpointMatchesNames(StructuredData::ObjectSP &bkpt_object_sp, 149 std::vector<std::string> &names); 150 151 virtual StructuredData::ObjectSP SerializeToStructuredData(); 152 153 static const char *GetSerializationKey() { return "Breakpoint"; } 154 /// Destructor. 155 /// 156 /// The destructor is not virtual since there should be no reason to 157 /// subclass breakpoints. The varieties of breakpoints are specified 158 /// instead by providing different resolvers & filters. 159 ~Breakpoint() override; 160 161 // Methods 162 163 /// Tell whether this breakpoint is an "internal" breakpoint. \return 164 /// Returns \b true if this is an internal breakpoint, \b false otherwise. 165 bool IsInternal() const; 166 167 /// Standard "Dump" method. At present it does nothing. 168 void Dump(Stream *s) override; 169 170 // The next set of methods provide ways to tell the breakpoint to update it's 171 // location list - usually done when modules appear or disappear. 172 173 /// Tell this breakpoint to clear all its breakpoint sites. Done when the 174 /// process holding the breakpoint sites is destroyed. 175 void ClearAllBreakpointSites(); 176 177 /// Tell this breakpoint to scan it's target's module list and resolve any 178 /// new locations that match the breakpoint's specifications. 179 void ResolveBreakpoint(); 180 181 /// Tell this breakpoint to scan a given module list and resolve any new 182 /// locations that match the breakpoint's specifications. 183 /// 184 /// \param[in] module_list 185 /// The list of modules to look in for new locations. 186 /// 187 /// \param[in] send_event 188 /// If \b true, send a breakpoint location added event for non-internal 189 /// breakpoints. 190 void ResolveBreakpointInModules(ModuleList &module_list, 191 bool send_event = true); 192 193 /// Tell this breakpoint to scan a given module list and resolve any new 194 /// locations that match the breakpoint's specifications. 195 /// 196 /// \param[in] module_list 197 /// The list of modules to look in for new locations. 198 /// 199 /// \param[in] new_locations 200 /// Fills new_locations with the new locations that were made. 201 void ResolveBreakpointInModules(ModuleList &module_list, 202 BreakpointLocationCollection &new_locations); 203 204 /// Like ResolveBreakpointInModules, but allows for "unload" events, in 205 /// which case we will remove any locations that are in modules that got 206 /// unloaded. 207 /// 208 /// \param[in] changed_modules 209 /// The list of modules to look in for new locations. 210 /// \param[in] load_event 211 /// If \b true then the modules were loaded, if \b false, unloaded. 212 /// \param[in] delete_locations 213 /// If \b true then the modules were unloaded delete any locations in the 214 /// changed modules. 215 void ModulesChanged(ModuleList &changed_modules, bool load_event, 216 bool delete_locations = false); 217 218 /// Tells the breakpoint the old module \a old_module_sp has been replaced 219 /// by new_module_sp (usually because the underlying file has been rebuilt, 220 /// and the old version is gone.) 221 /// 222 /// \param[in] old_module_sp 223 /// The old module that is going away. 224 /// \param[in] new_module_sp 225 /// The new module that is replacing it. 226 void ModuleReplaced(lldb::ModuleSP old_module_sp, 227 lldb::ModuleSP new_module_sp); 228 229 // The next set of methods provide access to the breakpoint locations for 230 // this breakpoint. 231 232 /// Add a location to the breakpoint's location list. This is only meant to 233 /// be called by the breakpoint's resolver. FIXME: how do I ensure that? 234 /// 235 /// \param[in] addr 236 /// The Address specifying the new location. 237 /// \param[out] new_location 238 /// Set to \b true if a new location was created, to \b false if there 239 /// already was a location at this Address. 240 /// \return 241 /// Returns a pointer to the new location. 242 lldb::BreakpointLocationSP AddLocation(const Address &addr, 243 bool *new_location = nullptr); 244 245 /// Find a breakpoint location by Address. 246 /// 247 /// \param[in] addr 248 /// The Address specifying the location. 249 /// \return 250 /// Returns a shared pointer to the location at \a addr. The pointer 251 /// in the shared pointer will be nullptr if there is no location at that 252 /// address. 253 lldb::BreakpointLocationSP FindLocationByAddress(const Address &addr); 254 255 /// Find a breakpoint location ID by Address. 256 /// 257 /// \param[in] addr 258 /// The Address specifying the location. 259 /// \return 260 /// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if 261 /// there is no breakpoint location at that address. 262 lldb::break_id_t FindLocationIDByAddress(const Address &addr); 263 264 /// Find a breakpoint location for a given breakpoint location ID. 265 /// 266 /// \param[in] bp_loc_id 267 /// The ID specifying the location. 268 /// \return 269 /// Returns a shared pointer to the location with ID \a bp_loc_id. The 270 /// pointer 271 /// in the shared pointer will be nullptr if there is no location with that 272 /// ID. 273 lldb::BreakpointLocationSP FindLocationByID(lldb::break_id_t bp_loc_id); 274 275 /// Get breakpoint locations by index. 276 /// 277 /// \param[in] index 278 /// The location index. 279 /// 280 /// \return 281 /// Returns a shared pointer to the location with index \a 282 /// index. The shared pointer might contain nullptr if \a index is 283 /// greater than then number of actual locations. 284 lldb::BreakpointLocationSP GetLocationAtIndex(size_t index); 285 286 /// Removes all invalid breakpoint locations. 287 /// 288 /// Removes all breakpoint locations with architectures that aren't 289 /// compatible with \a arch. Also remove any breakpoint locations with whose 290 /// locations have address where the section has been deleted (module and 291 /// object files no longer exist). 292 /// 293 /// This is typically used after the process calls exec, or anytime the 294 /// architecture of the target changes. 295 /// 296 /// \param[in] arch 297 /// If valid, check the module in each breakpoint to make sure 298 /// they are compatible, otherwise, ignore architecture. 299 void RemoveInvalidLocations(const ArchSpec &arch); 300 301 // The next section deals with various breakpoint options. 302 303 /// If \a enable is \b true, enable the breakpoint, if \b false disable it. 304 void SetEnabled(bool enable) override; 305 306 /// Check the Enable/Disable state. 307 /// \return 308 /// \b true if the breakpoint is enabled, \b false if disabled. 309 bool IsEnabled() override; 310 311 /// Set the breakpoint to ignore the next \a count breakpoint hits. 312 /// \param[in] count 313 /// The number of breakpoint hits to ignore. 314 void SetIgnoreCount(uint32_t count); 315 316 /// Return the current ignore count/ 317 /// \return 318 /// The number of breakpoint hits to be ignored. 319 uint32_t GetIgnoreCount() const; 320 321 /// Return the current hit count for all locations. \return 322 /// The current hit count for all locations. 323 uint32_t GetHitCount() const; 324 325 /// If \a one_shot is \b true, breakpoint will be deleted on first hit. 326 void SetOneShot(bool one_shot); 327 328 /// Check the OneShot state. 329 /// \return 330 /// \b true if the breakpoint is one shot, \b false otherwise. 331 bool IsOneShot() const; 332 333 /// If \a auto_continue is \b true, breakpoint will auto-continue when on 334 /// hit. 335 void SetAutoContinue(bool auto_continue); 336 337 /// Check the AutoContinue state. 338 /// \return 339 /// \b true if the breakpoint is set to auto-continue, \b false otherwise. 340 bool IsAutoContinue() const; 341 342 /// Set the valid thread to be checked when the breakpoint is hit. 343 /// \param[in] thread_id 344 /// If this thread hits the breakpoint, we stop, otherwise not. 345 void SetThreadID(lldb::tid_t thread_id); 346 347 /// Return the current stop thread value. 348 /// \return 349 /// The thread id for which the breakpoint hit will stop, 350 /// LLDB_INVALID_THREAD_ID for all threads. 351 lldb::tid_t GetThreadID() const; 352 353 void SetThreadIndex(uint32_t index); 354 355 uint32_t GetThreadIndex() const; 356 357 void SetThreadName(const char *thread_name); 358 359 const char *GetThreadName() const; 360 361 void SetQueueName(const char *queue_name); 362 363 const char *GetQueueName() const; 364 365 /// Set the callback action invoked when the breakpoint is hit. 366 /// 367 /// \param[in] callback 368 /// The method that will get called when the breakpoint is hit. 369 /// \param[in] baton 370 /// A void * pointer that will get passed back to the callback function. 371 /// \param[in] is_synchronous 372 /// If \b true the callback will be run on the private event thread 373 /// before the stop event gets reported. If false, the callback will get 374 /// handled on the public event thread after the stop has been posted. 375 void SetCallback(BreakpointHitCallback callback, void *baton, 376 bool is_synchronous = false); 377 378 void SetCallback(BreakpointHitCallback callback, 379 const lldb::BatonSP &callback_baton_sp, 380 bool is_synchronous = false); 381 382 void ClearCallback(); 383 384 /// Set the breakpoint's condition. 385 /// 386 /// \param[in] condition 387 /// The condition expression to evaluate when the breakpoint is hit. 388 /// Pass in nullptr to clear the condition. 389 void SetCondition(const char *condition); 390 391 /// Return a pointer to the text of the condition expression. 392 /// 393 /// \return 394 /// A pointer to the condition expression text, or nullptr if no 395 // condition has been set. 396 const char *GetConditionText() const; 397 398 // The next section are various utility functions. 399 400 /// Return the number of breakpoint locations that have resolved to actual 401 /// breakpoint sites. 402 /// 403 /// \return 404 /// The number locations resolved breakpoint sites. 405 size_t GetNumResolvedLocations() const; 406 407 /// Return whether this breakpoint has any resolved locations. 408 /// 409 /// \return 410 /// True if GetNumResolvedLocations > 0 411 bool HasResolvedLocations() const; 412 413 /// Return the number of breakpoint locations. 414 /// 415 /// \return 416 /// The number breakpoint locations. 417 size_t GetNumLocations() const; 418 419 /// Put a description of this breakpoint into the stream \a s. 420 /// 421 /// \param[in] s 422 /// Stream into which to dump the description. 423 /// 424 /// \param[in] level 425 /// The description level that indicates the detail level to 426 /// provide. 427 /// 428 /// \see lldb::DescriptionLevel 429 void GetDescription(Stream *s, lldb::DescriptionLevel level, 430 bool show_locations = false); 431 432 /// Set the "kind" description for a breakpoint. If the breakpoint is hit 433 /// the stop info will show this "kind" description instead of the 434 /// breakpoint number. Mostly useful for internal breakpoints, where the 435 /// breakpoint number doesn't have meaning to the user. 436 /// 437 /// \param[in] kind 438 /// New "kind" description. 439 void SetBreakpointKind(const char *kind) { m_kind_description.assign(kind); } 440 441 /// Return the "kind" description for a breakpoint. 442 /// 443 /// \return 444 /// The breakpoint kind, or nullptr if none is set. 445 const char *GetBreakpointKind() const { return m_kind_description.c_str(); } 446 447 /// Accessor for the breakpoint Target. 448 /// \return 449 /// This breakpoint's Target. 450 Target &GetTarget() { return m_target; } 451 452 const Target &GetTarget() const { return m_target; } 453 454 const lldb::TargetSP GetTargetSP(); 455 456 void GetResolverDescription(Stream *s); 457 458 /// Find breakpoint locations which match the (filename, line_number) 459 /// description. The breakpoint location collection is to be filled with the 460 /// matching locations. It should be initialized with 0 size by the API 461 /// client. 462 /// 463 /// \return 464 /// True if there is a match 465 /// 466 /// The locations which match the filename and line_number in loc_coll. 467 /// If its 468 /// size is 0 and true is returned, it means the breakpoint fully matches 469 /// the 470 /// description. 471 bool GetMatchingFileLine(ConstString filename, uint32_t line_number, 472 BreakpointLocationCollection &loc_coll); 473 474 void GetFilterDescription(Stream *s); 475 476 /// Returns the BreakpointOptions structure set at the breakpoint level. 477 /// 478 /// Meant to be used by the BreakpointLocation class. 479 /// 480 /// \return 481 /// A pointer to this breakpoint's BreakpointOptions. 482 BreakpointOptions *GetOptions(); 483 484 /// Returns the BreakpointOptions structure set at the breakpoint level. 485 /// 486 /// Meant to be used by the BreakpointLocation class. 487 /// 488 /// \return 489 /// A pointer to this breakpoint's BreakpointOptions. 490 const BreakpointOptions *GetOptions() const; 491 492 /// Invoke the callback action when the breakpoint is hit. 493 /// 494 /// Meant to be used by the BreakpointLocation class. 495 /// 496 /// \param[in] context 497 /// Described the breakpoint event. 498 /// 499 /// \param[in] bp_loc_id 500 /// Which breakpoint location hit this breakpoint. 501 /// 502 /// \return 503 /// \b true if the target should stop at this breakpoint and \b false not. 504 bool InvokeCallback(StoppointCallbackContext *context, 505 lldb::break_id_t bp_loc_id); 506 507 bool IsHardware() const { return m_hardware; } 508 509 lldb::BreakpointResolverSP GetResolver() { return m_resolver_sp; } 510 511 lldb::SearchFilterSP GetSearchFilter() { return m_filter_sp; } 512 513private: // The target needs to manage adding & removing names. It will do the 514 // checking for name validity as well. 515 bool AddName(llvm::StringRef new_name); 516 517 void RemoveName(const char *name_to_remove) { 518 if (name_to_remove) 519 m_name_list.erase(name_to_remove); 520 } 521 522public: 523 bool MatchesName(const char *name) { 524 return m_name_list.find(name) != m_name_list.end(); 525 } 526 527 void GetNames(std::vector<std::string> &names) { 528 names.clear(); 529 for (auto name : m_name_list) { 530 names.push_back(name); 531 } 532 } 533 534 /// Set a pre-condition filter that overrides all user provided 535 /// filters/callbacks etc. 536 /// 537 /// Used to define fancy breakpoints that can do dynamic hit detection 538 /// without taking up the condition slot - which really belongs to the user 539 /// anyway... 540 /// 541 /// The Precondition should not continue the target, it should return true 542 /// if the condition says to stop and false otherwise. 543 /// 544 void SetPrecondition(lldb::BreakpointPreconditionSP precondition_sp) { 545 m_precondition_sp = precondition_sp; 546 } 547 548 bool EvaluatePrecondition(StoppointCallbackContext &context); 549 550 lldb::BreakpointPreconditionSP GetPrecondition() { return m_precondition_sp; } 551 552 // Produces the OR'ed values for all the names assigned to this breakpoint. 553 const BreakpointName::Permissions &GetPermissions() const { 554 return m_permissions; 555 } 556 557 BreakpointName::Permissions &GetPermissions() { 558 return m_permissions; 559 } 560 561 bool AllowList() const { 562 return GetPermissions().GetAllowList(); 563 } 564 bool AllowDisable() const { 565 return GetPermissions().GetAllowDisable(); 566 } 567 bool AllowDelete() const { 568 return GetPermissions().GetAllowDelete(); 569 } 570 571protected: 572 friend class Target; 573 // Protected Methods 574 575 /// Constructors and Destructors 576 /// Only the Target can make a breakpoint, and it owns the breakpoint 577 /// lifespans. The constructor takes a filter and a resolver. Up in Target 578 /// there are convenience variants that make breakpoints for some common 579 /// cases. 580 /// 581 /// \param[in] target 582 /// The target in which the breakpoint will be set. 583 /// 584 /// \param[in] filter_sp 585 /// Shared pointer to the search filter that restricts the search domain of 586 /// the breakpoint. 587 /// 588 /// \param[in] resolver_sp 589 /// Shared pointer to the resolver object that will determine breakpoint 590 /// matches. 591 /// 592 /// \param hardware 593 /// If true, request a hardware breakpoint to be used to implement the 594 /// breakpoint locations. 595 /// 596 /// \param resolve_indirect_symbols 597 /// If true, and the address of a given breakpoint location in this 598 /// breakpoint is set on an 599 /// indirect symbol (i.e. Symbol::IsIndirect returns true) then the actual 600 /// breakpoint site will 601 /// be set on the target of the indirect symbol. 602 // This is the generic constructor 603 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp, 604 lldb::BreakpointResolverSP &resolver_sp, bool hardware, 605 bool resolve_indirect_symbols = true); 606 607 friend class BreakpointLocation; // To call the following two when determining 608 // whether to stop. 609 610 void DecrementIgnoreCount(); 611 612 // BreakpointLocation::IgnoreCountShouldStop & 613 // Breakpoint::IgnoreCountShouldStop can only be called once per stop, and 614 // BreakpointLocation::IgnoreCountShouldStop should be tested first, and if 615 // it returns false we should continue, otherwise we should test 616 // Breakpoint::IgnoreCountShouldStop. 617 618 bool IgnoreCountShouldStop(); 619 620 void IncrementHitCount() { m_hit_count++; } 621 622 void DecrementHitCount() { 623 assert(m_hit_count > 0); 624 m_hit_count--; 625 } 626 627private: 628 // This one should only be used by Target to copy breakpoints from target to 629 // target - primarily from the dummy target to prime new targets. 630 Breakpoint(Target &new_target, Breakpoint &bp_to_copy_from); 631 632 // For Breakpoint only 633 bool m_being_created; 634 bool 635 m_hardware; // If this breakpoint is required to use a hardware breakpoint 636 Target &m_target; // The target that holds this breakpoint. 637 std::unordered_set<std::string> m_name_list; // If not empty, this is the name 638 // of this breakpoint (many 639 // breakpoints can share the same 640 // name.) 641 lldb::SearchFilterSP 642 m_filter_sp; // The filter that constrains the breakpoint's domain. 643 lldb::BreakpointResolverSP 644 m_resolver_sp; // The resolver that defines this breakpoint. 645 lldb::BreakpointPreconditionSP m_precondition_sp; // The precondition is a 646 // breakpoint-level hit 647 // filter that can be used 648 // to skip certain breakpoint hits. For instance, exception breakpoints use 649 // this to limit the stop to certain exception classes, while leaving the 650 // condition & callback free for user specification. 651 std::unique_ptr<BreakpointOptions> 652 m_options_up; // Settable breakpoint options 653 BreakpointLocationList 654 m_locations; // The list of locations currently found for this breakpoint. 655 std::string m_kind_description; 656 bool m_resolve_indirect_symbols; 657 uint32_t m_hit_count; // Number of times this breakpoint/watchpoint has been 658 // hit. This is kept 659 // separately from the locations hit counts, since locations can go away when 660 // their backing library gets unloaded, and we would lose hit counts. 661 BreakpointName::Permissions m_permissions; 662 663 void SendBreakpointChangedEvent(lldb::BreakpointEventType eventKind); 664 665 void SendBreakpointChangedEvent(BreakpointEventData *data); 666 667 DISALLOW_COPY_AND_ASSIGN(Breakpoint); 668}; 669 670} // namespace lldb_private 671 672#endif // liblldb_Breakpoint_h_ 673