DynamicLoader.h revision 24943d2ee8bfaa7cf5893e4709143924157a5c1e 
1//===-- DynamicLoader.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_DynamicLoader_h_
11#define liblldb_DynamicLoader_h_
12
13// Project includes
14#include "lldb/lldb-private.h"
15#include "lldb/Core/PluginInterface.h"
16
17namespace lldb_private {
18
19//----------------------------------------------------------------------
20/// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
21/// @brief A plug-in interface definition class for dynamic loaders.
22///
23/// Dynamic loader plug-ins track image (shared library) loading and
24/// unloading. The class is initialized given a live process that is
25/// halted at its entry point or just after attaching.
26///
27/// Dynamic loader plug-ins can track the process by registering
28/// callbacks using the:
29/// Process::RegisterNotificationCallbacks (const Notifications&)
30/// function.
31///
32/// Breakpoints can also be set in the process which can register
33/// functions that get called using:
34/// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void *).
35/// These breakpoint callbacks return a boolean value that indicates if
36/// the process should continue or halt and should return the global
37/// setting for this using:
38/// DynamicLoader::StopWhenImagesChange() const.
39//----------------------------------------------------------------------
40class DynamicLoader :
41    public PluginInterface
42{
43public:
44    //------------------------------------------------------------------
45    /// Find a dynamic loader plugin for a given process.
46    ///
47    /// Scans the installed DynamicLoader plug-ins and tries to find
48    /// an instance that can be used to track image changes in \a
49    /// process.
50    ///
51    /// @param[in] process
52    ///     The process for which to try and locate a dynamic loader
53    ///     plug-in instance.
54    ///
55    /// @param[in] plugin_name
56    ///     An optional name of a specific dynamic loader plug-in that
57    ///     should be used. If NULL, pick the best plug-in.
58    //------------------------------------------------------------------
59    static DynamicLoader*
60    FindPlugin (Process *process, const char *plugin_name);
61
62    //------------------------------------------------------------------
63    /// Construct with a process.
64    //------------------------------------------------------------------
65    DynamicLoader (Process *process);
66
67    //------------------------------------------------------------------
68    /// Destructor.
69    ///
70    /// The destructor is virtual since this class is designed to be
71    /// inherited from by the plug-in instance.
72    //------------------------------------------------------------------
73    virtual
74    ~DynamicLoader ();
75
76    //------------------------------------------------------------------
77    /// Called after attaching a process.
78    ///
79    /// Allow DynamicLoader plug-ins to execute some code after
80    /// attaching to a process.
81    //------------------------------------------------------------------
82    virtual void
83    DidAttach () = 0;
84
85    //------------------------------------------------------------------
86    /// Called after launching a process.
87    ///
88    /// Allow DynamicLoader plug-ins to execute some code after
89    /// the process has stopped for the first time on launch.
90    //------------------------------------------------------------------
91    virtual void
92    DidLaunch () = 0;
93
94    //------------------------------------------------------------------
95    /// Get wether the process should stop when images change.
96    ///
97    /// When images (executables and shared libraries) get loaded or
98    /// unloaded, often debug sessions will want to try and resolve or
99    /// unresolve breakpoints that are set in these images. Any
100    /// breakpoints set by DynamicLoader plug-in instances should
101    /// return this value to ensure consistent debug session behaviour.
102    ///
103    /// @return
104    ///     Returns \b true if the process should stop when images
105    ///     change, \b false if the process should resume.
106    //------------------------------------------------------------------
107    bool
108    GetStopWhenImagesChange () const;
109
110    //------------------------------------------------------------------
111    /// Set wether the process should stop when images change.
112    ///
113    /// When images (executables and shared libraries) get loaded or
114    /// unloaded, often debug sessions will want to try and resolve or
115    /// unresolve breakpoints that are set in these images. The default
116    /// is set so that the process stops when images change, but this
117    /// can be overridden using this function callback.
118    ///
119    /// @param[in] stop
120    ///     Boolean value that indicates wether the process should stop
121    ///     when images change.
122    //------------------------------------------------------------------
123    void
124    SetStopWhenImagesChange (bool stop);
125
126    //------------------------------------------------------------------
127    /// Provides a plan to step through the dynamic loader trampoline
128    /// for the current state of \a thread.
129    ///
130    ///
131    /// @param[in] stop_others
132    ///     Whether the plan should be set to stop other threads.
133    ///
134    /// @return
135    ///    A pointer to the plan (caller owned) or NULL if we are not at such
136    ///    a trampoline.
137    //------------------------------------------------------------------
138    virtual lldb::ThreadPlanSP
139    GetStepThroughTrampolinePlan (Thread &thread, bool stop_others) = 0;
140
141protected:
142    //------------------------------------------------------------------
143    // Member variables.
144    //------------------------------------------------------------------
145    Process* m_process; ///< The process that this dynamic loader plug-in is tracking.
146    bool m_stop_when_images_change; ///< Boolean value that indicates if the process should stop when imamges change.
147private:
148    DISALLOW_COPY_AND_ASSIGN (DynamicLoader);
149
150};
151
152} // namespace lldb_private
153
154#endif  // liblldb_DynamicLoader_h_
155