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