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

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