1 //===-- BreakpointOptions.h -------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_BreakpointOptions_h_
11 #define liblldb_BreakpointOptions_h_
18 // Other libraries and framework includes
20 #include "lldb/Utility/Baton.h"
21 #include "lldb/Utility/Flags.h"
22 #include "lldb/Utility/StringList.h"
23 #include "lldb/Utility/StructuredData.h"
24 #include "lldb/lldb-private.h"
26 namespace lldb_private {
28 //----------------------------------------------------------------------
29 /// @class BreakpointOptions BreakpointOptions.h
30 /// "lldb/Breakpoint/BreakpointOptions.h"
31 /// @brief Class that manages the options on a breakpoint or breakpoint
33 //----------------------------------------------------------------------
35 class BreakpointOptions {
36 friend class BreakpointLocation;
37 friend class BreakpointName;
38 friend class lldb_private::BreakpointOptionGroup;
39 friend class Breakpoint;
46 eIgnoreCount = 1 << 3,
49 eAutoContinue = 1 << 6,
50 eAllOptions = (eCallback | eEnabled | eOneShot | eIgnoreCount | eThreadSpec
51 | eCondition | eAutoContinue)
55 : user_source(), script_source(),
56 interpreter(lldb::eScriptLanguageNone), stop_on_error(true) {}
58 CommandData(const StringList &user_source, lldb::ScriptLanguage interp)
59 : user_source(user_source), script_source(), interpreter(interp),
60 stop_on_error(true) {}
62 ~CommandData() = default;
64 static const char *GetSerializationKey() { return "BKPTCMDData"; }
66 StructuredData::ObjectSP SerializeToStructuredData();
68 static std::unique_ptr<CommandData>
69 CreateFromStructuredData(const StructuredData::Dictionary &options_dict,
72 StringList user_source;
73 std::string script_source;
74 enum lldb::ScriptLanguage
75 interpreter; // eScriptLanguageNone means command interpreter.
79 enum class OptionNames : uint32_t {
87 *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)];
89 static const char *GetKey(OptionNames enum_value) {
90 return g_option_names[static_cast<uint32_t>(enum_value)];
94 class CommandBaton : public TypedBaton<CommandData> {
96 explicit CommandBaton(std::unique_ptr<CommandData> Data)
97 : TypedBaton(std::move(Data)) {}
99 void GetDescription(Stream *s, lldb::DescriptionLevel level) const override;
102 typedef std::shared_ptr<CommandBaton> CommandBatonSP;
104 //------------------------------------------------------------------
105 // Constructors and Destructors
106 //------------------------------------------------------------------
108 //------------------------------------------------------------------
109 /// This constructor allows you to specify all the breakpoint options
110 /// except the callback. That one is more complicated, and better
113 /// @param[in] condition
114 /// The expression which if it evaluates to \b true if we are to stop
116 /// @param[in] enabled
117 /// Is this breakpoint enabled.
119 /// @param[in] ignore
120 /// How many breakpoint hits we should ignore before stopping.
122 //------------------------------------------------------------------
123 BreakpointOptions(const char *condition, bool enabled = true,
124 int32_t ignore = 0, bool one_shot = false,
125 bool auto_continue = false);
127 //------------------------------------------------------------------
128 /// Breakpoints make options with all flags set. Locations and Names make options
129 /// with no flags set.
130 //------------------------------------------------------------------
131 BreakpointOptions(bool all_flags_set);
132 BreakpointOptions(const BreakpointOptions &rhs);
134 virtual ~BreakpointOptions();
136 static std::unique_ptr<BreakpointOptions>
137 CreateFromStructuredData(Target &target,
138 const StructuredData::Dictionary &data_dict,
141 virtual StructuredData::ObjectSP SerializeToStructuredData();
143 static const char *GetSerializationKey() { return "BKPTOptions"; }
145 //------------------------------------------------------------------
147 //------------------------------------------------------------------
148 const BreakpointOptions &operator=(const BreakpointOptions &rhs);
150 //------------------------------------------------------------------
151 /// Copy over only the options set in the incoming BreakpointOptions.
152 //------------------------------------------------------------------
153 void CopyOverSetOptions(const BreakpointOptions &rhs);
155 //------------------------------------------------------------------
158 // Breakpoint callbacks come in two forms, synchronous and asynchronous.
159 // Synchronous callbacks will get
160 // run before any of the thread plans are consulted, and if they return false
161 // the target will continue
162 // "under the radar" of the thread plans. There are a couple of restrictions
163 // to synchronous callbacks:
164 // 1) They should NOT resume the target themselves. Just return false if you
165 // want the target to restart.
166 // 2) Breakpoints with synchronous callbacks can't have conditions (or rather,
167 // they can have them, but they
168 // won't do anything. Ditto with ignore counts, etc... You are supposed
169 // to control that all through the
171 // Asynchronous callbacks get run as part of the "ShouldStop" logic in the
172 // thread plan. The logic there is:
173 // a) If the breakpoint is thread specific and not for this thread, continue
174 // w/o running the callback.
175 // NB. This is actually enforced underneath the breakpoint system, the
176 // Process plugin is expected to
177 // call BreakpointSite::IsValidForThread, and set the thread's StopInfo
178 // to "no reason". That way,
179 // thread displays won't show stops for breakpoints not for that
181 // b) If the ignore count says we shouldn't stop, then ditto.
182 // c) If the condition says we shouldn't stop, then ditto.
183 // d) Otherwise, the callback will get run, and if it returns true we will
184 // stop, and if false we won't.
185 // The asynchronous callback can run the target itself, but at present that
186 // should be the last action the
187 // callback does. We will relax this condition at some point, but it will
188 // take a bit of plumbing to get
191 //------------------------------------------------------------------
193 //------------------------------------------------------------------
194 /// Adds a callback to the breakpoint option set.
196 /// @param[in] callback
197 /// The function to be called when the breakpoint gets hit.
199 /// @param[in] baton_sp
200 /// A baton which will get passed back to the callback when it is invoked.
202 /// @param[in] synchronous
203 /// Whether this is a synchronous or asynchronous callback. See discussion
205 //------------------------------------------------------------------
206 void SetCallback(BreakpointHitCallback callback,
207 const lldb::BatonSP &baton_sp, bool synchronous = false);
209 void SetCallback(BreakpointHitCallback callback,
210 const BreakpointOptions::CommandBatonSP &command_baton_sp,
211 bool synchronous = false);
213 //------------------------------------------------------------------
214 /// Returns the command line commands for the callback on this breakpoint.
216 /// @param[out] command_list
217 /// The commands will be appended to this list.
220 /// \btrue if the command callback is a command-line callback,
221 /// \bfalse otherwise.
222 //------------------------------------------------------------------
223 bool GetCommandLineCallbacks(StringList &command_list);
225 //------------------------------------------------------------------
226 /// Remove the callback from this option set.
227 //------------------------------------------------------------------
228 void ClearCallback();
230 // The rest of these functions are meant to be used only within the breakpoint
231 // handling mechanism.
233 //------------------------------------------------------------------
234 /// Use this function to invoke the callback for a specific stop.
236 /// @param[in] context
237 /// The context in which the callback is to be invoked. This includes the
239 /// execution context of the stop (since you might hit the same breakpoint
240 /// on multiple threads) and
241 /// whether we are currently executing synchronous or asynchronous
244 /// @param[in] break_id
245 /// The breakpoint ID that owns this option set.
247 /// @param[in] break_loc_id
248 /// The breakpoint location ID that owns this option set.
251 /// The callback return value.
252 //------------------------------------------------------------------
253 bool InvokeCallback(StoppointCallbackContext *context,
254 lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
256 //------------------------------------------------------------------
257 /// Used in InvokeCallback to tell whether it is the right time to run this
258 /// kind of callback.
261 /// The synchronicity of our callback.
262 //------------------------------------------------------------------
263 bool IsCallbackSynchronous() const { return m_callback_is_synchronous; }
265 //------------------------------------------------------------------
266 /// Fetch the baton from the callback.
270 //------------------------------------------------------------------
273 //------------------------------------------------------------------
274 /// Fetch a const version of the baton from the callback.
278 //------------------------------------------------------------------
279 const Baton *GetBaton() const;
281 //------------------------------------------------------------------
283 //------------------------------------------------------------------
284 //------------------------------------------------------------------
285 /// Set the breakpoint option's condition.
287 /// @param[in] condition
288 /// The condition expression to evaluate when the breakpoint is hit.
289 //------------------------------------------------------------------
290 void SetCondition(const char *condition);
292 //------------------------------------------------------------------
293 /// Return a pointer to the text of the condition expression.
296 /// A pointer to the condition expression text, or nullptr if no
297 // condition has been set.
298 //------------------------------------------------------------------
299 const char *GetConditionText(size_t *hash = nullptr) const;
301 //------------------------------------------------------------------
302 // Enabled/Ignore Count
303 //------------------------------------------------------------------
305 //------------------------------------------------------------------
306 /// Check the Enable/Disable state.
308 /// \b true if the breakpoint is enabled, \b false if disabled.
309 //------------------------------------------------------------------
310 bool IsEnabled() const { return m_enabled; }
312 //------------------------------------------------------------------
313 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
314 //------------------------------------------------------------------
315 void SetEnabled(bool enabled) {
317 m_set_flags.Set(eEnabled);
320 //------------------------------------------------------------------
321 /// Check the auto-continue state.
323 /// \b true if the breakpoint is set to auto-continue, \b false otherwise.
324 //------------------------------------------------------------------
325 bool IsAutoContinue() const { return m_auto_continue; }
327 //------------------------------------------------------------------
328 /// Set the auto-continue state.
329 //------------------------------------------------------------------
330 void SetAutoContinue(bool auto_continue) {
331 m_auto_continue = auto_continue;
332 m_set_flags.Set(eAutoContinue);
335 //------------------------------------------------------------------
336 /// Check the One-shot state.
338 /// \b true if the breakpoint is one-shot, \b false otherwise.
339 //------------------------------------------------------------------
340 bool IsOneShot() const { return m_one_shot; }
342 //------------------------------------------------------------------
343 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
344 //------------------------------------------------------------------
345 void SetOneShot(bool one_shot) {
346 m_one_shot = one_shot;
347 m_set_flags.Set(eOneShot);
350 //------------------------------------------------------------------
351 /// Set the breakpoint to ignore the next \a count breakpoint hits.
353 /// The number of breakpoint hits to ignore.
354 //------------------------------------------------------------------
356 void SetIgnoreCount(uint32_t n) {
358 m_set_flags.Set(eIgnoreCount);
361 //------------------------------------------------------------------
362 /// Return the current Ignore Count.
364 /// The number of breakpoint hits to be ignored.
365 //------------------------------------------------------------------
366 uint32_t GetIgnoreCount() const { return m_ignore_count; }
368 //------------------------------------------------------------------
369 /// Return the current thread spec for this option. This will return nullptr
371 /// specifications have been set for this Option yet.
373 /// The thread specification pointer for this option, or nullptr if none
376 //------------------------------------------------------------------
377 const ThreadSpec *GetThreadSpecNoCreate() const;
379 //------------------------------------------------------------------
380 /// Returns a pointer to the ThreadSpec for this option, creating it.
381 /// if it hasn't been created already. This API is used for setting the
382 /// ThreadSpec items for this option.
383 //------------------------------------------------------------------
384 ThreadSpec *GetThreadSpec();
386 void SetThreadID(lldb::tid_t thread_id);
388 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
390 //------------------------------------------------------------------
391 /// Returns true if the breakpoint option has a callback set.
392 //------------------------------------------------------------------
393 bool HasCallback() const;
395 //------------------------------------------------------------------
396 /// This is the default empty callback.
397 //------------------------------------------------------------------
398 static bool NullCallback(void *baton, StoppointCallbackContext *context,
399 lldb::user_id_t break_id,
400 lldb::user_id_t break_loc_id);
402 //------------------------------------------------------------------
403 /// Set a callback based on BreakpointOptions::CommandData.
404 /// @param[in] cmd_data
405 /// A UP holding the new'ed CommandData object.
406 /// The breakpoint will take ownership of pointer held by this object.
407 //------------------------------------------------------------------
408 void SetCommandDataCallback(std::unique_ptr<CommandData> &cmd_data);
412 bool AnySet() const {
413 return m_set_flags.AnySet(eAllOptions);
417 //------------------------------------------------------------------
418 // Classes that inherit from BreakpointOptions can see and modify these
419 //------------------------------------------------------------------
420 bool IsOptionSet(OptionKind kind)
422 return m_set_flags.Test(kind);
425 enum class OptionNames {
433 static const char *g_option_names[(size_t)OptionNames::LastOptionName];
435 static const char *GetKey(OptionNames enum_value) {
436 return g_option_names[(size_t)enum_value];
439 static bool BreakpointOptionsCallbackFunction(
440 void *baton, StoppointCallbackContext *context, lldb::user_id_t break_id,
441 lldb::user_id_t break_loc_id);
443 void SetThreadSpec(std::unique_ptr<ThreadSpec> &thread_spec_up);
446 //------------------------------------------------------------------
447 // For BreakpointOptions only
448 //------------------------------------------------------------------
449 BreakpointHitCallback m_callback; // This is the callback function pointer
450 lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
451 bool m_baton_is_command_baton;
452 bool m_callback_is_synchronous;
455 uint32_t m_ignore_count; // Number of times to ignore this breakpoint
456 std::unique_ptr<ThreadSpec>
457 m_thread_spec_ap; // Thread for which this breakpoint will take
458 std::string m_condition_text; // The condition to test.
459 size_t m_condition_text_hash; // Its hash, so that locations know when the
460 // condition is updated.
461 bool m_auto_continue; // If set, auto-continue from breakpoint.
462 Flags m_set_flags; // Which options are set at this level. Drawn
463 // from BreakpointOptions::SetOptionsFlags.
466 } // namespace lldb_private
468 #endif // liblldb_BreakpointOptions_h_