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