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 liblldb_BreakpointSite_h_
10 #define liblldb_BreakpointSite_h_
11 
12 
13 #include <list>
14 #include <mutex>
15 
16 
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 StoppointLocation {
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  ///
103  /// \param[in] context
104  /// The stream to dump this output.
105  void Dump(Stream *s) const override;
106 
107  /// The "Owners" are the breakpoint locations that share this breakpoint
108  /// site. The method adds the \a owner to this breakpoint site's owner list.
109  ///
110  /// \param[in] context
111  /// \a owner is the Breakpoint Location to add.
112  void AddOwner(const lldb::BreakpointLocationSP &owner);
113 
114  /// This method returns the number of breakpoint locations currently located
115  /// at this breakpoint site.
116  ///
117  /// \return
118  /// The number of owners.
119  size_t GetNumberOfOwners();
120 
121  /// This method returns the breakpoint location at index \a index located at
122  /// this breakpoint site. The owners are listed ordinally from 0 to
123  /// GetNumberOfOwners() - 1 so you can use this method to iterate over the
124  /// owners
125  ///
126  /// \param[in] index
127  /// The index in the list of owners for which you wish the owner location.
128  /// \return
129  /// A shared pointer to the breakpoint location at that index.
130  lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx);
131 
132  /// This method copies the breakpoint site's owners into a new collection.
133  /// It does this while the owners mutex is locked.
134  ///
135  /// \param[out] out_collection
136  /// The BreakpointLocationCollection into which to put the owners
137  /// of this breakpoint site.
138  ///
139  /// \return
140  /// The number of elements copied into out_collection.
141  size_t CopyOwnersList(BreakpointLocationCollection &out_collection);
142 
143  /// Check whether the owners of this breakpoint site have any thread
144  /// specifiers, and if yes, is \a thread contained in any of these
145  /// specifiers.
146  ///
147  /// \param[in] thread
148  /// The thread against which to test.
149  ///
150  /// return
151  /// \b true if the collection contains at least one location that
152  /// would be valid for this thread, false otherwise.
153  bool ValidForThisThread(Thread *thread);
154 
155  /// Print a description of this breakpoint site to the stream \a s.
156  /// GetDescription tells you about the breakpoint site's owners. Use
157  /// BreakpointSite::Dump(Stream *) to get information about the breakpoint
158  /// site itself.
159  ///
160  /// \param[in] s
161  /// The stream to which to print the description.
162  ///
163  /// \param[in] level
164  /// The description level that indicates the detail level to
165  /// provide.
166  ///
167  /// \see lldb::DescriptionLevel
169 
170  /// Tell whether a breakpoint has a location at this site.
171  ///
172  /// \param[in] bp_id
173  /// The breakpoint id to query.
174  ///
175  /// \result
176  /// \b true if bp_id has a location that is at this site,
177  /// \b false otherwise.
179 
180  /// Tell whether ALL the breakpoints in the location collection are
181  /// internal.
182  ///
183  /// \result
184  /// \b true if all breakpoint locations are owned by internal breakpoints,
185  /// \b false otherwise.
186  bool IsInternal() const;
187 
188  BreakpointSite::Type GetType() const { return m_type; }
189 
190  void SetType(BreakpointSite::Type type) { m_type = type; }
191 
192 private:
193  friend class Process;
194  friend class BreakpointLocation;
195  // The StopInfoBreakpoint knows when it is processing a hit for a thread for
196  // a site, so let it be the one to manage setting the location hit count once
197  // and only once.
198  friend class StopInfoBreakpoint;
199 
200  void BumpHitCounts();
201 
202  /// The method removes the owner at \a break_loc_id from this breakpoint
203  /// list.
204  ///
205  /// \param[in] context
206  /// \a break_loc_id is the Breakpoint Location to remove.
207  size_t RemoveOwner(lldb::break_id_t break_id, lldb::break_id_t break_loc_id);
208 
209  BreakpointSite::Type m_type; ///< The type of this breakpoint site.
210  uint8_t m_saved_opcode[8]; ///< The saved opcode bytes if this breakpoint site
211  ///uses trap opcodes.
212  uint8_t m_trap_opcode[8]; ///< The opcode that was used to create the
213  ///breakpoint if it is a software breakpoint site.
214  bool
215  m_enabled; ///< Boolean indicating if this breakpoint site enabled or not.
216 
217  // Consider adding an optimization where if there is only one owner, we don't
218  // store a list. The usual case will be only one owner...
219  BreakpointLocationCollection m_owners; ///< This has the BreakpointLocations
220  ///that share this breakpoint site.
221  std::recursive_mutex
222  m_owners_mutex; ///< This mutex protects the owners collection.
223 
224  static lldb::break_id_t GetNextID();
225 
226  // Only the Process can create breakpoint sites in
227  // Process::CreateBreakpointSite (lldb::BreakpointLocationSP &, bool).
229  const lldb::BreakpointLocationSP &owner, lldb::addr_t m_addr,
230  bool use_hardware);
231 
232  DISALLOW_COPY_AND_ASSIGN(BreakpointSite);
233 };
234 
235 } // namespace lldb_private
236 
237 #endif // liblldb_BreakpointSite_h_
Class that manages the actual breakpoint that will be inserted into the running program.
bool IsBreakpointAtThisSite(lldb::break_id_t bp_id)
Tell whether a breakpoint has a location at this site.
General Outline: A breakpoint location is defined by the breakpoint that produces it...
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
void AddOwner(const lldb::BreakpointLocationSP &owner)
The "Owners" are the breakpoint locations that share this breakpoint site.
int32_t break_id_t
Definition: lldb-types.h:88
bool SetTrapOpcode(const uint8_t *trap_opcode, uint32_t trap_opcode_size)
Sets the trap opcode.
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
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...
size_t GetTrapOpcodeMaxByteSize() const
Get the size of the trap opcode for this address.
size_t GetNumberOfOwners()
This method returns the number of breakpoint locations currently located at this breakpoint site...
uint8_t * GetTrapOpcodeBytes()
Returns the Opcode Bytes for this breakpoint.
size_t CopyOwnersList(BreakpointLocationCollection &out_collection)
This method copies the breakpoint site&#39;s owners into a new collection.
bool IsEnabled() const
Tells whether the current breakpoint site is enabled or not.
void GetDescription(Stream *s, lldb::DescriptionLevel level)
Print a description of this breakpoint site to the stream s.
bool ShouldStop(StoppointCallbackContext *context) override
Enquires of the breakpoint locations that produced this breakpoint site whether we should stop at thi...
void SetEnabled(bool enabled)
Sets whether the current breakpoint site is enabled or not.
BreakpointSite::Type GetType() const
uint8_t * GetSavedOpcodeBytes()
Gets the original instruction bytes that were overwritten by the trap.
A plug-in interface definition class for debugging a process.
Definition: Process.h:353
void SetType(BreakpointSite::Type type)
void Dump(Stream *s) const override
Standard Dump method.
uint64_t addr_t
Definition: lldb-types.h:83
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.
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
"lldb/Breakpoint/BreakpointSiteList.h" Class that manages lists of BreakpointSite shared pointers...
lldb::BreakpointLocationSP GetOwnerAtIndex(size_t idx)
This method returns the breakpoint location at index index located at this breakpoint site...