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

   1 //===-- BreakpointSite.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_BreakpointSite_h_
  11 #define liblldb_BreakpointSite_h_
  12
  13 // C Includes
  14
  15 // C++ Includes
  16 #include <list>
  17 #include <mutex>
  18
  19 // Other libraries and framework includes
  20
  21 // Project includes
  22 #include "lldb/Breakpoint/BreakpointLocationCollection.h"
  23 #include "lldb/Breakpoint/StoppointLocation.h"
  24 #include "lldb/Utility/UserID.h"
  25 #include "lldb/lldb-forward.h"
  26
  27 namespace lldb_private {
  28
  29 //----------------------------------------------------------------------
  30 /// @class BreakpointSite BreakpointSite.h "lldb/Breakpoint/BreakpointSite.h"
  31 /// @brief Class that manages the actual breakpoint that will be inserted
  32 /// into the running program.
  33 ///
  34 /// The BreakpointSite class handles the physical breakpoint that is
  35 /// actually inserted in the target program.  As such, it is also the
  36 /// one that  gets hit, when the program stops. It keeps a list of all
  37 /// BreakpointLocations that share this physical site. When the
  38 /// breakpoint is hit, all the locations are informed by the breakpoint
  39 /// site. Breakpoint sites are owned by the process.
  40 //----------------------------------------------------------------------
  41
  42 class BreakpointSite : public std::enable_shared_from_this<BreakpointSite>,
  43                        public StoppointLocation {
  44 public:
  45   enum Type {
  46     eSoftware, // Breakpoint opcode has been written to memory and
  47                // m_saved_opcode
  48                // and m_trap_opcode contain the saved and written opcode.
  49     eHardware, // Breakpoint site is set as a hardware breakpoint
  50     eExternal  // Breakpoint site is managed by an external debug nub or
  51                // debug interface where memory reads transparently will not
  52                // display any breakpoint opcodes.
  53   };
  54
  55   ~BreakpointSite() override;
  56
  57   //----------------------------------------------------------------------
  58   // This section manages the breakpoint traps
  59   //----------------------------------------------------------------------
  60
  61   //------------------------------------------------------------------
  62   /// Returns the Opcode Bytes for this breakpoint
  63   //------------------------------------------------------------------
  64   uint8_t *GetTrapOpcodeBytes();
  65
  66   //------------------------------------------------------------------
  67   /// Returns the Opcode Bytes for this breakpoint - const version
  68   //------------------------------------------------------------------
  69   const uint8_t *GetTrapOpcodeBytes() const;
  70
  71   //------------------------------------------------------------------
  72   /// Get the size of the trap opcode for this address
  73   //------------------------------------------------------------------
  74   size_t GetTrapOpcodeMaxByteSize() const;
  75
  76   //------------------------------------------------------------------
  77   /// Sets the trap opcode
  78   //------------------------------------------------------------------
  79   bool SetTrapOpcode(const uint8_t *trap_opcode, uint32_t trap_opcode_size);
  80
  81   //------------------------------------------------------------------
  82   /// Gets the original instruction bytes that were overwritten by the trap
  83   //------------------------------------------------------------------
  84   uint8_t *GetSavedOpcodeBytes();
  85
  86   //------------------------------------------------------------------
  87   /// Gets the original instruction bytes that were overwritten by the trap
  88   /// const version
  89   //------------------------------------------------------------------
  90   const uint8_t *GetSavedOpcodeBytes() const;
  91
  92   //------------------------------------------------------------------
  93   /// Says whether \a addr and size \a size intersects with the address \a
  94   /// intersect_addr
  95   //------------------------------------------------------------------
  96   bool IntersectsRange(lldb::addr_t addr, size_t size,
  97                        lldb::addr_t *intersect_addr, size_t *intersect_size,
  98                        size_t *opcode_offset) const;
  99
 100   //------------------------------------------------------------------
 101   /// Tells whether the current breakpoint site is enabled or not
 102   ///
 103   /// This is a low-level enable bit for the breakpoint sites.  If a
 104   /// breakpoint site has no enabled owners, it should just get
 105   /// removed.  This enable/disable is for the low-level target code
 106   /// to enable and disable breakpoint sites when single stepping,
 107   /// etc.
 108   //------------------------------------------------------------------
 109   bool IsEnabled() const;
 110
 111   //------------------------------------------------------------------
 112   /// Sets whether the current breakpoint site is enabled or not
 113   ///
 114   /// @param[in] enabled
 115   ///    \b true if the breakpoint is enabled, \b false otherwise.
 116   //------------------------------------------------------------------
 117   void SetEnabled(bool enabled);
 118
 119   //------------------------------------------------------------------
 120   /// Enquires of the breakpoint locations that produced this breakpoint site
 121   /// whether
 122   /// we should stop at this location.
 123   ///
 124   /// @param[in] context
 125   ///    This contains the information about this stop.
 126   ///
 127   /// @return
 128   ///    \b true if we should stop, \b false otherwise.
 129   //------------------------------------------------------------------
 130   bool ShouldStop(StoppointCallbackContext *context) override;
 131
 132   //------------------------------------------------------------------
 133   /// Standard Dump method
 134   ///
 135   /// @param[in] context
 136   ///    The stream to dump this output.
 137   //------------------------------------------------------------------
 138   void Dump(Stream *s) const override;
 139
 140   //------------------------------------------------------------------
 141   /// The "Owners" are the breakpoint locations that share this
 142   /// breakpoint site. The method adds the \a owner to this breakpoint
 143   /// site's owner list.
 144   ///
 145   /// @param[in] context
 146   ///    \a owner is the Breakpoint Location to add.
 147   //------------------------------------------------------------------
 148   void AddOwner(const lldb::BreakpointLocationSP &owner);
 149
 150   //------------------------------------------------------------------
 151   /// This method returns the number of breakpoint locations currently
 152   /// located at this breakpoint site.
 153   ///
 154   /// @return
 155   ///    The number of owners.
 156   //------------------------------------------------------------------
 157   size_t GetNumberOfOwners();
 158
 159   //------------------------------------------------------------------
 160   /// This method returns the breakpoint location at index \a index
 161   /// located at this breakpoint site.  The owners are listed ordinally
 162   /// from 0 to GetNumberOfOwners() - 1 so you can use this method to iterate
 163   /// over the owners
 164   ///
 165   /// @param[in] index
 166   ///     The index in the list of owners for which you wish the owner location.
 167   /// @return
 168   ///    A shared pointer to the breakpoint location at that index.
 169   //------------------------------------------------------------------
 170   lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx);
 171
 172   //------------------------------------------------------------------
 173   /// This method copies the breakpoint site's owners into a new collection.
 174   /// It does this while the owners mutex is locked.
 175   ///
 176   /// @param[out] out_collection
 177   ///    The BreakpointLocationCollection into which to put the owners
 178   ///    of this breakpoint site.
 179   ///
 180   /// @return
 181   ///    The number of elements copied into out_collection.
 182   //------------------------------------------------------------------
 183   size_t CopyOwnersList(BreakpointLocationCollection &out_collection);
 184
 185   //------------------------------------------------------------------
 186   /// Check whether the owners of this breakpoint site have any
 187   /// thread specifiers, and if yes, is \a thread contained in any
 188   /// of these specifiers.
 189   ///
 190   /// @param[in] thread
 191   ///     The thread against which to test.
 192   ///
 193   /// return
 194   ///     \b true if the collection contains at least one location that
 195   ///     would be valid for this thread, false otherwise.
 196   //------------------------------------------------------------------
 197   bool ValidForThisThread(Thread *thread);
 198
 199   //------------------------------------------------------------------
 200   /// Print a description of this breakpoint site to the stream \a s.
 201   /// GetDescription tells you about the breakpoint site's owners.
 202   /// Use BreakpointSite::Dump(Stream *) to get information about the
 203   /// breakpoint site itself.
 204   ///
 205   /// @param[in] s
 206   ///     The stream to which to print the description.
 207   ///
 208   /// @param[in] level
 209   ///     The description level that indicates the detail level to
 210   ///     provide.
 211   ///
 212   /// @see lldb::DescriptionLevel
 213   //------------------------------------------------------------------
 214   void GetDescription(Stream *s, lldb::DescriptionLevel level);
 215
 216   //------------------------------------------------------------------
 217   /// Tell whether a breakpoint has a location at this site.
 218   ///
 219   /// @param[in] bp_id
 220   ///     The breakpoint id to query.
 221   ///
 222   /// @result
 223   ///     \b true if bp_id has a location that is at this site,
 224   ///     \b false otherwise.
 225   //------------------------------------------------------------------
 226   bool IsBreakpointAtThisSite(lldb::break_id_t bp_id);
 227
 228   //------------------------------------------------------------------
 229   /// Tell whether ALL the breakpoints in the location collection are internal.
 230   ///
 231   /// @result
 232   ///     \b true if all breakpoint locations are owned by internal breakpoints,
 233   ///     \b false otherwise.
 234   //------------------------------------------------------------------
 235   bool IsInternal() const;
 236
 237   BreakpointSite::Type GetType() const { return m_type; }
 238
 239   void SetType(BreakpointSite::Type type) { m_type = type; }
 240
 241 private:
 242   friend class Process;
 243   friend class BreakpointLocation;
 244   // The StopInfoBreakpoint knows when it is processing a hit for a thread for a
 245   // site, so let it be the
 246   // one to manage setting the location hit count once and only once.
 247   friend class StopInfoBreakpoint;
 248
 249   void BumpHitCounts();
 250
 251   //------------------------------------------------------------------
 252   /// The method removes the owner at \a break_loc_id from this breakpoint list.
 253   ///
 254   /// @param[in] context
 255   ///    \a break_loc_id is the Breakpoint Location to remove.
 256   //------------------------------------------------------------------
 257   size_t RemoveOwner(lldb::break_id_t break_id, lldb::break_id_t break_loc_id);
 258
 259   BreakpointSite::Type m_type; ///< The type of this breakpoint site.
 260   uint8_t m_saved_opcode[8]; ///< The saved opcode bytes if this breakpoint site
 261                              ///uses trap opcodes.
 262   uint8_t m_trap_opcode[8];  ///< The opcode that was used to create the
 263                              ///breakpoint if it is a software breakpoint site.
 264   bool
 265       m_enabled; ///< Boolean indicating if this breakpoint site enabled or not.
 266
 267   // Consider adding an optimization where if there is only one
 268   // owner, we don't store a list.  The usual case will be only one owner...
 269   BreakpointLocationCollection m_owners; ///< This has the BreakpointLocations
 270                                          ///that share this breakpoint site.
 271   std::recursive_mutex
 272       m_owners_mutex; ///< This mutex protects the owners collection.
 273
 274   static lldb::break_id_t GetNextID();
 275
 276   // Only the Process can create breakpoint sites in
 277   // Process::CreateBreakpointSite (lldb::BreakpointLocationSP &, bool).
 278   BreakpointSite(BreakpointSiteList *list,
 279                  const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr,
 280                  bool use_hardware);
 281
 282   DISALLOW_COPY_AND_ASSIGN(BreakpointSite);
 283 };
 284
 285 } // namespace lldb_private
 286
 287 #endif // liblldb_BreakpointSite_h_