1 //===-- ClangFunctionCaller.h -----------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef liblldb_ClangFunctionCaller_h_ 10 #define liblldb_ClangFunctionCaller_h_ 11 12 #include "ClangExpressionHelper.h" 13 14 #include "lldb/Core/Address.h" 15 #include "lldb/Core/ClangForward.h" 16 #include "lldb/Core/Value.h" 17 #include "lldb/Core/ValueObjectList.h" 18 #include "lldb/Expression/FunctionCaller.h" 19 #include "lldb/Symbol/CompilerType.h" 20 #include "lldb/Target/Process.h" 21 22 namespace lldb_private { 23 24 class ASTStructExtractor; 25 class ClangExpressionParser; 26 27 /// \class ClangFunctionCaller ClangFunctionCaller.h 28 /// "lldb/Expression/ClangFunctionCaller.h" Encapsulates a function that can 29 /// be called. 30 /// 31 /// A given ClangFunctionCaller object can handle a single function signature. 32 /// Once constructed, it can set up any number of concurrent calls to 33 /// functions with that signature. 34 /// 35 /// It performs the call by synthesizing a structure that contains the pointer 36 /// to the function and the arguments that should be passed to that function, 37 /// and producing a special-purpose JIT-compiled function that accepts a void* 38 /// pointing to this struct as its only argument and calls the function in the 39 /// struct with the written arguments. This method lets Clang handle the 40 /// vagaries of function calling conventions. 41 /// 42 /// The simplest use of the ClangFunctionCaller is to construct it with a 43 /// function representative of the signature you want to use, then call 44 /// ExecuteFunction(ExecutionContext &, Stream &, Value &). 45 /// 46 /// If you need to reuse the arguments for several calls, you can call 47 /// InsertFunction() followed by WriteFunctionArguments(), which will return 48 /// the location of the args struct for the wrapper function in args_addr_ref. 49 /// 50 /// If you need to call the function on the thread plan stack, you can also 51 /// call InsertFunction() followed by GetThreadPlanToCallFunction(). 52 /// 53 /// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a 54 /// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated 55 /// and its address returned in that variable. 56 /// 57 /// Any of the methods that take arg_addr_ptr can be passed NULL, and the 58 /// argument space will be managed for you. 59 class ClangFunctionCaller : public FunctionCaller { 60 friend class ASTStructExtractor; 61 62 /// LLVM-style RTTI support. 63 static bool classof(const Expression *E) { 64 return E->getKind() == eKindClangFunctionCaller; 65 } 66 67 class ClangFunctionCallerHelper : public ClangExpressionHelper { 68 public: 69 ClangFunctionCallerHelper(ClangFunctionCaller &owner) : m_owner(owner) {} 70 71 ~ClangFunctionCallerHelper() override = default; 72 73 /// Return the object that the parser should use when resolving external 74 /// values. May be NULL if everything should be self-contained. 75 ClangExpressionDeclMap *DeclMap() override { return nullptr; } 76 77 /// Return the object that the parser should allow to access ASTs. May be 78 /// NULL if the ASTs do not need to be transformed. 79 /// 80 /// \param[in] passthrough 81 /// The ASTConsumer that the returned transformer should send 82 /// the ASTs to after transformation. 83 clang::ASTConsumer * 84 ASTTransformer(clang::ASTConsumer *passthrough) override; 85 86 private: 87 ClangFunctionCaller &m_owner; 88 std::unique_ptr<ASTStructExtractor> m_struct_extractor; ///< The class that 89 ///generates the 90 ///argument struct 91 ///layout. 92 }; 93 94 public: 95 /// Constructor 96 /// 97 /// \param[in] exe_scope 98 /// An execution context scope that gets us at least a target and 99 /// process. 100 /// 101 /// \param[in] ast_context 102 /// The AST context to evaluate argument types in. 103 /// 104 /// \param[in] return_qualtype 105 /// An opaque Clang QualType for the function result. Should be 106 /// defined in ast_context. 107 /// 108 /// \param[in] function_address 109 /// The address of the function to call. 110 /// 111 /// \param[in] arg_value_list 112 /// The default values to use when calling this function. Can 113 /// be overridden using WriteFunctionArguments(). 114 ClangFunctionCaller(ExecutionContextScope &exe_scope, 115 const CompilerType &return_type, 116 const Address &function_address, 117 const ValueList &arg_value_list, const char *name); 118 119 ~ClangFunctionCaller() override; 120 121 /// Compile the wrapper function 122 /// 123 /// \param[in] thread_to_use_sp 124 /// Compilation might end up calling functions. Pass in the thread you 125 /// want the compilation to use. If you pass in an empty ThreadSP it will 126 /// use the currently selected thread. 127 /// 128 /// \param[in] diagnostic_manager 129 /// The diagnostic manager to report parser errors to. 130 /// 131 /// \return 132 /// The number of errors. 133 unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp, 134 DiagnosticManager &diagnostic_manager) override; 135 136 ExpressionTypeSystemHelper *GetTypeSystemHelper() override { 137 return &m_type_system_helper; 138 } 139 140 protected: 141 const char *GetWrapperStructName() { return m_wrapper_struct_name.c_str(); } 142 143 private: 144 // For ClangFunctionCaller only 145 146 // Note: the parser needs to be destructed before the execution unit, so 147 // declare the execution unit first. 148 ClangFunctionCallerHelper m_type_system_helper; 149 }; 150 151 } // namespace lldb_private 152 153 #endif // liblldb_ClangFunctionCaller_h_ 154