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 | typedef lldb::break_id_t SiteID; |
49 | typedef lldb::break_id_t ConstituentID; |
50 | |
51 | ~BreakpointSite() override; |
52 | |
53 | // This section manages the breakpoint traps |
54 | |
55 | /// Returns the Opcode Bytes for this breakpoint |
56 | uint8_t *GetTrapOpcodeBytes(); |
57 | |
58 | /// Returns the Opcode Bytes for this breakpoint - const version |
59 | const uint8_t *GetTrapOpcodeBytes() const; |
60 | |
61 | /// Get the size of the trap opcode for this address |
62 | size_t GetTrapOpcodeMaxByteSize() const; |
63 | |
64 | /// Sets the trap opcode |
65 | bool SetTrapOpcode(const uint8_t *trap_opcode, uint32_t trap_opcode_size); |
66 | |
67 | /// Gets the original instruction bytes that were overwritten by the trap |
68 | uint8_t *GetSavedOpcodeBytes(); |
69 | |
70 | /// Gets the original instruction bytes that were overwritten by the trap |
71 | /// const version |
72 | const uint8_t *GetSavedOpcodeBytes() const; |
73 | |
74 | /// Says whether \a addr and size \a size intersects with the address \a |
75 | /// intersect_addr |
76 | bool IntersectsRange(lldb::addr_t addr, size_t size, |
77 | lldb::addr_t *intersect_addr, size_t *intersect_size, |
78 | size_t *opcode_offset) const; |
79 | |
80 | /// Tells whether the current breakpoint site is enabled or not |
81 | /// |
82 | /// This is a low-level enable bit for the breakpoint sites. If a |
83 | /// breakpoint site has no enabled constituents, it should just get removed. |
84 | /// This enable/disable is for the low-level target code to enable and disable |
85 | /// breakpoint sites when single stepping, etc. |
86 | bool IsEnabled() const; |
87 | |
88 | /// Sets whether the current breakpoint site is enabled or not |
89 | /// |
90 | /// \param[in] enabled |
91 | /// \b true if the breakpoint is enabled, \b false otherwise. |
92 | void SetEnabled(bool enabled); |
93 | |
94 | /// Enquires of the breakpoint locations that produced this breakpoint site |
95 | /// whether we should stop at this location. |
96 | /// |
97 | /// \param[in] context |
98 | /// This contains the information about this stop. |
99 | /// |
100 | /// \return |
101 | /// \b true if we should stop, \b false otherwise. |
102 | bool ShouldStop(StoppointCallbackContext *context) override; |
103 | |
104 | /// Standard Dump method |
105 | void Dump(Stream *s) const override; |
106 | |
107 | /// The "Constituents" are the breakpoint locations that share this breakpoint |
108 | /// site. The method adds the \a constituent to this breakpoint site's |
109 | /// constituent list. |
110 | /// |
111 | /// \param[in] constituent |
112 | /// \a constituent is the Breakpoint Location to add. |
113 | void AddConstituent(const lldb::BreakpointLocationSP &constituent); |
114 | |
115 | /// This method returns the number of breakpoint locations currently located |
116 | /// at this breakpoint site. |
117 | /// |
118 | /// \return |
119 | /// The number of constituents. |
120 | size_t GetNumberOfConstituents(); |
121 | |
122 | /// This method returns the breakpoint location at index \a index located at |
123 | /// this breakpoint site. The constituents are listed ordinally from 0 to |
124 | /// GetNumberOfConstituents() - 1 so you can use this method to iterate over |
125 | /// the constituents |
126 | /// |
127 | /// \param[in] idx |
128 | /// The index in the list of constituents for which you wish the |
129 | /// constituent location. |
130 | /// |
131 | /// \return |
132 | /// A shared pointer to the breakpoint location at that index. |
133 | lldb::BreakpointLocationSP GetConstituentAtIndex(size_t idx); |
134 | |
135 | /// This method copies the breakpoint site's constituents into a new |
136 | /// collection. It does this while the constituents mutex is locked. |
137 | /// |
138 | /// \param[out] out_collection |
139 | /// The BreakpointLocationCollection into which to put the constituents |
140 | /// of this breakpoint site. |
141 | /// |
142 | /// \return |
143 | /// The number of elements copied into out_collection. |
144 | size_t CopyConstituentsList(BreakpointLocationCollection &out_collection); |
145 | |
146 | /// Check whether the constituents of this breakpoint site have any thread |
147 | /// specifiers, and if yes, is \a thread contained in any of these |
148 | /// specifiers. |
149 | /// |
150 | /// \param[in] thread |
151 | /// The thread against which to test. |
152 | /// |
153 | /// return |
154 | /// \b true if the collection contains at least one location that |
155 | /// would be valid for this thread, false otherwise. |
156 | bool ValidForThisThread(Thread &thread); |
157 | |
158 | /// Print a description of this breakpoint site to the stream \a s. |
159 | /// GetDescription tells you about the breakpoint site's constituents. Use |
160 | /// BreakpointSite::Dump(Stream *) to get information about the breakpoint |
161 | /// site itself. |
162 | /// |
163 | /// \param[in] s |
164 | /// The stream to which to print the description. |
165 | /// |
166 | /// \param[in] level |
167 | /// The description level that indicates the detail level to |
168 | /// provide. |
169 | /// |
170 | /// \see lldb::DescriptionLevel |
171 | void GetDescription(Stream *s, lldb::DescriptionLevel level); |
172 | |
173 | /// Tell whether a breakpoint has a location at this site. |
174 | /// |
175 | /// \param[in] bp_id |
176 | /// The breakpoint id to query. |
177 | /// |
178 | /// \result |
179 | /// \b true if bp_id has a location that is at this site, |
180 | /// \b false otherwise. |
181 | bool IsBreakpointAtThisSite(lldb::break_id_t bp_id); |
182 | |
183 | /// Tell whether ALL the breakpoints in the location collection are |
184 | /// internal. |
185 | /// |
186 | /// \result |
187 | /// \b true if all breakpoint locations are owned by internal breakpoints, |
188 | /// \b false otherwise. |
189 | bool IsInternal() const; |
190 | |
191 | bool IsHardware() const override { |
192 | lldbassert(BreakpointSite::Type::eHardware == GetType() || |
193 | !HardwareRequired()); |
194 | return BreakpointSite::Type::eHardware == GetType(); |
195 | } |
196 | |
197 | BreakpointSite::Type GetType() const { return m_type; } |
198 | |
199 | void SetType(BreakpointSite::Type type) { m_type = type; } |
200 | |
201 | private: |
202 | friend class Process; |
203 | friend class BreakpointLocation; |
204 | // The StopInfoBreakpoint knows when it is processing a hit for a thread for |
205 | // a site, so let it be the one to manage setting the location hit count once |
206 | // and only once. |
207 | friend class StopInfoBreakpoint; |
208 | |
209 | void BumpHitCounts(); |
210 | |
211 | /// The method removes the constituent at \a break_loc_id from this breakpoint |
212 | /// list. |
213 | size_t RemoveConstituent(lldb::break_id_t break_id, |
214 | lldb::break_id_t break_loc_id); |
215 | |
216 | BreakpointSite::Type m_type; ///< The type of this breakpoint site. |
217 | uint8_t m_saved_opcode[8]; ///< The saved opcode bytes if this breakpoint site |
218 | ///uses trap opcodes. |
219 | uint8_t m_trap_opcode[8]; ///< The opcode that was used to create the |
220 | ///breakpoint if it is a software breakpoint site. |
221 | bool |
222 | m_enabled; ///< Boolean indicating if this breakpoint site enabled or not. |
223 | |
224 | // Consider adding an optimization where if there is only one constituent, we |
225 | // don't store a list. The usual case will be only one constituent... |
226 | BreakpointLocationCollection |
227 | m_constituents; ///< This has the BreakpointLocations |
228 | /// that share this breakpoint site. |
229 | std::recursive_mutex m_constituents_mutex; ///< This mutex protects the |
230 | ///< constituents collection. |
231 | |
232 | static lldb::break_id_t GetNextID(); |
233 | |
234 | // Only the Process can create breakpoint sites in |
235 | // Process::CreateBreakpointSite (lldb::BreakpointLocationSP &, bool). |
236 | BreakpointSite(const lldb::BreakpointLocationSP &constituent, |
237 | lldb::addr_t m_addr, bool use_hardware); |
238 | |
239 | BreakpointSite(const BreakpointSite &) = delete; |
240 | const BreakpointSite &operator=(const BreakpointSite &) = delete; |
241 | }; |
242 | |
243 | } // namespace lldb_private |
244 | |
245 | #endif // LLDB_BREAKPOINT_BREAKPOINTSITE_H |
246 | |