Breakpoint.h revision 269024
1//===-- Breakpoint.h --------------------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef liblldb_Breakpoint_h_ 11#define liblldb_Breakpoint_h_ 12 13// C Includes 14// C++ Includes 15// Other libraries and framework includes 16// Project 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" 24 25namespace lldb_private { 26 27//---------------------------------------------------------------------- 28/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" 29/// @brief Class that manages logical breakpoint setting. 30//---------------------------------------------------------------------- 31 32//---------------------------------------------------------------------- 33/// General Outline: 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. 37/// 38/// \b Filter: 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. 42/// 43/// \b Resolver: 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. 47/// 48/// The Breakpoint class also provides constructors for the common breakpoint cases 49/// which make the appropriate filter and resolver for you. 50/// 51/// \b Location List: 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. 56/// 57/// \b Options: 58/// This includes: 59/// \b Enabled/Disabled 60/// \b Ignore Count 61/// \b Callback 62/// \b Condition 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//---------------------------------------------------------------------- 76class Breakpoint: 77 public std::enable_shared_from_this<Breakpoint>, 78 public Stoppoint 79{ 80public: 81 82 static const ConstString & 83 GetEventIdentifier (); 84 85 86 //------------------------------------------------------------------ 87 /// An enum specifying the match style for breakpoint settings. At 88 /// present only used for function name style breakpoints. 89 //------------------------------------------------------------------ 90 typedef enum 91 { 92 Exact, 93 Regexp, 94 Glob 95 } MatchType; 96 97 class BreakpointEventData : 98 public EventData 99 { 100 public: 101 102 static const ConstString & 103 GetFlavorString (); 104 105 virtual const ConstString & 106 GetFlavor () const; 107 108 BreakpointEventData (lldb::BreakpointEventType sub_type, 109 const lldb::BreakpointSP &new_breakpoint_sp); 110 111 virtual 112 ~BreakpointEventData(); 113 114 lldb::BreakpointEventType 115 GetBreakpointEventType () const; 116 117 lldb::BreakpointSP & 118 GetBreakpoint (); 119 120 BreakpointLocationCollection & 121 GetBreakpointLocationCollection() 122 { 123 return m_locations; 124 } 125 126 127 virtual void 128 Dump (Stream *s) const; 129 130 static lldb::BreakpointEventType 131 GetBreakpointEventTypeFromEvent (const lldb::EventSP &event_sp); 132 133 static lldb::BreakpointSP 134 GetBreakpointFromEvent (const lldb::EventSP &event_sp); 135 136 static lldb::BreakpointLocationSP 137 GetBreakpointLocationAtIndexFromEvent (const lldb::EventSP &event_sp, uint32_t loc_idx); 138 139 static size_t 140 GetNumBreakpointLocationsFromEvent (const lldb::EventSP &event_sp); 141 142 static const BreakpointEventData * 143 GetEventDataFromEvent (const Event *event_sp); 144 145 private: 146 147 lldb::BreakpointEventType m_breakpoint_event; 148 lldb::BreakpointSP m_new_breakpoint_sp; 149 BreakpointLocationCollection m_locations; 150 151 DISALLOW_COPY_AND_ASSIGN (BreakpointEventData); 152 }; 153 154 155 //------------------------------------------------------------------ 156 /// Destructor. 157 /// 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 //------------------------------------------------------------------ 162 ~Breakpoint(); 163 164 //------------------------------------------------------------------ 165 // Methods 166 //------------------------------------------------------------------ 167 168 //------------------------------------------------------------------ 169 /// Tell whether this breakpoint is an "internal" breakpoint. 170 /// @return 171 /// Returns \b true if this is an internal breakpoint, \b false otherwise. 172 //------------------------------------------------------------------ 173 bool 174 IsInternal () const; 175 176 //------------------------------------------------------------------ 177 /// Standard "Dump" method. At present it does nothing. 178 //------------------------------------------------------------------ 179 void 180 Dump (Stream *s); 181 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 //------------------------------------------------------------------ 186 187 188 //------------------------------------------------------------------ 189 /// Tell this breakpoint to clear all its breakpoint sites. Done 190 /// when the process holding the breakpoint sites is destroyed. 191 //------------------------------------------------------------------ 192 void 193 ClearAllBreakpointSites (); 194 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 //------------------------------------------------------------------ 199 void 200 ResolveBreakpoint (); 201 202 //------------------------------------------------------------------ 203 /// Tell this breakpoint to scan a given module list and resolve any 204 /// new locations that match the breakpoint's specifications. 205 /// 206 /// @param[in] changed_modules 207 /// The list of modules to look in for new locations. 208 //------------------------------------------------------------------ 209 void 210 ResolveBreakpointInModules (ModuleList &changed_modules); 211 212 213 //------------------------------------------------------------------ 214 /// Like ResolveBreakpointInModules, but allows for "unload" events, in 215 /// which case we will remove any locations that are in modules that got 216 /// unloaded. 217 /// 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 //------------------------------------------------------------------ 225 void 226 ModulesChanged (ModuleList &changed_modules, 227 bool load_event, 228 bool delete_locations = false); 229 230 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.) 235 /// 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 //------------------------------------------------------------------ 241 void 242 ModuleReplaced (lldb::ModuleSP old_module_sp, lldb::ModuleSP new_module_sp); 243 244 //------------------------------------------------------------------ 245 // The next set of methods provide access to the breakpoint locations 246 // for this breakpoint. 247 //------------------------------------------------------------------ 248 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? 252 /// 253 /// @param[in] addr 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. 258 /// @return 259 /// Returns a pointer to the new location. 260 //------------------------------------------------------------------ 261 lldb::BreakpointLocationSP 262 AddLocation (const Address &addr, 263 bool *new_location = NULL); 264 265 //------------------------------------------------------------------ 266 /// Find a breakpoint location by Address. 267 /// 268 /// @param[in] addr 269 /// The Address specifying the location. 270 /// @return 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); 276 277 //------------------------------------------------------------------ 278 /// Find a breakpoint location ID by Address. 279 /// 280 /// @param[in] addr 281 /// The Address specifying the location. 282 /// @return 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 //------------------------------------------------------------------ 286 lldb::break_id_t 287 FindLocationIDByAddress (const Address &addr); 288 289 //------------------------------------------------------------------ 290 /// Find a breakpoint location for a given breakpoint location ID. 291 /// 292 /// @param[in] bp_loc_id 293 /// The ID specifying the location. 294 /// @return 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); 300 301 //------------------------------------------------------------------ 302 /// Get breakpoint locations by index. 303 /// 304 /// @param[in] index 305 /// The location index. 306 /// 307 /// @return 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); 314 315 //------------------------------------------------------------------ 316 /// Removes all invalid breakpoint locations. 317 /// 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). 322 /// 323 /// This is typically used after the process calls exec, or anytime 324 /// the architecture of the target changes. 325 /// 326 /// @param[in] arch 327 /// If valid, check the module in each breakpoint to make sure 328 /// they are compatible, otherwise, ignore architecture. 329 //------------------------------------------------------------------ 330 void 331 RemoveInvalidLocations (const ArchSpec &arch); 332 333 //------------------------------------------------------------------ 334 // The next section deals with various breakpoint options. 335 //------------------------------------------------------------------ 336 337 //------------------------------------------------------------------ 338 /// If \a enable is \b true, enable the breakpoint, if \b false disable it. 339 //------------------------------------------------------------------ 340 void 341 SetEnabled (bool enable); 342 343 //------------------------------------------------------------------ 344 /// Check the Enable/Disable state. 345 /// @return 346 /// \b true if the breakpoint is enabled, \b false if disabled. 347 //------------------------------------------------------------------ 348 bool 349 IsEnabled (); 350 351 //------------------------------------------------------------------ 352 /// Set the breakpoint to ignore the next \a count breakpoint hits. 353 /// @param[in] count 354 /// The number of breakpoint hits to ignore. 355 //------------------------------------------------------------------ 356 void 357 SetIgnoreCount (uint32_t count); 358 359 //------------------------------------------------------------------ 360 /// Return the current ignore count/ 361 /// @return 362 /// The number of breakpoint hits to be ignored. 363 //------------------------------------------------------------------ 364 uint32_t 365 GetIgnoreCount () const; 366 367 //------------------------------------------------------------------ 368 /// Return the current hit count for all locations. 369 /// @return 370 /// The current hit count for all locations. 371 //------------------------------------------------------------------ 372 uint32_t 373 GetHitCount () const; 374 375 376 //------------------------------------------------------------------ 377 /// If \a one_shot is \b true, breakpoint will be deleted on first hit. 378 //------------------------------------------------------------------ 379 void 380 SetOneShot (bool one_shot); 381 382 //------------------------------------------------------------------ 383 /// Check the OneShot state. 384 /// @return 385 /// \b true if the breakpoint is one shot, \b false otherwise. 386 //------------------------------------------------------------------ 387 bool 388 IsOneShot () const; 389 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 //------------------------------------------------------------------ 395 void 396 SetThreadID (lldb::tid_t thread_id); 397 398 //------------------------------------------------------------------ 399 /// Return the current stop thread value. 400 /// @return 401 /// The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads. 402 //------------------------------------------------------------------ 403 lldb::tid_t 404 GetThreadID () const; 405 406 void 407 SetThreadIndex (uint32_t index); 408 409 uint32_t 410 GetThreadIndex() const; 411 412 void 413 SetThreadName (const char *thread_name); 414 415 const char * 416 GetThreadName () const; 417 418 void 419 SetQueueName (const char *queue_name); 420 421 const char * 422 GetQueueName () const; 423 424 //------------------------------------------------------------------ 425 /// Set the callback action invoked when the breakpoint is hit. 426 /// 427 /// @param[in] callback 428 /// The method that will get called when the breakpoint is hit. 429 /// @param[in] baton 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. 435 /// 436 /// @return 437 /// \b true if the process should stop when you hit the breakpoint. 438 /// \b false if it should continue. 439 //------------------------------------------------------------------ 440 void 441 SetCallback (BreakpointHitCallback callback, 442 void *baton, 443 bool is_synchronous = false); 444 445 void 446 SetCallback (BreakpointHitCallback callback, 447 const lldb::BatonSP &callback_baton_sp, 448 bool is_synchronous = false); 449 450 void 451 ClearCallback (); 452 453 //------------------------------------------------------------------ 454 /// Set the breakpoint's condition. 455 /// 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); 461 462 //------------------------------------------------------------------ 463 /// Return a pointer to the text of the condition expression. 464 /// 465 /// @return 466 /// A pointer to the condition expression text, or NULL if no 467 // condition has been set. 468 //------------------------------------------------------------------ 469 const char *GetConditionText () const; 470 471 //------------------------------------------------------------------ 472 // The next section are various utility functions. 473 //------------------------------------------------------------------ 474 475 //------------------------------------------------------------------ 476 /// Return the number of breakpoint locations that have resolved to 477 /// actual breakpoint sites. 478 /// 479 /// @return 480 /// The number locations resolved breakpoint sites. 481 //------------------------------------------------------------------ 482 size_t 483 GetNumResolvedLocations() const; 484 485 //------------------------------------------------------------------ 486 /// Return the number of breakpoint locations. 487 /// 488 /// @return 489 /// The number breakpoint locations. 490 //------------------------------------------------------------------ 491 size_t 492 GetNumLocations() const; 493 494 //------------------------------------------------------------------ 495 /// Put a description of this breakpoint into the stream \a s. 496 /// 497 /// @param[in] s 498 /// Stream into which to dump the description. 499 /// 500 /// @param[in] level 501 /// The description level that indicates the detail level to 502 /// provide. 503 /// 504 /// @see lldb::DescriptionLevel 505 //------------------------------------------------------------------ 506 void 507 GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false); 508 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. 514 /// 515 /// @param[in] kind 516 /// New "kind" description. 517 //------------------------------------------------------------------ 518 void 519 SetBreakpointKind (const char *kind) 520 { 521 m_kind_description.assign (kind); 522 } 523 524 //------------------------------------------------------------------ 525 /// Return the "kind" description for a breakpoint. 526 /// 527 /// @return 528 /// The breakpoint kind, or NULL if none is set. 529 //------------------------------------------------------------------ 530 const char *GetBreakpointKind () const 531 { 532 return m_kind_description.c_str(); 533 } 534 535 //------------------------------------------------------------------ 536 /// Accessor for the breakpoint Target. 537 /// @return 538 /// This breakpoint's Target. 539 //------------------------------------------------------------------ 540 Target & 541 GetTarget (); 542 543 const Target & 544 GetTarget () const; 545 546 void 547 GetResolverDescription (Stream *s); 548 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. 553 /// 554 /// @return 555 /// True if there is a match 556 /// 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 559 /// description. 560 //------------------------------------------------------------------ 561 bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number, 562 BreakpointLocationCollection &loc_coll); 563 564 void 565 GetFilterDescription (Stream *s); 566 567 //------------------------------------------------------------------ 568 /// Returns the BreakpointOptions structure set at the breakpoint level. 569 /// 570 /// Meant to be used by the BreakpointLocation class. 571 /// 572 /// @return 573 /// A pointer to this breakpoint's BreakpointOptions. 574 //------------------------------------------------------------------ 575 BreakpointOptions * 576 GetOptions (); 577 578 579 //------------------------------------------------------------------ 580 /// Invoke the callback action when the breakpoint is hit. 581 /// 582 /// Meant to be used by the BreakpointLocation class. 583 /// 584 /// @param[in] context 585 /// Described the breakpoint event. 586 /// 587 /// @param[in] bp_loc_id 588 /// Which breakpoint location hit this breakpoint. 589 /// 590 /// @return 591 /// \b true if the target should stop at this breakpoint and \b false not. 592 //------------------------------------------------------------------ 593 bool 594 InvokeCallback (StoppointCallbackContext *context, 595 lldb::break_id_t bp_loc_id); 596 597 bool 598 IsHardware() const 599 { 600 return m_hardware; 601 } 602 603protected: 604 friend class Target; 605 //------------------------------------------------------------------ 606 // Protected Methods 607 //------------------------------------------------------------------ 608 609 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. 615 /// 616 /// @param[in] target 617 /// The target in which the breakpoint will be set. 618 /// 619 /// @param[in] filter_sp 620 /// Shared pointer to the search filter that restricts the search domain of the breakpoint. 621 /// 622 /// @param[in] resolver_sp 623 /// Shared pointer to the resolver object that will determine breakpoint matches. 624 /// 625 /// @param hardware 626 /// If true, request a hardware breakpoint to be used to implement the breakpoint locations. 627 /// 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, 637 bool hardware, 638 bool resolve_indirect_symbols = true); 639 640 friend class BreakpointLocation; // To call the following two when determining whether to stop. 641 642 void 643 DecrementIgnoreCount(); 644 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. 648 649 bool 650 IgnoreCountShouldStop (); 651 652private: 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; 665 666 void 667 SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind); 668 669 void 670 SendBreakpointChangedEvent (BreakpointEventData *data); 671 672 DISALLOW_COPY_AND_ASSIGN(Breakpoint); 673}; 674 675} // namespace lldb_private 676 677#endif // liblldb_Breakpoint_h_ 678