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 LLDB_BREAKPOINT_BREAKPOINTSITE_H 10 #define LLDB_BREAKPOINT_BREAKPOINTSITE_H 11 12 #include <list> 13 #include <mutex> 14 15 16 #include "lldb/Breakpoint/BreakpointLocationCollection.h" 17 #include "lldb/Breakpoint/StoppointSite.h" 18 #include "lldb/Utility/LLDBAssert.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 StoppointSite { 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 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 IsHardware()186 bool IsHardware() const override { 187 lldbassert(BreakpointSite::Type::eHardware == GetType() || 188 !HardwareRequired()); 189 return BreakpointSite::Type::eHardware == GetType(); 190 } 191 GetType()192 BreakpointSite::Type GetType() const { return m_type; } 193 SetType(BreakpointSite::Type type)194 void SetType(BreakpointSite::Type type) { m_type = type; } 195 196 private: 197 friend class Process; 198 friend class BreakpointLocation; 199 // The StopInfoBreakpoint knows when it is processing a hit for a thread for 200 // a site, so let it be the one to manage setting the location hit count once 201 // and only once. 202 friend class StopInfoBreakpoint; 203 204 void BumpHitCounts(); 205 206 /// The method removes the owner at \a break_loc_id from this breakpoint 207 /// list. 208 size_t RemoveOwner(lldb::break_id_t break_id, lldb::break_id_t break_loc_id); 209 210 BreakpointSite::Type m_type; ///< The type of this breakpoint site. 211 uint8_t m_saved_opcode[8]; ///< The saved opcode bytes if this breakpoint site 212 ///uses trap opcodes. 213 uint8_t m_trap_opcode[8]; ///< The opcode that was used to create the 214 ///breakpoint if it is a software breakpoint site. 215 bool 216 m_enabled; ///< Boolean indicating if this breakpoint site enabled or not. 217 218 // Consider adding an optimization where if there is only one owner, we don't 219 // store a list. The usual case will be only one owner... 220 BreakpointLocationCollection m_owners; ///< This has the BreakpointLocations 221 ///that share this breakpoint site. 222 std::recursive_mutex 223 m_owners_mutex; ///< This mutex protects the owners collection. 224 225 static lldb::break_id_t GetNextID(); 226 227 // Only the Process can create breakpoint sites in 228 // Process::CreateBreakpointSite (lldb::BreakpointLocationSP &, bool). 229 BreakpointSite(BreakpointSiteList *list, 230 const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr, 231 bool use_hardware); 232 233 BreakpointSite(const BreakpointSite &) = delete; 234 const BreakpointSite &operator=(const BreakpointSite &) = delete; 235 }; 236 237 } // namespace lldb_private 238 239 #endif // LLDB_BREAKPOINT_BREAKPOINTSITE_H 240