1//===-- SWIG Interface for SBBreakpoint -------------------------*- 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//===----------------------------------------------------------------------===// 8namespace lldb { 9 10%feature("docstring", 11"Represents a logical breakpoint and its associated settings. 12 13For example (from test/functionalities/breakpoint/breakpoint_ignore_count/ 14TestBreakpointIgnoreCount.py), 15 16 def breakpoint_ignore_count_python(self): 17 '''Use Python APIs to set breakpoint ignore count.''' 18 exe = os.path.join(os.getcwd(), 'a.out') 19 20 # Create a target by the debugger. 21 target = self.dbg.CreateTarget(exe) 22 self.assertTrue(target, VALID_TARGET) 23 24 # Now create a breakpoint on main.c by name 'c'. 25 breakpoint = target.BreakpointCreateByName('c', 'a.out') 26 self.assertTrue(breakpoint and 27 breakpoint.GetNumLocations() == 1, 28 VALID_BREAKPOINT) 29 30 # Get the breakpoint location from breakpoint after we verified that, 31 # indeed, it has one location. 32 location = breakpoint.GetLocationAtIndex(0) 33 self.assertTrue(location and 34 location.IsEnabled(), 35 VALID_BREAKPOINT_LOCATION) 36 37 # Set the ignore count on the breakpoint location. 38 location.SetIgnoreCount(2) 39 self.assertTrue(location.GetIgnoreCount() == 2, 40 'SetIgnoreCount() works correctly') 41 42 # Now launch the process, and do not stop at entry point. 43 process = target.LaunchSimple(None, None, os.getcwd()) 44 self.assertTrue(process, PROCESS_IS_VALID) 45 46 # Frame#0 should be on main.c:37, frame#1 should be on main.c:25, and 47 # frame#2 should be on main.c:48. 48 #lldbutil.print_stacktraces(process) 49 from lldbutil import get_stopped_thread 50 thread = get_stopped_thread(process, lldb.eStopReasonBreakpoint) 51 self.assertTrue(thread != None, 'There should be a thread stopped due to breakpoint') 52 frame0 = thread.GetFrameAtIndex(0) 53 frame1 = thread.GetFrameAtIndex(1) 54 frame2 = thread.GetFrameAtIndex(2) 55 self.assertTrue(frame0.GetLineEntry().GetLine() == self.line1 and 56 frame1.GetLineEntry().GetLine() == self.line3 and 57 frame2.GetLineEntry().GetLine() == self.line4, 58 STOPPED_DUE_TO_BREAKPOINT_IGNORE_COUNT) 59 60 # The hit count for the breakpoint should be 3. 61 self.assertTrue(breakpoint.GetHitCount() == 3) 62 63 process.Continue() 64 65SBBreakpoint supports breakpoint location iteration, for example, 66 67 for bl in breakpoint: 68 print('breakpoint location load addr: %s' % hex(bl.GetLoadAddress())) 69 print('breakpoint location condition: %s' % hex(bl.GetCondition())) 70 71and rich comparison methods which allow the API program to use, 72 73 if aBreakpoint == bBreakpoint: 74 ... 75 76to compare two breakpoints for equality." 77) SBBreakpoint; 78class SBBreakpoint 79{ 80public: 81 82 SBBreakpoint (); 83 84 SBBreakpoint (const lldb::SBBreakpoint& rhs); 85 86 ~SBBreakpoint(); 87 88 bool operator==(const lldb::SBBreakpoint &rhs); 89 90 bool operator!=(const lldb::SBBreakpoint &rhs); 91 92 break_id_t 93 GetID () const; 94 95 bool 96 IsValid() const; 97 98 explicit operator bool() const; 99 100 void 101 ClearAllBreakpointSites (); 102 103 lldb::SBBreakpointLocation 104 FindLocationByAddress (lldb::addr_t vm_addr); 105 106 lldb::break_id_t 107 FindLocationIDByAddress (lldb::addr_t vm_addr); 108 109 lldb::SBBreakpointLocation 110 FindLocationByID (lldb::break_id_t bp_loc_id); 111 112 lldb::SBBreakpointLocation 113 GetLocationAtIndex (uint32_t index); 114 115 void 116 SetEnabled (bool enable); 117 118 bool 119 IsEnabled (); 120 121 void 122 SetOneShot (bool one_shot); 123 124 bool 125 IsOneShot (); 126 127 bool 128 IsInternal (); 129 130 uint32_t 131 GetHitCount () const; 132 133 void 134 SetIgnoreCount (uint32_t count); 135 136 uint32_t 137 GetIgnoreCount () const; 138 139 %feature("docstring", " 140 The breakpoint stops only if the condition expression evaluates to true.") SetCondition; 141 void 142 SetCondition (const char *condition); 143 144 %feature("docstring", " 145 Get the condition expression for the breakpoint.") GetCondition; 146 const char * 147 GetCondition (); 148 149 void SetAutoContinue(bool auto_continue); 150 151 bool GetAutoContinue(); 152 153 void 154 SetThreadID (lldb::tid_t sb_thread_id); 155 156 lldb::tid_t 157 GetThreadID (); 158 159 void 160 SetThreadIndex (uint32_t index); 161 162 uint32_t 163 GetThreadIndex() const; 164 165 void 166 SetThreadName (const char *thread_name); 167 168 const char * 169 GetThreadName () const; 170 171 void 172 SetQueueName (const char *queue_name); 173 174 const char * 175 GetQueueName () const; 176 177 %feature("docstring", " 178 Set the name of the script function to be called when the breakpoint is hit.") SetScriptCallbackFunction; 179 void 180 SetScriptCallbackFunction (const char *callback_function_name); 181 182 %feature("docstring", " 183 Set the name of the script function to be called when the breakpoint is hit. 184 To use this variant, the function should take (frame, bp_loc, extra_args, dict) and 185 when the breakpoint is hit the extra_args will be passed to the callback function.") SetScriptCallbackFunction; 186 SBError 187 SetScriptCallbackFunction (const char *callback_function_name, 188 SBStructuredData &extra_args); 189 190 %feature("docstring", " 191 Provide the body for the script function to be called when the breakpoint is hit. 192 The body will be wrapped in a function, which be passed two arguments: 193 'frame' - which holds the bottom-most SBFrame of the thread that hit the breakpoint 194 'bpno' - which is the SBBreakpointLocation to which the callback was attached. 195 196 The error parameter is currently ignored, but will at some point hold the Python 197 compilation diagnostics. 198 Returns true if the body compiles successfully, false if not.") SetScriptCallbackBody; 199 SBError 200 SetScriptCallbackBody (const char *script_body_text); 201 202 void SetCommandLineCommands(SBStringList &commands); 203 204 bool GetCommandLineCommands(SBStringList &commands); 205 206 bool 207 AddName (const char *new_name); 208 209 void 210 RemoveName (const char *name_to_remove); 211 212 bool 213 MatchesName (const char *name); 214 215 void 216 GetNames (SBStringList &names); 217 218 size_t 219 GetNumResolvedLocations() const; 220 221 size_t 222 GetNumLocations() const; 223 224 bool 225 GetDescription (lldb::SBStream &description); 226 227 bool 228 GetDescription(lldb::SBStream &description, bool include_locations); 229 230 // Can only be called from a ScriptedBreakpointResolver... 231 SBError 232 AddLocation(SBAddress &address); 233 234 static bool 235 EventIsBreakpointEvent (const lldb::SBEvent &event); 236 237 static lldb::BreakpointEventType 238 GetBreakpointEventTypeFromEvent (const lldb::SBEvent& event); 239 240 static lldb::SBBreakpoint 241 GetBreakpointFromEvent (const lldb::SBEvent& event); 242 243 static lldb::SBBreakpointLocation 244 GetBreakpointLocationAtIndexFromEvent (const lldb::SBEvent& event, uint32_t loc_idx); 245 246 static uint32_t 247 GetNumBreakpointLocationsFromEvent (const lldb::SBEvent &event_sp); 248 249 bool 250 IsHardware (); 251 252 STRING_EXTENSION(SBBreakpoint) 253 254#ifdef SWIGPYTHON 255 %pythoncode %{ 256 257 class locations_access(object): 258 '''A helper object that will lazily hand out locations for a breakpoint when supplied an index.''' 259 def __init__(self, sbbreakpoint): 260 self.sbbreakpoint = sbbreakpoint 261 262 def __len__(self): 263 if self.sbbreakpoint: 264 return int(self.sbbreakpoint.GetNumLocations()) 265 return 0 266 267 def __getitem__(self, key): 268 if type(key) is int and key < len(self): 269 return self.sbbreakpoint.GetLocationAtIndex(key) 270 return None 271 272 def get_locations_access_object(self): 273 '''An accessor function that returns a locations_access() object which allows lazy location access from a lldb.SBBreakpoint object.''' 274 return self.locations_access (self) 275 276 def get_breakpoint_location_list(self): 277 '''An accessor function that returns a list() that contains all locations in a lldb.SBBreakpoint object.''' 278 locations = [] 279 accessor = self.get_locations_access_object() 280 for idx in range(len(accessor)): 281 locations.append(accessor[idx]) 282 return locations 283 284 def __iter__(self): 285 '''Iterate over all breakpoint locations in a lldb.SBBreakpoint 286 object.''' 287 return lldb_iter(self, 'GetNumLocations', 'GetLocationAtIndex') 288 289 def __len__(self): 290 '''Return the number of breakpoint locations in a lldb.SBBreakpoint 291 object.''' 292 return self.GetNumLocations() 293 294 locations = property(get_breakpoint_location_list, None, doc='''A read only property that returns a list() of lldb.SBBreakpointLocation objects for this breakpoint.''') 295 location = property(get_locations_access_object, None, doc='''A read only property that returns an object that can access locations by index (not location ID) (location = bkpt.location[12]).''') 296 id = property(GetID, None, doc='''A read only property that returns the ID of this breakpoint.''') 297 enabled = property(IsEnabled, SetEnabled, doc='''A read/write property that configures whether this breakpoint is enabled or not.''') 298 one_shot = property(IsOneShot, SetOneShot, doc='''A read/write property that configures whether this breakpoint is one-shot (deleted when hit) or not.''') 299 num_locations = property(GetNumLocations, None, doc='''A read only property that returns the count of locations of this breakpoint.''') 300 %} 301#endif 302 303 304}; 305 306class SBBreakpointListImpl; 307 308class LLDB_API SBBreakpointList 309{ 310public: 311 SBBreakpointList(SBTarget &target); 312 313 ~SBBreakpointList(); 314 315 size_t GetSize() const; 316 317 SBBreakpoint 318 GetBreakpointAtIndex(size_t idx); 319 320 SBBreakpoint 321 FindBreakpointByID(lldb::break_id_t); 322 323 void Append(const SBBreakpoint &sb_bkpt); 324 325 bool AppendIfUnique(const SBBreakpoint &sb_bkpt); 326 327 void AppendByID (lldb::break_id_t id); 328 329 void Clear(); 330private: 331 std::shared_ptr<SBBreakpointListImpl> m_opaque_sp; 332}; 333 334} // namespace lldb 335