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