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

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