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 25 namespace 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 //---------------------------------------------------------------------- 76 class Breakpoint: 77 public std::enable_shared_from_this<Breakpoint>, 78 public Stoppoint 79 { 80 public: 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 & GetBreakpointLocationCollection()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 // The next section deals with various breakpoint options. 317 //------------------------------------------------------------------ 318 319 //------------------------------------------------------------------ 320 /// If \a enable is \b true, enable the breakpoint, if \b false disable it. 321 //------------------------------------------------------------------ 322 void 323 SetEnabled (bool enable); 324 325 //------------------------------------------------------------------ 326 /// Check the Enable/Disable state. 327 /// @return 328 /// \b true if the breakpoint is enabled, \b false if disabled. 329 //------------------------------------------------------------------ 330 bool 331 IsEnabled (); 332 333 //------------------------------------------------------------------ 334 /// Set the breakpoint to ignore the next \a count breakpoint hits. 335 /// @param[in] count 336 /// The number of breakpoint hits to ignore. 337 //------------------------------------------------------------------ 338 void 339 SetIgnoreCount (uint32_t count); 340 341 //------------------------------------------------------------------ 342 /// Return the current ignore count/ 343 /// @return 344 /// The number of breakpoint hits to be ignored. 345 //------------------------------------------------------------------ 346 uint32_t 347 GetIgnoreCount () const; 348 349 //------------------------------------------------------------------ 350 /// Return the current hit count for all locations. 351 /// @return 352 /// The current hit count for all locations. 353 //------------------------------------------------------------------ 354 uint32_t 355 GetHitCount () const; 356 357 358 //------------------------------------------------------------------ 359 /// If \a one_shot is \b true, breakpoint will be deleted on first hit. 360 //------------------------------------------------------------------ 361 void 362 SetOneShot (bool one_shot); 363 364 //------------------------------------------------------------------ 365 /// Check the OneShot state. 366 /// @return 367 /// \b true if the breakpoint is one shot, \b false otherwise. 368 //------------------------------------------------------------------ 369 bool 370 IsOneShot () const; 371 372 //------------------------------------------------------------------ 373 /// Set the valid thread to be checked when the breakpoint is hit. 374 /// @param[in] thread_id 375 /// If this thread hits the breakpoint, we stop, otherwise not. 376 //------------------------------------------------------------------ 377 void 378 SetThreadID (lldb::tid_t thread_id); 379 380 //------------------------------------------------------------------ 381 /// Return the current stop thread value. 382 /// @return 383 /// The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads. 384 //------------------------------------------------------------------ 385 lldb::tid_t 386 GetThreadID () const; 387 388 void 389 SetThreadIndex (uint32_t index); 390 391 uint32_t 392 GetThreadIndex() const; 393 394 void 395 SetThreadName (const char *thread_name); 396 397 const char * 398 GetThreadName () const; 399 400 void 401 SetQueueName (const char *queue_name); 402 403 const char * 404 GetQueueName () const; 405 406 //------------------------------------------------------------------ 407 /// Set the callback action invoked when the breakpoint is hit. 408 /// 409 /// @param[in] callback 410 /// The method that will get called when the breakpoint is hit. 411 /// @param[in] baton 412 /// A void * pointer that will get passed back to the callback function. 413 /// @param[in] is_synchronous 414 /// If \b true the callback will be run on the private event thread 415 /// before the stop event gets reported. If false, the callback will get 416 /// handled on the public event thead after the stop has been posted. 417 /// 418 /// @return 419 /// \b true if the process should stop when you hit the breakpoint. 420 /// \b false if it should continue. 421 //------------------------------------------------------------------ 422 void 423 SetCallback (BreakpointHitCallback callback, 424 void *baton, 425 bool is_synchronous = false); 426 427 void 428 SetCallback (BreakpointHitCallback callback, 429 const lldb::BatonSP &callback_baton_sp, 430 bool is_synchronous = false); 431 432 void 433 ClearCallback (); 434 435 //------------------------------------------------------------------ 436 /// Set the breakpoint's condition. 437 /// 438 /// @param[in] condition 439 /// The condition expression to evaluate when the breakpoint is hit. 440 /// Pass in NULL to clear the condition. 441 //------------------------------------------------------------------ 442 void SetCondition (const char *condition); 443 444 //------------------------------------------------------------------ 445 /// Return a pointer to the text of the condition expression. 446 /// 447 /// @return 448 /// A pointer to the condition expression text, or NULL if no 449 // condition has been set. 450 //------------------------------------------------------------------ 451 const char *GetConditionText () const; 452 453 //------------------------------------------------------------------ 454 // The next section are various utility functions. 455 //------------------------------------------------------------------ 456 457 //------------------------------------------------------------------ 458 /// Return the number of breakpoint locations that have resolved to 459 /// actual breakpoint sites. 460 /// 461 /// @return 462 /// The number locations resolved breakpoint sites. 463 //------------------------------------------------------------------ 464 size_t 465 GetNumResolvedLocations() const; 466 467 //------------------------------------------------------------------ 468 /// Return the number of breakpoint locations. 469 /// 470 /// @return 471 /// The number breakpoint locations. 472 //------------------------------------------------------------------ 473 size_t 474 GetNumLocations() const; 475 476 //------------------------------------------------------------------ 477 /// Put a description of this breakpoint into the stream \a s. 478 /// 479 /// @param[in] s 480 /// Stream into which to dump the description. 481 /// 482 /// @param[in] level 483 /// The description level that indicates the detail level to 484 /// provide. 485 /// 486 /// @see lldb::DescriptionLevel 487 //------------------------------------------------------------------ 488 void 489 GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false); 490 491 //------------------------------------------------------------------ 492 /// Set the "kind" description for a breakpoint. If the breakpoint is hit 493 /// the stop info will show this "kind" description instead of the breakpoint 494 /// number. Mostly useful for internal breakpoints, where the breakpoint number 495 /// doesn't have meaning to the user. 496 /// 497 /// @param[in] kind 498 /// New "kind" description. 499 //------------------------------------------------------------------ 500 void SetBreakpointKind(const char * kind)501 SetBreakpointKind (const char *kind) 502 { 503 m_kind_description.assign (kind); 504 } 505 506 //------------------------------------------------------------------ 507 /// Return the "kind" description for a breakpoint. 508 /// 509 /// @return 510 /// The breakpoint kind, or NULL if none is set. 511 //------------------------------------------------------------------ GetBreakpointKind()512 const char *GetBreakpointKind () const 513 { 514 return m_kind_description.c_str(); 515 } 516 517 //------------------------------------------------------------------ 518 /// Accessor for the breakpoint Target. 519 /// @return 520 /// This breakpoint's Target. 521 //------------------------------------------------------------------ 522 Target & 523 GetTarget (); 524 525 const Target & 526 GetTarget () const; 527 528 void 529 GetResolverDescription (Stream *s); 530 531 //------------------------------------------------------------------ 532 /// Find breakpoint locations which match the (filename, line_number) description. 533 /// The breakpoint location collection is to be filled with the matching locations. 534 /// It should be initialized with 0 size by the API client. 535 /// 536 /// @return 537 /// True if there is a match 538 /// 539 /// The locations which match the filename and line_number in loc_coll. If its 540 /// size is 0 and true is returned, it means the breakpoint fully matches the 541 /// description. 542 //------------------------------------------------------------------ 543 bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number, 544 BreakpointLocationCollection &loc_coll); 545 546 void 547 GetFilterDescription (Stream *s); 548 549 //------------------------------------------------------------------ 550 /// Returns the BreakpointOptions structure set at the breakpoint level. 551 /// 552 /// Meant to be used by the BreakpointLocation class. 553 /// 554 /// @return 555 /// A pointer to this breakpoint's BreakpointOptions. 556 //------------------------------------------------------------------ 557 BreakpointOptions * 558 GetOptions (); 559 560 561 //------------------------------------------------------------------ 562 /// Invoke the callback action when the breakpoint is hit. 563 /// 564 /// Meant to be used by the BreakpointLocation class. 565 /// 566 /// @param[in] context 567 /// Described the breakpoint event. 568 /// 569 /// @param[in] bp_loc_id 570 /// Which breakpoint location hit this breakpoint. 571 /// 572 /// @return 573 /// \b true if the target should stop at this breakpoint and \b false not. 574 //------------------------------------------------------------------ 575 bool 576 InvokeCallback (StoppointCallbackContext *context, 577 lldb::break_id_t bp_loc_id); 578 579 protected: 580 friend class Target; 581 //------------------------------------------------------------------ 582 // Protected Methods 583 //------------------------------------------------------------------ 584 585 586 //------------------------------------------------------------------ 587 /// Constructors and Destructors 588 /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans. 589 /// The constructor takes a filter and a resolver. Up in Target there are convenience 590 /// variants that make breakpoints for some common cases. 591 //------------------------------------------------------------------ 592 // This is the generic constructor 593 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp, lldb::BreakpointResolverSP &resolver_sp); 594 595 friend class BreakpointLocation; // To call the following two when determining whether to stop. 596 597 void 598 DecrementIgnoreCount(); 599 600 // BreakpointLocation::IgnoreCountShouldStop & Breakpoint::IgnoreCountShouldStop can only be called once per stop, 601 // and BreakpointLocation::IgnoreCountShouldStop should be tested first, and if it returns false we should 602 // continue, otherwise we should test Breakpoint::IgnoreCountShouldStop. 603 604 bool 605 IgnoreCountShouldStop (); 606 607 private: 608 //------------------------------------------------------------------ 609 // For Breakpoint only 610 //------------------------------------------------------------------ 611 bool m_being_created; 612 Target &m_target; // The target that holds this breakpoint. 613 lldb::SearchFilterSP m_filter_sp; // The filter that constrains the breakpoint's domain. 614 lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint. 615 BreakpointOptions m_options; // Settable breakpoint options 616 BreakpointLocationList m_locations; // The list of locations currently found for this breakpoint. 617 std::string m_kind_description; 618 619 void 620 SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind); 621 622 void 623 SendBreakpointChangedEvent (BreakpointEventData *data); 624 625 DISALLOW_COPY_AND_ASSIGN(Breakpoint); 626 }; 627 628 } // namespace lldb_private 629 630 #endif // liblldb_Breakpoint_h_ 631