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