1 //===-- UserExpression.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_UserExpression_h_ 11 #define liblldb_UserExpression_h_ 12 13 #include <memory> 14 #include <string> 15 #include <vector> 16 17 #include "lldb/Core/Address.h" 18 #include "lldb/Expression/Expression.h" 19 #include "lldb/Expression/Materializer.h" 20 #include "lldb/Target/ExecutionContext.h" 21 #include "lldb/Target/Target.h" 22 #include "lldb/lldb-forward.h" 23 #include "lldb/lldb-private.h" 24 25 namespace lldb_private { 26 27 //---------------------------------------------------------------------- 28 /// @class UserExpression UserExpression.h "lldb/Expression/UserExpression.h" 29 /// Encapsulates a one-time expression for use in lldb. 30 /// 31 /// LLDB uses expressions for various purposes, notably to call functions 32 /// and as a backend for the expr command. UserExpression is a virtual base 33 /// class that encapsulates the objects needed to parse and interpret or 34 /// JIT an expression. The actual parsing part will be provided by the specific 35 /// implementations of UserExpression - which will be vended through the 36 /// appropriate TypeSystem. 37 //---------------------------------------------------------------------- 38 class UserExpression : public Expression { 39 public: 40 enum { kDefaultTimeout = 500000u }; 41 42 //------------------------------------------------------------------ 43 /// Constructor 44 /// 45 /// @param[in] expr 46 /// The expression to parse. 47 /// 48 /// @param[in] expr_prefix 49 /// If non-nullptr, a C string containing translation-unit level 50 /// definitions to be included when the expression is parsed. 51 /// 52 /// @param[in] language 53 /// If not eLanguageTypeUnknown, a language to use when parsing 54 /// the expression. Currently restricted to those languages 55 /// supported by Clang. 56 /// 57 /// @param[in] desired_type 58 /// If not eResultTypeAny, the type to use for the expression 59 /// result. 60 //------------------------------------------------------------------ 61 UserExpression(ExecutionContextScope &exe_scope, llvm::StringRef expr, 62 llvm::StringRef prefix, lldb::LanguageType language, 63 ResultType desired_type, 64 const EvaluateExpressionOptions &options); 65 66 //------------------------------------------------------------------ 67 /// Destructor 68 //------------------------------------------------------------------ 69 ~UserExpression() override; 70 71 //------------------------------------------------------------------ 72 /// Parse the expression 73 /// 74 /// @param[in] diagnostic_manager 75 /// A diagnostic manager to report parse errors and warnings to. 76 /// 77 /// @param[in] exe_ctx 78 /// The execution context to use when looking up entities that 79 /// are needed for parsing (locations of functions, types of 80 /// variables, persistent variables, etc.) 81 /// 82 /// @param[in] execution_policy 83 /// Determines whether interpretation is possible or mandatory. 84 /// 85 /// @param[in] keep_result_in_memory 86 /// True if the resulting persistent variable should reside in 87 /// target memory, if applicable. 88 /// 89 /// @return 90 /// True on success (no errors); false otherwise. 91 //------------------------------------------------------------------ 92 virtual bool Parse(DiagnosticManager &diagnostic_manager, 93 ExecutionContext &exe_ctx, 94 lldb_private::ExecutionPolicy execution_policy, 95 bool keep_result_in_memory, bool generate_debug_info) = 0; 96 97 //------------------------------------------------------------------ 98 /// Attempts to find possible command line completions for the given 99 /// (possible incomplete) user expression. 100 /// 101 /// @param[in] exe_ctx 102 /// The execution context to use when looking up entities that 103 /// are needed for parsing and completing (locations of functions, types 104 /// of variables, persistent variables, etc.) 105 /// 106 /// @param[out] request 107 /// The completion request to fill out. The completion should be a string 108 /// that would complete the current token at the cursor position. 109 /// Note that the string in the list replaces the current token 110 /// in the command line. 111 /// 112 /// @param[in] complete_pos 113 /// The position of the cursor inside the user expression string. 114 /// The completion process starts on the token that the cursor is in. 115 /// 116 /// @return 117 /// True if we added any completion results to the output; 118 /// false otherwise. 119 //------------------------------------------------------------------ Complete(ExecutionContext & exe_ctx,CompletionRequest & request,unsigned complete_pos)120 virtual bool Complete(ExecutionContext &exe_ctx, CompletionRequest &request, 121 unsigned complete_pos) { 122 return false; 123 } 124 125 virtual bool CanInterpret() = 0; 126 127 bool MatchesContext(ExecutionContext &exe_ctx); 128 129 //------------------------------------------------------------------ 130 /// Execute the parsed expression by callinng the derived class's DoExecute 131 /// method. 132 /// 133 /// @param[in] diagnostic_manager 134 /// A diagnostic manager to report errors to. 135 /// 136 /// @param[in] exe_ctx 137 /// The execution context to use when looking up entities that 138 /// are needed for parsing (locations of variables, etc.) 139 /// 140 /// @param[in] options 141 /// Expression evaluation options. 142 /// 143 /// @param[in] shared_ptr_to_me 144 /// This is a shared pointer to this UserExpression. This is 145 /// needed because Execute can push a thread plan that will hold onto 146 /// the UserExpression for an unbounded period of time. So you 147 /// need to give the thread plan a reference to this object that can 148 /// keep it alive. 149 /// 150 /// @param[in] result 151 /// A pointer to direct at the persistent variable in which the 152 /// expression's result is stored. 153 /// 154 /// @return 155 /// A Process::Execution results value. 156 //------------------------------------------------------------------ 157 lldb::ExpressionResults Execute(DiagnosticManager &diagnostic_manager, 158 ExecutionContext &exe_ctx, 159 const EvaluateExpressionOptions &options, 160 lldb::UserExpressionSP &shared_ptr_to_me, 161 lldb::ExpressionVariableSP &result); 162 163 //------------------------------------------------------------------ 164 /// Apply the side effects of the function to program state. 165 /// 166 /// @param[in] diagnostic_manager 167 /// A diagnostic manager to report errors to. 168 /// 169 /// @param[in] exe_ctx 170 /// The execution context to use when looking up entities that 171 /// are needed for parsing (locations of variables, etc.) 172 /// 173 /// @param[in] result 174 /// A pointer to direct at the persistent variable in which the 175 /// expression's result is stored. 176 /// 177 /// @param[in] function_stack_pointer 178 /// A pointer to the base of the function's stack frame. This 179 /// is used to determine whether the expression result resides in 180 /// memory that will still be valid, or whether it needs to be 181 /// treated as homeless for the purpose of future expressions. 182 /// 183 /// @return 184 /// A Process::Execution results value. 185 //------------------------------------------------------------------ 186 virtual bool FinalizeJITExecution( 187 DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, 188 lldb::ExpressionVariableSP &result, 189 lldb::addr_t function_stack_bottom = LLDB_INVALID_ADDRESS, 190 lldb::addr_t function_stack_top = LLDB_INVALID_ADDRESS) = 0; 191 192 //------------------------------------------------------------------ 193 /// Return the string that the parser should parse. 194 //------------------------------------------------------------------ Text()195 const char *Text() override { return m_expr_text.c_str(); } 196 197 //------------------------------------------------------------------ 198 /// Return the string that the user typed. 199 //------------------------------------------------------------------ GetUserText()200 const char *GetUserText() { return m_expr_text.c_str(); } 201 202 //------------------------------------------------------------------ 203 /// Return the function name that should be used for executing the 204 /// expression. Text() should contain the definition of this function. 205 //------------------------------------------------------------------ FunctionName()206 const char *FunctionName() override { return "$__lldb_expr"; } 207 208 //------------------------------------------------------------------ 209 /// Return the language that should be used when parsing. To use the 210 /// default, return eLanguageTypeUnknown. 211 //------------------------------------------------------------------ Language()212 lldb::LanguageType Language() override { return m_language; } 213 214 //------------------------------------------------------------------ 215 /// Return the desired result type of the function, or eResultTypeAny if 216 /// indifferent. 217 //------------------------------------------------------------------ DesiredResultType()218 ResultType DesiredResultType() override { return m_desired_type; } 219 220 //------------------------------------------------------------------ 221 /// Return true if validation code should be inserted into the expression. 222 //------------------------------------------------------------------ NeedsValidation()223 bool NeedsValidation() override { return true; } 224 225 //------------------------------------------------------------------ 226 /// Return true if external variables in the expression should be resolved. 227 //------------------------------------------------------------------ NeedsVariableResolution()228 bool NeedsVariableResolution() override { return true; } 229 GetOptions()230 EvaluateExpressionOptions *GetOptions() override { return &m_options; } 231 232 virtual lldb::ExpressionVariableSP GetResultAfterDematerialization(ExecutionContextScope * exe_scope)233 GetResultAfterDematerialization(ExecutionContextScope *exe_scope) { 234 return lldb::ExpressionVariableSP(); 235 } 236 GetJITModule()237 virtual lldb::ModuleSP GetJITModule() { return lldb::ModuleSP(); } 238 239 //------------------------------------------------------------------ 240 /// Evaluate one expression in the scratch context of the target passed in 241 /// the exe_ctx and return its result. 242 /// 243 /// @param[in] exe_ctx 244 /// The execution context to use when evaluating the expression. 245 /// 246 /// @param[in] options 247 /// Expression evaluation options. N.B. The language in the 248 /// evaluation options will be used to determine the language used for 249 /// expression evaluation. 250 /// 251 /// @param[in] expr_cstr 252 /// A C string containing the expression to be evaluated. 253 /// 254 /// @param[in] expr_prefix 255 /// If non-nullptr, a C string containing translation-unit level 256 /// definitions to be included when the expression is parsed. 257 /// 258 /// @param[in,out] result_valobj_sp 259 /// If execution is successful, the result valobj is placed here. 260 /// 261 /// @param[out] error 262 /// Filled in with an error in case the expression evaluation 263 /// fails to parse, run, or evaluated. 264 /// 265 /// @param[in] line_offset 266 /// The offset of the first line of the expression from the "beginning" of 267 /// a virtual source file used for error reporting and debug info. 268 /// 269 /// @param[out] fixed_expression 270 /// If non-nullptr, the fixed expression is copied into the provided 271 /// string. 272 /// 273 /// @param[out] jit_module_sp_ptr 274 /// If non-nullptr, used to persist the generated IR module. 275 /// 276 /// @result 277 /// A Process::ExpressionResults value. eExpressionCompleted for 278 /// success. 279 //------------------------------------------------------------------ 280 static lldb::ExpressionResults 281 Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options, 282 llvm::StringRef expr_cstr, llvm::StringRef expr_prefix, 283 lldb::ValueObjectSP &result_valobj_sp, Status &error, 284 uint32_t line_offset = 0, std::string *fixed_expression = nullptr, 285 lldb::ModuleSP *jit_module_sp_ptr = nullptr); 286 287 static const Status::ValueType kNoResult = 288 0x1001; ///< ValueObject::GetError() returns this if there is no result 289 /// from the expression. 290 GetFixedText()291 const char *GetFixedText() { 292 if (m_fixed_text.empty()) 293 return nullptr; 294 return m_fixed_text.c_str(); 295 } 296 297 protected: 298 virtual lldb::ExpressionResults 299 DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, 300 const EvaluateExpressionOptions &options, 301 lldb::UserExpressionSP &shared_ptr_to_me, 302 lldb::ExpressionVariableSP &result) = 0; 303 304 static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp, 305 ConstString &object_name, Status &err); 306 307 //------------------------------------------------------------------ 308 /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the 309 /// environment. 310 //------------------------------------------------------------------ 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 // liblldb_UserExpression_h_ 336