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 SBError 210 AddNameWithErrorHandling (const char *new_name); 211 212 void 213 RemoveName (const char *name_to_remove); 214 215 bool 216 MatchesName (const char *name); 217 218 void 219 GetNames (SBStringList &names); 220 221 size_t 222 GetNumResolvedLocations() const; 223 224 size_t 225 GetNumLocations() const; 226 227 bool 228 GetDescription (lldb::SBStream &description); 229 230 bool 231 GetDescription(lldb::SBStream &description, bool include_locations); 232 233 // Can only be called from a ScriptedBreakpointResolver... 234 SBError 235 AddLocation(SBAddress &address); 236 237 static bool 238 EventIsBreakpointEvent (const lldb::SBEvent &event); 239 240 static lldb::BreakpointEventType 241 GetBreakpointEventTypeFromEvent (const lldb::SBEvent& event); 242 243 static lldb::SBBreakpoint 244 GetBreakpointFromEvent (const lldb::SBEvent& event); 245 246 static lldb::SBBreakpointLocation 247 GetBreakpointLocationAtIndexFromEvent (const lldb::SBEvent& event, uint32_t loc_idx); 248 249 static uint32_t 250 GetNumBreakpointLocationsFromEvent (const lldb::SBEvent &event_sp); 251 252 bool 253 IsHardware (); 254 255 STRING_EXTENSION(SBBreakpoint) 256 257#ifdef SWIGPYTHON 258 %pythoncode %{ 259 260 class locations_access(object): 261 '''A helper object that will lazily hand out locations for a breakpoint when supplied an index.''' 262 def __init__(self, sbbreakpoint): 263 self.sbbreakpoint = sbbreakpoint 264 265 def __len__(self): 266 if self.sbbreakpoint: 267 return int(self.sbbreakpoint.GetNumLocations()) 268 return 0 269 270 def __getitem__(self, key): 271 if type(key) is int and key < len(self): 272 return self.sbbreakpoint.GetLocationAtIndex(key) 273 return None 274 275 def get_locations_access_object(self): 276 '''An accessor function that returns a locations_access() object which allows lazy location access from a lldb.SBBreakpoint object.''' 277 return self.locations_access (self) 278 279 def get_breakpoint_location_list(self): 280 '''An accessor function that returns a list() that contains all locations in a lldb.SBBreakpoint object.''' 281 locations = [] 282 accessor = self.get_locations_access_object() 283 for idx in range(len(accessor)): 284 locations.append(accessor[idx]) 285 return locations 286 287 def __iter__(self): 288 '''Iterate over all breakpoint locations in a lldb.SBBreakpoint 289 object.''' 290 return lldb_iter(self, 'GetNumLocations', 'GetLocationAtIndex') 291 292 def __len__(self): 293 '''Return the number of breakpoint locations in a lldb.SBBreakpoint 294 object.''' 295 return self.GetNumLocations() 296 297 locations = property(get_breakpoint_location_list, None, doc='''A read only property that returns a list() of lldb.SBBreakpointLocation objects for this breakpoint.''') 298 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]).''') 299 id = property(GetID, None, doc='''A read only property that returns the ID of this breakpoint.''') 300 enabled = property(IsEnabled, SetEnabled, doc='''A read/write property that configures whether this breakpoint is enabled or not.''') 301 one_shot = property(IsOneShot, SetOneShot, doc='''A read/write property that configures whether this breakpoint is one-shot (deleted when hit) or not.''') 302 num_locations = property(GetNumLocations, None, doc='''A read only property that returns the count of locations of this breakpoint.''') 303 %} 304#endif 305 306 307}; 308 309class SBBreakpointListImpl; 310 311class LLDB_API SBBreakpointList 312{ 313public: 314 SBBreakpointList(SBTarget &target); 315 316 ~SBBreakpointList(); 317 318 size_t GetSize() const; 319 320 SBBreakpoint 321 GetBreakpointAtIndex(size_t idx); 322 323 SBBreakpoint 324 FindBreakpointByID(lldb::break_id_t); 325 326 void Append(const SBBreakpoint &sb_bkpt); 327 328 bool AppendIfUnique(const SBBreakpoint &sb_bkpt); 329 330 void AppendByID (lldb::break_id_t id); 331 332 void Clear(); 333private: 334 std::shared_ptr<SBBreakpointListImpl> m_opaque_sp; 335}; 336 337} // namespace lldb 338