BreakpointLocation.h revision ca4fe802f0f8439a070e2adfb38ae2487fbde135 
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    //------------------------------------------------------------------
208    // The next section deals with this location's breakpoint sites.
209    //------------------------------------------------------------------
210
211    //------------------------------------------------------------------
212    /// Try to resolve the breakpoint site for this location.
213    ///
214    /// @return
215    ///     \b true if we were successful at setting a breakpoint site,
216    ///     \b false otherwise.
217    //------------------------------------------------------------------
218    bool
219    ResolveBreakpointSite ();
220
221    //------------------------------------------------------------------
222    /// Clear this breakpoint location's breakpoint site - for instance
223    /// when disabling the breakpoint.
224    ///
225    /// @return
226    ///     \b true if there was a breakpoint site to be cleared, \b false
227    ///     otherwise.
228    //------------------------------------------------------------------
229    bool
230    ClearBreakpointSite ();
231
232    //------------------------------------------------------------------
233    /// Return whether this breakpoint location has a breakpoint site.
234    /// @return
235    ///     \b true if there was a breakpoint site for this breakpoint
236    ///     location, \b false otherwise.
237    //------------------------------------------------------------------
238    bool
239    IsResolved () const;
240
241    lldb::BreakpointSiteSP
242    GetBreakpointSite() const;
243
244    //------------------------------------------------------------------
245    // The next section are generic report functions.
246    //------------------------------------------------------------------
247
248    //------------------------------------------------------------------
249    /// Print a description of this breakpoint location to the stream
250    /// \a s.
251    ///
252    /// @param[in] s
253    ///     The stream to which to print the description.
254    ///
255    /// @param[in] level
256    ///     The description level that indicates the detail level to
257    ///     provide.
258    ///
259    /// @see lldb::DescriptionLevel
260    //------------------------------------------------------------------
261    void
262    GetDescription (Stream *s, lldb::DescriptionLevel level);
263
264    //------------------------------------------------------------------
265    /// Standard "Dump" method.  At present it does nothing.
266    //------------------------------------------------------------------
267    void
268    Dump (Stream *s) const;
269
270    //------------------------------------------------------------------
271    /// Use this to set location specific breakpoint options.
272    ///
273    /// It will create a copy of the containing breakpoint's options if
274    /// that hasn't been done already
275    ///
276    /// @return
277    ///    A pointer to the breakpoint options.
278    //------------------------------------------------------------------
279    BreakpointOptions *
280    GetLocationOptions ();
281
282    //------------------------------------------------------------------
283    /// Use this to access breakpoint options from this breakpoint location.
284    /// This will point to the owning breakpoint's options unless options have
285    /// been set specifically on this location.
286    ///
287    /// @return
288    ///     A pointer to the containing breakpoint's options if this
289    ///     location doesn't have its own copy.
290    //------------------------------------------------------------------
291    const BreakpointOptions *
292    GetOptionsNoCreate () const;
293
294    bool
295    ValidForThisThread (Thread *thread);
296
297
298    //------------------------------------------------------------------
299    /// Invoke the callback action when the breakpoint is hit.
300    ///
301    /// Meant to be used by the BreakpointLocation class.
302    ///
303    /// @param[in] context
304    ///    Described the breakpoint event.
305    ///
306    /// @param[in] bp_loc_id
307    ///    Which breakpoint location hit this breakpoint.
308    ///
309    /// @return
310    ///     \b true if the target should stop at this breakpoint and \b
311    ///     false not.
312    //------------------------------------------------------------------
313    bool
314    InvokeCallback (StoppointCallbackContext *context);
315
316protected:
317    friend class BreakpointLocationList;
318    friend class CommandObjectBreakpointCommandAdd;
319    friend class Process;
320
321    //------------------------------------------------------------------
322    /// Set the breakpoint site for this location to \a bp_site_sp.
323    ///
324    /// @param[in] bp_site_sp
325    ///      The breakpoint site we are setting for this location.
326    ///
327    /// @return
328    ///     \b true if we were successful at setting the breakpoint site,
329    ///     \b false otherwise.
330    //------------------------------------------------------------------
331    bool
332    SetBreakpointSite (lldb::BreakpointSiteSP& bp_site_sp);
333
334private:
335
336    //------------------------------------------------------------------
337    // Constructors and Destructors
338    //
339    // Only the Breakpoint can make breakpoint locations, and it owns
340    // them.
341    //------------------------------------------------------------------
342
343    //------------------------------------------------------------------
344    /// Constructor.
345    ///
346    /// @param[in] owner
347    ///     A back pointer to the breakpoint that owns this location.
348    ///
349    /// @param[in] addr
350    ///     The Address defining this location.
351    ///
352    /// @param[in] tid
353    ///     The thread for which this breakpoint location is valid, or
354    ///     LLDB_INVALID_THREAD_ID if it is valid for all threads.
355    ///
356    /// @param[in] hardware
357    ///     \b true if a hardware breakpoint is requested.
358    //------------------------------------------------------------------
359
360    BreakpointLocation (lldb::break_id_t bid,
361                        Breakpoint &owner,
362                        const Address &addr,
363                        lldb::tid_t tid = LLDB_INVALID_THREAD_ID,
364                        bool hardware = false);
365
366    //------------------------------------------------------------------
367    // Data members:
368    //------------------------------------------------------------------
369    Address m_address; ///< The address defining this location.
370    Breakpoint &m_owner; ///< The breakpoint that produced this object.
371    std::auto_ptr<BreakpointOptions> m_options_ap; ///< Breakpoint options pointer, NULL if we're using our breakpoint's options.
372    lldb::BreakpointSiteSP m_bp_site_sp; ///< Our breakpoint site (it may be shared by more than one location.)
373
374    DISALLOW_COPY_AND_ASSIGN (BreakpointLocation);
375};
376
377} // namespace lldb_private
378
379#endif  // liblldb_BreakpointLocation_h_
380