Breakpoint.h revision 643ee7301b5d4b05c321d906bc0d7ff11f571295
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 Stoppoint 78{ 79public: 80 81 static const ConstString & 82 GetEventIdentifier (); 83 84 85 //------------------------------------------------------------------ 86 /// An enum specifying the match style for breakpoint settings. At 87 /// present only used for function name style breakpoints. 88 //------------------------------------------------------------------ 89 typedef enum 90 { 91 Exact, 92 Regexp, 93 Glob 94 } MatchType; 95 96 class BreakpointEventData : 97 public EventData 98 { 99 public: 100 101 static const ConstString & 102 GetFlavorString (); 103 104 virtual const ConstString & 105 GetFlavor () const; 106 107 BreakpointEventData (lldb::BreakpointEventType sub_type, 108 lldb::BreakpointSP &new_breakpoint_sp); 109 110 virtual 111 ~BreakpointEventData(); 112 113 lldb::BreakpointEventType 114 GetBreakpointEventType () const; 115 116 lldb::BreakpointSP & 117 GetBreakpoint (); 118 119 120 virtual void 121 Dump (Stream *s) const; 122 123 static lldb::BreakpointEventType 124 GetBreakpointEventTypeFromEvent (const lldb::EventSP &event_sp); 125 126 static lldb::BreakpointSP 127 GetBreakpointFromEvent (const lldb::EventSP &event_sp); 128 129 static lldb::BreakpointLocationSP 130 GetBreakpointLocationAtIndexFromEvent (const lldb::EventSP &event_sp, uint32_t loc_idx); 131 132 private: 133 static BreakpointEventData * 134 GetEventDataFromEvent (const lldb::EventSP &event_sp); 135 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 144 //------------------------------------------------------------------ 145 /// Destructor. 146 /// 147 /// The destructor is not virtual since there should be no reason to subclass 148 /// breakpoints. The varieties of breakpoints are specified instead by 149 /// providing different resolvers & filters. 150 //------------------------------------------------------------------ 151 ~Breakpoint(); 152 153 //------------------------------------------------------------------ 154 // Methods 155 //------------------------------------------------------------------ 156 157 //------------------------------------------------------------------ 158 /// Tell whether this breakpoint is an "internal" breakpoint. 159 /// @return 160 /// Returns \b true if this is an internal breakpoint, \b false otherwise. 161 //------------------------------------------------------------------ 162 bool 163 IsInternal () const; 164 165 //------------------------------------------------------------------ 166 /// Standard "Dump" method. At present it does nothing. 167 //------------------------------------------------------------------ 168 void 169 Dump (Stream *s); 170 171 //------------------------------------------------------------------ 172 // The next set of methods provide ways to tell the breakpoint to update 173 // it's location list - usually done when modules appear or disappear. 174 //------------------------------------------------------------------ 175 176 177 //------------------------------------------------------------------ 178 /// Tell this breakpoint to clear all its breakpoint sites. Done 179 /// when the process holding the breakpoint sites is destroyed. 180 //------------------------------------------------------------------ 181 void 182 ClearAllBreakpointSites (); 183 184 //------------------------------------------------------------------ 185 /// Tell this breakpoint to scan it's target's module list and resolve any 186 /// new locations that match the breakpoint's specifications. 187 //------------------------------------------------------------------ 188 void 189 ResolveBreakpoint (); 190 191 //------------------------------------------------------------------ 192 /// Tell this breakpoint to scan a given module list and resolve any 193 /// new locations that match the breakpoint's specifications. 194 /// 195 /// @param[in] changedModules 196 /// The list of modules to look in for new locations. 197 //------------------------------------------------------------------ 198 void 199 ResolveBreakpointInModules (ModuleList &changedModules); 200 201 202 //------------------------------------------------------------------ 203 /// Like ResolveBreakpointInModules, but allows for "unload" events, in 204 /// which case we will remove any locations that are in modules that got 205 /// unloaded. 206 /// 207 /// @param[in] changedModules 208 /// The list of modules to look in for new locations. 209 /// @param[in] load_event 210 /// If \b true then the modules were loaded, if \b false, unloaded. 211 //------------------------------------------------------------------ 212 void 213 ModulesChanged (ModuleList &changedModules, 214 bool load_event); 215 216 217 //------------------------------------------------------------------ 218 // The next set of methods provide access to the breakpoint locations 219 // for this breakpoint. 220 //------------------------------------------------------------------ 221 222 //------------------------------------------------------------------ 223 /// Add a location to the breakpoint's location list. This is only meant 224 /// to be called by the breakpoint's resolver. FIXME: how do I ensure that? 225 /// 226 /// @param[in] addr 227 /// The Address specifying the new location. 228 /// @param[out] new_location 229 /// Set to \b true if a new location was created, to \b false if there 230 /// already was a location at this Address. 231 /// @return 232 /// Returns a pointer to the new location. 233 //------------------------------------------------------------------ 234 lldb::BreakpointLocationSP 235 AddLocation (Address &addr, 236 bool *new_location = NULL); 237 238 //------------------------------------------------------------------ 239 /// Find a breakpoint location by Address. 240 /// 241 /// @param[in] addr 242 /// The Address specifying the location. 243 /// @return 244 /// Returns a shared pointer to the location at \a addr. The pointer 245 /// in the shared pointer will be NULL if there is no location at that address. 246 //------------------------------------------------------------------ 247 lldb::BreakpointLocationSP 248 FindLocationByAddress (Address &addr); 249 250 //------------------------------------------------------------------ 251 /// Find a breakpoint location ID by Address. 252 /// 253 /// @param[in] addr 254 /// The Address specifying the location. 255 /// @return 256 /// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if 257 /// there is no breakpoint location at that address. 258 //------------------------------------------------------------------ 259 lldb::break_id_t 260 FindLocationIDByAddress (Address &addr); 261 262 //------------------------------------------------------------------ 263 /// Find a breakpoint location for a given breakpoint location ID. 264 /// 265 /// @param[in] bp_loc_id 266 /// The ID specifying the location. 267 /// @return 268 /// Returns a shared pointer to the location with ID \a bp_loc_id. The pointer 269 /// in the shared pointer will be NULL if there is no location with that ID. 270 //------------------------------------------------------------------ 271 lldb::BreakpointLocationSP 272 FindLocationByID (lldb::break_id_t bp_loc_id); 273 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 NULL if \a index is 283 /// greater than then number of actual locations. 284 //------------------------------------------------------------------ 285 lldb::BreakpointLocationSP 286 GetLocationAtIndex (uint32_t index); 287 288 289 const lldb::BreakpointSP 290 GetSP (); 291 292 //------------------------------------------------------------------ 293 // The next section deals with various breakpoint options. 294 //------------------------------------------------------------------ 295 296 //------------------------------------------------------------------ 297 /// If \a enable is \b true, enable the breakpoint, if \b false disable it. 298 //------------------------------------------------------------------ 299 void 300 SetEnabled (bool enable); 301 302 //------------------------------------------------------------------ 303 /// Check the Enable/Disable state. 304 /// @return 305 /// \b true if the breakpoint is enabled, \b false if disabled. 306 //------------------------------------------------------------------ 307 bool 308 IsEnabled (); 309 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 //------------------------------------------------------------------ 315 void 316 SetIgnoreCount (uint32_t count); 317 318 //------------------------------------------------------------------ 319 /// Return the current ignore count/ 320 /// @return 321 /// The number of breakpoint hits to be ignored. 322 //------------------------------------------------------------------ 323 uint32_t 324 GetIgnoreCount () const; 325 326 //------------------------------------------------------------------ 327 /// Return the current hit count for all locations. 328 /// @return 329 /// The current hit count for all locations. 330 //------------------------------------------------------------------ 331 uint32_t 332 GetHitCount () const; 333 334 335 //------------------------------------------------------------------ 336 /// Set the valid thread to be checked when the breakpoint is hit. 337 /// @param[in] thread_id 338 /// If this thread hits the breakpoint, we stop, otherwise not. 339 //------------------------------------------------------------------ 340 void 341 SetThreadID (lldb::tid_t thread_id); 342 343 //------------------------------------------------------------------ 344 /// Return the current stop thread value. 345 /// @return 346 /// The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads. 347 //------------------------------------------------------------------ 348 lldb::tid_t 349 GetThreadID (); 350 351 //------------------------------------------------------------------ 352 /// Set the callback action invoked when the breakpoint is hit. The callback 353 /// Will return a bool indicating whether the target should stop at this breakpoint or not. 354 /// @param[in] callback 355 /// The method that will get called when the breakpoint is hit. 356 /// @param[in] baton 357 /// A void * pointer that will get passed back to the callback function. 358 //------------------------------------------------------------------ 359 void 360 SetCallback (BreakpointHitCallback callback, 361 void *baton, 362 bool is_synchronous = false); 363 364 void 365 SetCallback (BreakpointHitCallback callback, 366 const lldb::BatonSP &callback_baton_sp, 367 bool is_synchronous = false); 368 369 void 370 ClearCallback (); 371 372 //------------------------------------------------------------------ 373 /// Set the condition expression to be checked when the breakpoint is hit. 374 /// @param[in] expression 375 /// The method that will get called when the breakpoint is hit. 376 //------------------------------------------------------------------ 377 void 378 SetCondition (void *expression); 379 380 //------------------------------------------------------------------ 381 // The next section are various utility functions. 382 //------------------------------------------------------------------ 383 384 //------------------------------------------------------------------ 385 /// Return the number of breakpoint locations that have resolved to 386 /// actual breakpoint sites. 387 /// 388 /// @return 389 /// The number locations resolved breakpoint sites. 390 //------------------------------------------------------------------ 391 size_t 392 GetNumResolvedLocations() const; 393 394 //------------------------------------------------------------------ 395 /// Return the number of breakpoint locations. 396 /// 397 /// @return 398 /// The number breakpoint locations. 399 //------------------------------------------------------------------ 400 size_t 401 GetNumLocations() const; 402 403 //------------------------------------------------------------------ 404 /// Put a description of this breakpoint into the stream \a s. 405 /// 406 /// @param[in] s 407 /// Stream into which to dump the description. 408 /// 409 /// @param[in] level 410 /// The description level that indicates the detail level to 411 /// provide. 412 /// 413 /// @see lldb::DescriptionLevel 414 //------------------------------------------------------------------ 415 void 416 GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false); 417 418 //------------------------------------------------------------------ 419 /// Accessor for the breakpoint Target. 420 /// @return 421 /// This breakpoint's Target. 422 //------------------------------------------------------------------ 423 Target & 424 GetTarget (); 425 426 const Target & 427 GetTarget () const; 428 429 void 430 GetResolverDescription (Stream *s); 431 432 void 433 GetFilterDescription (Stream *s); 434 435 //------------------------------------------------------------------ 436 /// Returns the BreakpointOptions structure set at the breakpoint level. 437 /// 438 /// Meant to be used by the BreakpointLocation class. 439 /// 440 /// @return 441 /// A pointer to this breakpoint's BreakpointOptions. 442 //------------------------------------------------------------------ 443 BreakpointOptions * 444 GetOptions (); 445 446 447 //------------------------------------------------------------------ 448 /// Invoke the callback action when the breakpoint is hit. 449 /// 450 /// Meant to be used by the BreakpointLocation class. 451 /// 452 /// @param[in] context 453 /// Described the breakpoint event. 454 /// 455 /// @param[in] bp_loc_id 456 /// Which breakpoint location hit this breakpoint. 457 /// 458 /// @return 459 /// \b true if the target should stop at this breakpoint and \b false not. 460 //------------------------------------------------------------------ 461 bool 462 InvokeCallback (StoppointCallbackContext *context, 463 lldb::break_id_t bp_loc_id); 464 465 //------------------------------------------------------------------ 466 /// Returns the shared pointer that this breakpoint holds for the 467 /// breakpoint location passed in as \a bp_loc_ptr. Passing in a 468 /// breakpoint location that doesn't belong to this breakpoint will 469 /// cause an assert. 470 /// 471 /// Meant to be used by the BreakpointLocation::GetSP() function. 472 /// 473 /// @return 474 /// A copy of the shared pointer for the given location. 475 //------------------------------------------------------------------ 476 lldb::BreakpointLocationSP 477 GetLocationSP (BreakpointLocation *bp_loc_ptr); 478 479 480protected: 481 friend class Target; 482 //------------------------------------------------------------------ 483 // Protected Methods 484 //------------------------------------------------------------------ 485 486 487 //------------------------------------------------------------------ 488 /// Constructors and Destructors 489 /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans. 490 /// The constructor takes a filter and a resolver. Up in Target there are convenience 491 /// variants that make breakpoints for some common cases. 492 //------------------------------------------------------------------ 493 // This is the generic constructor 494 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp, lldb::BreakpointResolverSP &resolver_sp); 495 496private: 497 //------------------------------------------------------------------ 498 // For Breakpoint only 499 //------------------------------------------------------------------ 500 Target &m_target; // The target that holds this breakpoint. 501 lldb::SearchFilterSP m_filter_sp; // The filter that constrains the breakpoint's domain. 502 lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint. 503 BreakpointOptions m_options; // Settable breakpoint options 504 BreakpointLocationList m_locations; // The list of locations currently found for this breakpoint. 505 506 DISALLOW_COPY_AND_ASSIGN(Breakpoint); 507}; 508 509} // namespace lldb_private 510 511#endif // liblldb_Breakpoint_h_ 512