Breakpoint.h revision 598df88bd6fc33c6fb330bc859bdc277795501f3
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 uint32_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] changedModules 207 /// The list of modules to look in for new locations. 208 //------------------------------------------------------------------ 209 void 210 ResolveBreakpointInModules (ModuleList &changedModules); 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 //------------------------------------------------------------------ 223 void 224 ModulesChanged (ModuleList &changedModules, 225 bool load_event); 226 227 228 //------------------------------------------------------------------ 229 // The next set of methods provide access to the breakpoint locations 230 // for this breakpoint. 231 //------------------------------------------------------------------ 232 233 //------------------------------------------------------------------ 234 /// Add a location to the breakpoint's location list. This is only meant 235 /// to be called by the breakpoint's resolver. FIXME: how do I ensure that? 236 /// 237 /// @param[in] addr 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. 242 /// @return 243 /// Returns a pointer to the new location. 244 //------------------------------------------------------------------ 245 lldb::BreakpointLocationSP 246 AddLocation (const Address &addr, 247 bool *new_location = NULL); 248 249 //------------------------------------------------------------------ 250 /// Find a breakpoint location by Address. 251 /// 252 /// @param[in] addr 253 /// The Address specifying the location. 254 /// @return 255 /// Returns a shared pointer to the location at \a addr. The pointer 256 /// in the shared pointer will be NULL if there is no location at that address. 257 //------------------------------------------------------------------ 258 lldb::BreakpointLocationSP 259 FindLocationByAddress (const Address &addr); 260 261 //------------------------------------------------------------------ 262 /// Find a breakpoint location ID by Address. 263 /// 264 /// @param[in] addr 265 /// The Address specifying the location. 266 /// @return 267 /// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if 268 /// there is no breakpoint location at that address. 269 //------------------------------------------------------------------ 270 lldb::break_id_t 271 FindLocationIDByAddress (const Address &addr); 272 273 //------------------------------------------------------------------ 274 /// Find a breakpoint location for a given breakpoint location ID. 275 /// 276 /// @param[in] bp_loc_id 277 /// The ID specifying the location. 278 /// @return 279 /// Returns a shared pointer to the location with ID \a bp_loc_id. The pointer 280 /// in the shared pointer will be NULL if there is no location with that ID. 281 //------------------------------------------------------------------ 282 lldb::BreakpointLocationSP 283 FindLocationByID (lldb::break_id_t bp_loc_id); 284 285 //------------------------------------------------------------------ 286 /// Get breakpoint locations by index. 287 /// 288 /// @param[in] index 289 /// The location index. 290 /// 291 /// @return 292 /// Returns a shared pointer to the location with index \a 293 /// index. The shared pointer might contain NULL if \a index is 294 /// greater than then number of actual locations. 295 //------------------------------------------------------------------ 296 lldb::BreakpointLocationSP 297 GetLocationAtIndex (uint32_t index); 298 299 //------------------------------------------------------------------ 300 // The next section deals with various breakpoint options. 301 //------------------------------------------------------------------ 302 303 //------------------------------------------------------------------ 304 /// If \a enable is \b true, enable the breakpoint, if \b false disable it. 305 //------------------------------------------------------------------ 306 void 307 SetEnabled (bool enable); 308 309 //------------------------------------------------------------------ 310 /// Check the Enable/Disable state. 311 /// @return 312 /// \b true if the breakpoint is enabled, \b false if disabled. 313 //------------------------------------------------------------------ 314 bool 315 IsEnabled (); 316 317 //------------------------------------------------------------------ 318 /// Set the breakpoint to ignore the next \a count breakpoint hits. 319 /// @param[in] count 320 /// The number of breakpoint hits to ignore. 321 //------------------------------------------------------------------ 322 void 323 SetIgnoreCount (uint32_t count); 324 325 //------------------------------------------------------------------ 326 /// Return the current ignore count/ 327 /// @return 328 /// The number of breakpoint hits to be ignored. 329 //------------------------------------------------------------------ 330 uint32_t 331 GetIgnoreCount () const; 332 333 //------------------------------------------------------------------ 334 /// Return the current hit count for all locations. 335 /// @return 336 /// The current hit count for all locations. 337 //------------------------------------------------------------------ 338 uint32_t 339 GetHitCount () const; 340 341 342 //------------------------------------------------------------------ 343 /// Set the valid thread to be checked when the breakpoint is hit. 344 /// @param[in] thread_id 345 /// If this thread hits the breakpoint, we stop, otherwise not. 346 //------------------------------------------------------------------ 347 void 348 SetThreadID (lldb::tid_t thread_id); 349 350 //------------------------------------------------------------------ 351 /// Return the current stop thread value. 352 /// @return 353 /// The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads. 354 //------------------------------------------------------------------ 355 lldb::tid_t 356 GetThreadID () const; 357 358 void 359 SetThreadIndex (uint32_t index); 360 361 uint32_t 362 GetThreadIndex() const; 363 364 void 365 SetThreadName (const char *thread_name); 366 367 const char * 368 GetThreadName () const; 369 370 void 371 SetQueueName (const char *queue_name); 372 373 const char * 374 GetQueueName () const; 375 376 //------------------------------------------------------------------ 377 /// Set the callback action invoked when the breakpoint is hit. 378 /// 379 /// @param[in] callback 380 /// The method that will get called when the breakpoint is hit. 381 /// @param[in] baton 382 /// A void * pointer that will get passed back to the callback function. 383 /// @param[in] is_synchronous 384 /// If \b true the callback will be run on the private event thread 385 /// before the stop event gets reported. If false, the callback will get 386 /// handled on the public event thead after the stop has been posted. 387 /// 388 /// @return 389 /// \b true if the process should stop when you hit the breakpoint. 390 /// \b false if it should continue. 391 //------------------------------------------------------------------ 392 void 393 SetCallback (BreakpointHitCallback callback, 394 void *baton, 395 bool is_synchronous = false); 396 397 void 398 SetCallback (BreakpointHitCallback callback, 399 const lldb::BatonSP &callback_baton_sp, 400 bool is_synchronous = false); 401 402 void 403 ClearCallback (); 404 405 //------------------------------------------------------------------ 406 /// Set the breakpoint's condition. 407 /// 408 /// @param[in] condition 409 /// The condition expression to evaluate when the breakpoint is hit. 410 /// Pass in NULL to clear the condition. 411 //------------------------------------------------------------------ 412 void SetCondition (const char *condition); 413 414 //------------------------------------------------------------------ 415 /// Test the breakpoint condition in the Execution context passed in. 416 /// 417 /// @param[in] exe_ctx 418 /// The execution context in which to evaluate this expression. 419 /// 420 /// @param[in] break_loc_sp 421 /// A shared pointer to the location that we are testing thsi condition for. 422 /// 423 /// @param[in] error 424 /// Error messages will be written to this stream. 425 /// 426 /// @return 427 /// A thread plan to run to test the condition or NULL if no condition. 428 //------------------------------------------------------------------ 429 ThreadPlan *GetThreadPlanToTestCondition (ExecutionContext &exe_ctx, 430 lldb::BreakpointLocationSP break_loc_sp, 431 Stream &error); 432 433 //------------------------------------------------------------------ 434 /// Return a pointer to the text of the condition expression. 435 /// 436 /// @return 437 /// A pointer to the condition expression text, or NULL if no 438 // condition has been set. 439 //------------------------------------------------------------------ 440 const char *GetConditionText () const; 441 442 //------------------------------------------------------------------ 443 // The next section are various utility functions. 444 //------------------------------------------------------------------ 445 446 //------------------------------------------------------------------ 447 /// Return the number of breakpoint locations that have resolved to 448 /// actual breakpoint sites. 449 /// 450 /// @return 451 /// The number locations resolved breakpoint sites. 452 //------------------------------------------------------------------ 453 size_t 454 GetNumResolvedLocations() const; 455 456 //------------------------------------------------------------------ 457 /// Return the number of breakpoint locations. 458 /// 459 /// @return 460 /// The number breakpoint locations. 461 //------------------------------------------------------------------ 462 size_t 463 GetNumLocations() const; 464 465 //------------------------------------------------------------------ 466 /// Put a description of this breakpoint into the stream \a s. 467 /// 468 /// @param[in] s 469 /// Stream into which to dump the description. 470 /// 471 /// @param[in] level 472 /// The description level that indicates the detail level to 473 /// provide. 474 /// 475 /// @see lldb::DescriptionLevel 476 //------------------------------------------------------------------ 477 void 478 GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false); 479 480 //------------------------------------------------------------------ 481 /// Accessor for the breakpoint Target. 482 /// @return 483 /// This breakpoint's Target. 484 //------------------------------------------------------------------ 485 Target & 486 GetTarget (); 487 488 const Target & 489 GetTarget () const; 490 491 void 492 GetResolverDescription (Stream *s); 493 494 //------------------------------------------------------------------ 495 /// Find breakpoint locations which match the (filename, line_number) description. 496 /// The breakpoint location collection is to be filled with the matching locations. 497 /// It should be initialized with 0 size by the API client. 498 /// 499 /// @return 500 /// True if there is a match 501 /// 502 /// The locations which match the filename and line_number in loc_coll. If its 503 /// size is 0 and true is returned, it means the breakpoint fully matches the 504 /// description. 505 //------------------------------------------------------------------ 506 bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number, 507 BreakpointLocationCollection &loc_coll); 508 509 void 510 GetFilterDescription (Stream *s); 511 512 //------------------------------------------------------------------ 513 /// Returns the BreakpointOptions structure set at the breakpoint level. 514 /// 515 /// Meant to be used by the BreakpointLocation class. 516 /// 517 /// @return 518 /// A pointer to this breakpoint's BreakpointOptions. 519 //------------------------------------------------------------------ 520 BreakpointOptions * 521 GetOptions (); 522 523 524 //------------------------------------------------------------------ 525 /// Invoke the callback action when the breakpoint is hit. 526 /// 527 /// Meant to be used by the BreakpointLocation class. 528 /// 529 /// @param[in] context 530 /// Described the breakpoint event. 531 /// 532 /// @param[in] bp_loc_id 533 /// Which breakpoint location hit this breakpoint. 534 /// 535 /// @return 536 /// \b true if the target should stop at this breakpoint and \b false not. 537 //------------------------------------------------------------------ 538 bool 539 InvokeCallback (StoppointCallbackContext *context, 540 lldb::break_id_t bp_loc_id); 541 542protected: 543 friend class Target; 544 //------------------------------------------------------------------ 545 // Protected Methods 546 //------------------------------------------------------------------ 547 548 549 //------------------------------------------------------------------ 550 /// Constructors and Destructors 551 /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans. 552 /// The constructor takes a filter and a resolver. Up in Target there are convenience 553 /// variants that make breakpoints for some common cases. 554 //------------------------------------------------------------------ 555 // This is the generic constructor 556 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp, lldb::BreakpointResolverSP &resolver_sp); 557 558private: 559 //------------------------------------------------------------------ 560 // For Breakpoint only 561 //------------------------------------------------------------------ 562 bool m_being_created; 563 Target &m_target; // The target that holds this breakpoint. 564 lldb::SearchFilterSP m_filter_sp; // The filter that constrains the breakpoint's domain. 565 lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint. 566 BreakpointOptions m_options; // Settable breakpoint options 567 BreakpointLocationList m_locations; // The list of locations currently found for this breakpoint. 568 569 void 570 SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind); 571 572 void 573 SendBreakpointChangedEvent (BreakpointEventData *data); 574 575 DISALLOW_COPY_AND_ASSIGN(Breakpoint); 576}; 577 578} // namespace lldb_private 579 580#endif // liblldb_Breakpoint_h_ 581