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