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