]> CyberLeo.Net >> Repos - FreeBSD/releng/10.2.git/blob - contrib/llvm/tools/lldb/include/lldb/Breakpoint/Breakpoint.h
- Copy stable/10@285827 to releng/10.2 in preparation for 10.2-RC1
[FreeBSD/releng/10.2.git] / contrib / llvm / tools / lldb / include / lldb / Breakpoint / Breakpoint.h
1 //===-- Breakpoint.h --------------------------------------------*- C++ -*-===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9
10 #ifndef liblldb_Breakpoint_h_
11 #define liblldb_Breakpoint_h_
12
13 // C Includes
14 // C++ Includes
15 // Other libraries and framework includes
16 // Project includes
17 #include "lldb/Breakpoint/BreakpointLocationList.h"
18 #include "lldb/Breakpoint/BreakpointOptions.h"
19 #include "lldb/Breakpoint/BreakpointLocationCollection.h"
20 #include "lldb/Breakpoint/Stoppoint.h"
21 #include "lldb/Core/SearchFilter.h"
22 #include "lldb/Core/Event.h"
23 #include "lldb/Core/StringList.h"
24
25 namespace lldb_private {
26
27 //----------------------------------------------------------------------
28 /// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h"
29 /// @brief Class that manages logical breakpoint setting.
30 //----------------------------------------------------------------------
31
32 //----------------------------------------------------------------------
33 /// General Outline:
34 /// A breakpoint has four main parts, a filter, a resolver, the list of breakpoint
35 /// locations that have been determined for the filter/resolver pair, and finally
36 /// a set of options for the breakpoint.
37 ///
38 /// \b Filter:
39 /// This is an object derived from SearchFilter.  It manages the search
40 /// for breakpoint location matches through the symbols in the module list of the target
41 /// that owns it.  It also filters out locations based on whatever logic it wants.
42 ///
43 /// \b Resolver:
44 /// This is an object derived from BreakpointResolver.  It provides a
45 /// callback to the filter that will find breakpoint locations.  How it does this is
46 /// determined by what kind of resolver it is.
47 ///
48 /// The Breakpoint class also provides constructors for the common breakpoint cases
49 /// which make the appropriate filter and resolver for you.
50 ///
51 /// \b Location List:
52 /// This stores the breakpoint locations that have been determined
53 /// to date.  For a given breakpoint, there will be only one location with a given
54 /// address.  Adding a location at an already taken address will just return the location
55 /// already at that address.  Locations can be looked up by ID, or by address.
56 ///
57 /// \b Options:
58 /// This includes:
59 ///    \b Enabled/Disabled
60 ///    \b Ignore Count
61 ///    \b Callback
62 ///    \b Condition
63 /// Note, these options can be set on the breakpoint, and they can also be set on the
64 /// individual locations.  The options set on the breakpoint take precedence over the
65 /// options set on the individual location.
66 /// So for instance disabling the breakpoint will cause NONE of the locations to get hit.
67 /// But if the breakpoint is enabled, then the location's enabled state will be checked
68 /// to determine whether to insert that breakpoint location.
69 /// Similarly, if the breakpoint condition says "stop", we won't check the location's condition.
70 /// But if the breakpoint condition says "continue", then we will check the location for whether
71 /// to actually stop or not.
72 /// One subtle point worth observing here is that you don't actually stop at a Breakpoint, you
73 /// always stop at one of its locations.  So the "should stop" tests are done by the location,
74 /// not by the breakpoint.
75 //----------------------------------------------------------------------
76 class Breakpoint:
77     public std::enable_shared_from_this<Breakpoint>,
78     public Stoppoint
79 {
80 public:
81
82     static const ConstString &
83     GetEventIdentifier ();
84
85
86     //------------------------------------------------------------------
87     /// An enum specifying the match style for breakpoint settings.  At
88     /// present only used for function name style breakpoints.
89     //------------------------------------------------------------------
90     typedef enum
91     {
92         Exact,
93         Regexp,
94         Glob
95     } MatchType;
96
97     class BreakpointEventData :
98         public EventData
99     {
100     public:
101
102         static const ConstString &
103         GetFlavorString ();
104
105         virtual const ConstString &
106         GetFlavor () const;
107
108         BreakpointEventData (lldb::BreakpointEventType sub_type,
109                              const lldb::BreakpointSP &new_breakpoint_sp);
110
111         virtual
112         ~BreakpointEventData();
113
114         lldb::BreakpointEventType
115         GetBreakpointEventType () const;
116
117         lldb::BreakpointSP &
118         GetBreakpoint ();
119         
120         BreakpointLocationCollection &
121         GetBreakpointLocationCollection()
122         {
123             return m_locations;
124         }
125
126
127         virtual void
128         Dump (Stream *s) const;
129
130         static lldb::BreakpointEventType
131         GetBreakpointEventTypeFromEvent (const lldb::EventSP &event_sp);
132
133         static lldb::BreakpointSP
134         GetBreakpointFromEvent (const lldb::EventSP &event_sp);
135
136         static lldb::BreakpointLocationSP
137         GetBreakpointLocationAtIndexFromEvent (const lldb::EventSP &event_sp, uint32_t loc_idx);
138         
139         static size_t
140         GetNumBreakpointLocationsFromEvent (const lldb::EventSP &event_sp);
141
142         static const BreakpointEventData *
143         GetEventDataFromEvent (const Event *event_sp);
144
145     private:
146
147         lldb::BreakpointEventType m_breakpoint_event;
148         lldb::BreakpointSP m_new_breakpoint_sp;
149         BreakpointLocationCollection m_locations;
150
151         DISALLOW_COPY_AND_ASSIGN (BreakpointEventData);
152     };
153
154
155     //------------------------------------------------------------------
156     /// Destructor.
157     ///
158     /// The destructor is not virtual since there should be no reason to subclass
159     /// breakpoints.  The varieties of breakpoints are specified instead by
160     /// providing different resolvers & filters.
161     //------------------------------------------------------------------
162     ~Breakpoint();
163
164     //------------------------------------------------------------------
165     // Methods
166     //------------------------------------------------------------------
167
168     //------------------------------------------------------------------
169     /// Tell whether this breakpoint is an "internal" breakpoint.
170     /// @return
171     ///     Returns \b true if this is an internal breakpoint, \b false otherwise.
172     //------------------------------------------------------------------
173     bool
174     IsInternal () const;
175
176     //------------------------------------------------------------------
177     /// Standard "Dump" method.  At present it does nothing.
178     //------------------------------------------------------------------
179     void
180     Dump (Stream *s);
181
182     //------------------------------------------------------------------
183     // The next set of methods provide ways to tell the breakpoint to update
184     // it's location list - usually done when modules appear or disappear.
185     //------------------------------------------------------------------
186
187
188     //------------------------------------------------------------------
189     /// Tell this breakpoint to clear all its breakpoint sites.  Done
190     /// when the process holding the breakpoint sites is destroyed.
191     //------------------------------------------------------------------
192     void
193     ClearAllBreakpointSites ();
194
195     //------------------------------------------------------------------
196     /// Tell this breakpoint to scan it's target's module list and resolve any
197     /// new locations that match the breakpoint's specifications.
198     //------------------------------------------------------------------
199     void
200     ResolveBreakpoint ();
201
202     //------------------------------------------------------------------
203     /// Tell this breakpoint to scan a given module list and resolve any
204     /// new locations that match the breakpoint's specifications.
205     ///
206     /// @param[in] changed_modules
207     ///    The list of modules to look in for new locations.
208     //------------------------------------------------------------------
209     void
210     ResolveBreakpointInModules (ModuleList &changed_modules);
211
212
213     //------------------------------------------------------------------
214     /// Like ResolveBreakpointInModules, but allows for "unload" events, in
215     /// which case we will remove any locations that are in modules that got
216     /// unloaded.
217     ///
218     /// @param[in] changedModules
219     ///    The list of modules to look in for new locations.
220     /// @param[in] load_event
221     ///    If \b true then the modules were loaded, if \b false, unloaded.
222     /// @param[in] delete_locations
223     ///    If \b true then the modules were unloaded delete any locations in the changed modules.
224     //------------------------------------------------------------------
225     void
226     ModulesChanged (ModuleList &changed_modules,
227                     bool load_event,
228                     bool delete_locations = false);
229
230
231     //------------------------------------------------------------------
232     /// Tells the breakpoint the old module \a old_module_sp has been
233     /// replaced by new_module_sp (usually because the underlying file has been
234     /// rebuilt, and the old version is gone.)
235     ///
236     /// @param[in] old_module_sp
237     ///    The old module that is going away.
238     /// @param[in] new_module_sp
239     ///    The new module that is replacing it.
240     //------------------------------------------------------------------
241     void
242     ModuleReplaced (lldb::ModuleSP old_module_sp, lldb::ModuleSP new_module_sp);
243     
244     //------------------------------------------------------------------
245     // The next set of methods provide access to the breakpoint locations
246     // for this breakpoint.
247     //------------------------------------------------------------------
248
249     //------------------------------------------------------------------
250     /// Add a location to the breakpoint's location list.  This is only meant
251     /// to be called by the breakpoint's resolver.  FIXME: how do I ensure that?
252     ///
253     /// @param[in] addr
254     ///    The Address specifying the new location.
255     /// @param[out] new_location
256     ///    Set to \b true if a new location was created, to \b false if there
257     ///    already was a location at this Address.
258     /// @return
259     ///    Returns a pointer to the new location.
260     //------------------------------------------------------------------
261     lldb::BreakpointLocationSP
262     AddLocation (const Address &addr,
263                  bool *new_location = NULL);
264
265     //------------------------------------------------------------------
266     /// Find a breakpoint location by Address.
267     ///
268     /// @param[in] addr
269     ///    The Address specifying the location.
270     /// @return
271     ///    Returns a shared pointer to the location at \a addr.  The pointer
272     ///    in the shared pointer will be NULL if there is no location at that address.
273     //------------------------------------------------------------------
274     lldb::BreakpointLocationSP
275     FindLocationByAddress (const Address &addr);
276
277     //------------------------------------------------------------------
278     /// Find a breakpoint location ID by Address.
279     ///
280     /// @param[in] addr
281     ///    The Address specifying the location.
282     /// @return
283     ///    Returns the UID of the location at \a addr, or \b LLDB_INVALID_ID if
284     ///    there is no breakpoint location at that address.
285     //------------------------------------------------------------------
286     lldb::break_id_t
287     FindLocationIDByAddress (const Address &addr);
288
289     //------------------------------------------------------------------
290     /// Find a breakpoint location for a given breakpoint location ID.
291     ///
292     /// @param[in] bp_loc_id
293     ///    The ID specifying the location.
294     /// @return
295     ///    Returns a shared pointer to the location with ID \a bp_loc_id.  The pointer
296     ///    in the shared pointer will be NULL if there is no location with that ID.
297     //------------------------------------------------------------------
298     lldb::BreakpointLocationSP
299     FindLocationByID (lldb::break_id_t bp_loc_id);
300
301     //------------------------------------------------------------------
302     /// Get breakpoint locations by index.
303     ///
304     /// @param[in] index
305     ///    The location index.
306     ///
307     /// @return
308     ///     Returns a shared pointer to the location with index \a 
309     ///     index. The shared pointer might contain NULL if \a index is
310     ///     greater than then number of actual locations.
311     //------------------------------------------------------------------
312     lldb::BreakpointLocationSP
313     GetLocationAtIndex (size_t index);
314     
315     //------------------------------------------------------------------
316     /// Removes all invalid breakpoint locations.
317     ///
318     /// Removes all breakpoint locations with architectures that aren't
319     /// compatible with \a arch. Also remove any breakpoint locations
320     /// with whose locations have address where the section has been
321     /// deleted (module and object files no longer exist).
322     ///
323     /// This is typically used after the process calls exec, or anytime
324     /// the architecture of the target changes.
325     ///
326     /// @param[in] arch
327     ///     If valid, check the module in each breakpoint to make sure
328     ///     they are compatible, otherwise, ignore architecture.
329     //------------------------------------------------------------------
330     void
331     RemoveInvalidLocations (const ArchSpec &arch);
332
333     //------------------------------------------------------------------
334     // The next section deals with various breakpoint options.
335     //------------------------------------------------------------------
336
337     //------------------------------------------------------------------
338     /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
339     //------------------------------------------------------------------
340     void
341     SetEnabled (bool enable);
342
343     //------------------------------------------------------------------
344     /// Check the Enable/Disable state.
345     /// @return
346     ///     \b true if the breakpoint is enabled, \b false if disabled.
347     //------------------------------------------------------------------
348     bool
349     IsEnabled ();
350
351     //------------------------------------------------------------------
352     /// Set the breakpoint to ignore the next \a count breakpoint hits.
353     /// @param[in] count
354     ///    The number of breakpoint hits to ignore.
355     //------------------------------------------------------------------
356     void
357     SetIgnoreCount (uint32_t count);
358
359     //------------------------------------------------------------------
360     /// Return the current ignore count/
361     /// @return
362     ///     The number of breakpoint hits to be ignored.
363     //------------------------------------------------------------------
364     uint32_t
365     GetIgnoreCount () const;
366     
367     //------------------------------------------------------------------
368     /// Return the current hit count for all locations.
369     /// @return
370     ///     The current hit count for all locations.
371     //------------------------------------------------------------------
372     uint32_t
373     GetHitCount () const;
374
375
376     //------------------------------------------------------------------
377     /// If \a one_shot is \b true, breakpoint will be deleted on first hit.
378     //------------------------------------------------------------------
379     void
380     SetOneShot (bool one_shot);
381
382     //------------------------------------------------------------------
383     /// Check the OneShot state.
384     /// @return
385     ///     \b true if the breakpoint is one shot, \b false otherwise.
386     //------------------------------------------------------------------
387     bool
388     IsOneShot () const;
389
390     //------------------------------------------------------------------
391     /// Set the valid thread to be checked when the breakpoint is hit.
392     /// @param[in] thread_id
393     ///    If this thread hits the breakpoint, we stop, otherwise not.
394     //------------------------------------------------------------------
395     void
396     SetThreadID (lldb::tid_t thread_id);
397
398     //------------------------------------------------------------------
399     /// Return the current stop thread value.
400     /// @return
401     ///     The thread id for which the breakpoint hit will stop, LLDB_INVALID_THREAD_ID for all threads.
402     //------------------------------------------------------------------
403     lldb::tid_t
404     GetThreadID () const;
405
406     void
407     SetThreadIndex (uint32_t index);
408     
409     uint32_t
410     GetThreadIndex() const;
411     
412     void
413     SetThreadName (const char *thread_name);
414     
415     const char *
416     GetThreadName () const;
417     
418     void 
419     SetQueueName (const char *queue_name);
420     
421     const char *
422     GetQueueName () const;
423
424     //------------------------------------------------------------------
425     /// Set the callback action invoked when the breakpoint is hit.  
426     /// 
427     /// @param[in] callback
428     ///    The method that will get called when the breakpoint is hit.
429     /// @param[in] baton
430     ///    A void * pointer that will get passed back to the callback function.
431     /// @param[in] is_synchronous
432     ///    If \b true the callback will be run on the private event thread
433     ///    before the stop event gets reported.  If false, the callback will get
434     ///    handled on the public event thead after the stop has been posted.
435     ///
436     /// @return
437     ///    \b true if the process should stop when you hit the breakpoint.
438     ///    \b false if it should continue.
439     //------------------------------------------------------------------
440     void
441     SetCallback (BreakpointHitCallback callback, 
442                  void *baton,
443                  bool is_synchronous = false);
444
445     void
446     SetCallback (BreakpointHitCallback callback, 
447                  const lldb::BatonSP &callback_baton_sp,
448                  bool is_synchronous = false);
449
450     void
451     ClearCallback ();
452
453     //------------------------------------------------------------------
454     /// Set the breakpoint's condition.
455     ///
456     /// @param[in] condition
457     ///    The condition expression to evaluate when the breakpoint is hit.
458     ///    Pass in NULL to clear the condition.
459     //------------------------------------------------------------------
460     void SetCondition (const char *condition);
461     
462     //------------------------------------------------------------------
463     /// Return a pointer to the text of the condition expression.
464     ///
465     /// @return
466     ///    A pointer to the condition expression text, or NULL if no
467     //     condition has been set.
468     //------------------------------------------------------------------
469     const char *GetConditionText () const;
470
471     //------------------------------------------------------------------
472     // The next section are various utility functions.
473     //------------------------------------------------------------------
474
475     //------------------------------------------------------------------
476     /// Return the number of breakpoint locations that have resolved to
477     /// actual breakpoint sites.
478     ///
479     /// @return
480     ///     The number locations resolved breakpoint sites.
481     //------------------------------------------------------------------
482     size_t
483     GetNumResolvedLocations() const;
484
485     //------------------------------------------------------------------
486     /// Return the number of breakpoint locations.
487     ///
488     /// @return
489     ///     The number breakpoint locations.
490     //------------------------------------------------------------------
491     size_t
492     GetNumLocations() const;
493
494     //------------------------------------------------------------------
495     /// Put a description of this breakpoint into the stream \a s.
496     ///
497     /// @param[in] s
498     ///     Stream into which to dump the description.
499     ///
500     /// @param[in] level
501     ///     The description level that indicates the detail level to
502     ///     provide.
503     ///
504     /// @see lldb::DescriptionLevel
505     //------------------------------------------------------------------
506     void
507     GetDescription (Stream *s, lldb::DescriptionLevel level, bool show_locations = false);
508
509     //------------------------------------------------------------------
510     /// Set the "kind" description for a breakpoint.  If the breakpoint is hit
511     /// the stop info will show this "kind" description instead of the breakpoint
512     /// number.  Mostly useful for internal breakpoints, where the breakpoint number
513     /// doesn't have meaning to the user.
514     ///
515     /// @param[in] kind
516     ///     New "kind" description.
517     //------------------------------------------------------------------
518     void
519     SetBreakpointKind (const char *kind)
520     {
521         m_kind_description.assign (kind);
522     }
523     
524     //------------------------------------------------------------------
525     /// Return the "kind" description for a breakpoint.
526     ///
527     /// @return
528     ///     The breakpoint kind, or NULL if none is set.
529     //------------------------------------------------------------------
530     const char *GetBreakpointKind () const
531     {
532         return m_kind_description.c_str();
533     }
534
535     //------------------------------------------------------------------
536     /// Accessor for the breakpoint Target.
537     /// @return
538     ///     This breakpoint's Target.
539     //------------------------------------------------------------------
540     Target &
541     GetTarget ();
542
543     const Target &
544     GetTarget () const;
545
546     void
547     GetResolverDescription (Stream *s);
548
549     //------------------------------------------------------------------
550     /// Find breakpoint locations which match the (filename, line_number) description.
551     /// The breakpoint location collection is to be filled with the matching locations.
552     /// It should be initialized with 0 size by the API client.
553     ///
554     /// @return
555     ///     True if there is a match
556     ///
557     ///     The locations which match the filename and line_number in loc_coll.  If its
558     ///     size is 0 and true is returned, it means the breakpoint fully matches the
559     ///     description.
560     //------------------------------------------------------------------
561     bool GetMatchingFileLine(const ConstString &filename, uint32_t line_number,
562                              BreakpointLocationCollection &loc_coll);
563
564     void
565     GetFilterDescription (Stream *s);
566
567     //------------------------------------------------------------------
568     /// Returns the BreakpointOptions structure set at the breakpoint level.
569     ///
570     /// Meant to be used by the BreakpointLocation class.
571     ///
572     /// @return
573     ///     A pointer to this breakpoint's BreakpointOptions.
574     //------------------------------------------------------------------
575     BreakpointOptions *
576     GetOptions ();
577
578
579     //------------------------------------------------------------------
580     /// Invoke the callback action when the breakpoint is hit.
581     ///
582     /// Meant to be used by the BreakpointLocation class.
583     ///
584     /// @param[in] context
585     ///     Described the breakpoint event.
586     ///
587     /// @param[in] bp_loc_id
588     ///     Which breakpoint location hit this breakpoint.
589     ///
590     /// @return
591     ///     \b true if the target should stop at this breakpoint and \b false not.
592     //------------------------------------------------------------------
593     bool
594     InvokeCallback (StoppointCallbackContext *context,
595                     lldb::break_id_t bp_loc_id);
596
597     bool
598     IsHardware() const
599     {
600         return m_hardware;
601     }
602
603 protected:
604     friend class Target;
605     //------------------------------------------------------------------
606     // Protected Methods
607     //------------------------------------------------------------------
608
609
610     //------------------------------------------------------------------
611     /// Constructors and Destructors
612     /// Only the Target can make a breakpoint, and it owns the breakpoint lifespans.
613     /// The constructor takes a filter and a resolver.  Up in Target there are convenience
614     /// variants that make breakpoints for some common cases.
615     ///
616     /// @param[in] target
617     ///    The target in which the breakpoint will be set.
618     ///
619     /// @param[in] filter_sp
620     ///    Shared pointer to the search filter that restricts the search domain of the breakpoint.
621     ///
622     /// @param[in] resolver_sp
623     ///    Shared pointer to the resolver object that will determine breakpoint matches.
624     ///
625     /// @param hardware
626     ///    If true, request a hardware breakpoint to be used to implement the breakpoint locations.
627     ///
628     /// @param resolve_indirect_symbols
629     ///    If true, and the address of a given breakpoint location in this breakpoint is set on an
630     ///    indirect symbol (i.e. Symbol::IsIndirect returns true) then the actual breakpoint site will
631     ///    be set on the target of the indirect symbol.
632     //------------------------------------------------------------------
633     // This is the generic constructor
634     Breakpoint(Target &target,
635                lldb::SearchFilterSP &filter_sp,
636                lldb::BreakpointResolverSP &resolver_sp,
637                bool hardware,
638                bool resolve_indirect_symbols = true);
639     
640     friend class BreakpointLocation;  // To call the following two when determining whether to stop.
641
642     void
643     DecrementIgnoreCount();
644
645     // BreakpointLocation::IgnoreCountShouldStop & Breakpoint::IgnoreCountShouldStop can only be called once per stop, 
646     // and BreakpointLocation::IgnoreCountShouldStop should be tested first, and if it returns false we should
647     // continue, otherwise we should test Breakpoint::IgnoreCountShouldStop.
648     
649     bool
650     IgnoreCountShouldStop ();
651
652 private:
653     //------------------------------------------------------------------
654     // For Breakpoint only
655     //------------------------------------------------------------------
656     bool m_being_created;
657     bool m_hardware;                          // If this breakpoint is required to use a hardware breakpoint
658     Target &m_target;                         // The target that holds this breakpoint.
659     lldb::SearchFilterSP m_filter_sp;         // The filter that constrains the breakpoint's domain.
660     lldb::BreakpointResolverSP m_resolver_sp; // The resolver that defines this breakpoint.
661     BreakpointOptions m_options;              // Settable breakpoint options
662     BreakpointLocationList m_locations;       // The list of locations currently found for this breakpoint.
663     std::string m_kind_description;
664     bool m_resolve_indirect_symbols;
665     
666     void
667     SendBreakpointChangedEvent (lldb::BreakpointEventType eventKind);
668     
669     void
670     SendBreakpointChangedEvent (BreakpointEventData *data);
671
672     DISALLOW_COPY_AND_ASSIGN(Breakpoint);
673 };
674
675 } // namespace lldb_private
676
677 #endif  // liblldb_Breakpoint_h_