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