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