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 //===----------------------------------------------------------------------===//
8 namespace lldb {
9 
10 %feature("docstring",
11 "Represents a logical breakpoint and its associated settings.
12 
13 For example (from test/functionalities/breakpoint/breakpoint_ignore_count/
14 TestBreakpointIgnoreCount.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 
65 SBBreakpoint 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 
71 and rich comparison methods which allow the API program to use,::
72 
73     if aBreakpoint == bBreakpoint:
74         ...
75 
76 to compare two breakpoints for equality."
77 ) SBBreakpoint;
78 class SBBreakpoint
79 {
80 public:
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::SBTarget
104     GetTarget() const;
105 
106     lldb::SBBreakpointLocation
107     FindLocationByAddress (lldb::addr_t vm_addr);
108 
109     lldb::break_id_t
110     FindLocationIDByAddress (lldb::addr_t vm_addr);
111 
112     lldb::SBBreakpointLocation
113     FindLocationByID (lldb::break_id_t bp_loc_id);
114 
115     lldb::SBBreakpointLocation
116     GetLocationAtIndex (uint32_t index);
117 
118     void
119     SetEnabled (bool enable);
120 
121     bool
122     IsEnabled ();
123 
124     void
125     SetOneShot (bool one_shot);
126 
127     bool
128     IsOneShot ();
129 
130     bool
131     IsInternal ();
132 
133     uint32_t
134     GetHitCount () const;
135 
136     void
137     SetIgnoreCount (uint32_t count);
138 
139     uint32_t
140     GetIgnoreCount () const;
141 
142     %feature("docstring", "
143     The breakpoint stops only if the condition expression evaluates to true.") SetCondition;
144     void
145     SetCondition (const char *condition);
146 
147     %feature("docstring", "
148     Get the condition expression for the breakpoint.") GetCondition;
149     const char *
150     GetCondition ();
151 
152     void SetAutoContinue(bool auto_continue);
153 
154     bool GetAutoContinue();
155 
156     void
157     SetThreadID (lldb::tid_t sb_thread_id);
158 
159     lldb::tid_t
160     GetThreadID ();
161 
162     void
163     SetThreadIndex (uint32_t index);
164 
165     uint32_t
166     GetThreadIndex() const;
167 
168     void
169     SetThreadName (const char *thread_name);
170 
171     const char *
172     GetThreadName () const;
173 
174     void
175     SetQueueName (const char *queue_name);
176 
177     const char *
178     GetQueueName () const;
179 
180     %feature("docstring", "
181     Set the name of the script function to be called when the breakpoint is hit.") SetScriptCallbackFunction;
182     void
183     SetScriptCallbackFunction (const char *callback_function_name);
184 
185     %feature("docstring", "
186     Set the name of the script function to be called when the breakpoint is hit.
187     To use this variant, the function should take (frame, bp_loc, extra_args, internal_dict) and
188     when the breakpoint is hit the extra_args will be passed to the callback function.") SetScriptCallbackFunction;
189     SBError
190     SetScriptCallbackFunction (const char *callback_function_name,
191                                SBStructuredData &extra_args);
192 
193     %feature("docstring", "
194     Provide the body for the script function to be called when the breakpoint is hit.
195     The body will be wrapped in a function, which be passed two arguments:
196     'frame' - which holds the bottom-most SBFrame of the thread that hit the breakpoint
197     'bpno'  - which is the SBBreakpointLocation to which the callback was attached.
198 
199     The error parameter is currently ignored, but will at some point hold the Python
200     compilation diagnostics.
201     Returns true if the body compiles successfully, false if not.") SetScriptCallbackBody;
202     SBError
203     SetScriptCallbackBody (const char *script_body_text);
204 
205     void SetCommandLineCommands(SBStringList &commands);
206 
207     bool GetCommandLineCommands(SBStringList &commands);
208 
209     bool
210     AddName (const char *new_name);
211 
212     SBError
213     AddNameWithErrorHandling (const char *new_name);
214 
215     void
216     RemoveName (const char *name_to_remove);
217 
218     bool
219     MatchesName (const char *name);
220 
221     void
222     GetNames (SBStringList &names);
223 
224     size_t
225     GetNumResolvedLocations() const;
226 
227     size_t
228     GetNumLocations() const;
229 
230     bool
231     GetDescription (lldb::SBStream &description);
232 
233     bool
234     GetDescription(lldb::SBStream &description, bool include_locations);
235 
236     // Can only be called from a ScriptedBreakpointResolver...
237     SBError
238     AddLocation(SBAddress &address);
239 
240     SBStructuredData SBBreakpoint::SerializeToStructuredData();
241 
242     static bool
243     EventIsBreakpointEvent (const lldb::SBEvent &event);
244 
245     static lldb::BreakpointEventType
246     GetBreakpointEventTypeFromEvent (const lldb::SBEvent& event);
247 
248     static lldb::SBBreakpoint
249     GetBreakpointFromEvent (const lldb::SBEvent& event);
250 
251     static lldb::SBBreakpointLocation
252     GetBreakpointLocationAtIndexFromEvent (const lldb::SBEvent& event, uint32_t loc_idx);
253 
254     static uint32_t
255     GetNumBreakpointLocationsFromEvent (const lldb::SBEvent &event_sp);
256 
257     bool
258     IsHardware ();
259 
260     STRING_EXTENSION(SBBreakpoint)
261 
262 #ifdef SWIGPYTHON
263     %pythoncode %{
264 
265         class locations_access(object):
266             '''A helper object that will lazily hand out locations for a breakpoint when supplied an index.'''
267             def __init__(self, sbbreakpoint):
268                 self.sbbreakpoint = sbbreakpoint
269 
270             def __len__(self):
271                 if self.sbbreakpoint:
272                     return int(self.sbbreakpoint.GetNumLocations())
273                 return 0
274 
275             def __getitem__(self, key):
276                 if type(key) is int and key < len(self):
277                     return self.sbbreakpoint.GetLocationAtIndex(key)
278                 return None
279 
280         def get_locations_access_object(self):
281             '''An accessor function that returns a locations_access() object which allows lazy location access from a lldb.SBBreakpoint object.'''
282             return self.locations_access (self)
283 
284         def get_breakpoint_location_list(self):
285             '''An accessor function that returns a list() that contains all locations in a lldb.SBBreakpoint object.'''
286             locations = []
287             accessor = self.get_locations_access_object()
288             for idx in range(len(accessor)):
289                 locations.append(accessor[idx])
290             return locations
291 
292         def __iter__(self):
293             '''Iterate over all breakpoint locations in a lldb.SBBreakpoint
294             object.'''
295             return lldb_iter(self, 'GetNumLocations', 'GetLocationAtIndex')
296 
297         def __len__(self):
298             '''Return the number of breakpoint locations in a lldb.SBBreakpoint
299             object.'''
300             return self.GetNumLocations()
301 
302         locations = property(get_breakpoint_location_list, None, doc='''A read only property that returns a list() of lldb.SBBreakpointLocation objects for this breakpoint.''')
303         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]).''')
304         id = property(GetID, None, doc='''A read only property that returns the ID of this breakpoint.''')
305         enabled = property(IsEnabled, SetEnabled, doc='''A read/write property that configures whether this breakpoint is enabled or not.''')
306         one_shot = property(IsOneShot, SetOneShot, doc='''A read/write property that configures whether this breakpoint is one-shot (deleted when hit) or not.''')
307         num_locations = property(GetNumLocations, None, doc='''A read only property that returns the count of locations of this breakpoint.''')
308     %}
309 #endif
310 
311 
312 };
313 
314 class SBBreakpointListImpl;
315 
316 
317 %feature("docstring",
318 "Represents a list of :py:class:`SBBreakpoint`."
319 ) SBBreakpointList;
320 class LLDB_API SBBreakpointList
321 {
322 public:
323   SBBreakpointList(SBTarget &target);
324 
325   ~SBBreakpointList();
326 
327   size_t GetSize() const;
328 
329   SBBreakpoint
330   GetBreakpointAtIndex(size_t idx);
331 
332   SBBreakpoint
333   FindBreakpointByID(lldb::break_id_t);
334 
335   void Append(const SBBreakpoint &sb_bkpt);
336 
337   bool AppendIfUnique(const SBBreakpoint &sb_bkpt);
338 
339   void AppendByID (lldb::break_id_t id);
340 
341   void Clear();
342 private:
343   std::shared_ptr<SBBreakpointListImpl> m_opaque_sp;
344 };
345 
346 } // namespace lldb
347