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

   1 //===-- BreakpointLocation.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_BreakpointLocation_h_
  11 #define liblldb_BreakpointLocation_h_
  12
  13 // C Includes
  14
  15 // C++ Includes
  16 #include <list>
  17
  18 // Other libraries and framework includes
  19
  20 // Project includes
  21 #include "lldb/lldb-private.h"
  22 #include "lldb/Breakpoint/StoppointLocation.h"
  23 #include "lldb/Core/Address.h"
  24 #include "lldb/Core/StringList.h"
  25 #include "lldb/Core/UserID.h"
  26 #include "lldb/Host/Mutex.h"
  27 #include "lldb/Target/Process.h"
  28 #include "lldb/Expression/ClangUserExpression.h"
  29
  30 namespace lldb_private {
  31
  32 //----------------------------------------------------------------------
  33 /// @class BreakpointLocation BreakpointLocation.h "lldb/Breakpoint/BreakpointLocation.h"
  34 /// @brief Class that manages one unique (by address) instance of a logical breakpoint.
  35 //----------------------------------------------------------------------
  36
  37 //----------------------------------------------------------------------
  38 /// General Outline:
  39 /// A breakpoint location is defined by the breakpoint that produces it,
  40 /// and the address that resulted in this particular instantiation.
  41 /// Each breakpoint location also may have a breakpoint site if its
  42 /// address has been loaded into the program.
  43 /// Finally it has a settable options object.
  44 ///
  45 /// FIXME: Should we also store some fingerprint for the location, so
  46 /// we can map one location to the "equivalent location" on rerun?  This
  47 /// would be useful if you've set options on the locations.
  48 //----------------------------------------------------------------------
  49
  50 class BreakpointLocation :
  51     public std::enable_shared_from_this<BreakpointLocation>,
  52     public StoppointLocation
  53 {
  54 public:
  55
  56     ~BreakpointLocation ();
  57
  58     //------------------------------------------------------------------
  59     /// Gets the load address for this breakpoint location
  60     /// @return
  61     ///     Returns breakpoint location load address, \b
  62     ///     LLDB_INVALID_ADDRESS if not yet set.
  63     //------------------------------------------------------------------
  64     lldb::addr_t
  65     GetLoadAddress () const;
  66
  67     //------------------------------------------------------------------
  68     /// Gets the Address for this breakpoint location
  69     /// @return
  70     ///     Returns breakpoint location Address.
  71     //------------------------------------------------------------------
  72     Address &
  73     GetAddress ();
  74     //------------------------------------------------------------------
  75     /// Gets the Breakpoint that created this breakpoint location
  76     /// @return
  77     ///     Returns the owning breakpoint.
  78     //------------------------------------------------------------------
  79     Breakpoint &
  80     GetBreakpoint ();
  81
  82     //------------------------------------------------------------------
  83     /// Determines whether we should stop due to a hit at this
  84     /// breakpoint location.
  85     ///
  86     /// Side Effects: This may evaluate the breakpoint condition, and
  87     /// run the callback.  So this command may do a considerable amount
  88     /// of work.
  89     ///
  90     /// @return
  91     ///     \b true if this breakpoint location thinks we should stop,
  92     ///     \b false otherwise.
  93     //------------------------------------------------------------------
  94     bool
  95     ShouldStop (StoppointCallbackContext *context);
  96
  97     //------------------------------------------------------------------
  98     // The next section deals with various breakpoint options.
  99     //------------------------------------------------------------------
 100
 101     //------------------------------------------------------------------
 102     /// If \a enable is \b true, enable the breakpoint, if \b false
 103     /// disable it.
 104     //------------------------------------------------------------------
 105     void
 106     SetEnabled(bool enabled);
 107
 108     //------------------------------------------------------------------
 109     /// Check the Enable/Disable state.
 110     ///
 111     /// @return
 112     ///     \b true if the breakpoint is enabled, \b false if disabled.
 113     //------------------------------------------------------------------
 114     bool
 115     IsEnabled () const;
 116
 117     //------------------------------------------------------------------
 118     /// Return the current Ignore Count.
 119     ///
 120     /// @return
 121     ///     The number of breakpoint hits to be ignored.
 122     //------------------------------------------------------------------
 123     uint32_t
 124     GetIgnoreCount ();
 125
 126     //------------------------------------------------------------------
 127     /// Set the breakpoint to ignore the next \a count breakpoint hits.
 128     ///
 129     /// @param[in] count
 130     ///    The number of breakpoint hits to ignore.
 131     //------------------------------------------------------------------
 132     void
 133     SetIgnoreCount (uint32_t n);
 134
 135     //------------------------------------------------------------------
 136     /// Set the callback action invoked when the breakpoint is hit.
 137     ///
 138     /// The callback will return a bool indicating whether the target
 139     /// should stop at this breakpoint or not.
 140     ///
 141     /// @param[in] callback
 142     ///     The method that will get called when the breakpoint is hit.
 143     ///
 144     /// @param[in] callback_baton_sp
 145     ///     A shared pointer to a Baton that provides the void * needed
 146     ///     for the callback.
 147     ///
 148     /// @see lldb_private::Baton
 149     //------------------------------------------------------------------
 150     void
 151     SetCallback (BreakpointHitCallback callback,
 152                  const lldb::BatonSP &callback_baton_sp,
 153                  bool is_synchronous);
 154
 155     void
 156     SetCallback (BreakpointHitCallback callback,
 157                  void *baton,
 158                  bool is_synchronous);
 159
 160     void
 161     ClearCallback ();
 162
 163     //------------------------------------------------------------------
 164     /// Set the breakpoint location's condition.
 165     ///
 166     /// @param[in] condition
 167     ///    The condition expression to evaluate when the breakpoint is hit.
 168     //------------------------------------------------------------------
 169     void
 170     SetCondition (const char *condition);
 171
 172     //------------------------------------------------------------------
 173     /// Return a pointer to the text of the condition expression.
 174     ///
 175     /// @return
 176     ///    A pointer to the condition expression text, or NULL if no
 177     //     condition has been set.
 178     //------------------------------------------------------------------
 179     const char *
 180     GetConditionText (size_t *hash = NULL) const;
 181
 182     bool
 183     ConditionSaysStop (ExecutionContext &exe_ctx, Error &error);
 184
 185
 186     //------------------------------------------------------------------
 187     /// Set the valid thread to be checked when the breakpoint is hit.
 188     ///
 189     /// @param[in] thread_id
 190     ///    If this thread hits the breakpoint, we stop, otherwise not.
 191     //------------------------------------------------------------------
 192     void
 193     SetThreadID (lldb::tid_t thread_id);
 194
 195     lldb::tid_t
 196     GetThreadID ();
 197
 198     void
 199     SetThreadIndex (uint32_t index);
 200
 201     uint32_t
 202     GetThreadIndex() const;
 203
 204     void
 205     SetThreadName (const char *thread_name);
 206
 207     const char *
 208     GetThreadName () const;
 209
 210     void
 211     SetQueueName (const char *queue_name);
 212
 213     const char *
 214     GetQueueName () const;
 215
 216     //------------------------------------------------------------------
 217     // The next section deals with this location's breakpoint sites.
 218     //------------------------------------------------------------------
 219
 220     //------------------------------------------------------------------
 221     /// Try to resolve the breakpoint site for this location.
 222     ///
 223     /// @return
 224     ///     \b true if we were successful at setting a breakpoint site,
 225     ///     \b false otherwise.
 226     //------------------------------------------------------------------
 227     bool
 228     ResolveBreakpointSite ();
 229
 230     //------------------------------------------------------------------
 231     /// Clear this breakpoint location's breakpoint site - for instance
 232     /// when disabling the breakpoint.
 233     ///
 234     /// @return
 235     ///     \b true if there was a breakpoint site to be cleared, \b false
 236     ///     otherwise.
 237     //------------------------------------------------------------------
 238     bool
 239     ClearBreakpointSite ();
 240
 241     //------------------------------------------------------------------
 242     /// Return whether this breakpoint location has a breakpoint site.
 243     /// @return
 244     ///     \b true if there was a breakpoint site for this breakpoint
 245     ///     location, \b false otherwise.
 246     //------------------------------------------------------------------
 247     bool
 248     IsResolved () const;
 249
 250     lldb::BreakpointSiteSP
 251     GetBreakpointSite() const;
 252
 253     //------------------------------------------------------------------
 254     // The next section are generic report functions.
 255     //------------------------------------------------------------------
 256
 257     //------------------------------------------------------------------
 258     /// Print a description of this breakpoint location to the stream
 259     /// \a s.
 260     ///
 261     /// @param[in] s
 262     ///     The stream to which to print the description.
 263     ///
 264     /// @param[in] level
 265     ///     The description level that indicates the detail level to
 266     ///     provide.
 267     ///
 268     /// @see lldb::DescriptionLevel
 269     //------------------------------------------------------------------
 270     void
 271     GetDescription (Stream *s, lldb::DescriptionLevel level);
 272
 273     //------------------------------------------------------------------
 274     /// Standard "Dump" method.  At present it does nothing.
 275     //------------------------------------------------------------------
 276     void
 277     Dump (Stream *s) const;
 278
 279     //------------------------------------------------------------------
 280     /// Use this to set location specific breakpoint options.
 281     ///
 282     /// It will create a copy of the containing breakpoint's options if
 283     /// that hasn't been done already
 284     ///
 285     /// @return
 286     ///    A pointer to the breakpoint options.
 287     //------------------------------------------------------------------
 288     BreakpointOptions *
 289     GetLocationOptions ();
 290
 291     //------------------------------------------------------------------
 292     /// Use this to access breakpoint options from this breakpoint location.
 293     /// This will point to the owning breakpoint's options unless options have
 294     /// been set specifically on this location.
 295     ///
 296     /// @return
 297     ///     A pointer to the containing breakpoint's options if this
 298     ///     location doesn't have its own copy.
 299     //------------------------------------------------------------------
 300     const BreakpointOptions *
 301     GetOptionsNoCreate () const;
 302
 303     bool
 304     ValidForThisThread (Thread *thread);
 305
 306
 307     //------------------------------------------------------------------
 308     /// Invoke the callback action when the breakpoint is hit.
 309     ///
 310     /// Meant to be used by the BreakpointLocation class.
 311     ///
 312     /// @param[in] context
 313     ///    Described the breakpoint event.
 314     ///
 315     /// @param[in] bp_loc_id
 316     ///    Which breakpoint location hit this breakpoint.
 317     ///
 318     /// @return
 319     ///     \b true if the target should stop at this breakpoint and \b
 320     ///     false not.
 321     //------------------------------------------------------------------
 322     bool
 323     InvokeCallback (StoppointCallbackContext *context);
 324
 325 protected:
 326     friend class BreakpointLocationList;
 327     friend class CommandObjectBreakpointCommandAdd;
 328     friend class Process;
 329
 330     //------------------------------------------------------------------
 331     /// Set the breakpoint site for this location to \a bp_site_sp.
 332     ///
 333     /// @param[in] bp_site_sp
 334     ///      The breakpoint site we are setting for this location.
 335     ///
 336     /// @return
 337     ///     \b true if we were successful at setting the breakpoint site,
 338     ///     \b false otherwise.
 339     //------------------------------------------------------------------
 340     bool
 341     SetBreakpointSite (lldb::BreakpointSiteSP& bp_site_sp);
 342
 343     void
 344     DecrementIgnoreCount();
 345
 346     bool
 347     IgnoreCountShouldStop();
 348
 349 private:
 350
 351     //------------------------------------------------------------------
 352     // Constructors and Destructors
 353     //
 354     // Only the Breakpoint can make breakpoint locations, and it owns
 355     // them.
 356     //------------------------------------------------------------------
 357
 358     //------------------------------------------------------------------
 359     /// Constructor.
 360     ///
 361     /// @param[in] owner
 362     ///     A back pointer to the breakpoint that owns this location.
 363     ///
 364     /// @param[in] addr
 365     ///     The Address defining this location.
 366     ///
 367     /// @param[in] tid
 368     ///     The thread for which this breakpoint location is valid, or
 369     ///     LLDB_INVALID_THREAD_ID if it is valid for all threads.
 370     ///
 371     /// @param[in] hardware
 372     ///     \b true if a hardware breakpoint is requested.
 373     //------------------------------------------------------------------
 374
 375     BreakpointLocation (lldb::break_id_t bid,
 376                         Breakpoint &owner,
 377                         const Address &addr,
 378                         lldb::tid_t tid = LLDB_INVALID_THREAD_ID,
 379                         bool hardware = false);
 380
 381     //------------------------------------------------------------------
 382     // Data members:
 383     //------------------------------------------------------------------
 384     bool m_being_created;
 385     Address m_address; ///< The address defining this location.
 386     Breakpoint &m_owner; ///< The breakpoint that produced this object.
 387     std::unique_ptr<BreakpointOptions> m_options_ap; ///< Breakpoint options pointer, NULL if we're using our breakpoint's options.
 388     lldb::BreakpointSiteSP m_bp_site_sp; ///< Our breakpoint site (it may be shared by more than one location.)
 389     ClangUserExpression::ClangUserExpressionSP m_user_expression_sp; ///< The compiled expression to use in testing our condition.
 390     Mutex m_condition_mutex; ///< Guards parsing and evaluation of the condition, which could be evaluated by multiple processes.
 391     size_t m_condition_hash; ///< For testing whether the condition source code changed.
 392
 393     void
 394     SendBreakpointLocationChangedEvent (lldb::BreakpointEventType eventKind);
 395
 396     DISALLOW_COPY_AND_ASSIGN (BreakpointLocation);
 397 };
 398
 399 } // namespace lldb_private
 400
 401 #endif  // liblldb_BreakpointLocation_h_