BreakpointLocation.h revision 28e23861bedbeb5e46be7d2af4c33bf5132422c6 
1//===-- BreakpointLocation.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_BreakpointLocation_h_
11#define liblldb_BreakpointLocation_h_
12
13// C Includes
14
15// C++ Includes
16#include <list>
17#include <memory>
18
19// Other libraries and framework includes
20
21// Project includes
22#include "lldb/lldb-private.h"
23#include "lldb/Breakpoint/StoppointLocation.h"
24#include "lldb/Core/UserID.h"
25#include "lldb/Core/Address.h"
26#include "lldb/Target/Process.h"
27#include "lldb/Core/StringList.h"
28
29namespace lldb_private {
30
31//----------------------------------------------------------------------
32/// @class BreakpointLocation BreakpointLocation.h "lldb/Breakpoint/BreakpointLocation.h"
33/// @brief Class that manages one unique (by address) instance of a logical breakpoint.
34//----------------------------------------------------------------------
35
36//----------------------------------------------------------------------
37/// General Outline:
38/// A breakpoint location is defined by the breakpoint that produces it,
39/// and the address that resulted in this particular instantiation.
40/// Each breakpoint location also may have a breakpoint site if its
41/// address has been loaded into the program.
42/// Finally it has a settable options object.
43///
44/// FIXME: Should we also store some fingerprint for the location, so
45/// we can map one location to the "equivalent location" on rerun?  This
46/// would be useful if you've set options on the locations.
47//----------------------------------------------------------------------
48
49class BreakpointLocation :
50    public std::tr1::enable_shared_from_this<BreakpointLocation>,
51    public StoppointLocation
52{
53public:
54
55    ~BreakpointLocation ();
56
57    //------------------------------------------------------------------
58    /// Gets the load address for this breakpoint location
59    /// @return
60    ///     Returns breakpoint location load address, \b
61    ///     LLDB_INVALID_ADDRESS if not yet set.
62    //------------------------------------------------------------------
63    lldb::addr_t
64    GetLoadAddress () const;
65
66    //------------------------------------------------------------------
67    /// Gets the Address for this breakpoint location
68    /// @return
69    ///     Returns breakpoint location Address.
70    //------------------------------------------------------------------
71    Address &
72    GetAddress ();
73    //------------------------------------------------------------------
74    /// Gets the Breakpoint that created this breakpoint location
75    /// @return
76    ///     Returns the owning breakpoint.
77    //------------------------------------------------------------------
78    Breakpoint &
79    GetBreakpoint ();
80
81    //------------------------------------------------------------------
82    /// Determines whether we should stop due to a hit at this
83    /// breakpoint location.
84    ///
85    /// Side Effects: This may evaluate the breakpoint condition, and
86    /// run the callback.  So this command may do a considerable amount
87    /// of work.
88    ///
89    /// @return
90    ///     \b true if this breakpoint location thinks we should stop,
91    ///     \b false otherwise.
92    //------------------------------------------------------------------
93    bool
94    ShouldStop (StoppointCallbackContext *context);
95
96    //------------------------------------------------------------------
97    // The next section deals with various breakpoint options.
98    //------------------------------------------------------------------
99
100    //------------------------------------------------------------------
101    /// If \a enable is \b true, enable the breakpoint, if \b false
102    /// disable it.
103    //------------------------------------------------------------------
104    void
105    SetEnabled(bool enabled);
106
107    //------------------------------------------------------------------
108    /// Check the Enable/Disable state.
109    ///
110    /// @return
111    ///     \b true if the breakpoint is enabled, \b false if disabled.
112    //------------------------------------------------------------------
113    bool
114    IsEnabled () const;
115
116    //------------------------------------------------------------------
117    /// Return the current Ignore Count.
118    ///
119    /// @return
120    ///     The number of breakpoint hits to be ignored.
121    //------------------------------------------------------------------
122    uint32_t
123    GetIgnoreCount ();
124
125    //------------------------------------------------------------------
126    /// Set the breakpoint to ignore the next \a count breakpoint hits.
127    ///
128    /// @param[in] count
129    ///    The number of breakpoint hits to ignore.
130    //------------------------------------------------------------------
131    void
132    SetIgnoreCount (uint32_t n);
133
134    //------------------------------------------------------------------
135    /// Set the callback action invoked when the breakpoint is hit.
136    ///
137    /// The callback will return a bool indicating whether the target
138    /// should stop at this breakpoint or not.
139    ///
140    /// @param[in] callback
141    ///     The method that will get called when the breakpoint is hit.
142    ///
143    /// @param[in] callback_baton_sp
144    ///     A shared pointer to a Baton that provides the void * needed
145    ///     for the callback.
146    ///
147    /// @see lldb_private::Baton
148    //------------------------------------------------------------------
149    void
150    SetCallback (BreakpointHitCallback callback,
151                 const lldb::BatonSP &callback_baton_sp,
152                 bool is_synchronous);
153
154    void
155    SetCallback (BreakpointHitCallback callback,
156                 void *baton,
157                 bool is_synchronous);
158
159    void
160    ClearCallback ();
161
162    //------------------------------------------------------------------
163    /// Set the breakpoint location's condition.
164    ///
165    /// @param[in] condition
166    ///    The condition expression to evaluate when the breakpoint is hit.
167    //------------------------------------------------------------------
168    void
169    SetCondition (const char *condition);
170
171    //------------------------------------------------------------------
172    /// Test the breakpoint location's condition in the Execution context passed in.
173    ///
174    /// @param[in] exe_ctx
175    ///    The execution context in which to evaluate this expression.
176    ///
177    /// @param[in] error
178    ///    Error messages will be written to this stream.
179    ///
180    /// @return
181    ///     A thread plan to run to test the condition, or NULL if there is no condition.
182    //------------------------------------------------------------------
183    ThreadPlan *
184    GetThreadPlanToTestCondition (ExecutionContext &exe_ctx,
185                                  Stream &error);
186
187    //------------------------------------------------------------------
188    /// Return a pointer to the text of the condition expression.
189    ///
190    /// @return
191    ///    A pointer to the condition expression text, or NULL if no
192    //     condition has been set.
193    //------------------------------------------------------------------
194    const char *
195    GetConditionText () const;
196
197
198    //------------------------------------------------------------------
199    /// Set the valid thread to be checked when the breakpoint is hit.
200    ///
201    /// @param[in] thread_id
202    ///    If this thread hits the breakpoint, we stop, otherwise not.
203    //------------------------------------------------------------------
204    void
205    SetThreadID (lldb::tid_t thread_id);
206
207    lldb::tid_t
208    GetThreadID ();
209
210    void
211    SetThreadIndex (uint32_t index);
212
213    uint32_t
214    GetThreadIndex() const;
215
216    void
217    SetThreadName (const char *thread_name);
218
219    const char *
220    GetThreadName () const;
221
222    void
223    SetQueueName (const char *queue_name);
224
225    const char *
226    GetQueueName () const;
227
228    //------------------------------------------------------------------
229    // The next section deals with this location's breakpoint sites.
230    //------------------------------------------------------------------
231
232    //------------------------------------------------------------------
233    /// Try to resolve the breakpoint site for this location.
234    ///
235    /// @return
236    ///     \b true if we were successful at setting a breakpoint site,
237    ///     \b false otherwise.
238    //------------------------------------------------------------------
239    bool
240    ResolveBreakpointSite ();
241
242    //------------------------------------------------------------------
243    /// Clear this breakpoint location's breakpoint site - for instance
244    /// when disabling the breakpoint.
245    ///
246    /// @return
247    ///     \b true if there was a breakpoint site to be cleared, \b false
248    ///     otherwise.
249    //------------------------------------------------------------------
250    bool
251    ClearBreakpointSite ();
252
253    //------------------------------------------------------------------
254    /// Return whether this breakpoint location has a breakpoint site.
255    /// @return
256    ///     \b true if there was a breakpoint site for this breakpoint
257    ///     location, \b false otherwise.
258    //------------------------------------------------------------------
259    bool
260    IsResolved () const;
261
262    lldb::BreakpointSiteSP
263    GetBreakpointSite() const;
264
265    //------------------------------------------------------------------
266    // The next section are generic report functions.
267    //------------------------------------------------------------------
268
269    //------------------------------------------------------------------
270    /// Print a description of this breakpoint location to the stream
271    /// \a s.
272    ///
273    /// @param[in] s
274    ///     The stream to which to print the description.
275    ///
276    /// @param[in] level
277    ///     The description level that indicates the detail level to
278    ///     provide.
279    ///
280    /// @see lldb::DescriptionLevel
281    //------------------------------------------------------------------
282    void
283    GetDescription (Stream *s, lldb::DescriptionLevel level);
284
285    //------------------------------------------------------------------
286    /// Standard "Dump" method.  At present it does nothing.
287    //------------------------------------------------------------------
288    void
289    Dump (Stream *s) const;
290
291    //------------------------------------------------------------------
292    /// Use this to set location specific breakpoint options.
293    ///
294    /// It will create a copy of the containing breakpoint's options if
295    /// that hasn't been done already
296    ///
297    /// @return
298    ///    A pointer to the breakpoint options.
299    //------------------------------------------------------------------
300    BreakpointOptions *
301    GetLocationOptions ();
302
303    //------------------------------------------------------------------
304    /// Use this to access breakpoint options from this breakpoint location.
305    /// This will point to the owning breakpoint's options unless options have
306    /// been set specifically on this location.
307    ///
308    /// @return
309    ///     A pointer to the containing breakpoint's options if this
310    ///     location doesn't have its own copy.
311    //------------------------------------------------------------------
312    const BreakpointOptions *
313    GetOptionsNoCreate () const;
314
315    bool
316    ValidForThisThread (Thread *thread);
317
318
319    //------------------------------------------------------------------
320    /// Invoke the callback action when the breakpoint is hit.
321    ///
322    /// Meant to be used by the BreakpointLocation class.
323    ///
324    /// @param[in] context
325    ///    Described the breakpoint event.
326    ///
327    /// @param[in] bp_loc_id
328    ///    Which breakpoint location hit this breakpoint.
329    ///
330    /// @return
331    ///     \b true if the target should stop at this breakpoint and \b
332    ///     false not.
333    //------------------------------------------------------------------
334    bool
335    InvokeCallback (StoppointCallbackContext *context);
336
337protected:
338    friend class BreakpointLocationList;
339    friend class CommandObjectBreakpointCommandAdd;
340    friend class Process;
341
342    //------------------------------------------------------------------
343    /// Set the breakpoint site for this location to \a bp_site_sp.
344    ///
345    /// @param[in] bp_site_sp
346    ///      The breakpoint site we are setting for this location.
347    ///
348    /// @return
349    ///     \b true if we were successful at setting the breakpoint site,
350    ///     \b false otherwise.
351    //------------------------------------------------------------------
352    bool
353    SetBreakpointSite (lldb::BreakpointSiteSP& bp_site_sp);
354
355private:
356
357    //------------------------------------------------------------------
358    // Constructors and Destructors
359    //
360    // Only the Breakpoint can make breakpoint locations, and it owns
361    // them.
362    //------------------------------------------------------------------
363
364    //------------------------------------------------------------------
365    /// Constructor.
366    ///
367    /// @param[in] owner
368    ///     A back pointer to the breakpoint that owns this location.
369    ///
370    /// @param[in] addr
371    ///     The Address defining this location.
372    ///
373    /// @param[in] tid
374    ///     The thread for which this breakpoint location is valid, or
375    ///     LLDB_INVALID_THREAD_ID if it is valid for all threads.
376    ///
377    /// @param[in] hardware
378    ///     \b true if a hardware breakpoint is requested.
379    //------------------------------------------------------------------
380
381    BreakpointLocation (lldb::break_id_t bid,
382                        Breakpoint &owner,
383                        const Address &addr,
384                        lldb::tid_t tid = LLDB_INVALID_THREAD_ID,
385                        bool hardware = false);
386
387    //------------------------------------------------------------------
388    // Data members:
389    //------------------------------------------------------------------
390    bool m_being_created;
391    Address m_address; ///< The address defining this location.
392    Breakpoint &m_owner; ///< The breakpoint that produced this object.
393    std::auto_ptr<BreakpointOptions> m_options_ap; ///< Breakpoint options pointer, NULL if we're using our breakpoint's options.
394    lldb::BreakpointSiteSP m_bp_site_sp; ///< Our breakpoint site (it may be shared by more than one location.)
395
396    void
397    SendBreakpointLocationChangedEvent (lldb::BreakpointEventType eventKind);
398
399    DISALLOW_COPY_AND_ASSIGN (BreakpointLocation);
400};
401
402} // namespace lldb_private
403
404#endif  // liblldb_BreakpointLocation_h_
405