aboutsummaryrefslogtreecommitdiff
path: root/include/lldb/Breakpoint/Breakpoint.h
blob: 15693f86e3820ddfb3cccc46880a891b6fbdcb65 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
//===-- Breakpoint.h --------------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_Breakpoint_h_
#define liblldb_Breakpoint_h_

// C Includes
// C++ Includes
// Other libraries and framework includes
// Project includes
#include "lldb/Breakpoint/BreakpointLocationList.h"
#include "lldb/Breakpoint/BreakpointOptions.h"
#include "lldb/Breakpoint/BreakpointLocationCollection.h"
#include "lldb/Breakpoint/Stoppoint.h"
#include "lldb/Core/SearchFilter.h"
#include "lldb/Core/Event.h"
#include "lldb/Core/StringList.h"

namespace lldb_private {

//----------------------------------------------------------------------
/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h"
/// @brief Class that manages logical breakpoint setting.
//----------------------------------------------------------------------

//----------------------------------------------------------------------
/// General Outline:
/// A breakpoint has four main parts, a filter, a resolver, the list of breakpoint
/// locations that have been determined for the filter/resolver pair, and finally
/// a set of options for the breakpoint.
///
/// \b Filter:
/// This is an object derived from SearchFilter.  It manages the search
/// for breakpoint location matches through the symbols in the module list of the target
/// that owns it.  It also filters out locations based on whatever logic it wants.
///
/// \b Resolver:
/// This is an object derived from BreakpointResolver.  It provides a
/// callback to the filter that will find breakpoint locations.  How it does this is
/// determined by what kind of resolver it is.
///
/// The Breakpoint class also provides constructors for the common breakpoint cases
/// which make the appropriate filter and resolver for you.
///
/// \b Location List:
/// This stores the breakpoint locations that have been determined
/// to date.  For a given breakpoint, there will be only one location with a given
/// address.  Adding a location at an already taken address will just return the location
/// already at that address.  Locations can be looked up by ID, or by address.
///
/// \b Options:
/// This includes:
///    \b Enabled/Disabled
///    \b Ignore Count
///    \b Callback
///    \b Condition
/// Note, these options can be set on the breakpoint, and they can also be set on the
/// individual locations.  The options set on the breakpoint take precedence over the
/// options set on the individual location.
/// So for instance disabling the breakpoint will cause NONE of the locations to get hit.
/// But if the breakpoint is enabled, then the location's enabled state will be checked
/// to determine whether to insert that breakpoint location.
/// Similarly, if the breakpoint condition says "stop", we won't check the location's condition.
/// But if the breakpoint condition says "continue", then we will check the location for whether
/// to actually stop or not.
/// One subtle point worth observing here is that you don't actually stop at a Breakpoint, you
/// always stop at one of its locations.  So the "should stop" tests are done by the location,
/// not by the breakpoint.
//----------------------------------------------------------------------
class Breakpoint:
    public std::enable_shared_from_this<Breakpoint>,
    public Stoppoint
{
public:

    static const ConstString &
    GetEventIdentifier ();


    //------------------------------------------------------------------
    /// An enum specifying the match style for breakpoint settings.  At
    /// present only used for function name style breakpoints.
    //------------------------------------------------------------------
    typedef enum
    {
        Exact,
        Regexp,
        Glob
    } MatchType;

    class BreakpointEventData :
        public EventData
    {
    public:

        static const ConstString &
        GetFlavorString ();

        virtual const ConstString &
        GetFlavor () const;

        BreakpointEventData (lldb::BreakpointEventType sub_type,
                             const lldb::BreakpointSP &new_breakpoint_sp);

        virtual
        ~BreakpointEventData();

        lldb::BreakpointEventType
        GetBreakpointEventType () const;

        lldb::BreakpointSP &
        GetBreakpoint ();
        
        BreakpointLocationCollection &
        GetBreakpointLocationCollection()
        {
            return m_locations;
        }


        virtual void
        Dump (Stream *s) const;

        static lldb::BreakpointEventType
        GetBreakpointEventTypeFromEvent (const lldb::EventSP &event_sp);

        static lldb::BreakpointSP
        GetBreakpointFromEvent (const lldb::EventSP &event_sp);

        static lldb::BreakpointLocationSP
        GetBreakpointLocationAtIndexFromEvent (const lldb::EventSP &event_sp, uint32_t loc_idx);
        
        static size_t
        GetNumBreakpointLocationsFromEvent (const lldb::EventSP &event_sp);

        static const BreakpointEventData *
        GetEventDataFromEvent (const Event *event_sp);

    private:

        lldb::BreakpointEventType m_breakpoint_event;
        lldb::BreakpointSP m_new_breakpoint_sp;
        BreakpointLocationCollection m_locations;

        DISALLOW_COPY_AND_ASSIGN (BreakpointEventData);
    };


    //------------------------------------------------------------------
    /// Destructor.
    ///
    /// The destructor is not virtual since there should be no reason to subclass
    /// breakpoints.  The varieties of breakpoints are specified instead by
    /// providing different resolvers & filters.
    //------------------------------------------------------------------
    ~Breakpoint();

    //------------------------------------------------------------------
    // Methods
    //------------------------------------------------------------------

    //------------------------------------------------------------------
    /// Tell whether this breakpoint is an "internal" breakpoint.
    /// @return
    ///     Returns \b true if this is an internal breakpoint, \b false otherwise.
    //------------------------------------------------------------------
    bool
    IsInternal () const;

    //------------------------------------------------------------------
    /// Standard "Dump" method.  At present it does nothing.
    //------------------------------------------------------------------
    void
    Dump (Stream *s);

    //------------------------------------------------------------------
    // The next set of methods provide ways to tell the breakpoint to update
    // it's location list - usually done when modules appear or disappear.
    //------------------------------------------------------------------


    //------------------------------------------------------------------
    /// Tell this breakpoint to clear all its breakpoint sites.  Done
    /// when the process holding the breakpoint sites is destroyed.
    //------------------------------------------------------------------
    void
    ClearAllBreakpointSites ();

    //------------------------------------------------------------------
    /// Tell this breakpoint to scan it's target's module list and resolve any
    /// new locations that match the breakpoint's specifications.
    //------------------------------------------------------------------
    void
    ResolveBreakpoint ();

    //------------------------------------------------------------------
    /// Tell this breakpoint to scan a given module list and resolve any
    /// new locations that match the breakpoint's specifications.
    ///
    /// @param[in] changed_modules
    ///    The list of modules to look in for new locations.
    //------------------------------------------------------------------
    void
    ResolveBreakpointInModules (ModuleList &changed_modules);


    //------------------------------------------------------------------
    /// Like ResolveBreakpointInModules, but allows for "unload" events, in
    /// which case we will remove any locations that are in modules that got
    /// unloaded.
    ///
    /// @param[in] changedModules
    ///    The list of modules to look in for new locations.
    /// @param[in] load_event
    ///    If \b true then the modules were loaded, if \b false, unloaded.
    /// @param[in] delete_locations
    ///    If \b true then the modules were unloaded delete any locations in the changed modules.
    //------------------------------------------------------------------
    void
    ModulesChanged (ModuleList &changed_modules,
                    bool load_event,
                    bool delete_locations = false);


    //------------------------------------------------------------------
    /// Tells the breakpoint the old module \a old_module_sp has been
    /// replaced by new_module_sp (usually because the underlying file has been
    /// rebuilt, and the old version is gone.)
    ///
    /// @param[in] old_module_sp
    ///    The old module that is going away.
    /// @param[in] new_module_sp
    ///    The new module that is replacing it.
    //------------------------------------------------------------------
    void
    ModuleReplaced (lldb::ModuleSP old_module_sp, lldb::ModuleSP new_module_sp);
    
    //------------------------------------------------------------------
    // The next set of methods provide access to the breakpoint locations
    // for this breakpoint.
    //------------------------------------------------------------------

    //------------------------------------------------------------------
    /// Add a location to the breakpoint's location list.  This is only meant
    /// to be called by the breakpoint's resolver.  FIXME: how do I ensure that?
    ///
    /// @param[in] addr
    ///    The Address specifying the new location.
    /// @param[out] new_location
    ///    Set to \b true if a new location was created, to \b false if there
    ///    already was a location at this Address.
    /// @return
    ///    Returns a pointer to the new location.
    //------------------------------------------------------------------
    lldb::BreakpointLocationSP
    AddLocation (const Address &addr,
                 bool *new_location = NULL);

    //------------------------------------------------------------------
    /// Find a breakpoint location by Address.
    ///
    /// @param[in] addr
    ///    The Address specifying the location.
    /// @return
    ///    Returns a shared pointer to the location at \a addr.  The pointer
    ///    in the shared pointer will be NULL if there is no location at that address.
    //------------------------------------------------------------------
    lldb::BreakpointLocationSP
    FindLocationByAddress (const Address &addr);

    //------------------------------------------------------------------
    /// Find a breakpoint location ID by Address.
    ///
    /// @param[in] addr
    ///    The Address specifying the location.
    /// @return
    ///    Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if
    ///    there is no breakpoint location at that address.
    //------------------------------------------------------------------
    lldb::break_id_t
    FindLocationIDByAddress (const Address &addr);

    //------------------------------------------------------------------
    /// Find a breakpoint location for a given breakpoint location ID.
    ///
    /// @param[in] bp_loc_id
    ///    The ID specifying the location.
    /// @return
    ///    Returns a shared pointer to the location with ID \a bp_loc_id.  The pointer
    ///    in the shared pointer will be NULL if there is no location with that ID.
    //------------------------------------------------------------------
    lldb::BreakpointLocationSP
    FindLocationByID (lldb::break_id_t bp_loc_id);

    //------------------------------------------------------------------
    /// Get breakpoint locations by index.
    ///
    /// @param[in] index
    ///    The location index.
    ///
    /// @return
    ///     Returns a shared pointer to the location with index \a 
    ///     index. The shared pointer might contain NULL if \a index is
    ///     greater than then number of actual locations.
    //------------------------------------------------------------------
    lldb::BreakpointLocationSP
    GetLocationAtIndex (size_t index);
    
    //------------------------------------------------------------------
    /// Removes all invalid breakpoint locations.
    ///
    /// Removes all breakpoint locations with architectures that aren't
    /// compatible with \a arch. Also remove any breakpoint locations
    /// with whose locations have address where the section has been
    /// deleted (module and object files no longer exist).
    ///
    /// This is typically used after the process calls exec, or anytime
    /// the architecture of the target changes.
    ///
    /// @param[in] arch
    ///     If valid, check the module in each breakpoint to make sure
    ///     they are compatible, otherwise, ignore architecture.
    //------------------------------------------------------------------
    void
    RemoveInvalidLocations (const ArchSpec &arch);

    //------------------------------------------------------------------
    // The next section deals with various breakpoint options.
    //------------------------------------------------------------------

    //------------------------------------------------------------------
    /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
    //------------------------------------------------------------------
    void
    SetEnabled (bool enable);

    //------------------------------------------------------------------
    /// Check the Enable/Disable state.
    /// @return
    ///     \b true if the breakpoint is enabled, \b false if disabled.
    //------------------------------------------------------------------
    bool
    IsEnabled ();

    //------------------------------------------------------------------
    /// Set the breakpoint to ignore the next \a count breakpoint hits.
    /// @param[in] count
    ///    The number of breakpoint hits to ignore.
    //------------------------------------------------------------------
    void
    SetIgnoreCount (uint32_t count);

    //------------------------------------------------------------------
    /// Return the current ignore count/
    /// @return
    ///     The number of breakpoint hits to be ignored.
    //------------------------------------------------------------------
    uint32_t
    GetIgnoreCount () const;
    
    //------------------------------------------------------------------
    /// Return the current hit count for all locations.
    /// @return
    ///     The current hit count for all locations.
    //------------------------------------------------------------------
    uint32_t
    GetHitCount () const;


    //------------------------------------------------------------------
    /// If \a one_shot is \b true, breakpoint will be deleted on first hit.
    //------------------------------------------------------------------
    void
    SetOneShot (bool one_shot);

    //------------------------------------------------------------------
    /// Check the OneShot state.
    /// @return
    ///     \b true if the breakpoint is one shot, \b false otherwise.
    //------------------------------------------------------------------
    bool
    IsOneShot () const;

    //------------------------------------------------------------------
    /// Set the valid thread to be checked when the breakpoint is hit.
    /// @param[in] thread_id
    ///    If this thread hits the breakpoint, we stop, otherwise not.
    //------------------------------------------------------------------
    void
    SetThreadID (lldb::tid_t thread_id);

    //------------------------------------------------------------------
    /// Return the current stop thread value.
    /// @return
    ///     The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads.
    //------------------------------------------------------------------
    lldb::tid_t
    GetThreadID () const;

    void
    SetThreadIndex (uint32_t index);
    
    uint32_t
    GetThreadIndex() const;
    
    void
    SetThreadName (const char *thread_name);
    
    const char *
    GetThreadName () const;
    
    void 
    SetQueueName (const char *queue_name);
    
    const char *
    GetQueueName () const;

    //------------------------------------------------------------------
    /// Set the callback action invoked when the breakpoint is hit.  
    /// 
    /// @param[in] callback
    ///    The method that will get called when the breakpoint is hit.
    /// @param[in] baton
    ///    A void * pointer that will get passed back to the callback function.
    /// @param[in] is_synchronous
    ///    If \b true the callback will be run on the private event thread
    ///    before the stop event gets reported.  If false, the callback will get
    ///    handled on the public event thread after the stop has been posted.
    ///
    /// @return
    ///    \b true if the process should stop when you hit the breakpoint.
    ///    \b false if it should continue.
    //------------------------------------------------------------------
    void
    SetCallback (BreakpointHitCallback callback, 
                 void *baton,
                 bool is_synchronous = false);

    void
    SetCallback (BreakpointHitCallback callback, 
                 const lldb::BatonSP &callback_baton_sp,
                 bool is_synchronous = false);

    void
    ClearCallback ();

    //------------------------------------------------------------------
    /// Set the breakpoint's condition.
    ///
    /// @param[in] condition
    ///    The condition expression to evaluate when the breakpoint is hit.
    ///    Pass in NULL to clear the condition.
    //------------------------------------------------------------------
    void SetCondition (const char *condition);
    
    //------------------------------------------------------------------
    /// Return a pointer to the text of the condition expression.
    ///
    /// @return
    ///    A pointer to the condition expression text, or NULL if no
    //     condition has been set.
    //------------------------------------------------------------------
    const char *GetConditionText () const;

    //------------------------------------------------------------------
    // The next section are various utility functions.
    //------------------------------------------------------------------

    //------------------------------------------------------------------
    /// Return the number of breakpoint locations that have resolved to
    /// actual breakpoint sites.
    ///
    /// @return
    ///     The number locations resolved breakpoint sites.
    //------------------------------------------------------------------
    size_t
    GetNumResolvedLocations() const;

    //------------------------------------------------------------------
    /// Return the number of breakpoint locations.
    ///
    /// @return
    ///     The number breakpoint locations.
    //------------------------------------------------------------------
    size_t
    GetNumLocations() const;

    //------------------------------------------------------------------
    /// Put a description of this breakpoint into the stream \a s.
    ///
    /// @param[in] s
    ///     Stream into which to dump the description.
    ///
    /// @param[in] level
    ///     The description level that indicates the detail level to
    ///     provide.
    ///
    /// @see lldb::DescriptionLevel
    //------------------------------------------------------------------
    void
    GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false);

    //------------------------------------------------------------------
    /// Set the "kind" description for a breakpoint.  If the breakpoint is hit
    /// the stop info will show this "kind" description instead of the breakpoint
    /// number.  Mostly useful for internal breakpoints, where the breakpoint number
    /// doesn't have meaning to the user.
    ///
    /// @param[in] kind
    ///     New "kind" description.
    //------------------------------------------------------------------
    void
    SetBreakpointKind (const char *kind)
    {
        m_kind_description.assign (kind);
    }
    
    //------------------------------------------------------------------
    /// Return the "kind" description for a breakpoint.
    ///
    /// @return
    ///     The breakpoint kind, or NULL if none is set.
    //------------------------------------------------------------------
    const char *GetBreakpointKind () const
    {
        return m_kind_description.c_str();
    }

    //------------------------------------------------------------------
    /// Accessor for the breakpoint Target.
    /// @return
    ///     This breakpoint's Target.
    //------------------------------------------------------------------
    Target &
    GetTarget ();

    const Target &
    GetTarget () const;

    void
    GetResolverDescription (Stream *s);

    //------------------------------------------------------------------
    /// Find breakpoint locations which match the (filename, line_number) description.
    /// The breakpoint location collection is to be filled with the matching locations.
    /// It should be initialized with 0 size by the API client.
    ///
    /// @return
    ///     True if there is a match
    ///
    ///     The locations which match the filename and line_number in loc_coll.  If its
    ///     size is 0 and true is returned, it means the breakpoint fully matches the
    ///     description.
    //------------------------------------------------------------------
    bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number,
                             BreakpointLocationCollection &loc_coll);

    void
    GetFilterDescription (Stream *s);

    //------------------------------------------------------------------
    /// Returns the BreakpointOptions structure set at the breakpoint level.
    ///
    /// Meant to be used by the BreakpointLocation class.
    ///
    /// @return
    ///     A pointer to this breakpoint's BreakpointOptions.
    //------------------------------------------------------------------
    BreakpointOptions *
    GetOptions ();


    //------------------------------------------------------------------
    /// Invoke the callback action when the breakpoint is hit.
    ///
    /// Meant to be used by the BreakpointLocation class.
    ///
    /// @param[in] context
    ///     Described the breakpoint event.
    ///
    /// @param[in] bp_loc_id
    ///     Which breakpoint location hit this breakpoint.
    ///
    /// @return
    ///     \b true if the target should stop at this breakpoint and \b false not.
    //------------------------------------------------------------------
    bool
    InvokeCallback (StoppointCallbackContext *context,
                    lldb::break_id_t bp_loc_id);

    bool
    IsHardware() const
    {
        return m_hardware;
    }

protected:
    friend class Target;
    //------------------------------------------------------------------
    // Protected Methods
    //------------------------------------------------------------------


    //------------------------------------------------------------------
    /// Constructors and Destructors
    /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans.
    /// The constructor takes a filter and a resolver.  Up in Target there are convenience
    /// variants that make breakpoints for some common cases.
    ///
    /// @param[in] target
    ///    The target in which the breakpoint will be set.
    ///
    /// @param[in] filter_sp
    ///    Shared pointer to the search filter that restricts the search domain of the breakpoint.
    ///
    /// @param[in] resolver_sp
    ///    Shared pointer to the resolver object that will determine breakpoint matches.
    ///
    /// @param hardware
    ///    If true, request a hardware breakpoint to be used to implement the breakpoint locations.
    ///
    /// @param resolve_indirect_symbols
    ///    If true, and the address of a given breakpoint location in this breakpoint is set on an
    ///    indirect symbol (i.e. Symbol::IsIndirect returns true) then the actual breakpoint site will
    ///    be set on the target of the indirect symbol.
    //------------------------------------------------------------------
    // This is the generic constructor
    Breakpoint(Target &target,
               lldb::SearchFilterSP &filter_sp,
               lldb::BreakpointResolverSP &resolver_sp,
               bool hardware,
               bool resolve_indirect_symbols = true);
    
    friend class BreakpointLocation;  // To call the following two when determining whether to stop.

    void
    DecrementIgnoreCount();

    // BreakpointLocation::IgnoreCountShouldStop & Breakpoint::IgnoreCountShouldStop can only be called once per stop, 
    // and BreakpointLocation::IgnoreCountShouldStop should be tested first, and if it returns false we should
    // continue, otherwise we should test Breakpoint::IgnoreCountShouldStop.
    
    bool
    IgnoreCountShouldStop ();

private:
    //------------------------------------------------------------------
    // For Breakpoint only
    //------------------------------------------------------------------
    bool m_being_created;
    bool m_hardware;                          // If this breakpoint is required to use a hardware breakpoint
    Target &m_target;                         // The target that holds this breakpoint.
    lldb::SearchFilterSP m_filter_sp;         // The filter that constrains the breakpoint's domain.
    lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint.
    BreakpointOptions m_options;              // Settable breakpoint options
    BreakpointLocationList m_locations;       // The list of locations currently found for this breakpoint.
    std::string m_kind_description;
    bool m_resolve_indirect_symbols;
    
    void
    SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind);
    
    void
    SendBreakpointChangedEvent (BreakpointEventData *data);

    DISALLOW_COPY_AND_ASSIGN(Breakpoint);
};

} // namespace lldb_private

#endif  // liblldb_Breakpoint_h_