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