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