DynamicLoader.h revision 323ce42219c4b036e21212ce7d1398253a91e9db 
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/Error.h"
16#include "lldb/Core/PluginInterface.h"
17
18namespace lldb_private {
19
20//----------------------------------------------------------------------
21/// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h"
22/// @brief A plug-in interface definition class for dynamic loaders.
23///
24/// Dynamic loader plug-ins track image (shared library) loading and
25/// unloading. The class is initialized given a live process that is
26/// halted at its entry point or just after attaching.
27///
28/// Dynamic loader plug-ins can track the process by registering
29/// callbacks using the:
30/// Process::RegisterNotificationCallbacks (const Notifications&)
31/// function.
32///
33/// Breakpoints can also be set in the process which can register
34/// functions that get called using:
35/// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void *).
36/// These breakpoint callbacks return a boolean value that indicates if
37/// the process should continue or halt and should return the global
38/// setting for this using:
39/// DynamicLoader::StopWhenImagesChange() const.
40//----------------------------------------------------------------------
41class DynamicLoader :
42    public PluginInterface
43{
44public:
45    //------------------------------------------------------------------
46    /// Find a dynamic loader plugin for a given process.
47    ///
48    /// Scans the installed DynamicLoader plug-ins and tries to find
49    /// an instance that can be used to track image changes in \a
50    /// process.
51    ///
52    /// @param[in] process
53    ///     The process for which to try and locate a dynamic loader
54    ///     plug-in instance.
55    ///
56    /// @param[in] plugin_name
57    ///     An optional name of a specific dynamic loader plug-in that
58    ///     should be used. If NULL, pick the best plug-in.
59    //------------------------------------------------------------------
60    static DynamicLoader*
61    FindPlugin (Process *process, const char *plugin_name);
62
63    //------------------------------------------------------------------
64    /// Construct with a process.
65    //------------------------------------------------------------------
66    DynamicLoader (Process *process);
67
68    //------------------------------------------------------------------
69    /// Destructor.
70    ///
71    /// The destructor is virtual since this class is designed to be
72    /// inherited from by the plug-in instance.
73    //------------------------------------------------------------------
74    virtual
75    ~DynamicLoader ();
76
77    //------------------------------------------------------------------
78    /// Called after attaching a process.
79    ///
80    /// Allow DynamicLoader plug-ins to execute some code after
81    /// attaching to a process.
82    //------------------------------------------------------------------
83    virtual void
84    DidAttach () = 0;
85
86    //------------------------------------------------------------------
87    /// Called after launching a process.
88    ///
89    /// Allow DynamicLoader plug-ins to execute some code after
90    /// the process has stopped for the first time on launch.
91    //------------------------------------------------------------------
92    virtual void
93    DidLaunch () = 0;
94
95
96
97    //------------------------------------------------------------------
98    /// Get whether the process should stop when images change.
99    ///
100    /// When images (executables and shared libraries) get loaded or
101    /// unloaded, often debug sessions will want to try and resolve or
102    /// unresolve breakpoints that are set in these images. Any
103    /// breakpoints set by DynamicLoader plug-in instances should
104    /// return this value to ensure consistent debug session behaviour.
105    ///
106    /// @return
107    ///     Returns \b true if the process should stop when images
108    ///     change, \b false if the process should resume.
109    //------------------------------------------------------------------
110    bool
111    GetStopWhenImagesChange () const;
112
113    //------------------------------------------------------------------
114    /// Set whether the process should stop when images change.
115    ///
116    /// When images (executables and shared libraries) get loaded or
117    /// unloaded, often debug sessions will want to try and resolve or
118    /// unresolve breakpoints that are set in these images. The default
119    /// is set so that the process stops when images change, but this
120    /// can be overridden using this function callback.
121    ///
122    /// @param[in] stop
123    ///     Boolean value that indicates whether the process should stop
124    ///     when images change.
125    //------------------------------------------------------------------
126    void
127    SetStopWhenImagesChange (bool stop);
128
129    //------------------------------------------------------------------
130    /// Provides a plan to step through the dynamic loader trampoline
131    /// for the current state of \a thread.
132    ///
133    ///
134    /// @param[in] stop_others
135    ///     Whether the plan should be set to stop other threads.
136    ///
137    /// @return
138    ///    A pointer to the plan (caller owned) or NULL if we are not at such
139    ///    a trampoline.
140    //------------------------------------------------------------------
141    virtual lldb::ThreadPlanSP
142    GetStepThroughTrampolinePlan (Thread &thread, bool stop_others) = 0;
143
144
145    //------------------------------------------------------------------
146    /// Some dynamic loaders provide features where there are a group of symbols "equivalent to"
147    /// a given symbol one of which will be chosen when the symbol is bound.  If you want to
148    /// set a breakpoint on one of these symbols, you really need to set it on all the
149    /// equivalent symbols.
150    ///
151    ///
152    /// @param[in] original_symbol
153    ///     The symbol for which we are finding equivalences.
154    ///
155    /// @param[in] module_list
156    ///     The set of modules in which to search.
157    ///
158    /// @param[out] equivalent_symbols
159    ///     The equivalent symbol list - any equivalent symbols found are appended to this list.
160    ///
161    /// @return
162    ///    Number of equivalent symbols found.
163    //------------------------------------------------------------------
164    virtual size_t
165    FindEquivalentSymbols (Symbol *original_symbol, ModuleList &module_list, SymbolContextList &equivalent_symbols)
166    {
167        return 0;
168    }
169
170    //------------------------------------------------------------------
171    /// Ask if it is ok to try and load or unload an shared library
172    /// (image).
173    ///
174    /// The dynamic loader often knows when it would be ok to try and
175    /// load or unload a shared library. This function call allows the
176    /// dynamic loader plug-ins to check any current dyld state to make
177    /// sure it is an ok time to load a shared library.
178    ///
179    /// @return
180    ///     \b True if it is currently ok to try and load a shared
181    ///     library into the process, \b false otherwise.
182    //------------------------------------------------------------------
183    virtual Error
184    CanLoadImage () = 0;
185
186protected:
187    //------------------------------------------------------------------
188    // Member variables.
189    //------------------------------------------------------------------
190    Process* m_process; ///< The process that this dynamic loader plug-in is tracking.
191    bool m_stop_when_images_change; ///< Boolean value that indicates if the process should stop when imamges change.
192private:
193    DISALLOW_COPY_AND_ASSIGN (DynamicLoader);
194
195};
196
197} // namespace lldb_private
198
199#endif  // liblldb_DynamicLoader_h_
200