/usr/lib/llvm-3.4/include/lldb/Breakpoint/Breakpoint.h is in liblldb-3.4-dev 1:3.4.2-13.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 | //===-- Breakpoint.h --------------------------------------------*- C++ -*-===//
//
// The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
#ifndef liblldb_Breakpoint_h_
#define liblldb_Breakpoint_h_
// C Includes
// C++ Includes
// Other libraries and framework includes
// Project includes
#include "lldb/Breakpoint/BreakpointLocationList.h"
#include "lldb/Breakpoint/BreakpointOptions.h"
#include "lldb/Breakpoint/BreakpointLocationCollection.h"
#include "lldb/Breakpoint/Stoppoint.h"
#include "lldb/Core/SearchFilter.h"
#include "lldb/Core/Event.h"
#include "lldb/Core/StringList.h"
namespace lldb_private {
//----------------------------------------------------------------------
/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h"
/// @brief Class that manages logical breakpoint setting.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
/// General Outline:
/// A breakpoint has four main parts, a filter, a resolver, the list of breakpoint
/// locations that have been determined for the filter/resolver pair, and finally
/// a set of options for the breakpoint.
///
/// \b Filter:
/// This is an object derived from SearchFilter. It manages the search
/// for breakpoint location matches through the symbols in the module list of the target
/// that owns it. It also filters out locations based on whatever logic it wants.
///
/// \b Resolver:
/// This is an object derived from BreakpointResolver. It provides a
/// callback to the filter that will find breakpoint locations. How it does this is
/// determined by what kind of resolver it is.
///
/// The Breakpoint class also provides constructors for the common breakpoint cases
/// which make the appropriate filter and resolver for you.
///
/// \b Location List:
/// This stores the breakpoint locations that have been determined
/// to date. For a given breakpoint, there will be only one location with a given
/// address. Adding a location at an already taken address will just return the location
/// already at that address. Locations can be looked up by ID, or by address.
///
/// \b Options:
/// This includes:
/// \b Enabled/Disabled
/// \b Ignore Count
/// \b Callback
/// \b Condition
/// Note, these options can be set on the breakpoint, and they can also be set on the
/// individual locations. The options set on the breakpoint take precedence over the
/// options set on the individual location.
/// So for instance disabling the breakpoint will cause NONE of the locations to get hit.
/// But if the breakpoint is enabled, then the location's enabled state will be checked
/// to determine whether to insert that breakpoint location.
/// Similarly, if the breakpoint condition says "stop", we won't check the location's condition.
/// But if the breakpoint condition says "continue", then we will check the location for whether
/// to actually stop or not.
/// One subtle point worth observing here is that you don't actually stop at a Breakpoint, you
/// always stop at one of its locations. So the "should stop" tests are done by the location,
/// not by the breakpoint.
//----------------------------------------------------------------------
class Breakpoint:
public std::enable_shared_from_this<Breakpoint>,
public Stoppoint
{
public:
static const ConstString &
GetEventIdentifier ();
//------------------------------------------------------------------
/// An enum specifying the match style for breakpoint settings. At
/// present only used for function name style breakpoints.
//------------------------------------------------------------------
typedef enum
{
Exact,
Regexp,
Glob
} MatchType;
class BreakpointEventData :
public EventData
{
public:
static const ConstString &
GetFlavorString ();
virtual const ConstString &
GetFlavor () const;
BreakpointEventData (lldb::BreakpointEventType sub_type,
const lldb::BreakpointSP &new_breakpoint_sp);
virtual
~BreakpointEventData();
lldb::BreakpointEventType
GetBreakpointEventType () const;
lldb::BreakpointSP &
GetBreakpoint ();
BreakpointLocationCollection &
GetBreakpointLocationCollection()
{
return m_locations;
}
virtual void
Dump (Stream *s) const;
static lldb::BreakpointEventType
GetBreakpointEventTypeFromEvent (const lldb::EventSP &event_sp);
static lldb::BreakpointSP
GetBreakpointFromEvent (const lldb::EventSP &event_sp);
static lldb::BreakpointLocationSP
GetBreakpointLocationAtIndexFromEvent (const lldb::EventSP &event_sp, uint32_t loc_idx);
static size_t
GetNumBreakpointLocationsFromEvent (const lldb::EventSP &event_sp);
static const BreakpointEventData *
GetEventDataFromEvent (const Event *event_sp);
private:
lldb::BreakpointEventType m_breakpoint_event;
lldb::BreakpointSP m_new_breakpoint_sp;
BreakpointLocationCollection m_locations;
DISALLOW_COPY_AND_ASSIGN (BreakpointEventData);
};
//------------------------------------------------------------------
/// Destructor.
///
/// The destructor is not virtual since there should be no reason to subclass
/// breakpoints. The varieties of breakpoints are specified instead by
/// providing different resolvers & filters.
//------------------------------------------------------------------
~Breakpoint();
//------------------------------------------------------------------
// Methods
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Tell whether this breakpoint is an "internal" breakpoint.
/// @return
/// Returns \b true if this is an internal breakpoint, \b false otherwise.
//------------------------------------------------------------------
bool
IsInternal () const;
//------------------------------------------------------------------
/// Standard "Dump" method. At present it does nothing.
//------------------------------------------------------------------
void
Dump (Stream *s);
//------------------------------------------------------------------
// The next set of methods provide ways to tell the breakpoint to update
// it's location list - usually done when modules appear or disappear.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Tell this breakpoint to clear all its breakpoint sites. Done
/// when the process holding the breakpoint sites is destroyed.
//------------------------------------------------------------------
void
ClearAllBreakpointSites ();
//------------------------------------------------------------------
/// Tell this breakpoint to scan it's target's module list and resolve any
/// new locations that match the breakpoint's specifications.
//------------------------------------------------------------------
void
ResolveBreakpoint ();
//------------------------------------------------------------------
/// Tell this breakpoint to scan a given module list and resolve any
/// new locations that match the breakpoint's specifications.
///
/// @param[in] changed_modules
/// The list of modules to look in for new locations.
//------------------------------------------------------------------
void
ResolveBreakpointInModules (ModuleList &changed_modules);
//------------------------------------------------------------------
/// Like ResolveBreakpointInModules, but allows for "unload" events, in
/// which case we will remove any locations that are in modules that got
/// unloaded.
///
/// @param[in] changedModules
/// The list of modules to look in for new locations.
/// @param[in] load_event
/// If \b true then the modules were loaded, if \b false, unloaded.
/// @param[in] delete_locations
/// If \b true then the modules were unloaded delete any locations in the changed modules.
//------------------------------------------------------------------
void
ModulesChanged (ModuleList &changed_modules,
bool load_event,
bool delete_locations = false);
//------------------------------------------------------------------
/// Tells the breakpoint the old module \a old_module_sp has been
/// replaced by new_module_sp (usually because the underlying file has been
/// rebuilt, and the old version is gone.)
///
/// @param[in] old_module_sp
/// The old module that is going away.
/// @param[in] new_module_sp
/// The new module that is replacing it.
//------------------------------------------------------------------
void
ModuleReplaced (lldb::ModuleSP old_module_sp, lldb::ModuleSP new_module_sp);
//------------------------------------------------------------------
// The next set of methods provide access to the breakpoint locations
// for this breakpoint.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Add a location to the breakpoint's location list. This is only meant
/// to be called by the breakpoint's resolver. FIXME: how do I ensure that?
///
/// @param[in] addr
/// The Address specifying the new location.
/// @param[out] new_location
/// Set to \b true if a new location was created, to \b false if there
/// already was a location at this Address.
/// @return
/// Returns a pointer to the new location.
//------------------------------------------------------------------
lldb::BreakpointLocationSP
AddLocation (const Address &addr,
bool *new_location = NULL);
//------------------------------------------------------------------
/// Find a breakpoint location by Address.
///
/// @param[in] addr
/// The Address specifying the location.
/// @return
/// Returns a shared pointer to the location at \a addr. The pointer
/// in the shared pointer will be NULL if there is no location at that address.
//------------------------------------------------------------------
lldb::BreakpointLocationSP
FindLocationByAddress (const Address &addr);
//------------------------------------------------------------------
/// Find a breakpoint location ID by Address.
///
/// @param[in] addr
/// The Address specifying the location.
/// @return
/// Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if
/// there is no breakpoint location at that address.
//------------------------------------------------------------------
lldb::break_id_t
FindLocationIDByAddress (const Address &addr);
//------------------------------------------------------------------
/// Find a breakpoint location for a given breakpoint location ID.
///
/// @param[in] bp_loc_id
/// The ID specifying the location.
/// @return
/// Returns a shared pointer to the location with ID \a bp_loc_id. The pointer
/// in the shared pointer will be NULL if there is no location with that ID.
//------------------------------------------------------------------
lldb::BreakpointLocationSP
FindLocationByID (lldb::break_id_t bp_loc_id);
//------------------------------------------------------------------
/// Get breakpoint locations by index.
///
/// @param[in] index
/// The location index.
///
/// @return
/// Returns a shared pointer to the location with index \a
/// index. The shared pointer might contain NULL if \a index is
/// greater than then number of actual locations.
//------------------------------------------------------------------
lldb::BreakpointLocationSP
GetLocationAtIndex (size_t index);
//------------------------------------------------------------------
/// Removes all invalid breakpoint locations.
///
/// Removes all breakpoint locations with architectures that aren't
/// compatible with \a arch. Also remove any breakpoint locations
/// with whose locations have address where the section has been
/// deleted (module and object files no longer exist).
///
/// This is typically used after the process calls exec, or anytime
/// the architecture of the target changes.
///
/// @param[in] arch
/// If valid, check the module in each breakpoint to make sure
/// they are compatible, otherwise, ignore architecture.
//------------------------------------------------------------------
void
RemoveInvalidLocations (const ArchSpec &arch);
//------------------------------------------------------------------
// The next section deals with various breakpoint options.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// If \a enable is \b true, enable the breakpoint, if \b false disable it.
//------------------------------------------------------------------
void
SetEnabled (bool enable);
//------------------------------------------------------------------
/// Check the Enable/Disable state.
/// @return
/// \b true if the breakpoint is enabled, \b false if disabled.
//------------------------------------------------------------------
bool
IsEnabled ();
//------------------------------------------------------------------
/// Set the breakpoint to ignore the next \a count breakpoint hits.
/// @param[in] count
/// The number of breakpoint hits to ignore.
//------------------------------------------------------------------
void
SetIgnoreCount (uint32_t count);
//------------------------------------------------------------------
/// Return the current ignore count/
/// @return
/// The number of breakpoint hits to be ignored.
//------------------------------------------------------------------
uint32_t
GetIgnoreCount () const;
//------------------------------------------------------------------
/// Return the current hit count for all locations.
/// @return
/// The current hit count for all locations.
//------------------------------------------------------------------
uint32_t
GetHitCount () const;
//------------------------------------------------------------------
/// If \a one_shot is \b true, breakpoint will be deleted on first hit.
//------------------------------------------------------------------
void
SetOneShot (bool one_shot);
//------------------------------------------------------------------
/// Check the OneShot state.
/// @return
/// \b true if the breakpoint is one shot, \b false otherwise.
//------------------------------------------------------------------
bool
IsOneShot () const;
//------------------------------------------------------------------
/// Set the valid thread to be checked when the breakpoint is hit.
/// @param[in] thread_id
/// If this thread hits the breakpoint, we stop, otherwise not.
//------------------------------------------------------------------
void
SetThreadID (lldb::tid_t thread_id);
//------------------------------------------------------------------
/// Return the current stop thread value.
/// @return
/// The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads.
//------------------------------------------------------------------
lldb::tid_t
GetThreadID () const;
void
SetThreadIndex (uint32_t index);
uint32_t
GetThreadIndex() const;
void
SetThreadName (const char *thread_name);
const char *
GetThreadName () const;
void
SetQueueName (const char *queue_name);
const char *
GetQueueName () const;
//------------------------------------------------------------------
/// Set the callback action invoked when the breakpoint is hit.
///
/// @param[in] callback
/// The method that will get called when the breakpoint is hit.
/// @param[in] baton
/// A void * pointer that will get passed back to the callback function.
/// @param[in] is_synchronous
/// If \b true the callback will be run on the private event thread
/// before the stop event gets reported. If false, the callback will get
/// handled on the public event thead after the stop has been posted.
///
/// @return
/// \b true if the process should stop when you hit the breakpoint.
/// \b false if it should continue.
//------------------------------------------------------------------
void
SetCallback (BreakpointHitCallback callback,
void *baton,
bool is_synchronous = false);
void
SetCallback (BreakpointHitCallback callback,
const lldb::BatonSP &callback_baton_sp,
bool is_synchronous = false);
void
ClearCallback ();
//------------------------------------------------------------------
/// Set the breakpoint's condition.
///
/// @param[in] condition
/// The condition expression to evaluate when the breakpoint is hit.
/// Pass in NULL to clear the condition.
//------------------------------------------------------------------
void SetCondition (const char *condition);
//------------------------------------------------------------------
/// Return a pointer to the text of the condition expression.
///
/// @return
/// A pointer to the condition expression text, or NULL if no
// condition has been set.
//------------------------------------------------------------------
const char *GetConditionText () const;
//------------------------------------------------------------------
// The next section are various utility functions.
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Return the number of breakpoint locations that have resolved to
/// actual breakpoint sites.
///
/// @return
/// The number locations resolved breakpoint sites.
//------------------------------------------------------------------
size_t
GetNumResolvedLocations() const;
//------------------------------------------------------------------
/// Return the number of breakpoint locations.
///
/// @return
/// The number breakpoint locations.
//------------------------------------------------------------------
size_t
GetNumLocations() const;
//------------------------------------------------------------------
/// Put a description of this breakpoint into the stream \a s.
///
/// @param[in] s
/// Stream into which to dump the description.
///
/// @param[in] level
/// The description level that indicates the detail level to
/// provide.
///
/// @see lldb::DescriptionLevel
//------------------------------------------------------------------
void
GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false);
//------------------------------------------------------------------
/// Set the "kind" description for a breakpoint. If the breakpoint is hit
/// the stop info will show this "kind" description instead of the breakpoint
/// number. Mostly useful for internal breakpoints, where the breakpoint number
/// doesn't have meaning to the user.
///
/// @param[in] kind
/// New "kind" description.
//------------------------------------------------------------------
void
SetBreakpointKind (const char *kind)
{
m_kind_description.assign (kind);
}
//------------------------------------------------------------------
/// Return the "kind" description for a breakpoint.
///
/// @return
/// The breakpoint kind, or NULL if none is set.
//------------------------------------------------------------------
const char *GetBreakpointKind () const
{
return m_kind_description.c_str();
}
//------------------------------------------------------------------
/// Accessor for the breakpoint Target.
/// @return
/// This breakpoint's Target.
//------------------------------------------------------------------
Target &
GetTarget ();
const Target &
GetTarget () const;
void
GetResolverDescription (Stream *s);
//------------------------------------------------------------------
/// Find breakpoint locations which match the (filename, line_number) description.
/// The breakpoint location collection is to be filled with the matching locations.
/// It should be initialized with 0 size by the API client.
///
/// @return
/// True if there is a match
///
/// The locations which match the filename and line_number in loc_coll. If its
/// size is 0 and true is returned, it means the breakpoint fully matches the
/// description.
//------------------------------------------------------------------
bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number,
BreakpointLocationCollection &loc_coll);
void
GetFilterDescription (Stream *s);
//------------------------------------------------------------------
/// Returns the BreakpointOptions structure set at the breakpoint level.
///
/// Meant to be used by the BreakpointLocation class.
///
/// @return
/// A pointer to this breakpoint's BreakpointOptions.
//------------------------------------------------------------------
BreakpointOptions *
GetOptions ();
//------------------------------------------------------------------
/// Invoke the callback action when the breakpoint is hit.
///
/// Meant to be used by the BreakpointLocation class.
///
/// @param[in] context
/// Described the breakpoint event.
///
/// @param[in] bp_loc_id
/// Which breakpoint location hit this breakpoint.
///
/// @return
/// \b true if the target should stop at this breakpoint and \b false not.
//------------------------------------------------------------------
bool
InvokeCallback (StoppointCallbackContext *context,
lldb::break_id_t bp_loc_id);
bool
IsHardware() const
{
return m_hardware;
}
protected:
friend class Target;
//------------------------------------------------------------------
// Protected Methods
//------------------------------------------------------------------
//------------------------------------------------------------------
/// Constructors and Destructors
/// Only the Target can make a breakpoint, and it owns the breakpoint lifespans.
/// The constructor takes a filter and a resolver. Up in Target there are convenience
/// variants that make breakpoints for some common cases.
//------------------------------------------------------------------
// This is the generic constructor
Breakpoint(Target &target,
lldb::SearchFilterSP &filter_sp,
lldb::BreakpointResolverSP &resolver_sp,
bool hardware);
friend class BreakpointLocation; // To call the following two when determining whether to stop.
void
DecrementIgnoreCount();
// BreakpointLocation::IgnoreCountShouldStop & Breakpoint::IgnoreCountShouldStop can only be called once per stop,
// and BreakpointLocation::IgnoreCountShouldStop should be tested first, and if it returns false we should
// continue, otherwise we should test Breakpoint::IgnoreCountShouldStop.
bool
IgnoreCountShouldStop ();
private:
//------------------------------------------------------------------
// For Breakpoint only
//------------------------------------------------------------------
bool m_being_created;
bool m_hardware; // If this breakpoint is required to use a hardware breakpoint
Target &m_target; // The target that holds this breakpoint.
lldb::SearchFilterSP m_filter_sp; // The filter that constrains the breakpoint's domain.
lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint.
BreakpointOptions m_options; // Settable breakpoint options
BreakpointLocationList m_locations; // The list of locations currently found for this breakpoint.
std::string m_kind_description;
void
SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind);
void
SendBreakpointChangedEvent (BreakpointEventData *data);
DISALLOW_COPY_AND_ASSIGN(Breakpoint);
};
} // namespace lldb_private
#endif // liblldb_Breakpoint_h_
|