1 //===-- BreakpointLocation.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_BreakpointLocation_h_ 10 #define liblldb_BreakpointLocation_h_ 11 12 #include <memory> 13 #include <mutex> 14 15 #include "lldb/Breakpoint/BreakpointOptions.h" 16 #include "lldb/Breakpoint/StoppointLocation.h" 17 #include "lldb/Core/Address.h" 18 #include "lldb/Utility/UserID.h" 19 #include "lldb/lldb-private.h" 20 21 namespace lldb_private { 22 23 /// \class BreakpointLocation BreakpointLocation.h 24 /// "lldb/Breakpoint/BreakpointLocation.h" Class that manages one unique (by 25 /// address) instance of a logical breakpoint. 26 27 /// General Outline: 28 /// A breakpoint location is defined by the breakpoint that produces it, 29 /// and the address that resulted in this particular instantiation. Each 30 /// breakpoint location also may have a breakpoint site if its address has 31 /// been loaded into the program. Finally it has a settable options object. 32 /// 33 /// FIXME: Should we also store some fingerprint for the location, so 34 /// we can map one location to the "equivalent location" on rerun? This would 35 /// be useful if you've set options on the locations. 36 37 class BreakpointLocation 38 : public std::enable_shared_from_this<BreakpointLocation>, 39 public StoppointLocation { 40 public: 41 ~BreakpointLocation() override; 42 43 /// Gets the load address for this breakpoint location \return 44 /// Returns breakpoint location load address, \b 45 /// LLDB_INVALID_ADDRESS if not yet set. 46 lldb::addr_t GetLoadAddress() const override; 47 48 /// Gets the Address for this breakpoint location \return 49 /// Returns breakpoint location Address. 50 Address &GetAddress(); 51 /// Gets the Breakpoint that created this breakpoint location \return 52 /// Returns the owning breakpoint. 53 Breakpoint &GetBreakpoint(); 54 55 Target &GetTarget(); 56 57 /// Determines whether we should stop due to a hit at this breakpoint 58 /// location. 59 /// 60 /// Side Effects: This may evaluate the breakpoint condition, and run the 61 /// callback. So this command may do a considerable amount of work. 62 /// 63 /// \return 64 /// \b true if this breakpoint location thinks we should stop, 65 /// \b false otherwise. 66 bool ShouldStop(StoppointCallbackContext *context) override; 67 68 // The next section deals with various breakpoint options. 69 70 /// If \a enabled is \b true, enable the breakpoint, if \b false disable it. 71 void SetEnabled(bool enabled); 72 73 /// Check the Enable/Disable state. 74 /// 75 /// \return 76 /// \b true if the breakpoint is enabled, \b false if disabled. 77 bool IsEnabled() const; 78 79 /// If \a auto_continue is \b true, set the breakpoint to continue when hit. 80 void SetAutoContinue(bool auto_continue); 81 82 /// Check the AutoContinue state. 83 /// 84 /// \return 85 /// \b true if the breakpoint is set to auto-continue, \b false if not. 86 bool IsAutoContinue() const; 87 88 /// Return the current Ignore Count. 89 /// 90 /// \return 91 /// The number of breakpoint hits to be ignored. 92 uint32_t GetIgnoreCount(); 93 94 /// Set the breakpoint to ignore the next \a count breakpoint hits. 95 /// 96 /// \param[in] n 97 /// The number of breakpoint hits to ignore. 98 void SetIgnoreCount(uint32_t n); 99 100 /// Set the callback action invoked when the breakpoint is hit. 101 /// 102 /// The callback will return a bool indicating whether the target should 103 /// stop at this breakpoint or not. 104 /// 105 /// \param[in] callback 106 /// The method that will get called when the breakpoint is hit. 107 /// 108 /// \param[in] callback_baton_sp 109 /// A shared pointer to a Baton that provides the void * needed 110 /// for the callback. 111 /// 112 /// \see lldb_private::Baton 113 void SetCallback(BreakpointHitCallback callback, 114 const lldb::BatonSP &callback_baton_sp, bool is_synchronous); 115 116 void SetCallback(BreakpointHitCallback callback, void *baton, 117 bool is_synchronous); 118 119 void ClearCallback(); 120 121 /// Set the breakpoint location's condition. 122 /// 123 /// \param[in] condition 124 /// The condition expression to evaluate when the breakpoint is hit. 125 void SetCondition(const char *condition); 126 127 /// Return a pointer to the text of the condition expression. 128 /// 129 /// \return 130 /// A pointer to the condition expression text, or nullptr if no 131 // condition has been set. 132 const char *GetConditionText(size_t *hash = nullptr) const; 133 134 bool ConditionSaysStop(ExecutionContext &exe_ctx, Status &error); 135 136 /// Set the valid thread to be checked when the breakpoint is hit. 137 /// 138 /// \param[in] thread_id 139 /// If this thread hits the breakpoint, we stop, otherwise not. 140 void SetThreadID(lldb::tid_t thread_id); 141 142 lldb::tid_t GetThreadID(); 143 144 void SetThreadIndex(uint32_t index); 145 146 uint32_t GetThreadIndex() const; 147 148 void SetThreadName(const char *thread_name); 149 150 const char *GetThreadName() const; 151 152 void SetQueueName(const char *queue_name); 153 154 const char *GetQueueName() const; 155 156 // The next section deals with this location's breakpoint sites. 157 158 /// Try to resolve the breakpoint site for this location. 159 /// 160 /// \return 161 /// \b true if we were successful at setting a breakpoint site, 162 /// \b false otherwise. 163 bool ResolveBreakpointSite(); 164 165 /// Clear this breakpoint location's breakpoint site - for instance when 166 /// disabling the breakpoint. 167 /// 168 /// \return 169 /// \b true if there was a breakpoint site to be cleared, \b false 170 /// otherwise. 171 bool ClearBreakpointSite(); 172 173 /// Return whether this breakpoint location has a breakpoint site. \return 174 /// \b true if there was a breakpoint site for this breakpoint 175 /// location, \b false otherwise. 176 bool IsResolved() const; 177 178 lldb::BreakpointSiteSP GetBreakpointSite() const; 179 180 // The next section are generic report functions. 181 182 /// Print a description of this breakpoint location to the stream \a s. 183 /// 184 /// \param[in] s 185 /// The stream to which to print the description. 186 /// 187 /// \param[in] level 188 /// The description level that indicates the detail level to 189 /// provide. 190 /// 191 /// \see lldb::DescriptionLevel 192 void GetDescription(Stream *s, lldb::DescriptionLevel level); 193 194 /// Standard "Dump" method. At present it does nothing. 195 void Dump(Stream *s) const override; 196 197 /// Use this to set location specific breakpoint options. 198 /// 199 /// It will create a copy of the containing breakpoint's options if that 200 /// hasn't been done already 201 /// 202 /// \return 203 /// A pointer to the breakpoint options. 204 BreakpointOptions *GetLocationOptions(); 205 206 /// Use this to access breakpoint options from this breakpoint location. 207 /// This will return the options that have a setting for the specified 208 /// BreakpointOptions kind. 209 /// 210 /// \param[in] kind 211 /// The particular option you are looking up. 212 /// \return 213 /// A pointer to the containing breakpoint's options if this 214 /// location doesn't have its own copy. 215 const BreakpointOptions *GetOptionsSpecifyingKind( 216 BreakpointOptions::OptionKind kind) const; 217 218 bool ValidForThisThread(Thread *thread); 219 220 /// Invoke the callback action when the breakpoint is hit. 221 /// 222 /// Meant to be used by the BreakpointLocation class. 223 /// 224 /// \param[in] context 225 /// Described the breakpoint event. 226 /// 227 /// \return 228 /// \b true if the target should stop at this breakpoint and \b 229 /// false not. 230 bool InvokeCallback(StoppointCallbackContext *context); 231 232 /// Returns whether we should resolve Indirect functions in setting the 233 /// breakpoint site for this location. 234 /// 235 /// \return 236 /// \b true if the breakpoint SITE for this location should be set on the 237 /// resolved location for Indirect functions. 238 bool ShouldResolveIndirectFunctions() { 239 return m_should_resolve_indirect_functions; 240 } 241 242 /// Returns whether the address set in the breakpoint site for this location 243 /// was found by resolving an indirect symbol. 244 /// 245 /// \return 246 /// \b true or \b false as given in the description above. 247 bool IsIndirect() { return m_is_indirect; } 248 249 void SetIsIndirect(bool is_indirect) { m_is_indirect = is_indirect; } 250 251 /// Returns whether the address set in the breakpoint location was re-routed 252 /// to the target of a re-exported symbol. 253 /// 254 /// \return 255 /// \b true or \b false as given in the description above. 256 bool IsReExported() { return m_is_reexported; } 257 258 void SetIsReExported(bool is_reexported) { m_is_reexported = is_reexported; } 259 260 /// Returns whether the two breakpoint locations might represent "equivalent 261 /// locations". This is used when modules changed to determine if a Location 262 /// in the old module might be the "same as" the input location. 263 /// 264 /// \param[in] location 265 /// The location to compare against. 266 /// 267 /// \return 268 /// \b true or \b false as given in the description above. 269 bool EquivalentToLocation(BreakpointLocation &location); 270 271 protected: 272 friend class BreakpointSite; 273 friend class BreakpointLocationList; 274 friend class Process; 275 friend class StopInfoBreakpoint; 276 277 /// Set the breakpoint site for this location to \a bp_site_sp. 278 /// 279 /// \param[in] bp_site_sp 280 /// The breakpoint site we are setting for this location. 281 /// 282 /// \return 283 /// \b true if we were successful at setting the breakpoint site, 284 /// \b false otherwise. 285 bool SetBreakpointSite(lldb::BreakpointSiteSP &bp_site_sp); 286 287 void DecrementIgnoreCount(); 288 289 bool IgnoreCountShouldStop(); 290 291 private: 292 void SwapLocation(lldb::BreakpointLocationSP swap_from); 293 294 void BumpHitCount(); 295 296 void UndoBumpHitCount(); 297 298 // Constructors and Destructors 299 // 300 // Only the Breakpoint can make breakpoint locations, and it owns them. 301 302 /// Constructor. 303 /// 304 /// \param[in] owner 305 /// A back pointer to the breakpoint that owns this location. 306 /// 307 /// \param[in] addr 308 /// The Address defining this location. 309 /// 310 /// \param[in] tid 311 /// The thread for which this breakpoint location is valid, or 312 /// LLDB_INVALID_THREAD_ID if it is valid for all threads. 313 /// 314 /// \param[in] hardware 315 /// \b true if a hardware breakpoint is requested. 316 317 BreakpointLocation(lldb::break_id_t bid, Breakpoint &owner, 318 const Address &addr, lldb::tid_t tid, bool hardware, 319 bool check_for_resolver = true); 320 321 // Data members: 322 bool m_being_created; 323 bool m_should_resolve_indirect_functions; 324 bool m_is_reexported; 325 bool m_is_indirect; 326 Address m_address; ///< The address defining this location. 327 Breakpoint &m_owner; ///< The breakpoint that produced this object. 328 std::unique_ptr<BreakpointOptions> m_options_up; ///< Breakpoint options 329 /// pointer, nullptr if we're 330 /// using our breakpoint's 331 /// options. 332 lldb::BreakpointSiteSP m_bp_site_sp; ///< Our breakpoint site (it may be 333 ///shared by more than one location.) 334 lldb::UserExpressionSP m_user_expression_sp; ///< The compiled expression to 335 ///use in testing our condition. 336 std::mutex m_condition_mutex; ///< Guards parsing and evaluation of the 337 ///condition, which could be evaluated by 338 /// multiple processes. 339 size_t m_condition_hash; ///< For testing whether the condition source code 340 ///changed. 341 342 void SetShouldResolveIndirectFunctions(bool do_resolve) { 343 m_should_resolve_indirect_functions = do_resolve; 344 } 345 346 void SendBreakpointLocationChangedEvent(lldb::BreakpointEventType eventKind); 347 348 DISALLOW_COPY_AND_ASSIGN(BreakpointLocation); 349 }; 350 351 } // namespace lldb_private 352 353 #endif // liblldb_BreakpointLocation_h_ 354