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 22namespace 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 35class BreakpointSite : public std::enable_shared_from_this<BreakpointSite>, 36 public StoppointLocation { 37public: 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 void Dump(Stream *s) const override; 103 104 /// The "Owners" are the breakpoint locations that share this breakpoint 105 /// site. The method adds the \a owner to this breakpoint site's owner list. 106 /// 107 /// \param[in] owner 108 /// \a owner is the Breakpoint Location to add. 109 void AddOwner(const lldb::BreakpointLocationSP &owner); 110 111 /// This method returns the number of breakpoint locations currently located 112 /// at this breakpoint site. 113 /// 114 /// \return 115 /// The number of owners. 116 size_t GetNumberOfOwners(); 117 118 /// This method returns the breakpoint location at index \a index located at 119 /// this breakpoint site. The owners are listed ordinally from 0 to 120 /// GetNumberOfOwners() - 1 so you can use this method to iterate over the 121 /// owners 122 /// 123 /// \param[in] idx 124 /// The index in the list of owners for which you wish the owner location. 125 /// 126 /// \return 127 /// A shared pointer to the breakpoint location at that index. 128 lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx); 129 130 /// This method copies the breakpoint site's owners into a new collection. 131 /// It does this while the owners mutex is locked. 132 /// 133 /// \param[out] out_collection 134 /// The BreakpointLocationCollection into which to put the owners 135 /// of this breakpoint site. 136 /// 137 /// \return 138 /// The number of elements copied into out_collection. 139 size_t CopyOwnersList(BreakpointLocationCollection &out_collection); 140 141 /// Check whether the owners of this breakpoint site have any thread 142 /// specifiers, and if yes, is \a thread contained in any of these 143 /// specifiers. 144 /// 145 /// \param[in] thread 146 /// The thread against which to test. 147 /// 148 /// return 149 /// \b true if the collection contains at least one location that 150 /// would be valid for this thread, false otherwise. 151 bool ValidForThisThread(Thread *thread); 152 153 /// Print a description of this breakpoint site to the stream \a s. 154 /// GetDescription tells you about the breakpoint site's owners. Use 155 /// BreakpointSite::Dump(Stream *) to get information about the breakpoint 156 /// site itself. 157 /// 158 /// \param[in] s 159 /// The stream to which to print the description. 160 /// 161 /// \param[in] level 162 /// The description level that indicates the detail level to 163 /// provide. 164 /// 165 /// \see lldb::DescriptionLevel 166 void GetDescription(Stream *s, lldb::DescriptionLevel level); 167 168 /// Tell whether a breakpoint has a location at this site. 169 /// 170 /// \param[in] bp_id 171 /// The breakpoint id to query. 172 /// 173 /// \result 174 /// \b true if bp_id has a location that is at this site, 175 /// \b false otherwise. 176 bool IsBreakpointAtThisSite(lldb::break_id_t bp_id); 177 178 /// Tell whether ALL the breakpoints in the location collection are 179 /// internal. 180 /// 181 /// \result 182 /// \b true if all breakpoint locations are owned by internal breakpoints, 183 /// \b false otherwise. 184 bool IsInternal() const; 185 186 BreakpointSite::Type GetType() const { return m_type; } 187 188 void SetType(BreakpointSite::Type type) { m_type = type; } 189 190private: 191 friend class Process; 192 friend class BreakpointLocation; 193 // The StopInfoBreakpoint knows when it is processing a hit for a thread for 194 // a site, so let it be the one to manage setting the location hit count once 195 // and only once. 196 friend class StopInfoBreakpoint; 197 198 void BumpHitCounts(); 199 200 /// The method removes the owner at \a break_loc_id from this breakpoint 201 /// list. 202 size_t RemoveOwner(lldb::break_id_t break_id, lldb::break_id_t break_loc_id); 203 204 BreakpointSite::Type m_type; ///< The type of this breakpoint site. 205 uint8_t m_saved_opcode[8]; ///< The saved opcode bytes if this breakpoint site 206 ///uses trap opcodes. 207 uint8_t m_trap_opcode[8]; ///< The opcode that was used to create the 208 ///breakpoint if it is a software breakpoint site. 209 bool 210 m_enabled; ///< Boolean indicating if this breakpoint site enabled or not. 211 212 // Consider adding an optimization where if there is only one owner, we don't 213 // store a list. The usual case will be only one owner... 214 BreakpointLocationCollection m_owners; ///< This has the BreakpointLocations 215 ///that share this breakpoint site. 216 std::recursive_mutex 217 m_owners_mutex; ///< This mutex protects the owners collection. 218 219 static lldb::break_id_t GetNextID(); 220 221 // Only the Process can create breakpoint sites in 222 // Process::CreateBreakpointSite (lldb::BreakpointLocationSP &, bool). 223 BreakpointSite(BreakpointSiteList *list, 224 const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr, 225 bool use_hardware); 226 227 DISALLOW_COPY_AND_ASSIGN(BreakpointSite); 228}; 229 230} // namespace lldb_private 231 232#endif // liblldb_BreakpointSite_h_ 233