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