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/Core/Baton.h"
21 #include "lldb/Core/StringList.h"
22 #include "lldb/Core/StructuredData.h"
23 #include "lldb/lldb-private.h"
25 namespace lldb_private {
27 //----------------------------------------------------------------------
28 /// @class BreakpointOptions BreakpointOptions.h
29 /// "lldb/Breakpoint/BreakpointOptions.h"
30 /// @brief Class that manages the options on a breakpoint or breakpoint
32 //----------------------------------------------------------------------
34 class BreakpointOptions {
38 : user_source(), script_source(),
39 interpreter(lldb::eScriptLanguageNone), stop_on_error(true) {}
41 CommandData(const StringList &user_source, lldb::ScriptLanguage interp)
42 : user_source(user_source), script_source(), interpreter(interp),
43 stop_on_error(true) {}
45 ~CommandData() = default;
47 static const char *GetSerializationKey() { return "BKPTCMDData"; }
49 StructuredData::ObjectSP SerializeToStructuredData();
51 static std::unique_ptr<CommandData>
52 CreateFromStructuredData(const StructuredData::Dictionary &options_dict,
55 StringList user_source;
56 std::string script_source;
57 enum lldb::ScriptLanguage
58 interpreter; // eScriptLanguageNone means command interpreter.
62 enum class OptionNames : uint32_t {
70 *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)];
72 static const char *GetKey(OptionNames enum_value) {
73 return g_option_names[static_cast<uint32_t>(enum_value)];
77 class CommandBaton : public TypedBaton<CommandData> {
79 explicit CommandBaton(std::unique_ptr<CommandData> Data)
80 : TypedBaton(std::move(Data)) {}
82 void GetDescription(Stream *s, lldb::DescriptionLevel level) const override;
85 typedef std::shared_ptr<CommandBaton> CommandBatonSP;
87 //------------------------------------------------------------------
88 // Constructors and Destructors
89 //------------------------------------------------------------------
90 //------------------------------------------------------------------
91 /// Default constructor. The breakpoint is enabled, and has no condition,
92 /// callback, ignore count, etc...
93 //------------------------------------------------------------------
95 BreakpointOptions(const BreakpointOptions &rhs);
97 static BreakpointOptions *CopyOptionsNoCallback(BreakpointOptions &rhs);
99 //------------------------------------------------------------------
100 /// This constructor allows you to specify all the breakpoint options
101 /// except the callback. That one is more complicated, and better
104 /// @param[in] condition
105 /// The expression which if it evaluates to \b true if we are to stop
107 /// @param[in] enabled
108 /// Is this breakpoint enabled.
110 /// @param[in] ignore
111 /// How many breakpoint hits we should ignore before stopping.
113 //------------------------------------------------------------------
114 BreakpointOptions(const char *condition, bool enabled = true,
115 int32_t ignore = 0, bool one_shot = false);
117 virtual ~BreakpointOptions();
119 static std::unique_ptr<BreakpointOptions>
120 CreateFromStructuredData(Target &target,
121 const StructuredData::Dictionary &data_dict,
124 virtual StructuredData::ObjectSP SerializeToStructuredData();
126 static const char *GetSerializationKey() { return "BKPTOptions"; }
128 //------------------------------------------------------------------
130 //------------------------------------------------------------------
131 const BreakpointOptions &operator=(const BreakpointOptions &rhs);
133 //------------------------------------------------------------------
136 // Breakpoint callbacks come in two forms, synchronous and asynchronous.
137 // Synchronous callbacks will get
138 // run before any of the thread plans are consulted, and if they return false
139 // the target will continue
140 // "under the radar" of the thread plans. There are a couple of restrictions
141 // to synchronous callbacks:
142 // 1) They should NOT resume the target themselves. Just return false if you
143 // want the target to restart.
144 // 2) Breakpoints with synchronous callbacks can't have conditions (or rather,
145 // they can have them, but they
146 // won't do anything. Ditto with ignore counts, etc... You are supposed
147 // to control that all through the
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
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
165 // callback does. We will relax this condition at some point, but it will
166 // take a bit of plumbing to get
169 //------------------------------------------------------------------
171 //------------------------------------------------------------------
172 /// Adds a callback to the breakpoint option set.
174 /// @param[in] callback
175 /// The function to be called when the breakpoint gets hit.
177 /// @param[in] baton_sp
178 /// A baton which will get passed back to the callback when it is invoked.
180 /// @param[in] synchronous
181 /// Whether this is a synchronous or asynchronous callback. See discussion
183 //------------------------------------------------------------------
184 void SetCallback(BreakpointHitCallback callback,
185 const lldb::BatonSP &baton_sp, bool synchronous = false);
187 void SetCallback(BreakpointHitCallback callback,
188 const BreakpointOptions::CommandBatonSP &command_baton_sp,
189 bool synchronous = false);
191 //------------------------------------------------------------------
192 /// Returns the command line commands for the callback on this breakpoint.
194 /// @param[out] command_list
195 /// The commands will be appended to this list.
198 /// \btrue if the command callback is a command-line callback,
199 /// \bfalse otherwise.
200 //------------------------------------------------------------------
201 bool GetCommandLineCallbacks(StringList &command_list);
203 //------------------------------------------------------------------
204 /// Remove the callback from this option set.
205 //------------------------------------------------------------------
206 void ClearCallback();
208 // The rest of these functions are meant to be used only within the breakpoint
209 // handling mechanism.
211 //------------------------------------------------------------------
212 /// Use this function to invoke the callback for a specific stop.
214 /// @param[in] context
215 /// The context in which the callback is to be invoked. This includes the
217 /// execution context of the stop (since you might hit the same breakpoint
218 /// on multiple threads) and
219 /// whether we are currently executing synchronous or asynchronous
222 /// @param[in] break_id
223 /// The breakpoint ID that owns this option set.
225 /// @param[in] break_loc_id
226 /// The breakpoint location ID that owns this option set.
229 /// The callback return value.
230 //------------------------------------------------------------------
231 bool InvokeCallback(StoppointCallbackContext *context,
232 lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
234 //------------------------------------------------------------------
235 /// Used in InvokeCallback to tell whether it is the right time to run this
236 /// kind of callback.
239 /// The synchronicity of our callback.
240 //------------------------------------------------------------------
241 bool IsCallbackSynchronous() const { return m_callback_is_synchronous; }
243 //------------------------------------------------------------------
244 /// Fetch the baton from the callback.
248 //------------------------------------------------------------------
251 //------------------------------------------------------------------
252 /// Fetch a const version of the baton from the callback.
256 //------------------------------------------------------------------
257 const Baton *GetBaton() const;
259 //------------------------------------------------------------------
261 //------------------------------------------------------------------
262 //------------------------------------------------------------------
263 /// Set the breakpoint option's condition.
265 /// @param[in] condition
266 /// The condition expression to evaluate when the breakpoint is hit.
267 //------------------------------------------------------------------
268 void SetCondition(const char *condition);
270 //------------------------------------------------------------------
271 /// Return a pointer to the text of the condition expression.
274 /// A pointer to the condition expression text, or nullptr if no
275 // condition has been set.
276 //------------------------------------------------------------------
277 const char *GetConditionText(size_t *hash = nullptr) const;
279 //------------------------------------------------------------------
280 // Enabled/Ignore Count
281 //------------------------------------------------------------------
283 //------------------------------------------------------------------
284 /// Check the Enable/Disable state.
286 /// \b true if the breakpoint is enabled, \b false if disabled.
287 //------------------------------------------------------------------
288 bool IsEnabled() const { return m_enabled; }
290 //------------------------------------------------------------------
291 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
292 //------------------------------------------------------------------
293 void SetEnabled(bool enabled) { m_enabled = enabled; }
295 //------------------------------------------------------------------
296 /// Check the One-shot state.
298 /// \b true if the breakpoint is one-shot, \b false otherwise.
299 //------------------------------------------------------------------
300 bool IsOneShot() const { return m_one_shot; }
302 //------------------------------------------------------------------
303 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
304 //------------------------------------------------------------------
305 void SetOneShot(bool one_shot) { m_one_shot = one_shot; }
307 //------------------------------------------------------------------
308 /// Set the breakpoint to ignore the next \a count breakpoint hits.
310 /// The number of breakpoint hits to ignore.
311 //------------------------------------------------------------------
313 void SetIgnoreCount(uint32_t n) { m_ignore_count = n; }
315 //------------------------------------------------------------------
316 /// Return the current Ignore Count.
318 /// The number of breakpoint hits to be ignored.
319 //------------------------------------------------------------------
320 uint32_t GetIgnoreCount() const { return m_ignore_count; }
322 //------------------------------------------------------------------
323 /// Return the current thread spec for this option. This will return nullptr
325 /// specifications have been set for this Option yet.
327 /// The thread specification pointer for this option, or nullptr if none
330 //------------------------------------------------------------------
331 const ThreadSpec *GetThreadSpecNoCreate() const;
333 //------------------------------------------------------------------
334 /// Returns a pointer to the ThreadSpec for this option, creating it.
335 /// if it hasn't been created already. This API is used for setting the
336 /// ThreadSpec items for this option.
337 //------------------------------------------------------------------
338 ThreadSpec *GetThreadSpec();
340 void SetThreadID(lldb::tid_t thread_id);
342 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
344 //------------------------------------------------------------------
345 /// Returns true if the breakpoint option has a callback set.
346 //------------------------------------------------------------------
347 bool HasCallback() const;
349 //------------------------------------------------------------------
350 /// This is the default empty callback.
351 //------------------------------------------------------------------
352 static bool NullCallback(void *baton, StoppointCallbackContext *context,
353 lldb::user_id_t break_id,
354 lldb::user_id_t break_loc_id);
356 //------------------------------------------------------------------
357 /// Set a callback based on BreakpointOptions::CommandData.
358 /// @param[in] cmd_data
359 /// A UP holding the new'ed CommandData object.
360 /// The breakpoint will take ownership of pointer held by this object.
361 //------------------------------------------------------------------
362 void SetCommandDataCallback(std::unique_ptr<CommandData> &cmd_data);
365 //------------------------------------------------------------------
366 // Classes that inherit from BreakpointOptions can see and modify these
367 //------------------------------------------------------------------
368 enum class OptionNames {
375 static const char *g_option_names[(size_t)OptionNames::LastOptionName];
377 static const char *GetKey(OptionNames enum_value) {
378 return g_option_names[(size_t)enum_value];
381 static bool BreakpointOptionsCallbackFunction(
382 void *baton, StoppointCallbackContext *context, lldb::user_id_t break_id,
383 lldb::user_id_t break_loc_id);
385 void SetThreadSpec(std::unique_ptr<ThreadSpec> &thread_spec_up);
388 //------------------------------------------------------------------
389 // For BreakpointOptions only
390 //------------------------------------------------------------------
391 BreakpointHitCallback m_callback; // This is the callback function pointer
392 lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
393 bool m_baton_is_command_baton;
394 bool m_callback_is_synchronous;
397 uint32_t m_ignore_count; // Number of times to ignore this breakpoint
398 std::unique_ptr<ThreadSpec>
399 m_thread_spec_ap; // Thread for which this breakpoint will take
400 std::string m_condition_text; // The condition to test.
401 size_t m_condition_text_hash; // Its hash, so that locations know when the
402 // condition is updated.
405 } // namespace lldb_private
407 #endif // liblldb_BreakpointOptions_h_