Breakpoint.h revision c7f5d5c3a3b48869f5ad2a3cdc4b20ca40929ba3
1521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o//===-- Breakpoint.h --------------------------------------------*- C++ -*-===// 2521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// 3521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// The LLVM Compiler Infrastructure 4521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// 5521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// This file is distributed under the University of Illinois Open Source 6521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// License. See LICENSE.TXT for details. 7521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// 8521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o//===----------------------------------------------------------------------===// 9521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o 10521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#ifndef liblldb_Breakpoint_h_ 11521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#define liblldb_Breakpoint_h_ 12521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o 13521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// C Includes 14521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// C++ Includes 15521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// Other libraries and framework includes 16521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o// Project includes 17521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#include "lldb/Breakpoint/BreakpointLocationList.h" 18521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#include "lldb/Breakpoint/BreakpointOptions.h" 19521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#include "lldb/Breakpoint/BreakpointLocationCollection.h" 20521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#include "lldb/Breakpoint/Stoppoint.h" 21521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#include "lldb/Core/SearchFilter.h" 22521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#include "lldb/Core/Event.h" 23521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o#include "lldb/Core/StringList.h" 24521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o 25521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'onamespace lldb_private { 26521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o 27521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o//---------------------------------------------------------------------- 28521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" 29521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// @brief Class that manages logical breakpoint setting. 30521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o//---------------------------------------------------------------------- 31521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o 32521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o//---------------------------------------------------------------------- 33521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// General Outline: 34521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// A breakpoint has four main parts, a filter, a resolver, the list of breakpoint 352ecc6fefa176f3203598225eb9ae2f61c3ae9c10Theodore Ts'o/// locations that have been determined for the filter/resolver pair, and finally 36521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// a set of options for the breakpoint. 37521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// 38521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// \b Filter: 39521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// This is an object derived from SearchFilter. It manages the search 40521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// for breakpoint location matches through the symbols in the module list of the target 41521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// that owns it. It also filters out locations based on whatever logic it wants. 42521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// 43521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// \b Resolver: 44521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// This is an object derived from BreakpointResolver. It provides a 45521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// callback to the filter that will find breakpoint locations. How it does this is 46521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// determined by what kind of resolver it is. 47521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// 48521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// The Breakpoint class also provides constructors for the common breakpoint cases 49521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// which make the appropriate filter and resolver for you. 50521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// 51521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// \b Location List: 52521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// This stores the breakpoint locations that have been determined 53521e36857227b21e7ab47b0a97f788d2af9f9717Theodore Ts'o/// 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 447protected: 448 friend class Target; 449 friend class BreakpointLocation; // To call InvokeCallback 450 //------------------------------------------------------------------ 451 /// Constructors and Destructors 452 /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans. 453 /// The constructor takes a filter and a resolver. Up in Target there are convenience 454 /// variants that make breakpoints for some common cases. 455 //------------------------------------------------------------------ 456 // This is the generic constructor 457 Breakpoint(Target &target, lldb::SearchFilterSP &filter_sp, lldb::BreakpointResolverSP &resolver_sp); 458 459 //------------------------------------------------------------------ 460 // Protected Methods 461 //------------------------------------------------------------------ 462 463 //------------------------------------------------------------------ 464 /// Invoke the callback action when the breakpoint is hit. 465 /// 466 /// Meant to be used by the BreakpointLocation class. 467 /// 468 /// @param[in] context 469 /// Described the breakpoint event. 470 /// 471 /// @param[in] bp_loc_id 472 /// Which breakpoint location hit this breakpoint. 473 /// 474 /// @return 475 /// \b true if the target should stop at this breakpoint and \b false not. 476 //------------------------------------------------------------------ 477 bool 478 InvokeCallback (StoppointCallbackContext *context, 479 lldb::break_id_t bp_loc_id); 480 481protected: 482 483 //------------------------------------------------------------------ 484 /// Returns the shared pointer that this breakpoint holds for the 485 /// breakpoint location passed in as \a bp_loc_ptr. Passing in a 486 /// breakpoint location that doesn't belong to this breakpoint will 487 /// cause an assert. 488 /// 489 /// Meant to be used by the BreakpointLocation::GetSP() function. 490 /// 491 /// @return 492 /// A copy of the shared pointer for the given location. 493 //------------------------------------------------------------------ 494 lldb::BreakpointLocationSP 495 GetLocationSP (BreakpointLocation *bp_loc_ptr); 496 497private: 498 //------------------------------------------------------------------ 499 // For Breakpoint only 500 //------------------------------------------------------------------ 501 Target &m_target; // The target that holds this breakpoint. 502 lldb::SearchFilterSP m_filter_sp; // The filter that constrains the breakpoint's domain. 503 lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint. 504 BreakpointOptions m_options; // Settable breakpoint options 505 BreakpointLocationList m_locations; // The list of locations currently found for this breakpoint. 506 507 DISALLOW_COPY_AND_ASSIGN(Breakpoint); 508}; 509 510} // namespace lldb_private 511 512#endif // liblldb_Breakpoint_h_ 513