LLDB  mainline
BreakpointOptions.h
Go to the documentation of this file.
1 //===-- BreakpointOptions.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_BreakpointOptions_h_
10 #define liblldb_BreakpointOptions_h_
11 
12 #include <memory>
13 #include <string>
14 
15 #include "lldb/Utility/Baton.h"
16 #include "lldb/Utility/Flags.h"
19 #include "lldb/lldb-private.h"
20 
21 namespace lldb_private {
22 
23 /// \class BreakpointOptions BreakpointOptions.h
24 /// "lldb/Breakpoint/BreakpointOptions.h" Class that manages the options on a
25 /// breakpoint or breakpoint location.
26 
28 friend class BreakpointLocation;
29 friend class BreakpointName;
31 friend class Breakpoint;
32 
33 public:
34  enum OptionKind {
35  eCallback = 1 << 0,
36  eEnabled = 1 << 1,
37  eOneShot = 1 << 2,
38  eIgnoreCount = 1 << 3,
39  eThreadSpec = 1 << 4,
40  eCondition = 1 << 5,
41  eAutoContinue = 1 << 6,
44  };
45  struct CommandData {
49 
51  : user_source(user_source), script_source(), interpreter(interp),
52  stop_on_error(true) {}
53 
54  ~CommandData() = default;
55 
56  static const char *GetSerializationKey() { return "BKPTCMDData"; }
57 
59 
60  static std::unique_ptr<CommandData>
62  Status &error);
63 
65  std::string script_source;
67  interpreter; // eScriptLanguageNone means command interpreter.
69 
70  private:
71  enum class OptionNames : uint32_t {
72  UserSource = 0,
73  Interpreter,
74  StopOnError,
75  LastOptionName
76  };
77 
78  static const char
79  *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)];
80 
81  static const char *GetKey(OptionNames enum_value) {
82  return g_option_names[static_cast<uint32_t>(enum_value)];
83  }
84  };
85 
86  class CommandBaton : public TypedBaton<CommandData> {
87  public:
88  explicit CommandBaton(std::unique_ptr<CommandData> Data)
89  : TypedBaton(std::move(Data)) {}
90 
91  void GetDescription(Stream *s, lldb::DescriptionLevel level) const override;
92  };
93 
94  typedef std::shared_ptr<CommandBaton> CommandBatonSP;
95 
96  // Constructors and Destructors
97 
98  /// This constructor allows you to specify all the breakpoint options except
99  /// the callback. That one is more complicated, and better to do by hand.
100  ///
101  /// \param[in] condition
102  /// The expression which if it evaluates to \b true if we are to stop
103  ///
104  /// \param[in] enabled
105  /// Is this breakpoint enabled.
106  ///
107  /// \param[in] ignore
108  /// How many breakpoint hits we should ignore before stopping.
109  ///
110  BreakpointOptions(const char *condition, bool enabled = true,
111  int32_t ignore = 0, bool one_shot = false,
112  bool auto_continue = false);
113 
114  /// Breakpoints make options with all flags set. Locations and Names make
115  /// options with no flags set.
116  BreakpointOptions(bool all_flags_set);
118 
119  virtual ~BreakpointOptions();
120 
121  static std::unique_ptr<BreakpointOptions>
123  const StructuredData::Dictionary &data_dict,
124  Status &error);
125 
127 
128  static const char *GetSerializationKey() { return "BKPTOptions"; }
129 
130  // Operators
131  const BreakpointOptions &operator=(const BreakpointOptions &rhs);
132 
133  /// Copy over only the options set in the incoming BreakpointOptions.
134  void CopyOverSetOptions(const BreakpointOptions &rhs);
135 
136  // Callbacks
137  //
138  // Breakpoint callbacks come in two forms, synchronous and asynchronous.
139  // Synchronous callbacks will get run before any of the thread plans are
140  // consulted, and if they return false the target will continue "under the
141  // radar" of the thread plans. There are a couple of restrictions to
142  // synchronous callbacks:
143  // 1) They should NOT resume the target themselves.
144  // Just return false if you want the target to restart.
145  // 2) Breakpoints with synchronous callbacks can't have conditions
146  // (or rather, they can have them, but they won't do anything.
147  // Ditto with ignore counts, etc... You are supposed to control that all
148  // through the callback.
149  // Asynchronous callbacks get run as part of the "ShouldStop" logic in the
150  // thread plan. The logic there is:
151  // a) If the breakpoint is thread specific and not for this thread, continue
152  // w/o running the callback.
153  // NB. This is actually enforced underneath the breakpoint system, the
154  // Process plugin is expected to
155  // call BreakpointSite::IsValidForThread, and set the thread's StopInfo
156  // to "no reason". That way,
157  // thread displays won't show stops for breakpoints not for that
158  // thread...
159  // b) If the ignore count says we shouldn't stop, then ditto.
160  // c) If the condition says we shouldn't stop, then ditto.
161  // d) Otherwise, the callback will get run, and if it returns true we will
162  // stop, and if false we won't.
163  // The asynchronous callback can run the target itself, but at present that
164  // should be the last action the callback does. We will relax this condition
165  // at some point, but it will take a bit of plumbing to get that to work.
166  //
167 
168  /// Adds a callback to the breakpoint option set.
169  ///
170  /// \param[in] callback
171  /// The function to be called when the breakpoint gets hit.
172  ///
173  /// \param[in] baton_sp
174  /// A baton which will get passed back to the callback when it is invoked.
175  ///
176  /// \param[in] synchronous
177  /// Whether this is a synchronous or asynchronous callback. See discussion
178  /// above.
179  void SetCallback(BreakpointHitCallback callback,
180  const lldb::BatonSP &baton_sp, bool synchronous = false);
181 
182  void SetCallback(BreakpointHitCallback callback,
183  const BreakpointOptions::CommandBatonSP &command_baton_sp,
184  bool synchronous = false);
185 
186  /// Returns the command line commands for the callback on this breakpoint.
187  ///
188  /// \param[out] command_list
189  /// The commands will be appended to this list.
190  ///
191  /// \return
192  /// \btrue if the command callback is a command-line callback,
193  /// \bfalse otherwise.
194  bool GetCommandLineCallbacks(StringList &command_list);
195 
196  /// Remove the callback from this option set.
197  void ClearCallback();
198 
199  // The rest of these functions are meant to be used only within the
200  // breakpoint handling mechanism.
201 
202  /// Use this function to invoke the callback for a specific stop.
203  ///
204  /// \param[in] context
205  /// The context in which the callback is to be invoked. This includes the
206  /// stop event, the
207  /// execution context of the stop (since you might hit the same breakpoint
208  /// on multiple threads) and
209  /// whether we are currently executing synchronous or asynchronous
210  /// callbacks.
211  ///
212  /// \param[in] break_id
213  /// The breakpoint ID that owns this option set.
214  ///
215  /// \param[in] break_loc_id
216  /// The breakpoint location ID that owns this option set.
217  ///
218  /// \return
219  /// The callback return value.
221  lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
222 
223  /// Used in InvokeCallback to tell whether it is the right time to run this
224  /// kind of callback.
225  ///
226  /// \return
227  /// The synchronicity of our callback.
228  bool IsCallbackSynchronous() const { return m_callback_is_synchronous; }
229 
230  /// Fetch the baton from the callback.
231  ///
232  /// \return
233  /// The baton.
234  Baton *GetBaton();
235 
236  /// Fetch a const version of the baton from the callback.
237  ///
238  /// \return
239  /// The baton.
240  const Baton *GetBaton() const;
241 
242  // Condition
243  /// Set the breakpoint option's condition.
244  ///
245  /// \param[in] condition
246  /// The condition expression to evaluate when the breakpoint is hit.
247  void SetCondition(const char *condition);
248 
249  /// Return a pointer to the text of the condition expression.
250  ///
251  /// \return
252  /// A pointer to the condition expression text, or nullptr if no
253  // condition has been set.
254  const char *GetConditionText(size_t *hash = nullptr) const;
255 
256  // Enabled/Ignore Count
257 
258  /// Check the Enable/Disable state.
259  /// \return
260  /// \b true if the breakpoint is enabled, \b false if disabled.
261  bool IsEnabled() const { return m_enabled; }
262 
263  /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
264  void SetEnabled(bool enabled) {
265  m_enabled = enabled;
266  m_set_flags.Set(eEnabled);
267  }
268 
269  /// Check the auto-continue state.
270  /// \return
271  /// \b true if the breakpoint is set to auto-continue, \b false otherwise.
272  bool IsAutoContinue() const { return m_auto_continue; }
273 
274  /// Set the auto-continue state.
275  void SetAutoContinue(bool auto_continue) {
276  m_auto_continue = auto_continue;
277  m_set_flags.Set(eAutoContinue);
278  }
279 
280  /// Check the One-shot state.
281  /// \return
282  /// \b true if the breakpoint is one-shot, \b false otherwise.
283  bool IsOneShot() const { return m_one_shot; }
284 
285  /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
286  void SetOneShot(bool one_shot) {
287  m_one_shot = one_shot;
288  m_set_flags.Set(eOneShot);
289  }
290 
291  /// Set the breakpoint to ignore the next \a count breakpoint hits.
292  /// \param[in] count
293  /// The number of breakpoint hits to ignore.
294 
296  m_ignore_count = n;
297  m_set_flags.Set(eIgnoreCount);
298  }
299 
300  /// Return the current Ignore Count.
301  /// \return
302  /// The number of breakpoint hits to be ignored.
303  uint32_t GetIgnoreCount() const { return m_ignore_count; }
304 
305  /// Return the current thread spec for this option. This will return nullptr
306  /// if the no thread specifications have been set for this Option yet.
307  /// \return
308  /// The thread specification pointer for this option, or nullptr if none
309  /// has
310  /// been set yet.
311  const ThreadSpec *GetThreadSpecNoCreate() const;
312 
313  /// Returns a pointer to the ThreadSpec for this option, creating it. if it
314  /// hasn't been created already. This API is used for setting the
315  /// ThreadSpec items for this option.
317 
318  void SetThreadID(lldb::tid_t thread_id);
319 
320  void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
321 
322  /// Returns true if the breakpoint option has a callback set.
323  bool HasCallback() const;
324 
325  /// This is the default empty callback.
326  static bool NullCallback(void *baton, StoppointCallbackContext *context,
327  lldb::user_id_t break_id,
328  lldb::user_id_t break_loc_id);
329 
330  /// Set a callback based on BreakpointOptions::CommandData. \param[in]
331  /// cmd_data
332  /// A UP holding the new'ed CommandData object.
333  /// The breakpoint will take ownership of pointer held by this object.
334  void SetCommandDataCallback(std::unique_ptr<CommandData> &cmd_data);
335 
336  void Clear();
337 
338  bool AnySet() const {
339  return m_set_flags.AnySet(eAllOptions);
340  }
341 
342 protected:
343  // Classes that inherit from BreakpointOptions can see and modify these
345  {
346  return m_set_flags.Test(kind);
347  }
348 
349  enum class OptionNames {
350  ConditionText = 0,
351  IgnoreCount,
352  EnabledState,
353  OneShotState,
354  AutoContinue,
355  LastOptionName
356  };
357  static const char *g_option_names[(size_t)OptionNames::LastOptionName];
358 
359  static const char *GetKey(OptionNames enum_value) {
360  return g_option_names[(size_t)enum_value];
361  }
362 
364  void *baton, StoppointCallbackContext *context, lldb::user_id_t break_id,
365  lldb::user_id_t break_loc_id);
366 
367  void SetThreadSpec(std::unique_ptr<ThreadSpec> &thread_spec_up);
368 
369 private:
370  // For BreakpointOptions only
371  BreakpointHitCallback m_callback; // This is the callback function pointer
372  lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
373  bool m_baton_is_command_baton;
374  bool m_callback_is_synchronous;
375  bool m_enabled;
376  bool m_one_shot;
377  uint32_t m_ignore_count; // Number of times to ignore this breakpoint
378  std::unique_ptr<ThreadSpec>
379  m_thread_spec_up; // Thread for which this breakpoint will take
380  std::string m_condition_text; // The condition to test.
381  size_t m_condition_text_hash; // Its hash, so that locations know when the
382  // condition is updated.
383  bool m_auto_continue; // If set, auto-continue from breakpoint.
384  Flags m_set_flags; // Which options are set at this level. Drawn
385  // from BreakpointOptions::SetOptionsFlags.
386 };
387 
388 } // namespace lldb_private
389 
390 #endif // liblldb_BreakpointOptions_h_
bool IsAutoContinue() const
Check the auto-continue state.
General Outline: A breakpoint location is defined by the breakpoint that produces it...
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
static std::unique_ptr< CommandData > CreateFromStructuredData(const StructuredData::Dictionary &options_dict, Status &error)
void SetAutoContinue(bool auto_continue)
Set the auto-continue state.
void ClearCallback()
Remove the callback from this option set.
General Outline: A breakpoint has four main parts, a filter, a resolver, the list of breakpoint locat...
Definition: Breakpoint.h:78
void SetCommandDataCallback(std::unique_ptr< CommandData > &cmd_data)
Set a callback based on BreakpointOptions::CommandData.
Baton * GetBaton()
Fetch the baton from the callback.
bool HasCallback() const
Returns true if the breakpoint option has a callback set.
void GetDescription(Stream *s, lldb::DescriptionLevel level) const
void SetOneShot(bool one_shot)
If enable is true, enable the breakpoint, if false disable it.
uint32_t GetIgnoreCount() const
Return the current Ignore Count.
bool IsEnabled() const
Check the Enable/Disable state.
void SetThreadSpec(std::unique_ptr< ThreadSpec > &thread_spec_up)
uint64_t user_id_t
Definition: lldb-types.h:84
void SetCondition(const char *condition)
Set the breakpoint option&#39;s condition.
bool IsOptionSet(OptionKind kind)
BreakpointOptions(const char *condition, bool enabled=true, int32_t ignore=0, bool one_shot=false, bool auto_continue=false)
This constructor allows you to specify all the breakpoint options except the callback.
void SetEnabled(bool enabled)
If enable is true, enable the breakpoint, if false disable it.
uint64_t tid_t
Definition: lldb-types.h:86
static const char * GetSerializationKey()
static const char * GetKey(OptionNames enum_value)
const ThreadSpec * GetThreadSpecNoCreate() const
Return the current thread spec for this option.
void CopyOverSetOptions(const BreakpointOptions &rhs)
Copy over only the options set in the incoming BreakpointOptions.
std::shared_ptr< CommandBaton > CommandBatonSP
CommandBaton(std::unique_ptr< CommandData > Data)
ThreadSpec * GetThreadSpec()
Returns a pointer to the ThreadSpec for this option, creating it.
const BreakpointOptions & operator=(const BreakpointOptions &rhs)
bool InvokeCallback(StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id)
Use this function to invoke the callback for a specific stop.
void SetIgnoreCount(uint32_t n)
Set the breakpoint to ignore the next count breakpoint hits.
A class to manage flags.
Definition: Flags.h:22
bool GetCommandLineCallbacks(StringList &command_list)
Returns the command line commands for the callback on this breakpoint.
bool IsCallbackSynchronous() const
Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
const char * GetConditionText(size_t *hash=nullptr) const
Return a pointer to the text of the condition expression.
"lldb/Breakpoint/BreakpointOptions.h" Class that manages the options on a breakpoint or breakpoint lo...
Definition: SBAddress.h:15
static bool BreakpointOptionsCallbackFunction(void *baton, StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id)
std::shared_ptr< Object > ObjectSP
bool IsOneShot() const
Check the One-shot state.
static bool NullCallback(void *baton, StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id)
This is the default empty callback.
void SetThreadID(lldb::tid_t thread_id)
A class designed to wrap callback batons so they can cleanup any acquired resources.
Definition: Baton.h:33
void SetCallback(BreakpointHitCallback callback, const lldb::BatonSP &baton_sp, bool synchronous=false)
Adds a callback to the breakpoint option set.
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
StructuredData::ObjectSP SerializeToStructuredData()
CommandData(const StringList &user_source, lldb::ScriptLanguage interp)
An error handling class.
Definition: Status.h:44