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: isA(const void * ClassID)40 bool isA(const void *ClassID) const override { return ClassID == &ID; } classof(const Expression * obj)41 static bool classof(const Expression *obj) { return obj->isA(&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, SourceLanguage 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. Complete(ExecutionContext & exe_ctx,CompletionRequest & request,unsigned complete_pos)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. Text()186 const char *Text() override { return m_expr_text.c_str(); } 187 188 /// Return the string that the user typed. GetUserText()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. FunctionName()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. IsParseCacheable()202 virtual bool IsParseCacheable() { return true; } 203 /// Return the language that should be used when parsing. To use the 204 /// default, return eLanguageTypeUnknown. Language()205 SourceLanguage Language() const override { return m_language; } 206 207 /// Return the desired result type of the function, or eResultTypeAny if 208 /// indifferent. DesiredResultType()209 ResultType DesiredResultType() override { return m_desired_type; } 210 211 /// Return true if validation code should be inserted into the expression. NeedsValidation()212 bool NeedsValidation() override { return true; } 213 214 /// Return true if external variables in the expression should be resolved. NeedsVariableResolution()215 bool NeedsVariableResolution() override { return true; } 216 GetOptions()217 EvaluateExpressionOptions *GetOptions() override { return &m_options; } 218 219 virtual lldb::ExpressionVariableSP GetResultAfterDematerialization(ExecutionContextScope * exe_scope)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 GetFixedText()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 /// The address the process is stopped in. 319 Address m_address; 320 /// The text of the expression, as typed by the user. 321 std::string m_expr_text; 322 /// The text of the translation-level definitions, as provided by the user. 323 std::string m_expr_prefix; 324 /// The text of the expression with fix-its applied this won't be set if the 325 /// fixed text doesn't parse. 326 std::string m_fixed_text; 327 /// The language to use when parsing (unknown means use defaults). 328 SourceLanguage m_language; 329 /// The type to coerce the expression's result to. If eResultTypeAny, inferred 330 /// from the expression. 331 ResultType m_desired_type; 332 /// Additional options provided by the user. 333 EvaluateExpressionOptions m_options; 334 }; 335 336 } // namespace lldb_private 337 338 #endif // LLDB_EXPRESSION_USEREXPRESSION_H 339