ClangUserExpression.h revision 102b2c2681c9a830afe25bfea35557421905e42c
1//===-- ClangUserExpression.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_ClangUserExpression_h_ 11#define liblldb_ClangUserExpression_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#include "lldb/Expression/ClangExpressionVariable.h" 27#include "lldb/Expression/IRForTarget.h" 28#include "lldb/Expression/Materializer.h" 29#include "lldb/Symbol/TaggedASTType.h" 30#include "lldb/Target/ExecutionContext.h" 31 32#include "llvm/ExecutionEngine/JITMemoryManager.h" 33 34namespace lldb_private 35{ 36 37//---------------------------------------------------------------------- 38/// @class ClangUserExpression ClangUserExpression.h "lldb/Expression/ClangUserExpression.h" 39/// @brief Encapsulates a single expression for use with Clang 40/// 41/// LLDB uses expressions for various purposes, notably to call functions 42/// and as a backend for the expr command. ClangUserExpression encapsulates 43/// the objects needed to parse and interpret or JIT an expression. It 44/// uses the Clang parser to produce LLVM IR from the expression. 45//---------------------------------------------------------------------- 46class ClangUserExpression : public ClangExpression 47{ 48public: 49 typedef std::shared_ptr<ClangUserExpression> ClangUserExpressionSP; 50 51 enum { kDefaultTimeout = 500000u }; 52 //------------------------------------------------------------------ 53 /// Constructor 54 /// 55 /// @param[in] expr 56 /// The expression to parse. 57 /// 58 /// @param[in] expr_prefix 59 /// If non-NULL, a C string containing translation-unit level 60 /// definitions to be included when the expression is parsed. 61 /// 62 /// @param[in] language 63 /// If not eLanguageTypeUnknown, a language to use when parsing 64 /// the expression. Currently restricted to those languages 65 /// supported by Clang. 66 /// 67 /// @param[in] desired_type 68 /// If not eResultTypeAny, the type to use for the expression 69 /// result. 70 //------------------------------------------------------------------ 71 ClangUserExpression (const char *expr, 72 const char *expr_prefix, 73 lldb::LanguageType language, 74 ResultType desired_type); 75 76 //------------------------------------------------------------------ 77 /// Destructor 78 //------------------------------------------------------------------ 79 virtual 80 ~ClangUserExpression (); 81 82 //------------------------------------------------------------------ 83 /// Parse the expression 84 /// 85 /// @param[in] error_stream 86 /// A stream to print parse errors and warnings to. 87 /// 88 /// @param[in] exe_ctx 89 /// The execution context to use when looking up entities that 90 /// are needed for parsing (locations of functions, types of 91 /// variables, persistent variables, etc.) 92 /// 93 /// @param[in] execution_policy 94 /// Determines whether interpretation is possible or mandatory. 95 /// 96 /// @param[in] keep_result_in_memory 97 /// True if the resulting persistent variable should reside in 98 /// target memory, if applicable. 99 /// 100 /// @return 101 /// True on success (no errors); false otherwise. 102 //------------------------------------------------------------------ 103 bool 104 Parse (Stream &error_stream, 105 ExecutionContext &exe_ctx, 106 lldb_private::ExecutionPolicy execution_policy, 107 bool keep_result_in_memory); 108 109 bool 110 CanInterpret () 111 { 112 return m_can_interpret; 113 } 114 115 //------------------------------------------------------------------ 116 /// Execute the parsed expression 117 /// 118 /// @param[in] error_stream 119 /// A stream to print errors to. 120 /// 121 /// @param[in] exe_ctx 122 /// The execution context to use when looking up entities that 123 /// are needed for parsing (locations of variables, etc.) 124 /// 125 /// @param[in] unwind_on_error 126 /// If true, and the execution stops before completion, we unwind the 127 /// function call, and return the program state to what it was before the 128 /// execution. If false, we leave the program in the stopped state. 129 /// 130 /// @param[in] ignore_breakpoints 131 /// If true, ignore breakpoints while executing the expression. 132 /// 133 /// @param[in] shared_ptr_to_me 134 /// This is a shared pointer to this ClangUserExpression. This is 135 /// needed because Execute can push a thread plan that will hold onto 136 /// the ClangUserExpression 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 /// @param[in] try_all_threads 145 /// If true, then we will try to run all threads if the function doesn't complete on 146 /// one thread. See timeout_usec for the interaction of this variable and 147 /// the timeout. 148 /// 149 /// @param[in] timeout_usec 150 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 151 /// will try on one thread for the lesser of .25 sec and half the total timeout. 152 /// then switch to running all threads, otherwise this will be the total timeout. 153 /// 154 /// 155 /// @return 156 /// A Process::Execution results value. 157 //------------------------------------------------------------------ 158 ExecutionResults 159 Execute (Stream &error_stream, 160 ExecutionContext &exe_ctx, 161 bool unwind_on_error, 162 bool ignore_breakpoints, 163 ClangUserExpressionSP &shared_ptr_to_me, 164 lldb::ClangExpressionVariableSP &result, 165 bool try_all_threads, 166 uint32_t timeout_usec); 167 168 ThreadPlan * 169 GetThreadPlanToExecuteJITExpression (Stream &error_stream, 170 ExecutionContext &exe_ctx); 171 172 //------------------------------------------------------------------ 173 /// Apply the side effects of the function to program state. 174 /// 175 /// @param[in] error_stream 176 /// A stream to print errors to. 177 /// 178 /// @param[in] exe_ctx 179 /// The execution context to use when looking up entities that 180 /// are needed for parsing (locations of variables, etc.) 181 /// 182 /// @param[in] result 183 /// A pointer to direct at the persistent variable in which the 184 /// expression's result is stored. 185 /// 186 /// @param[in] function_stack_pointer 187 /// A pointer to the base of the function's stack frame. This 188 /// is used to determine whether the expession result resides in 189 /// memory that will still be valid, or whether it needs to be 190 /// treated as homeless for the purpose of future expressions. 191 /// 192 /// @return 193 /// A Process::Execution results value. 194 //------------------------------------------------------------------ 195 bool 196 FinalizeJITExecution (Stream &error_stream, 197 ExecutionContext &exe_ctx, 198 lldb::ClangExpressionVariableSP &result, 199 lldb::addr_t function_stack_pointer = LLDB_INVALID_ADDRESS); 200 201 //------------------------------------------------------------------ 202 /// Return the string that the parser should parse. Must be a full 203 /// translation unit. 204 //------------------------------------------------------------------ 205 const char * 206 Text () 207 { 208 return m_transformed_text.c_str(); 209 } 210 211 //------------------------------------------------------------------ 212 /// Return the string that the user typed. 213 //------------------------------------------------------------------ 214 const char * 215 GetUserText () 216 { 217 return m_expr_text.c_str(); 218 } 219 220 //------------------------------------------------------------------ 221 /// Return the function name that should be used for executing the 222 /// expression. Text() should contain the definition of this 223 /// function. 224 //------------------------------------------------------------------ 225 const char * 226 FunctionName () 227 { 228 return "$__lldb_expr"; 229 } 230 231 //------------------------------------------------------------------ 232 /// Return the language that should be used when parsing. To use 233 /// the default, return eLanguageTypeUnknown. 234 //------------------------------------------------------------------ 235 virtual lldb::LanguageType 236 Language () 237 { 238 return m_language; 239 } 240 241 //------------------------------------------------------------------ 242 /// Return the object that the parser should use when resolving external 243 /// values. May be NULL if everything should be self-contained. 244 //------------------------------------------------------------------ 245 ClangExpressionDeclMap * 246 DeclMap () 247 { 248 return m_expr_decl_map.get(); 249 } 250 251 //------------------------------------------------------------------ 252 /// Return the object that the parser should allow to access ASTs. 253 /// May be NULL if the ASTs do not need to be transformed. 254 /// 255 /// @param[in] passthrough 256 /// The ASTConsumer that the returned transformer should send 257 /// the ASTs to after transformation. 258 //------------------------------------------------------------------ 259 clang::ASTConsumer * 260 ASTTransformer (clang::ASTConsumer *passthrough); 261 262 //------------------------------------------------------------------ 263 /// Return the desired result type of the function, or 264 /// eResultTypeAny if indifferent. 265 //------------------------------------------------------------------ 266 virtual ResultType 267 DesiredResultType () 268 { 269 return m_desired_type; 270 } 271 272 //------------------------------------------------------------------ 273 /// Return true if validation code should be inserted into the 274 /// expression. 275 //------------------------------------------------------------------ 276 bool 277 NeedsValidation () 278 { 279 return true; 280 } 281 282 //------------------------------------------------------------------ 283 /// Return true if external variables in the expression should be 284 /// resolved. 285 //------------------------------------------------------------------ 286 bool 287 NeedsVariableResolution () 288 { 289 return true; 290 } 291 292 //------------------------------------------------------------------ 293 /// Evaluate one expression and return its result. 294 /// 295 /// @param[in] exe_ctx 296 /// The execution context to use when evaluating the expression. 297 /// 298 /// @param[in] execution_policy 299 /// Determines whether or not to try using the IR interpreter to 300 /// avoid running the expression on the parser. 301 /// 302 /// @param[in] language 303 /// If not eLanguageTypeUnknown, a language to use when parsing 304 /// the expression. Currently restricted to those languages 305 /// supported by Clang. 306 /// 307 /// @param[in] unwind_on_error 308 /// True if the thread's state should be restored in the case 309 /// of an error. 310 /// 311 /// @param[in] ignore_breakpoints 312 /// If true, ignore breakpoints while executing the expression. 313 /// 314 /// @param[in] result_type 315 /// If not eResultTypeAny, the type of the desired result. Will 316 /// result in parse errors if impossible. 317 /// 318 /// @param[in] expr_cstr 319 /// A C string containing the expression to be evaluated. 320 /// 321 /// @param[in] expr_prefix 322 /// If non-NULL, a C string containing translation-unit level 323 /// definitions to be included when the expression is parsed. 324 /// 325 /// @param[in/out] result_valobj_sp 326 /// If execution is successful, the result valobj is placed here. 327 /// 328 /// @param[in] try_all_threads 329 /// If true, then we will try to run all threads if the function doesn't complete on 330 /// one thread. See timeout_usec for the interaction of this variable and 331 /// the timeout. 332 /// 333 /// @param[in] timeout_usec 334 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 335 /// will try on one thread for the lesser of .25 sec and half the total timeout. 336 /// then switch to running all threads, otherwise this will be the total timeout. 337 /// 338 /// @result 339 /// A Process::ExecutionResults value. eExecutionCompleted for success. 340 //------------------------------------------------------------------ 341 static ExecutionResults 342 Evaluate (ExecutionContext &exe_ctx, 343 lldb_private::ExecutionPolicy execution_policy, 344 lldb::LanguageType language, 345 ResultType desired_type, 346 bool unwind_on_error, 347 bool ignore_breakpoints, 348 const char *expr_cstr, 349 const char *expr_prefix, 350 lldb::ValueObjectSP &result_valobj_sp, 351 bool try_all_threads, 352 uint32_t timeout_usec); 353 354 static ExecutionResults 355 EvaluateWithError (ExecutionContext &exe_ctx, 356 lldb_private::ExecutionPolicy execution_policy, 357 lldb::LanguageType language, 358 ResultType desired_type, 359 bool unwind_on_error, 360 bool ignore_breakpoints, 361 const char *expr_cstr, 362 const char *expr_prefix, 363 lldb::ValueObjectSP &result_valobj_sp, 364 Error &error, 365 bool try_all_threads, 366 uint32_t timeout_usec); 367 368 static const Error::ValueType kNoResult = 0x1001; ///< ValueObject::GetError() returns this if there is no result from the expression. 369private: 370 //------------------------------------------------------------------ 371 /// Populate m_cplusplus and m_objetivec based on the environment. 372 //------------------------------------------------------------------ 373 374 void 375 ScanContext (ExecutionContext &exe_ctx, 376 lldb_private::Error &err); 377 378 bool 379 PrepareToExecuteJITExpression (Stream &error_stream, 380 ExecutionContext &exe_ctx, 381 lldb::addr_t &struct_address, 382 lldb::addr_t &object_ptr, 383 lldb::addr_t &cmd_ptr); 384 385 void 386 InstallContext (ExecutionContext &exe_ctx) 387 { 388 m_process_wp = exe_ctx.GetProcessSP(); 389 m_target_wp = exe_ctx.GetTargetSP(); 390 m_frame_wp = exe_ctx.GetFrameSP(); 391 } 392 393 bool 394 LockAndCheckContext (ExecutionContext &exe_ctx, 395 lldb::TargetSP &target_sp, 396 lldb::ProcessSP &process_sp, 397 lldb::StackFrameSP &frame_sp) 398 { 399 target_sp = m_target_wp.lock(); 400 process_sp = m_process_wp.lock(); 401 frame_sp = m_frame_wp.lock(); 402 403 if ((target_sp && target_sp.get() != exe_ctx.GetTargetPtr()) || 404 (process_sp && process_sp.get() != exe_ctx.GetProcessPtr()) || 405 (frame_sp && frame_sp.get() != exe_ctx.GetFramePtr())) 406 return false; 407 408 return true; 409 } 410 411 lldb::TargetWP m_target_wp; ///< The target used as the context for the expression. 412 lldb::ProcessWP m_process_wp; ///< The process used as the context for the expression. 413 lldb::StackFrameWP m_frame_wp; ///< The stack frame used as context for the expression. 414 415 std::string m_expr_text; ///< The text of the expression, as typed by the user 416 std::string m_expr_prefix; ///< The text of the translation-level definitions, as provided by the user 417 lldb::LanguageType m_language; ///< The language to use when parsing (eLanguageTypeUnknown means use defaults) 418 bool m_allow_cxx; ///< True if the language allows C++. 419 bool m_allow_objc; ///< True if the language allows Objective-C. 420 std::string m_transformed_text; ///< The text of the expression, as send to the parser 421 ResultType m_desired_type; ///< The type to coerce the expression's result to. If eResultTypeAny, inferred from the expression. 422 423 std::unique_ptr<ClangExpressionDeclMap> m_expr_decl_map; ///< The map to use when parsing the expression. 424 std::unique_ptr<IRExecutionUnit> m_execution_unit_ap; ///< The execution unit the expression is stored in. 425 std::unique_ptr<Materializer> m_materializer_ap; ///< The materializer to use when running the expression. 426 std::unique_ptr<ASTResultSynthesizer> m_result_synthesizer; ///< The result synthesizer, if one is needed. 427 428 bool m_enforce_valid_object; ///< True if the expression parser should enforce the presence of a valid class pointer in order to generate the expression as a method. 429 bool m_cplusplus; ///< True if the expression is compiled as a C++ member function (true if it was parsed when exe_ctx was in a C++ method). 430 bool m_objectivec; ///< True if the expression is compiled as an Objective-C method (true if it was parsed when exe_ctx was in an Objective-C method). 431 bool m_static_method; ///< True if the expression is compiled as a static (or class) method (currently true if it was parsed when exe_ctx was in an Objective-C class method). 432 bool m_needs_object_ptr; ///< True if "this" or "self" must be looked up and passed in. False if the expression doesn't really use them and they can be NULL. 433 bool m_const_object; ///< True if "this" is const. 434 Target *m_target; ///< The target for storing persistent data like types and variables. 435 436 bool m_can_interpret; ///< True if the expression could be evaluated statically; false otherwise. 437 lldb::addr_t m_materialized_address; ///< The address at which the arguments to the expression have been materialized. 438 Materializer::DematerializerSP m_dematerializer_sp; ///< The dematerializer. 439}; 440 441} // namespace lldb_private 442 443#endif // liblldb_ClangUserExpression_h_ 444