1 //===-- WatchpointOptions.h -------------------------------------*- C++ -*-===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef liblldb_WatchpointOptions_h_
11 #define liblldb_WatchpointOptions_h_
12 
13 // C Includes
14 // C++ Includes
15 // Other libraries and framework includes
16 // Project includes
17 #include "lldb/lldb-private.h"
18 #include "lldb/Core/Baton.h"
19 #include "lldb/Core/StringList.h"
20 
21 namespace lldb_private {
22 
23 //----------------------------------------------------------------------
24 /// @class WatchpointOptions WatchpointOptions.h "lldb/Breakpoint/WatchpointOptions.h"
25 /// @brief Class that manages the options on a watchpoint.
26 //----------------------------------------------------------------------
27 
28 class WatchpointOptions
29 {
30 public:
31     //------------------------------------------------------------------
32     // Constructors and Destructors
33     //------------------------------------------------------------------
34     //------------------------------------------------------------------
35     /// Default constructor.  The watchpoint is enabled, and has no condition,
36     /// callback, ignore count, etc...
37     //------------------------------------------------------------------
38     WatchpointOptions();
39     WatchpointOptions(const WatchpointOptions& rhs);
40 
41     static WatchpointOptions *
42     CopyOptionsNoCallback (WatchpointOptions &rhs);
43     //------------------------------------------------------------------
44     /// This constructor allows you to specify all the watchpoint options.
45     ///
46     /// @param[in] callback
47     ///    This is the plugin for some code that gets run, returns \b true if we are to stop.
48     ///
49     /// @param[in] baton
50     ///    Client data that will get passed to the callback.
51     ///
52     /// @param[in] thread_id
53     ///    Only stop if \a thread_id hits the watchpoint.
54     //------------------------------------------------------------------
55     WatchpointOptions(WatchpointHitCallback callback,
56                       void *baton,
57                       lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
58 
59     virtual ~WatchpointOptions();
60 
61     //------------------------------------------------------------------
62     // Operators
63     //------------------------------------------------------------------
64     const WatchpointOptions&
65     operator=(const WatchpointOptions& rhs);
66 
67     //------------------------------------------------------------------
68     // Callbacks
69     //
70     // Watchpoint callbacks come in two forms, synchronous and asynchronous.  Synchronous callbacks will get
71     // run before any of the thread plans are consulted, and if they return false the target will continue
72     // "under the radar" of the thread plans.  There are a couple of restrictions to synchronous callbacks:
73     // 1) They should NOT resume the target themselves.  Just return false if you want the target to restart.
74     // 2) Watchpoints with synchronous callbacks can't have conditions (or rather, they can have them, but they
75     //    won't do anything.  Ditto with ignore counts, etc...  You are supposed to control that all through the
76     //    callback.
77     // Asynchronous callbacks get run as part of the "ShouldStop" logic in the thread plan.  The logic there is:
78     //   a) If the watchpoint is thread specific and not for this thread, continue w/o running the callback.
79     //   b) If the ignore count says we shouldn't stop, then ditto.
80     //   c) If the condition says we shouldn't stop, then ditto.
81     //   d) Otherwise, the callback will get run, and if it returns true we will stop, and if false we won't.
82     //  The asynchronous callback can run the target itself, but at present that should be the last action the
83     //  callback does.  We will relax this condition at some point, but it will take a bit of plumbing to get
84     //  that to work.
85     //
86     //------------------------------------------------------------------
87 
88     //------------------------------------------------------------------
89     /// Adds a callback to the watchpoint option set.
90     ///
91     /// @param[in] callback
92     ///    The function to be called when the watchpoint gets hit.
93     ///
94     /// @param[in] baton_sp
95     ///    A baton which will get passed back to the callback when it is invoked.
96     ///
97     /// @param[in] synchronous
98     ///    Whether this is a synchronous or asynchronous callback.  See discussion above.
99     //------------------------------------------------------------------
100     void SetCallback (WatchpointHitCallback callback, const lldb::BatonSP &baton_sp, bool synchronous = false);
101 
102 
103     //------------------------------------------------------------------
104     /// Remove the callback from this option set.
105     //------------------------------------------------------------------
106     void ClearCallback ();
107 
108     // The rest of these functions are meant to be used only within the watchpoint handling mechanism.
109 
110     //------------------------------------------------------------------
111     /// Use this function to invoke the callback for a specific stop.
112     ///
113     /// @param[in] context
114     ///    The context in which the callback is to be invoked.  This includes the stop event, the
115     ///    execution context of the stop (since you might hit the same watchpoint on multiple threads) and
116     ///    whether we are currently executing synchronous or asynchronous callbacks.
117     ///
118     /// @param[in] watch_id
119     ///    The watchpoint ID that owns this option set.
120     ///
121     /// @return
122     ///     The callback return value.
123     //------------------------------------------------------------------
124     bool InvokeCallback (StoppointCallbackContext *context, lldb::user_id_t watch_id);
125 
126     //------------------------------------------------------------------
127     /// Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
128     ///
129     /// @return
130     ///     The synchronicity of our callback.
131     //------------------------------------------------------------------
IsCallbackSynchronous()132     bool IsCallbackSynchronous () {
133         return m_callback_is_synchronous;
134     }
135 
136     //------------------------------------------------------------------
137     /// Fetch the baton from the callback.
138     ///
139     /// @return
140     ///     The baton.
141     //------------------------------------------------------------------
142     Baton *GetBaton ();
143 
144     //------------------------------------------------------------------
145     /// Fetch  a const version of the baton from the callback.
146     ///
147     /// @return
148     ///     The baton.
149     //------------------------------------------------------------------
150     const Baton *GetBaton () const;
151 
152     //------------------------------------------------------------------
153     /// Return the current thread spec for this option.  This will return NULL if the no thread
154     /// specifications have been set for this Option yet.
155     /// @return
156     ///     The thread specification pointer for this option, or NULL if none has
157     ///     been set yet.
158     //------------------------------------------------------------------
159     const ThreadSpec *
160     GetThreadSpecNoCreate () const;
161 
162     //------------------------------------------------------------------
163     /// Returns a pointer to the ThreadSpec for this option, creating it.
164     /// if it hasn't been created already.   This API is used for setting the
165     /// ThreadSpec items for this option.
166     //------------------------------------------------------------------
167     ThreadSpec *
168     GetThreadSpec ();
169 
170     void
171     SetThreadID(lldb::tid_t thread_id);
172 
173     void
174     GetDescription (Stream *s, lldb::DescriptionLevel level) const;
175 
176     //------------------------------------------------------------------
177     /// Get description for callback only.
178     //------------------------------------------------------------------
179     void
180     GetCallbackDescription (Stream *s, lldb::DescriptionLevel level) const;
181 
182     //------------------------------------------------------------------
183     /// Returns true if the watchpoint option has a callback set.
184     //------------------------------------------------------------------
185     bool
186     HasCallback();
187 
188     //------------------------------------------------------------------
189     /// This is the default empty callback.
190     /// @return
191     ///     The thread id for which the watchpoint hit will stop,
192     ///     LLDB_INVALID_THREAD_ID for all threads.
193     //------------------------------------------------------------------
194     static bool
195     NullCallback (void *baton,
196                   StoppointCallbackContext *context,
197                   lldb::user_id_t watch_id);
198 
199 
200     struct CommandData
201     {
CommandDataCommandData202         CommandData () :
203             user_source(),
204             script_source(),
205             stop_on_error(true)
206         {
207         }
208 
~CommandDataCommandData209         ~CommandData ()
210         {
211         }
212 
213         StringList user_source;
214         std::string script_source;
215         bool stop_on_error;
216     };
217 
218     class CommandBaton : public Baton
219     {
220     public:
CommandBaton(CommandData * data)221         CommandBaton (CommandData *data) :
222             Baton (data)
223         {
224         }
225 
226         virtual
~CommandBaton()227         ~CommandBaton ()
228         {
229             delete ((CommandData *)m_data);
230             m_data = NULL;
231         }
232 
233         virtual void
234         GetDescription (Stream *s, lldb::DescriptionLevel level) const;
235 
236     };
237 
238 protected:
239     //------------------------------------------------------------------
240     // Classes that inherit from WatchpointOptions can see and modify these
241     //------------------------------------------------------------------
242 
243 private:
244     //------------------------------------------------------------------
245     // For WatchpointOptions only
246     //------------------------------------------------------------------
247     WatchpointHitCallback m_callback; // This is the callback function pointer
248     lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
249     bool m_callback_is_synchronous;
250     std::unique_ptr<ThreadSpec> m_thread_spec_ap; // Thread for which this watchpoint will take
251 };
252 
253 } // namespace lldb_private
254 
255 #endif  // liblldb_WatchpointOptions_h_
256