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