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 
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
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 {
187  lldbassert(BreakpointSite::Type::eHardware == GetType() ||
188  !HardwareRequired());
189  return BreakpointSite::Type::eHardware == GetType();
190  }
191 
192  BreakpointSite::Type GetType() const { return m_type; }
193 
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).
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
lldb_private::BreakpointSite::IsBreakpointAtThisSite
bool IsBreakpointAtThisSite(lldb::break_id_t bp_id)
Tell whether a breakpoint has a location at this site.
Definition: BreakpointSite.cpp:64
lldb_private::BreakpointSite::GetSavedOpcodeBytes
uint8_t * GetSavedOpcodeBytes()
Gets the original instruction bytes that were overwritten by the trap.
Definition: BreakpointSite.cpp:115
lldb_private::BreakpointSite::IsInternal
bool IsInternal() const
Tell whether ALL the breakpoints in the location collection are internal.
Definition: BreakpointSite.cpp:92
lldb_private::StoppointCallbackContext
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
Definition: StoppointCallbackContext.h:26
lldb_private::BreakpointSite::Type
Type
Definition: BreakpointSite.h:38
lldb_private::BreakpointSite::CopyOwnersList
size_t CopyOwnersList(BreakpointLocationCollection &out_collection)
This method copies the breakpoint site's owners into a new collection.
Definition: BreakpointSite.cpp:202
lldb_private::BreakpointSite::BumpHitCounts
void BumpHitCounts()
Definition: BreakpointSite.cpp:152
lldb_private::BreakpointSite::AddOwner
void AddOwner(const lldb::BreakpointLocationSP &owner)
The "Owners" are the breakpoint locations that share this breakpoint site.
Definition: BreakpointSite.cpp:125
lldb_private::StopInfoBreakpoint
Definition: StopInfo.cpp:84
lldb_private::Process
Definition: Process.h:340
lldb_private::BreakpointSite::GetOwnerAtIndex
lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx)
This method returns the breakpoint location at index index located at this breakpoint site.
Definition: BreakpointSite.cpp:142
lldb_private::BreakpointSite::BreakpointSite
BreakpointSite(BreakpointSiteList *list, const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr, bool use_hardware)
lldb_private::BreakpointSite::GetType
BreakpointSite::Type GetType() const
Definition: BreakpointSite.h:192
lldb_private::BreakpointSite::m_enabled
bool m_enabled
Boolean indicating if this breakpoint site enabled or not.
Definition: BreakpointSite.h:216
lldb_private::Stream
Definition: Stream.h:28
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb_private::BreakpointSite::ValidForThisThread
bool ValidForThisThread(Thread &thread)
Check whether the owners of this breakpoint site have any thread specifiers, and if yes,...
Definition: BreakpointSite.cpp:147
lldb_private::BreakpointLocation
General Outline: A breakpoint location is defined by the breakpoint that produces it,...
Definition: BreakpointLocation.h:37
lldb_private::BreakpointSite::m_trap_opcode
uint8_t m_trap_opcode[8]
The opcode that was used to create the breakpoint if it is a software breakpoint site.
Definition: BreakpointSite.h:213
lldb_private::BreakpointSite::m_type
BreakpointSite::Type m_type
The type of this breakpoint site.
Definition: BreakpointSite.h:210
lldb_private::BreakpointSite
Definition: BreakpointSite.h:35
LLDBAssert.h
lldb_private::BreakpointSite::GetTrapOpcodeMaxByteSize
size_t GetTrapOpcodeMaxByteSize() const
Get the size of the trap opcode for this address.
Definition: BreakpointSite.cpp:100
lldb_private::BreakpointSite::m_owners_mutex
std::recursive_mutex m_owners_mutex
This mutex protects the owners collection.
Definition: BreakpointSite.h:223
lldb_private::BreakpointSite::eExternal
@ eExternal
Definition: BreakpointSite.h:43
lldb_private::Thread
Definition: Thread.h:60
lldb_private::StoppointSite::HardwareRequired
bool HardwareRequired() const
Definition: StoppointSite.h:37
lldb_private::BreakpointSite::SetEnabled
void SetEnabled(bool enabled)
Sets whether the current breakpoint site is enabled or not.
Definition: BreakpointSite.cpp:123
lldb::break_id_t
int32_t break_id_t
Definition: lldb-types.h:88
lldb_private::BreakpointSite::operator=
const BreakpointSite & operator=(const BreakpointSite &)=delete
lldb_private::BreakpointSite::IsHardware
bool IsHardware() const override
Definition: BreakpointSite.h:186
lldb_private::BreakpointSite::m_owners
BreakpointLocationCollection m_owners
This has the BreakpointLocations that share this breakpoint site.
Definition: BreakpointSite.h:220
lldb_private::BreakpointSite::~BreakpointSite
~BreakpointSite() override
Definition: BreakpointSite.cpp:34
lldb_private::BreakpointLocationCollection
Definition: BreakpointLocationCollection.h:20
UserID.h
lldb_private::BreakpointSite::IntersectsRange
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.
Definition: BreakpointSite.cpp:159
lldbassert
#define lldbassert(x)
Definition: LLDBAssert.h:15
lldb_private::BreakpointSite::m_saved_opcode
uint8_t m_saved_opcode[8]
The saved opcode bytes if this breakpoint site uses trap opcodes.
Definition: BreakpointSite.h:211
lldb_private::BreakpointSite::GetTrapOpcodeBytes
uint8_t * GetTrapOpcodeBytes()
Returns the Opcode Bytes for this breakpoint.
Definition: BreakpointSite.cpp:94
uint32_t
lldb_private::BreakpointSite::RemoveOwner
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.
Definition: BreakpointSite.cpp:130
lldb_private::BreakpointSite::GetDescription
void GetDescription(Stream *s, lldb::DescriptionLevel level)
Print a description of this breakpoint site to the stream s.
Definition: BreakpointSite.cpp:84
lldb_private::BreakpointSite::eHardware
@ eHardware
Definition: BreakpointSite.h:42
lldb_private::BreakpointSite::GetNextID
static lldb::break_id_t GetNextID()
Definition: BreakpointSite.cpp:42
lldb_private::BreakpointSite::ShouldStop
bool ShouldStop(StoppointCallbackContext *context) override
Enquires of the breakpoint locations that produced this breakpoint site whether we should stop at thi...
Definition: BreakpointSite.cpp:50
lldb_private::BreakpointSite::IsEnabled
bool IsEnabled() const
Tells whether the current breakpoint site is enabled or not.
Definition: BreakpointSite.cpp:121
lldb_private::BreakpointSite::eSoftware
@ eSoftware
Definition: BreakpointSite.h:39
BreakpointLocationCollection.h
StoppointSite.h
lldb-forward.h
lldb_private::StoppointSite::m_addr
lldb::addr_t m_addr
The load address of this stop point.
Definition: StoppointSite.h:56
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::BreakpointSite::SetTrapOpcode
bool SetTrapOpcode(const uint8_t *trap_opcode, uint32_t trap_opcode_size)
Sets the trap opcode.
Definition: BreakpointSite.cpp:104
lldb_private::BreakpointSite::GetNumberOfOwners
size_t GetNumberOfOwners()
This method returns the number of breakpoint locations currently located at this breakpoint site.
Definition: BreakpointSite.cpp:137
lldb_private::BreakpointSite::Dump
void Dump(Stream *s) const override
Standard Dump method.
Definition: BreakpointSite.cpp:74
lldb_private::BreakpointSite::SetType
void SetType(BreakpointSite::Type type)
Definition: BreakpointSite.h:194
lldb_private::BreakpointSiteList
Definition: BreakpointSiteList.h:23
lldb::DescriptionLevel
DescriptionLevel
Description levels for "void GetDescription(Stream *, DescriptionLevel)" calls.
Definition: lldb-enumerations.h:207
lldb_private::StoppointSite
Definition: StoppointSite.h:18