LLDB mainline
BreakpointSite.h
Go to the documentation of this file.
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
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 StoppointSite {
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
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.
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 bool IsHardware() const override {
190 }
191
193
194 void SetType(BreakpointSite::Type type) { m_type = type; }
195
196private:
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
226
227 // Only the Process can create breakpoint sites in
228 // Process::CreateBreakpointSite (lldb::BreakpointLocationSP &, bool).
230 const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr,
231 bool use_hardware);
232
234 const BreakpointSite &operator=(const BreakpointSite &) = delete;
235};
236
237} // namespace lldb_private
238
239#endif // LLDB_BREAKPOINT_BREAKPOINTSITE_H
#define lldbassert(x)
Definition: LLDBAssert.h:15
General Outline: A breakpoint location is defined by the breakpoint that produces it,...
"lldb/Breakpoint/BreakpointSiteList.h" Class that manages lists of BreakpointSite shared pointers.
Class that manages the actual breakpoint that will be inserted into the running program.
bool SetTrapOpcode(const uint8_t *trap_opcode, uint32_t trap_opcode_size)
Sets the trap opcode.
static lldb::break_id_t GetNextID()
void Dump(Stream *s) const override
Standard Dump method.
bool ShouldStop(StoppointCallbackContext *context) override
Enquires of the breakpoint locations that produced this breakpoint site whether we should stop at thi...
const BreakpointSite & operator=(const BreakpointSite &)=delete
size_t GetTrapOpcodeMaxByteSize() const
Get the size of the trap opcode for this address.
BreakpointSite::Type m_type
The type of this breakpoint site.
BreakpointSite::Type GetType() const
void SetType(BreakpointSite::Type type)
bool IntersectsRange(lldb::addr_t addr, size_t size, lldb::addr_t *intersect_addr, size_t *intersect_size, size_t *opcode_offset) const
Says whether addr and size size intersects with the address intersect_addr.
void AddOwner(const lldb::BreakpointLocationSP &owner)
The "Owners" are the breakpoint locations that share this breakpoint site.
bool IsBreakpointAtThisSite(lldb::break_id_t bp_id)
Tell whether a breakpoint has a location at this site.
uint8_t * GetTrapOpcodeBytes()
Returns the Opcode Bytes for this breakpoint.
bool IsInternal() const
Tell whether ALL the breakpoints in the location collection are internal.
bool ValidForThisThread(Thread &thread)
Check whether the owners of this breakpoint site have any thread specifiers, and if yes,...
void GetDescription(Stream *s, lldb::DescriptionLevel level)
Print a description of this breakpoint site to the stream s.
size_t CopyOwnersList(BreakpointLocationCollection &out_collection)
This method copies the breakpoint site's owners into a new collection.
BreakpointLocationCollection m_owners
This has the BreakpointLocations that share this breakpoint site.
uint8_t m_trap_opcode[8]
The opcode that was used to create the breakpoint if it is a software breakpoint site.
uint8_t * GetSavedOpcodeBytes()
Gets the original instruction bytes that were overwritten by the trap.
BreakpointSite(const BreakpointSite &)=delete
bool IsHardware() const override
lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx)
This method returns the breakpoint location at index index located at this breakpoint site.
bool m_enabled
Boolean indicating if this breakpoint site enabled or not.
uint8_t m_saved_opcode[8]
The saved opcode bytes if this breakpoint site uses trap opcodes.
size_t GetNumberOfOwners()
This method returns the number of breakpoint locations currently located at this breakpoint site.
bool IsEnabled() const
Tells whether the current breakpoint site is enabled or not.
BreakpointSite(BreakpointSiteList *list, const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr, bool use_hardware)
std::recursive_mutex m_owners_mutex
This mutex protects the owners collection.
size_t RemoveOwner(lldb::break_id_t break_id, lldb::break_id_t break_loc_id)
The method removes the owner at break_loc_id from this breakpoint list.
void SetEnabled(bool enabled)
Sets whether the current breakpoint site is enabled or not.
A plug-in interface definition class for debugging a process.
Definition: Process.h:342
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
lldb::addr_t m_addr
The load address of this stop point.
Definition: StoppointSite.h:56
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
A class that represents a running process on the host machine.
DescriptionLevel
Description levels for "void GetDescription(Stream *, DescriptionLevel)" calls.
int32_t break_id_t
Definition: lldb-types.h:88
uint64_t addr_t
Definition: lldb-types.h:83