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