1 //===-- ClangUtilityFunction.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_ClangUtilityFunction_h_
11 #define liblldb_ClangUtilityFunction_h_
12 
13 // C Includes
14 // C++ Includes
15 #include <string>
16 #include <map>
17 #include <vector>
18 
19 // Other libraries and framework includes
20 // Project includes
21 
22 #include "lldb/lldb-forward.h"
23 #include "lldb/lldb-private.h"
24 #include "lldb/Core/ClangForward.h"
25 #include "lldb/Expression/ClangExpression.h"
26 
27 namespace lldb_private
28 {
29 
30 //----------------------------------------------------------------------
31 /// @class ClangUtilityFunction ClangUtilityFunction.h "lldb/Expression/ClangUtilityFunction.h"
32 /// @brief Encapsulates a single expression for use with Clang
33 ///
34 /// LLDB uses expressions for various purposes, notably to call functions
35 /// and as a backend for the expr command.  ClangUtilityFunction encapsulates
36 /// a self-contained function meant to be used from other code.  Utility
37 /// functions can perform error-checking for ClangUserExpressions,
38 //----------------------------------------------------------------------
39 class ClangUtilityFunction : public ClangExpression
40 {
41 public:
42     //------------------------------------------------------------------
43     /// Constructor
44     ///
45     /// @param[in] text
46     ///     The text of the function.  Must be a full translation unit.
47     ///
48     /// @param[in] name
49     ///     The name of the function, as used in the text.
50     //------------------------------------------------------------------
51     ClangUtilityFunction (const char *text,
52                           const char *name);
53 
54     virtual
55     ~ClangUtilityFunction ();
56 
57     //------------------------------------------------------------------
58     /// Install the utility function into a process
59     ///
60     /// @param[in] error_stream
61     ///     A stream to print parse errors and warnings to.
62     ///
63     /// @param[in] exe_ctx
64     ///     The execution context to install the utility function to.
65     ///
66     /// @return
67     ///     True on success (no errors); false otherwise.
68     //------------------------------------------------------------------
69     bool
70     Install (Stream &error_stream, ExecutionContext &exe_ctx);
71 
72     //------------------------------------------------------------------
73     /// Check whether the given PC is inside the function
74     ///
75     /// Especially useful if the function dereferences NULL to indicate a failed
76     /// assert.
77     ///
78     /// @param[in] pc
79     ///     The program counter to check.
80     ///
81     /// @return
82     ///     True if the program counter falls within the function's bounds;
83     ///     false if not (or the function is not JIT compiled)
84     //------------------------------------------------------------------
85     bool
ContainsAddress(lldb::addr_t address)86     ContainsAddress (lldb::addr_t address)
87     {
88         // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS,
89         // so this always returns false if the function is not JIT compiled yet
90         return (address >= m_jit_start_addr && address < m_jit_end_addr);
91     }
92 
93 
94     //------------------------------------------------------------------
95     /// Return the string that the parser should parse.  Must be a full
96     /// translation unit.
97     //------------------------------------------------------------------
98     const char *
Text()99     Text ()
100     {
101         return m_function_text.c_str();
102     }
103 
104     //------------------------------------------------------------------
105     /// Return the function name that should be used for executing the
106     /// expression.  Text() should contain the definition of this
107     /// function.
108     //------------------------------------------------------------------
109     const char *
FunctionName()110     FunctionName ()
111     {
112         return m_function_name.c_str();
113     }
114 
115     //------------------------------------------------------------------
116     /// Return the object that the parser should use when resolving external
117     /// values.  May be NULL if everything should be self-contained.
118     //------------------------------------------------------------------
119     ClangExpressionDeclMap *
DeclMap()120     DeclMap ()
121     {
122         return m_expr_decl_map.get();
123     }
124 
125     //------------------------------------------------------------------
126     /// Return the object that the parser should use when registering
127     /// local variables.  May be NULL if the Expression doesn't care.
128     //------------------------------------------------------------------
129     ClangExpressionVariableList *
LocalVariables()130     LocalVariables ()
131     {
132         return NULL;
133     }
134 
135     //------------------------------------------------------------------
136     /// Return the object that the parser should allow to access ASTs.
137     /// May be NULL if the ASTs do not need to be transformed.
138     ///
139     /// @param[in] passthrough
140     ///     The ASTConsumer that the returned transformer should send
141     ///     the ASTs to after transformation.
142     //------------------------------------------------------------------
143     clang::ASTConsumer *
ASTTransformer(clang::ASTConsumer * passthrough)144     ASTTransformer (clang::ASTConsumer *passthrough)
145     {
146         return NULL;
147     }
148 
149     //------------------------------------------------------------------
150     /// Return true if validation code should be inserted into the
151     /// expression.
152     //------------------------------------------------------------------
153     bool
NeedsValidation()154     NeedsValidation ()
155     {
156         return false;
157     }
158 
159     //------------------------------------------------------------------
160     /// Return true if external variables in the expression should be
161     /// resolved.
162     //------------------------------------------------------------------
163     bool
NeedsVariableResolution()164     NeedsVariableResolution ()
165     {
166         return false;
167     }
168 
169 private:
170     std::unique_ptr<ClangExpressionDeclMap>  m_expr_decl_map;    ///< The map to use when parsing and materializing the expression.
171     std::unique_ptr<IRExecutionUnit>         m_execution_unit_ap;
172 
173     std::string                             m_function_text;    ///< The text of the function.  Must be a well-formed translation unit.
174     std::string                             m_function_name;    ///< The name of the function.
175 };
176 
177 } // namespace lldb_private
178 
179 #endif  // liblldb_ClangUtilityFunction_h_
180