contrib/llvm/tools/lldb/include/lldb/Breakpoint/Breakpoint.h

   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 &
 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
 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     //------------------------------------------------------------------
 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_