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 /// Class that manages the actual breakpoint that will be inserted into the
  32 /// running program.
  33 ///
  34 /// The BreakpointSite class handles the physical breakpoint that is actually
  35 /// inserted in the target program.  As such, it is also the one that  gets
  36 /// hit, when the program stops. It keeps a list of all BreakpointLocations
  37 /// that share this physical site. When the breakpoint is hit, all the
  38 /// locations are informed by the breakpoint site. Breakpoint sites are owned
  39 /// 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 removed.  This
 105   /// enable/disable is for the low-level target code to enable and disable
 106   /// breakpoint sites when single stepping, etc.
 107   //------------------------------------------------------------------
 108   bool IsEnabled() const;
 109
 110   //------------------------------------------------------------------
 111   /// Sets whether the current breakpoint site is enabled or not
 112   ///
 113   /// @param[in] enabled
 114   ///    \b true if the breakpoint is enabled, \b false otherwise.
 115   //------------------------------------------------------------------
 116   void SetEnabled(bool enabled);
 117
 118   //------------------------------------------------------------------
 119   /// Enquires of the breakpoint locations that produced this breakpoint site
 120   /// whether we should stop at this location.
 121   ///
 122   /// @param[in] context
 123   ///    This contains the information about this stop.
 124   ///
 125   /// @return
 126   ///    \b true if we should stop, \b false otherwise.
 127   //------------------------------------------------------------------
 128   bool ShouldStop(StoppointCallbackContext *context) override;
 129
 130   //------------------------------------------------------------------
 131   /// Standard Dump method
 132   ///
 133   /// @param[in] context
 134   ///    The stream to dump this output.
 135   //------------------------------------------------------------------
 136   void Dump(Stream *s) const override;
 137
 138   //------------------------------------------------------------------
 139   /// The "Owners" are the breakpoint locations that share this breakpoint
 140   /// site. The method adds the \a owner to this breakpoint site's owner list.
 141   ///
 142   /// @param[in] context
 143   ///    \a owner is the Breakpoint Location to add.
 144   //------------------------------------------------------------------
 145   void AddOwner(const lldb::BreakpointLocationSP &owner);
 146
 147   //------------------------------------------------------------------
 148   /// This method returns the number of breakpoint locations currently located
 149   /// at this breakpoint site.
 150   ///
 151   /// @return
 152   ///    The number of owners.
 153   //------------------------------------------------------------------
 154   size_t GetNumberOfOwners();
 155
 156   //------------------------------------------------------------------
 157   /// This method returns the breakpoint location at index \a index located at
 158   /// this breakpoint site.  The owners are listed ordinally from 0 to
 159   /// GetNumberOfOwners() - 1 so you can use this method to iterate over the
 160   /// owners
 161   ///
 162   /// @param[in] index
 163   ///     The index in the list of owners for which you wish the owner location.
 164   /// @return
 165   ///    A shared pointer to the breakpoint location at that index.
 166   //------------------------------------------------------------------
 167   lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx);
 168
 169   //------------------------------------------------------------------
 170   /// This method copies the breakpoint site's owners into a new collection.
 171   /// It does this while the owners mutex is locked.
 172   ///
 173   /// @param[out] out_collection
 174   ///    The BreakpointLocationCollection into which to put the owners
 175   ///    of this breakpoint site.
 176   ///
 177   /// @return
 178   ///    The number of elements copied into out_collection.
 179   //------------------------------------------------------------------
 180   size_t CopyOwnersList(BreakpointLocationCollection &out_collection);
 181
 182   //------------------------------------------------------------------
 183   /// Check whether the owners of this breakpoint site have any thread
 184   /// specifiers, and if yes, is \a thread contained in any of these
 185   /// specifiers.
 186   ///
 187   /// @param[in] thread
 188   ///     The thread against which to test.
 189   ///
 190   /// return
 191   ///     \b true if the collection contains at least one location that
 192   ///     would be valid for this thread, false otherwise.
 193   //------------------------------------------------------------------
 194   bool ValidForThisThread(Thread *thread);
 195
 196   //------------------------------------------------------------------
 197   /// Print a description of this breakpoint site to the stream \a s.
 198   /// GetDescription tells you about the breakpoint site's owners. Use
 199   /// BreakpointSite::Dump(Stream *) to get information about the breakpoint
 200   /// site itself.
 201   ///
 202   /// @param[in] s
 203   ///     The stream to which to print the description.
 204   ///
 205   /// @param[in] level
 206   ///     The description level that indicates the detail level to
 207   ///     provide.
 208   ///
 209   /// @see lldb::DescriptionLevel
 210   //------------------------------------------------------------------
 211   void GetDescription(Stream *s, lldb::DescriptionLevel level);
 212
 213   //------------------------------------------------------------------
 214   /// Tell whether a breakpoint has a location at this site.
 215   ///
 216   /// @param[in] bp_id
 217   ///     The breakpoint id to query.
 218   ///
 219   /// @result
 220   ///     \b true if bp_id has a location that is at this site,
 221   ///     \b false otherwise.
 222   //------------------------------------------------------------------
 223   bool IsBreakpointAtThisSite(lldb::break_id_t bp_id);
 224
 225   //------------------------------------------------------------------
 226   /// Tell whether ALL the breakpoints in the location collection are
 227   /// internal.
 228   ///
 229   /// @result
 230   ///     \b true if all breakpoint locations are owned by internal breakpoints,
 231   ///     \b false otherwise.
 232   //------------------------------------------------------------------
 233   bool IsInternal() const;
 234
 235   BreakpointSite::Type GetType() const { return m_type; }
 236
 237   void SetType(BreakpointSite::Type type) { m_type = type; }
 238
 239 private:
 240   friend class Process;
 241   friend class BreakpointLocation;
 242   // The StopInfoBreakpoint knows when it is processing a hit for a thread for
 243   // a site, so let it be the one to manage setting the location hit count once
 244   // and only once.
 245   friend class StopInfoBreakpoint;
 246
 247   void BumpHitCounts();
 248
 249   //------------------------------------------------------------------
 250   /// The method removes the owner at \a break_loc_id from this breakpoint
 251   /// list.
 252   ///
 253   /// @param[in] context
 254   ///    \a break_loc_id is the Breakpoint Location to remove.
 255   //------------------------------------------------------------------
 256   size_t RemoveOwner(lldb::break_id_t break_id, lldb::break_id_t break_loc_id);
 257
 258   BreakpointSite::Type m_type; ///< The type of this breakpoint site.
 259   uint8_t m_saved_opcode[8]; ///< The saved opcode bytes if this breakpoint site
 260                              ///uses trap opcodes.
 261   uint8_t m_trap_opcode[8];  ///< The opcode that was used to create the
 262                              ///breakpoint if it is a software breakpoint site.
 263   bool
 264       m_enabled; ///< Boolean indicating if this breakpoint site enabled or not.
 265
 266   // Consider adding an optimization where if there is only one owner, we don't
 267   // store a list.  The usual case will be only one owner...
 268   BreakpointLocationCollection m_owners; ///< This has the BreakpointLocations
 269                                          ///that share this breakpoint site.
 270   std::recursive_mutex
 271       m_owners_mutex; ///< This mutex protects the owners collection.
 272
 273   static lldb::break_id_t GetNextID();
 274
 275   // Only the Process can create breakpoint sites in
 276   // Process::CreateBreakpointSite (lldb::BreakpointLocationSP &, bool).
 277   BreakpointSite(BreakpointSiteList *list,
 278                  const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr,
 279                  bool use_hardware);
 280
 281   DISALLOW_COPY_AND_ASSIGN(BreakpointSite);
 282 };
 283
 284 } // namespace lldb_private
 285
 286 #endif // liblldb_BreakpointSite_h_