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