1 | //===-- UserExpression.h ----------------------------------------*- C++ -*-===// |
2 | // |
3 | // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
4 | // See https://llvm.org/LICENSE.txt for license information. |
5 | // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
6 | // |
7 | //===----------------------------------------------------------------------===// |
8 | |
9 | #ifndef LLDB_EXPRESSION_USEREXPRESSION_H |
10 | #define LLDB_EXPRESSION_USEREXPRESSION_H |
11 | |
12 | #include <memory> |
13 | #include <string> |
14 | #include <vector> |
15 | |
16 | #include "lldb/Core/Address.h" |
17 | #include "lldb/Expression/Expression.h" |
18 | #include "lldb/Expression/Materializer.h" |
19 | #include "lldb/Target/ExecutionContext.h" |
20 | #include "lldb/Target/Target.h" |
21 | #include "lldb/lldb-forward.h" |
22 | #include "lldb/lldb-private.h" |
23 | |
24 | namespace lldb_private { |
25 | |
26 | /// \class UserExpression UserExpression.h "lldb/Expression/UserExpression.h" |
27 | /// Encapsulates a one-time expression for use in lldb. |
28 | /// |
29 | /// LLDB uses expressions for various purposes, notably to call functions |
30 | /// and as a backend for the expr command. UserExpression is a virtual base |
31 | /// class that encapsulates the objects needed to parse and interpret or |
32 | /// JIT an expression. The actual parsing part will be provided by the specific |
33 | /// implementations of UserExpression - which will be vended through the |
34 | /// appropriate TypeSystem. |
35 | class UserExpression : public Expression { |
36 | /// LLVM RTTI support. |
37 | static char ID; |
38 | |
39 | public: |
40 | bool isA(const void *ClassID) const override { return ClassID == &ID; } |
41 | static bool classof(const Expression *obj) { return obj->isA(ClassID: &ID); } |
42 | |
43 | enum { kDefaultTimeout = 500000u }; |
44 | |
45 | /// Constructor |
46 | /// |
47 | /// \param[in] expr |
48 | /// The expression to parse. |
49 | /// |
50 | /// \param[in] language |
51 | /// If not eLanguageTypeUnknown, a language to use when parsing |
52 | /// the expression. Currently restricted to those languages |
53 | /// supported by Clang. |
54 | /// |
55 | /// \param[in] desired_type |
56 | /// If not eResultTypeAny, the type to use for the expression |
57 | /// result. |
58 | UserExpression(ExecutionContextScope &exe_scope, llvm::StringRef expr, |
59 | llvm::StringRef prefix, lldb::LanguageType language, |
60 | ResultType desired_type, |
61 | const EvaluateExpressionOptions &options); |
62 | |
63 | /// Destructor |
64 | ~UserExpression() override; |
65 | |
66 | /// Parse the expression |
67 | /// |
68 | /// \param[in] diagnostic_manager |
69 | /// A diagnostic manager to report parse errors and warnings to. |
70 | /// |
71 | /// \param[in] exe_ctx |
72 | /// The execution context to use when looking up entities that |
73 | /// are needed for parsing (locations of functions, types of |
74 | /// variables, persistent variables, etc.) |
75 | /// |
76 | /// \param[in] execution_policy |
77 | /// Determines whether interpretation is possible or mandatory. |
78 | /// |
79 | /// \param[in] keep_result_in_memory |
80 | /// True if the resulting persistent variable should reside in |
81 | /// target memory, if applicable. |
82 | /// |
83 | /// \return |
84 | /// True on success (no errors); false otherwise. |
85 | virtual bool Parse(DiagnosticManager &diagnostic_manager, |
86 | ExecutionContext &exe_ctx, |
87 | lldb_private::ExecutionPolicy execution_policy, |
88 | bool keep_result_in_memory, bool generate_debug_info) = 0; |
89 | |
90 | /// Attempts to find possible command line completions for the given |
91 | /// (possible incomplete) user expression. |
92 | /// |
93 | /// \param[in] exe_ctx |
94 | /// The execution context to use when looking up entities that |
95 | /// are needed for parsing and completing (locations of functions, types |
96 | /// of variables, persistent variables, etc.) |
97 | /// |
98 | /// \param[out] request |
99 | /// The completion request to fill out. The completion should be a string |
100 | /// that would complete the current token at the cursor position. |
101 | /// Note that the string in the list replaces the current token |
102 | /// in the command line. |
103 | /// |
104 | /// \param[in] complete_pos |
105 | /// The position of the cursor inside the user expression string. |
106 | /// The completion process starts on the token that the cursor is in. |
107 | /// |
108 | /// \return |
109 | /// True if we added any completion results to the output; |
110 | /// false otherwise. |
111 | virtual bool Complete(ExecutionContext &exe_ctx, CompletionRequest &request, |
112 | unsigned complete_pos) { |
113 | return false; |
114 | } |
115 | |
116 | virtual bool CanInterpret() = 0; |
117 | |
118 | bool MatchesContext(ExecutionContext &exe_ctx); |
119 | |
120 | /// Execute the parsed expression by callinng the derived class's DoExecute |
121 | /// method. |
122 | /// |
123 | /// \param[in] diagnostic_manager |
124 | /// A diagnostic manager to report errors to. |
125 | /// |
126 | /// \param[in] exe_ctx |
127 | /// The execution context to use when looking up entities that |
128 | /// are needed for parsing (locations of variables, etc.) |
129 | /// |
130 | /// \param[in] options |
131 | /// Expression evaluation options. |
132 | /// |
133 | /// \param[in] shared_ptr_to_me |
134 | /// This is a shared pointer to this UserExpression. This is |
135 | /// needed because Execute can push a thread plan that will hold onto |
136 | /// the UserExpression for an unbounded period of time. So you |
137 | /// need to give the thread plan a reference to this object that can |
138 | /// keep it alive. |
139 | /// |
140 | /// \param[in] result |
141 | /// A pointer to direct at the persistent variable in which the |
142 | /// expression's result is stored. |
143 | /// |
144 | /// \return |
145 | /// A Process::Execution results value. |
146 | lldb::ExpressionResults Execute(DiagnosticManager &diagnostic_manager, |
147 | ExecutionContext &exe_ctx, |
148 | const EvaluateExpressionOptions &options, |
149 | lldb::UserExpressionSP &shared_ptr_to_me, |
150 | lldb::ExpressionVariableSP &result); |
151 | |
152 | /// Apply the side effects of the function to program state. |
153 | /// |
154 | /// \param[in] diagnostic_manager |
155 | /// A diagnostic manager to report errors to. |
156 | /// |
157 | /// \param[in] exe_ctx |
158 | /// The execution context to use when looking up entities that |
159 | /// are needed for parsing (locations of variables, etc.) |
160 | /// |
161 | /// \param[in] result |
162 | /// A pointer to direct at the persistent variable in which the |
163 | /// expression's result is stored. |
164 | /// |
165 | /// \param[in] function_stack_bottom |
166 | /// A pointer to the bottom of the function's stack frame. This |
167 | /// is used to determine whether the expression result resides in |
168 | /// memory that will still be valid, or whether it needs to be |
169 | /// treated as homeless for the purpose of future expressions. |
170 | /// |
171 | /// \param[in] function_stack_top |
172 | /// A pointer to the top of the function's stack frame. This |
173 | /// is used to determine whether the expression result resides in |
174 | /// memory that will still be valid, or whether it needs to be |
175 | /// treated as homeless for the purpose of future expressions. |
176 | /// |
177 | /// \return |
178 | /// A Process::Execution results value. |
179 | virtual bool FinalizeJITExecution( |
180 | DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, |
181 | lldb::ExpressionVariableSP &result, |
182 | lldb::addr_t function_stack_bottom = LLDB_INVALID_ADDRESS, |
183 | lldb::addr_t function_stack_top = LLDB_INVALID_ADDRESS) = 0; |
184 | |
185 | /// Return the string that the parser should parse. |
186 | const char *Text() override { return m_expr_text.c_str(); } |
187 | |
188 | /// Return the string that the user typed. |
189 | const char *GetUserText() { return m_expr_text.c_str(); } |
190 | |
191 | /// Return the function name that should be used for executing the |
192 | /// expression. Text() should contain the definition of this function. |
193 | const char *FunctionName() override { return "$__lldb_expr" ; } |
194 | |
195 | /// Returns whether the call to Parse on this user expression is cacheable. |
196 | /// This function exists to provide an escape hatch for supporting languages |
197 | /// where parsing an expression in the exact same context is unsafe. For |
198 | /// example, languages where generic functions aren't monomorphized, but |
199 | /// implement some other mechanism to represent generic values, may be unsafe |
200 | /// to cache, as the concrete type substitution may be different in every |
201 | /// expression evaluation. |
202 | virtual bool IsParseCacheable() { return true; } |
203 | /// Return the language that should be used when parsing. To use the |
204 | /// default, return eLanguageTypeUnknown. |
205 | lldb::LanguageType Language() const override { return m_language; } |
206 | |
207 | /// Return the desired result type of the function, or eResultTypeAny if |
208 | /// indifferent. |
209 | ResultType DesiredResultType() override { return m_desired_type; } |
210 | |
211 | /// Return true if validation code should be inserted into the expression. |
212 | bool NeedsValidation() override { return true; } |
213 | |
214 | /// Return true if external variables in the expression should be resolved. |
215 | bool NeedsVariableResolution() override { return true; } |
216 | |
217 | EvaluateExpressionOptions *GetOptions() override { return &m_options; } |
218 | |
219 | virtual lldb::ExpressionVariableSP |
220 | GetResultAfterDematerialization(ExecutionContextScope *exe_scope) { |
221 | return lldb::ExpressionVariableSP(); |
222 | } |
223 | |
224 | /// Evaluate one expression in the scratch context of the target passed in |
225 | /// the exe_ctx and return its result. |
226 | /// |
227 | /// \param[in] exe_ctx |
228 | /// The execution context to use when evaluating the expression. |
229 | /// |
230 | /// \param[in] options |
231 | /// Expression evaluation options. N.B. The language in the |
232 | /// evaluation options will be used to determine the language used for |
233 | /// expression evaluation. |
234 | /// |
235 | /// \param[in] expr_cstr |
236 | /// A C string containing the expression to be evaluated. |
237 | /// |
238 | /// \param[in] expr_prefix |
239 | /// If non-nullptr, a C string containing translation-unit level |
240 | /// definitions to be included when the expression is parsed. |
241 | /// |
242 | /// \param[in,out] result_valobj_sp |
243 | /// If execution is successful, the result valobj is placed here. |
244 | /// |
245 | /// \param[out] error |
246 | /// Filled in with an error in case the expression evaluation |
247 | /// fails to parse, run, or evaluated. |
248 | /// |
249 | /// \param[out] fixed_expression |
250 | /// If non-nullptr, the fixed expression is copied into the provided |
251 | /// string. |
252 | /// |
253 | /// \param[in] ctx_obj |
254 | /// If specified, then the expression will be evaluated in the context of |
255 | /// this object. It means that the context object's address will be |
256 | /// treated as `this` for the expression (the expression will be |
257 | /// evaluated as if it was inside of a method of the context object's |
258 | /// class, and its `this` parameter were pointing to the context object). |
259 | /// The parameter makes sense for class and union types only. |
260 | /// Currently there is a limitation: the context object must be located |
261 | /// in the debuggee process' memory (and have the load address). |
262 | /// |
263 | /// \result |
264 | /// A Process::ExpressionResults value. eExpressionCompleted for |
265 | /// success. |
266 | static lldb::ExpressionResults |
267 | Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options, |
268 | llvm::StringRef expr_cstr, llvm::StringRef expr_prefix, |
269 | lldb::ValueObjectSP &result_valobj_sp, Status &error, |
270 | std::string *fixed_expression = nullptr, |
271 | ValueObject *ctx_obj = nullptr); |
272 | |
273 | static const Status::ValueType kNoResult = |
274 | 0x1001; ///< ValueObject::GetError() returns this if there is no result |
275 | /// from the expression. |
276 | |
277 | llvm::StringRef GetFixedText() { |
278 | return m_fixed_text; |
279 | } |
280 | |
281 | protected: |
282 | virtual lldb::ExpressionResults |
283 | DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, |
284 | const EvaluateExpressionOptions &options, |
285 | lldb::UserExpressionSP &shared_ptr_to_me, |
286 | lldb::ExpressionVariableSP &result) = 0; |
287 | |
288 | static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp, |
289 | llvm::StringRef object_name, |
290 | Status &err); |
291 | |
292 | /// Return ValueObject for a given variable name in the current stack frame |
293 | /// |
294 | /// \param[in] frame Current stack frame. When passed a 'nullptr', this |
295 | /// function returns an empty ValueObjectSP. |
296 | /// |
297 | /// \param[in] object_name Name of the variable in the current stack frame |
298 | /// for which we want the ValueObjectSP. |
299 | /// |
300 | /// \param[out] err Status object which will get set on error. |
301 | /// |
302 | /// \returns On success returns a ValueObjectSP corresponding to the variable |
303 | /// with 'object_name' in the current 'frame'. Otherwise, returns |
304 | /// 'nullptr' (and sets the error status parameter 'err'). |
305 | static lldb::ValueObjectSP |
306 | GetObjectPointerValueObject(lldb::StackFrameSP frame, |
307 | llvm::StringRef object_name, Status &err); |
308 | |
309 | /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the |
310 | /// environment. |
311 | |
312 | void InstallContext(ExecutionContext &exe_ctx); |
313 | |
314 | bool LockAndCheckContext(ExecutionContext &exe_ctx, lldb::TargetSP &target_sp, |
315 | lldb::ProcessSP &process_sp, |
316 | lldb::StackFrameSP &frame_sp); |
317 | |
318 | Address m_address; ///< The address the process is stopped in. |
319 | std::string m_expr_text; ///< The text of the expression, as typed by the user |
320 | std::string m_expr_prefix; ///< The text of the translation-level definitions, |
321 | ///as provided by the user |
322 | std::string m_fixed_text; ///< The text of the expression with fix-its applied |
323 | ///- this won't be set if the fixed text doesn't |
324 | ///parse. |
325 | lldb::LanguageType m_language; ///< The language to use when parsing |
326 | ///(eLanguageTypeUnknown means use defaults) |
327 | ResultType m_desired_type; ///< The type to coerce the expression's result to. |
328 | ///If eResultTypeAny, inferred from the expression. |
329 | EvaluateExpressionOptions |
330 | m_options; ///< Additional options provided by the user. |
331 | }; |
332 | |
333 | } // namespace lldb_private |
334 | |
335 | #endif // LLDB_EXPRESSION_USEREXPRESSION_H |
336 | |