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 35 namespace 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 //---------------------------------------------------------------------- 47 class ClangUserExpression : public ClangExpression 48 { 49 public: 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 CanInterpret()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] options 130 /// Expression evaluation options. 131 /// 132 /// @param[in] shared_ptr_to_me 133 /// This is a shared pointer to this ClangUserExpression. This is 134 /// needed because Execute can push a thread plan that will hold onto 135 /// the ClangUserExpression for an unbounded period of time. So you 136 /// need to give the thread plan a reference to this object that can 137 /// keep it alive. 138 /// 139 /// @param[in] result 140 /// A pointer to direct at the persistent variable in which the 141 /// expression's result is stored. 142 /// 143 /// @return 144 /// A Process::Execution results value. 145 //------------------------------------------------------------------ 146 ExecutionResults 147 Execute (Stream &error_stream, 148 ExecutionContext &exe_ctx, 149 const EvaluateExpressionOptions& options, 150 ClangUserExpressionSP &shared_ptr_to_me, 151 lldb::ClangExpressionVariableSP &result); 152 153 //------------------------------------------------------------------ 154 /// Apply the side effects of the function to program state. 155 /// 156 /// @param[in] error_stream 157 /// A stream to print errors to. 158 /// 159 /// @param[in] exe_ctx 160 /// The execution context to use when looking up entities that 161 /// are needed for parsing (locations of variables, etc.) 162 /// 163 /// @param[in] result 164 /// A pointer to direct at the persistent variable in which the 165 /// expression's result is stored. 166 /// 167 /// @param[in] function_stack_pointer 168 /// A pointer to the base of the function's stack frame. This 169 /// is used to determine whether the expession result resides in 170 /// memory that will still be valid, or whether it needs to be 171 /// treated as homeless for the purpose of future expressions. 172 /// 173 /// @return 174 /// A Process::Execution results value. 175 //------------------------------------------------------------------ 176 bool 177 FinalizeJITExecution (Stream &error_stream, 178 ExecutionContext &exe_ctx, 179 lldb::ClangExpressionVariableSP &result, 180 lldb::addr_t function_stack_bottom = LLDB_INVALID_ADDRESS, 181 lldb::addr_t function_stack_top = LLDB_INVALID_ADDRESS); 182 183 //------------------------------------------------------------------ 184 /// Return the string that the parser should parse. Must be a full 185 /// translation unit. 186 //------------------------------------------------------------------ 187 const char * Text()188 Text () 189 { 190 return m_transformed_text.c_str(); 191 } 192 193 //------------------------------------------------------------------ 194 /// Return the string that the user typed. 195 //------------------------------------------------------------------ 196 const char * GetUserText()197 GetUserText () 198 { 199 return m_expr_text.c_str(); 200 } 201 202 //------------------------------------------------------------------ 203 /// Return the function name that should be used for executing the 204 /// expression. Text() should contain the definition of this 205 /// function. 206 //------------------------------------------------------------------ 207 const char * FunctionName()208 FunctionName () 209 { 210 return "$__lldb_expr"; 211 } 212 213 //------------------------------------------------------------------ 214 /// Return the language that should be used when parsing. To use 215 /// the default, return eLanguageTypeUnknown. 216 //------------------------------------------------------------------ 217 virtual lldb::LanguageType Language()218 Language () 219 { 220 return m_language; 221 } 222 223 //------------------------------------------------------------------ 224 /// Return the object that the parser should use when resolving external 225 /// values. May be NULL if everything should be self-contained. 226 //------------------------------------------------------------------ 227 ClangExpressionDeclMap * DeclMap()228 DeclMap () 229 { 230 return m_expr_decl_map.get(); 231 } 232 233 //------------------------------------------------------------------ 234 /// Return the object that the parser should allow to access ASTs. 235 /// May be NULL if the ASTs do not need to be transformed. 236 /// 237 /// @param[in] passthrough 238 /// The ASTConsumer that the returned transformer should send 239 /// the ASTs to after transformation. 240 //------------------------------------------------------------------ 241 clang::ASTConsumer * 242 ASTTransformer (clang::ASTConsumer *passthrough); 243 244 //------------------------------------------------------------------ 245 /// Return the desired result type of the function, or 246 /// eResultTypeAny if indifferent. 247 //------------------------------------------------------------------ 248 virtual ResultType DesiredResultType()249 DesiredResultType () 250 { 251 return m_desired_type; 252 } 253 254 //------------------------------------------------------------------ 255 /// Return true if validation code should be inserted into the 256 /// expression. 257 //------------------------------------------------------------------ 258 bool NeedsValidation()259 NeedsValidation () 260 { 261 return true; 262 } 263 264 //------------------------------------------------------------------ 265 /// Return true if external variables in the expression should be 266 /// resolved. 267 //------------------------------------------------------------------ 268 bool NeedsVariableResolution()269 NeedsVariableResolution () 270 { 271 return true; 272 } 273 274 //------------------------------------------------------------------ 275 /// Evaluate one expression and return its result. 276 /// 277 /// @param[in] exe_ctx 278 /// The execution context to use when evaluating the expression. 279 /// 280 /// @param[in] options 281 /// Expression evaluation options. 282 /// 283 /// @param[in] expr_cstr 284 /// A C string containing the expression to be evaluated. 285 /// 286 /// @param[in] expr_prefix 287 /// If non-NULL, a C string containing translation-unit level 288 /// definitions to be included when the expression is parsed. 289 /// 290 /// @param[in/out] result_valobj_sp 291 /// If execution is successful, the result valobj is placed here. 292 /// 293 /// @param[out] 294 /// Filled in with an error in case the expression evaluation 295 /// fails to parse, run, or evaluated. 296 /// 297 /// @result 298 /// A Process::ExecutionResults value. eExecutionCompleted for success. 299 //------------------------------------------------------------------ 300 static ExecutionResults 301 Evaluate (ExecutionContext &exe_ctx, 302 const EvaluateExpressionOptions& options, 303 const char *expr_cstr, 304 const char *expr_prefix, 305 lldb::ValueObjectSP &result_valobj_sp, 306 Error &error); 307 308 static const Error::ValueType kNoResult = 0x1001; ///< ValueObject::GetError() returns this if there is no result from the expression. 309 private: 310 //------------------------------------------------------------------ 311 /// Populate m_cplusplus and m_objetivec based on the environment. 312 //------------------------------------------------------------------ 313 314 void 315 ScanContext (ExecutionContext &exe_ctx, 316 lldb_private::Error &err); 317 318 bool 319 PrepareToExecuteJITExpression (Stream &error_stream, 320 ExecutionContext &exe_ctx, 321 lldb::addr_t &struct_address, 322 lldb::addr_t &object_ptr, 323 lldb::addr_t &cmd_ptr); 324 325 void 326 InstallContext (ExecutionContext &exe_ctx); 327 328 bool 329 LockAndCheckContext (ExecutionContext &exe_ctx, 330 lldb::TargetSP &target_sp, 331 lldb::ProcessSP &process_sp, 332 lldb::StackFrameSP &frame_sp); 333 334 lldb::ProcessWP m_process_wp; ///< The process used as the context for the expression. 335 Address m_address; ///< The address the process is stopped in. 336 lldb::addr_t m_stack_frame_bottom; ///< The bottom of the allocated stack frame. 337 lldb::addr_t m_stack_frame_top; ///< The top of the allocated stack frame. 338 339 std::string m_expr_text; ///< The text of the expression, as typed by the user 340 std::string m_expr_prefix; ///< The text of the translation-level definitions, as provided by the user 341 lldb::LanguageType m_language; ///< The language to use when parsing (eLanguageTypeUnknown means use defaults) 342 bool m_allow_cxx; ///< True if the language allows C++. 343 bool m_allow_objc; ///< True if the language allows Objective-C. 344 std::string m_transformed_text; ///< The text of the expression, as send to the parser 345 ResultType m_desired_type; ///< The type to coerce the expression's result to. If eResultTypeAny, inferred from the expression. 346 347 std::unique_ptr<ClangExpressionDeclMap> m_expr_decl_map; ///< The map to use when parsing the expression. 348 std::unique_ptr<IRExecutionUnit> m_execution_unit_ap; ///< The execution unit the expression is stored in. 349 std::unique_ptr<Materializer> m_materializer_ap; ///< The materializer to use when running the expression. 350 std::unique_ptr<ASTResultSynthesizer> m_result_synthesizer; ///< The result synthesizer, if one is needed. 351 352 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. 353 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). 354 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). 355 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). 356 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. 357 bool m_const_object; ///< True if "this" is const. 358 Target *m_target; ///< The target for storing persistent data like types and variables. 359 360 bool m_can_interpret; ///< True if the expression could be evaluated statically; false otherwise. 361 lldb::addr_t m_materialized_address; ///< The address at which the arguments to the expression have been materialized. 362 Materializer::DematerializerSP m_dematerializer_sp; ///< The dematerializer. 363 }; 364 365 } // namespace lldb_private 366 367 #endif // liblldb_ClangUserExpression_h_ 368