1249259Sdim//===-- ClangFunction.h -----------------------------------------*- C++ -*-===// 2249259Sdim// 3249259Sdim// The LLVM Compiler Infrastructure 4249259Sdim// 5249259Sdim// This file is distributed under the University of Illinois Open Source 6249259Sdim// License. See LICENSE.TXT for details. 7249259Sdim// 8249259Sdim//===----------------------------------------------------------------------===// 9249259Sdim 10249259Sdim#ifndef lldb_ClangFunction_h_ 11249259Sdim#define lldb_ClangFunction_h_ 12249259Sdim 13249259Sdim// C Includes 14249259Sdim// C++ Includes 15249259Sdim#include <vector> 16249259Sdim#include <list> 17249259Sdim// Other libraries and framework includes 18249259Sdim// Project includes 19249259Sdim#include "lldb/Core/ClangForward.h" 20249259Sdim#include "lldb/Core/Address.h" 21249259Sdim#include "lldb/Core/ArchSpec.h" 22249259Sdim#include "lldb/Core/Value.h" 23249259Sdim#include "lldb/Core/ValueObjectList.h" 24249259Sdim#include "lldb/Expression/ClangExpression.h" 25249259Sdim#include "lldb/Target/Process.h" 26249259Sdim 27249259Sdimnamespace lldb_private 28249259Sdim{ 29249259Sdim 30249259Sdimclass ASTStructExtractor; 31249259Sdimclass ClangExpressionParser; 32249259Sdim 33249259Sdim//---------------------------------------------------------------------- 34249259Sdim/// @class ClangFunction ClangFunction.h "lldb/Expression/ClangFunction.h" 35249259Sdim/// @brief Encapsulates a function that can be called. 36249259Sdim/// 37249259Sdim/// A given ClangFunction object can handle a single function signature. 38249259Sdim/// Once constructed, it can set up any number of concurrent calls to 39249259Sdim/// functions with that signature. 40249259Sdim/// 41249259Sdim/// It performs the call by synthesizing a structure that contains the pointer 42249259Sdim/// to the function and the arguments that should be passed to that function, 43249259Sdim/// and producing a special-purpose JIT-compiled function that accepts a void* 44249259Sdim/// pointing to this struct as its only argument and calls the function in the 45249259Sdim/// struct with the written arguments. This method lets Clang handle the 46249259Sdim/// vagaries of function calling conventions. 47249259Sdim/// 48249259Sdim/// The simplest use of the ClangFunction is to construct it with a 49249259Sdim/// function representative of the signature you want to use, then call 50249259Sdim/// ExecuteFunction(ExecutionContext &, Stream &, Value &). 51249259Sdim/// 52249259Sdim/// If you need to reuse the arguments for several calls, you can call 53249259Sdim/// InsertFunction() followed by WriteFunctionArguments(), which will return 54249259Sdim/// the location of the args struct for the wrapper function in args_addr_ref. 55249259Sdim/// 56249259Sdim/// If you need to call the function on the thread plan stack, you can also 57249259Sdim/// call InsertFunction() followed by GetThreadPlanToCallFunction(). 58249259Sdim/// 59249259Sdim/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed 60249259Sdim/// a pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated 61249259Sdim/// and its address returned in that variable. 62249259Sdim/// 63249259Sdim/// Any of the methods that take arg_addr_ptr can be passed NULL, and the 64249259Sdim/// argument space will be managed for you. 65249259Sdim//---------------------------------------------------------------------- 66249259Sdimclass ClangFunction : public ClangExpression 67249259Sdim{ 68249259Sdim friend class ASTStructExtractor; 69249259Sdimpublic: 70249259Sdim //------------------------------------------------------------------ 71249259Sdim /// Constructor 72249259Sdim /// 73249259Sdim /// @param[in] exe_scope 74249259Sdim /// An execution context scope that gets us at least a target and 75249259Sdim /// process. 76249259Sdim /// 77249259Sdim /// @param[in] function_ptr 78249259Sdim /// The default function to be called. Can be overridden using 79249259Sdim /// WriteFunctionArguments(). 80249259Sdim /// 81249259Sdim /// @param[in] ast_context 82249259Sdim /// The AST context to evaluate argument types in. 83249259Sdim /// 84249259Sdim /// @param[in] arg_value_list 85249259Sdim /// The default values to use when calling this function. Can 86249259Sdim /// be overridden using WriteFunctionArguments(). 87249259Sdim //------------------------------------------------------------------ 88249259Sdim ClangFunction (ExecutionContextScope &exe_scope, 89249259Sdim Function &function_ptr, 90249259Sdim ClangASTContext *ast_context, 91249259Sdim const ValueList &arg_value_list); 92249259Sdim 93249259Sdim //------------------------------------------------------------------ 94249259Sdim /// Constructor 95249259Sdim /// 96249259Sdim /// @param[in] exe_scope 97249259Sdim /// An execution context scope that gets us at least a target and 98249259Sdim /// process. 99249259Sdim /// 100249259Sdim /// @param[in] ast_context 101249259Sdim /// The AST context to evaluate argument types in. 102249259Sdim /// 103249259Sdim /// @param[in] return_qualtype 104249259Sdim /// An opaque Clang QualType for the function result. Should be 105249259Sdim /// defined in ast_context. 106249259Sdim /// 107249259Sdim /// @param[in] function_address 108249259Sdim /// The address of the function to call. 109249259Sdim /// 110249259Sdim /// @param[in] arg_value_list 111249259Sdim /// The default values to use when calling this function. Can 112249259Sdim /// be overridden using WriteFunctionArguments(). 113249259Sdim //------------------------------------------------------------------ 114249259Sdim ClangFunction (ExecutionContextScope &exe_scope, 115249259Sdim const ClangASTType &return_type, 116249259Sdim const Address& function_address, 117249259Sdim const ValueList &arg_value_list); 118249259Sdim 119249259Sdim //------------------------------------------------------------------ 120249259Sdim /// Destructor 121249259Sdim //------------------------------------------------------------------ 122249259Sdim virtual 123249259Sdim ~ClangFunction(); 124249259Sdim 125249259Sdim //------------------------------------------------------------------ 126249259Sdim /// Compile the wrapper function 127249259Sdim /// 128249259Sdim /// @param[in] errors 129249259Sdim /// The stream to print parser errors to. 130249259Sdim /// 131249259Sdim /// @return 132249259Sdim /// The number of errors. 133249259Sdim //------------------------------------------------------------------ 134249259Sdim unsigned 135249259Sdim CompileFunction (Stream &errors); 136249259Sdim 137249259Sdim //------------------------------------------------------------------ 138249259Sdim /// Insert the default function wrapper and its default argument struct 139249259Sdim /// 140249259Sdim /// @param[in] exe_ctx 141249259Sdim /// The execution context to insert the function and its arguments 142249259Sdim /// into. 143249259Sdim /// 144249259Sdim /// @param[in,out] args_addr_ref 145249259Sdim /// The address of the structure to write the arguments into. May 146249259Sdim /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 147249259Sdim /// and args_addr_ref is pointed to it. 148249259Sdim /// 149249259Sdim /// @param[in] errors 150249259Sdim /// The stream to write errors to. 151249259Sdim /// 152249259Sdim /// @return 153249259Sdim /// True on success; false otherwise. 154249259Sdim //------------------------------------------------------------------ 155249259Sdim bool 156249259Sdim InsertFunction (ExecutionContext &exe_ctx, 157249259Sdim lldb::addr_t &args_addr_ref, 158249259Sdim Stream &errors); 159249259Sdim 160249259Sdim //------------------------------------------------------------------ 161249259Sdim /// Insert the default function wrapper (using the JIT) 162249259Sdim /// 163249259Sdim /// @param[in] exe_ctx 164249259Sdim /// The execution context to insert the function and its arguments 165249259Sdim /// into. 166249259Sdim /// 167249259Sdim /// @param[in] errors 168249259Sdim /// The stream to write errors to. 169249259Sdim /// 170249259Sdim /// @return 171249259Sdim /// True on success; false otherwise. 172249259Sdim //------------------------------------------------------------------ 173249259Sdim bool WriteFunctionWrapper (ExecutionContext &exe_ctx, 174249259Sdim Stream &errors); 175249259Sdim 176249259Sdim //------------------------------------------------------------------ 177249259Sdim /// Insert the default function argument struct 178249259Sdim /// 179249259Sdim /// @param[in] exe_ctx 180249259Sdim /// The execution context to insert the function and its arguments 181249259Sdim /// into. 182249259Sdim /// 183249259Sdim /// @param[in,out] args_addr_ref 184249259Sdim /// The address of the structure to write the arguments into. May 185249259Sdim /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 186249259Sdim /// and args_addr_ref is pointed to it. 187249259Sdim /// 188249259Sdim /// @param[in] errors 189249259Sdim /// The stream to write errors to. 190249259Sdim /// 191249259Sdim /// @return 192249259Sdim /// True on success; false otherwise. 193249259Sdim //------------------------------------------------------------------ 194249259Sdim bool WriteFunctionArguments (ExecutionContext &exe_ctx, 195249259Sdim lldb::addr_t &args_addr_ref, 196249259Sdim Stream &errors); 197249259Sdim 198249259Sdim //------------------------------------------------------------------ 199249259Sdim /// Insert an argument struct with a non-default function address and 200249259Sdim /// non-default argument values 201249259Sdim /// 202249259Sdim /// @param[in] exe_ctx 203249259Sdim /// The execution context to insert the function and its arguments 204249259Sdim /// into. 205249259Sdim /// 206249259Sdim /// @param[in,out] args_addr_ref 207249259Sdim /// The address of the structure to write the arguments into. May 208249259Sdim /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 209249259Sdim /// and args_addr_ref is pointed to it. 210249259Sdim /// 211249259Sdim /// @param[in] function_address 212249259Sdim /// The address of the function to call. 213249259Sdim /// 214249259Sdim /// @param[in] arg_values 215249259Sdim /// The values of the function's arguments. 216249259Sdim /// 217249259Sdim /// @param[in] errors 218249259Sdim /// The stream to write errors to. 219249259Sdim /// 220249259Sdim /// @return 221249259Sdim /// True on success; false otherwise. 222249259Sdim //------------------------------------------------------------------ 223249259Sdim bool WriteFunctionArguments (ExecutionContext &exe_ctx, 224249259Sdim lldb::addr_t &args_addr_ref, 225249259Sdim Address function_address, 226249259Sdim ValueList &arg_values, 227249259Sdim Stream &errors); 228249259Sdim 229249259Sdim //------------------------------------------------------------------ 230249259Sdim /// Run the function this ClangFunction was created with. 231249259Sdim /// 232249259Sdim /// This is the full version. 233249259Sdim /// 234249259Sdim /// @param[in] exe_ctx 235249259Sdim /// The thread & process in which this function will run. 236249259Sdim /// 237249259Sdim /// @param[in] args_addr_ptr 238249259Sdim /// If NULL, the function will take care of allocating & deallocating the wrapper 239249259Sdim /// args structure. Otherwise, if set to LLDB_INVALID_ADDRESS, a new structure 240249259Sdim /// will be allocated, filled and the address returned to you. You are responsible 241249259Sdim /// for deallocating it. And if passed in with a value other than LLDB_INVALID_ADDRESS, 242249259Sdim /// this should point to an already allocated structure with the values already written. 243249259Sdim /// 244249259Sdim /// @param[in] errors 245249259Sdim /// Errors will be written here if there are any. 246249259Sdim /// 247249259Sdim /// @param[in] options 248249259Sdim /// The options for this expression execution. 249249259Sdim /// 250249259Sdim /// @param[out] results 251249259Sdim /// The result value will be put here after running the function. 252249259Sdim /// 253249259Sdim /// @return 254249259Sdim /// Returns one of the ExecutionResults enum indicating function call status. 255249259Sdim //------------------------------------------------------------------ 256249259Sdim ExecutionResults 257249259Sdim ExecuteFunction(ExecutionContext &exe_ctx, 258249259Sdim lldb::addr_t *args_addr_ptr, 259249259Sdim const EvaluateExpressionOptions &options, 260249259Sdim Stream &errors, 261249259Sdim Value &results); 262249259Sdim 263249259Sdim //------------------------------------------------------------------ 264249259Sdim /// Get a thread plan to run the function this ClangFunction was created with. 265249259Sdim /// 266249259Sdim /// @param[in] exe_ctx 267249259Sdim /// The execution context to insert the function and its arguments 268249259Sdim /// into. 269249259Sdim /// 270249259Sdim /// @param[in] func_addr 271249259Sdim /// The address of the function in the target process. 272249259Sdim /// 273249259Sdim /// @param[in] args_addr 274249259Sdim /// The address of the argument struct. 275249259Sdim /// 276249259Sdim /// @param[in] errors 277249259Sdim /// The stream to write errors to. 278249259Sdim /// 279249259Sdim /// @param[in] stop_others 280249259Sdim /// True if other threads should pause during execution. 281249259Sdim /// 282249259Sdim /// @param[in] unwind_on_error 283249259Sdim /// True if the thread plan may simply be discarded if an error occurs. 284249259Sdim /// 285249259Sdim /// @return 286249259Sdim /// A ThreadPlan for executing the function. 287249259Sdim //------------------------------------------------------------------ 288249259Sdim ThreadPlan * 289249259Sdim GetThreadPlanToCallFunction (ExecutionContext &exe_ctx, 290249259Sdim lldb::addr_t args_addr, 291249259Sdim const EvaluateExpressionOptions &options, 292249259Sdim Stream &errors); 293249259Sdim 294249259Sdim //------------------------------------------------------------------ 295249259Sdim /// Get the result of the function from its struct 296249259Sdim /// 297249259Sdim /// @param[in] exe_ctx 298249259Sdim /// The execution context to retrieve the result from. 299249259Sdim /// 300249259Sdim /// @param[in] args_addr 301249259Sdim /// The address of the argument struct. 302249259Sdim /// 303249259Sdim /// @param[out] ret_value 304249259Sdim /// The value returned by the function. 305249259Sdim /// 306249259Sdim /// @return 307249259Sdim /// True on success; false otherwise. 308249259Sdim //------------------------------------------------------------------ 309249259Sdim bool FetchFunctionResults (ExecutionContext &exe_ctx, 310249259Sdim lldb::addr_t args_addr, 311249259Sdim Value &ret_value); 312249259Sdim 313249259Sdim //------------------------------------------------------------------ 314249259Sdim /// Deallocate the arguments structure 315249259Sdim /// 316249259Sdim /// @param[in] exe_ctx 317249259Sdim /// The execution context to insert the function and its arguments 318249259Sdim /// into. 319249259Sdim /// 320249259Sdim /// @param[in] args_addr 321249259Sdim /// The address of the argument struct. 322249259Sdim //------------------------------------------------------------------ 323249259Sdim void DeallocateFunctionResults (ExecutionContext &exe_ctx, 324249259Sdim lldb::addr_t args_addr); 325249259Sdim 326249259Sdim //------------------------------------------------------------------ 327249259Sdim /// Interface for ClangExpression 328249259Sdim //------------------------------------------------------------------ 329249259Sdim 330249259Sdim //------------------------------------------------------------------ 331249259Sdim /// Return the string that the parser should parse. Must be a full 332249259Sdim /// translation unit. 333249259Sdim //------------------------------------------------------------------ 334249259Sdim const char * 335249259Sdim Text () 336249259Sdim { 337249259Sdim return m_wrapper_function_text.c_str(); 338249259Sdim } 339249259Sdim 340249259Sdim //------------------------------------------------------------------ 341249259Sdim /// Return the function name that should be used for executing the 342249259Sdim /// expression. Text() should contain the definition of this 343249259Sdim /// function. 344249259Sdim //------------------------------------------------------------------ 345249259Sdim const char * 346249259Sdim FunctionName () 347249259Sdim { 348249259Sdim return m_wrapper_function_name.c_str(); 349249259Sdim } 350249259Sdim 351249259Sdim //------------------------------------------------------------------ 352249259Sdim /// Return the object that the parser should use when resolving external 353249259Sdim /// values. May be NULL if everything should be self-contained. 354249259Sdim //------------------------------------------------------------------ 355249259Sdim ClangExpressionDeclMap * 356249259Sdim DeclMap () 357249259Sdim { 358249259Sdim return NULL; 359249259Sdim } 360249259Sdim 361249259Sdim //------------------------------------------------------------------ 362249259Sdim /// Return the object that the parser should use when registering 363249259Sdim /// local variables. May be NULL if the Expression doesn't care. 364249259Sdim //------------------------------------------------------------------ 365249259Sdim ClangExpressionVariableList * 366249259Sdim LocalVariables () 367249259Sdim { 368249259Sdim return NULL; 369249259Sdim } 370249259Sdim 371263508Sdim //------------------------------------------------------------------ 372263508Sdim /// Return the object that the parser should allow to access ASTs. 373263508Sdim /// May be NULL if the ASTs do not need to be transformed. 374263508Sdim /// 375263508Sdim /// @param[in] passthrough 376263508Sdim /// The ASTConsumer that the returned transformer should send 377263508Sdim /// the ASTs to after transformation. 378263508Sdim //------------------------------------------------------------------ 379249259Sdim clang::ASTConsumer * 380249259Sdim ASTTransformer (clang::ASTConsumer *passthrough); 381249259Sdim 382249259Sdim //------------------------------------------------------------------ 383249259Sdim /// Return true if validation code should be inserted into the 384249259Sdim /// expression. 385249259Sdim //------------------------------------------------------------------ 386249259Sdim bool 387249259Sdim NeedsValidation () 388249259Sdim { 389249259Sdim return false; 390249259Sdim } 391249259Sdim 392249259Sdim //------------------------------------------------------------------ 393249259Sdim /// Return true if external variables in the expression should be 394249259Sdim /// resolved. 395249259Sdim //------------------------------------------------------------------ 396249259Sdim bool 397249259Sdim NeedsVariableResolution () 398249259Sdim { 399249259Sdim return false; 400249259Sdim } 401249259Sdim 402249259Sdim ValueList 403249259Sdim GetArgumentValues () const 404249259Sdim { 405249259Sdim return m_arg_values; 406249259Sdim } 407249259Sdimprivate: 408249259Sdim //------------------------------------------------------------------ 409249259Sdim // For ClangFunction only 410249259Sdim //------------------------------------------------------------------ 411249259Sdim 412249259Sdim std::unique_ptr<ClangExpressionParser> m_parser; ///< The parser responsible for compiling the function. 413249259Sdim std::unique_ptr<IRExecutionUnit> m_execution_unit_ap; 414249259Sdim 415249259Sdim Function *m_function_ptr; ///< The function we're going to call. May be NULL if we don't have debug info for the function. 416249259Sdim Address m_function_addr; ///< If we don't have the FunctionSP, we at least need the address & return type. 417263508Sdim ClangASTType m_function_return_type; ///< The opaque clang qual type for the function return type. 418263508Sdim 419263508Sdim std::string m_wrapper_function_name; ///< The name of the wrapper function. 420263508Sdim std::string m_wrapper_function_text; ///< The contents of the wrapper function. 421263508Sdim std::string m_wrapper_struct_name; ///< The name of the struct that contains the target function address, arguments, and result. 422263508Sdim std::list<lldb::addr_t> m_wrapper_args_addrs; ///< The addresses of the arguments to the wrapper function. 423263508Sdim 424263508Sdim std::unique_ptr<ASTStructExtractor> m_struct_extractor; ///< The class that generates the argument struct below. 425263508Sdim 426263508Sdim bool m_struct_valid; ///< True if the ASTStructExtractor has populated the variables below. 427263508Sdim 428263508Sdim //------------------------------------------------------------------ 429263508Sdim /// These values are populated by the ASTStructExtractor 430263508Sdim size_t m_struct_size; ///< The size of the argument struct, in bytes. 431263508Sdim std::vector<uint64_t> m_member_offsets; ///< The offset of each member in the struct, in bytes. 432263508Sdim uint64_t m_return_size; ///< The size of the result variable, in bytes. 433263508Sdim uint64_t m_return_offset; ///< The offset of the result variable in the struct, in bytes. 434263508Sdim //------------------------------------------------------------------ 435263508Sdim 436263508Sdim ValueList m_arg_values; ///< The default values of the arguments. 437263508Sdim 438263508Sdim bool m_compiled; ///< True if the wrapper function has already been parsed. 439263508Sdim bool m_JITted; ///< True if the wrapper function has already been JIT-compiled. 440263508Sdim}; 441263508Sdim 442263508Sdim} // Namespace lldb_private 443263508Sdim 444263508Sdim#endif // lldb_ClangFunction_h_ 445263508Sdim