1061da546Spatrick //===-- FunctionCaller.h ----------------------------------------*- C++ -*-===// 2061da546Spatrick // 3061da546Spatrick // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4061da546Spatrick // See https://llvm.org/LICENSE.txt for license information. 5061da546Spatrick // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6061da546Spatrick // 7061da546Spatrick //===----------------------------------------------------------------------===// 8061da546Spatrick 9*dda28197Spatrick #ifndef LLDB_EXPRESSION_FUNCTIONCALLER_H 10*dda28197Spatrick #define LLDB_EXPRESSION_FUNCTIONCALLER_H 11061da546Spatrick 12061da546Spatrick #include <list> 13061da546Spatrick #include <memory> 14061da546Spatrick #include <string> 15061da546Spatrick #include <vector> 16061da546Spatrick 17061da546Spatrick #include "lldb/Core/Address.h" 18061da546Spatrick #include "lldb/Core/Value.h" 19061da546Spatrick #include "lldb/Expression/Expression.h" 20061da546Spatrick #include "lldb/Expression/ExpressionParser.h" 21061da546Spatrick #include "lldb/Symbol/CompilerType.h" 22061da546Spatrick 23061da546Spatrick namespace lldb_private { 24061da546Spatrick 25061da546Spatrick /// \class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h" 26061da546Spatrick /// Encapsulates a function that can be called. 27061da546Spatrick /// 28061da546Spatrick /// A given FunctionCaller object can handle a single function signature. 29061da546Spatrick /// Once constructed, it can set up any number of concurrent calls to 30061da546Spatrick /// functions with that signature. 31061da546Spatrick /// 32061da546Spatrick /// It performs the call by synthesizing a structure that contains the pointer 33061da546Spatrick /// to the function and the arguments that should be passed to that function, 34061da546Spatrick /// and producing a special-purpose JIT-compiled function that accepts a void* 35061da546Spatrick /// pointing to this struct as its only argument and calls the function in the 36061da546Spatrick /// struct with the written arguments. This method lets Clang handle the 37061da546Spatrick /// vagaries of function calling conventions. 38061da546Spatrick /// 39061da546Spatrick /// The simplest use of the FunctionCaller is to construct it with a function 40061da546Spatrick /// representative of the signature you want to use, then call 41061da546Spatrick /// ExecuteFunction(ExecutionContext &, Stream &, Value &). 42061da546Spatrick /// 43061da546Spatrick /// If you need to reuse the arguments for several calls, you can call 44061da546Spatrick /// InsertFunction() followed by WriteFunctionArguments(), which will return 45061da546Spatrick /// the location of the args struct for the wrapper function in args_addr_ref. 46061da546Spatrick /// 47061da546Spatrick /// If you need to call the function on the thread plan stack, you can also 48061da546Spatrick /// call InsertFunction() followed by GetThreadPlanToCallFunction(). 49061da546Spatrick /// 50061da546Spatrick /// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a 51061da546Spatrick /// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated 52061da546Spatrick /// and its address returned in that variable. 53061da546Spatrick /// 54061da546Spatrick /// Any of the methods that take arg_addr_ptr can be passed nullptr, and the 55061da546Spatrick /// argument space will be managed for you. 56061da546Spatrick class FunctionCaller : public Expression { 57061da546Spatrick // LLVM RTTI support 58061da546Spatrick static char ID; 59061da546Spatrick 60061da546Spatrick public: isA(const void * ClassID)61061da546Spatrick bool isA(const void *ClassID) const override { return ClassID == &ID; } classof(const Expression * obj)62061da546Spatrick static bool classof(const Expression *obj) { return obj->isA(&ID); } 63061da546Spatrick 64061da546Spatrick /// Constructor 65061da546Spatrick /// 66061da546Spatrick /// \param[in] exe_scope 67061da546Spatrick /// An execution context scope that gets us at least a target and 68061da546Spatrick /// process. 69061da546Spatrick /// 70061da546Spatrick /// \param[in] return_type 71061da546Spatrick /// An opaque Clang QualType for the function result. Should be 72061da546Spatrick /// defined in ast_context. 73061da546Spatrick /// 74061da546Spatrick /// \param[in] function_address 75061da546Spatrick /// The address of the function to call. 76061da546Spatrick /// 77061da546Spatrick /// \param[in] arg_value_list 78061da546Spatrick /// The default values to use when calling this function. Can 79061da546Spatrick /// be overridden using WriteFunctionArguments(). 80061da546Spatrick FunctionCaller(ExecutionContextScope &exe_scope, 81061da546Spatrick const CompilerType &return_type, 82061da546Spatrick const Address &function_address, 83061da546Spatrick const ValueList &arg_value_list, const char *name); 84061da546Spatrick 85061da546Spatrick /// Destructor 86061da546Spatrick ~FunctionCaller() override; 87061da546Spatrick 88061da546Spatrick /// Compile the wrapper function 89061da546Spatrick /// 90061da546Spatrick /// \param[in] thread_to_use_sp 91061da546Spatrick /// Compilation might end up calling functions. Pass in the thread you 92061da546Spatrick /// want the compilation to use. If you pass in an empty ThreadSP it will 93061da546Spatrick /// use the currently selected thread. 94061da546Spatrick /// 95061da546Spatrick /// \param[in] diagnostic_manager 96061da546Spatrick /// The diagnostic manager to report parser errors to. 97061da546Spatrick /// 98061da546Spatrick /// \return 99061da546Spatrick /// The number of errors. 100061da546Spatrick virtual unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp, 101061da546Spatrick DiagnosticManager &diagnostic_manager) = 0; 102061da546Spatrick 103061da546Spatrick /// Insert the default function wrapper and its default argument struct 104061da546Spatrick /// 105061da546Spatrick /// \param[in] exe_ctx 106061da546Spatrick /// The execution context to insert the function and its arguments 107061da546Spatrick /// into. 108061da546Spatrick /// 109061da546Spatrick /// \param[in,out] args_addr_ref 110061da546Spatrick /// The address of the structure to write the arguments into. May 111061da546Spatrick /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 112061da546Spatrick /// and args_addr_ref is pointed to it. 113061da546Spatrick /// 114061da546Spatrick /// \param[in] diagnostic_manager 115061da546Spatrick /// The diagnostic manager to report errors to. 116061da546Spatrick /// 117061da546Spatrick /// \return 118061da546Spatrick /// True on success; false otherwise. 119061da546Spatrick bool InsertFunction(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref, 120061da546Spatrick DiagnosticManager &diagnostic_manager); 121061da546Spatrick 122061da546Spatrick /// Insert the default function wrapper (using the JIT) 123061da546Spatrick /// 124061da546Spatrick /// \param[in] exe_ctx 125061da546Spatrick /// The execution context to insert the function and its arguments 126061da546Spatrick /// into. 127061da546Spatrick /// 128061da546Spatrick /// \param[in] diagnostic_manager 129061da546Spatrick /// The diagnostic manager to report errors to. 130061da546Spatrick /// 131061da546Spatrick /// \return 132061da546Spatrick /// True on success; false otherwise. 133061da546Spatrick bool WriteFunctionWrapper(ExecutionContext &exe_ctx, 134061da546Spatrick DiagnosticManager &diagnostic_manager); 135061da546Spatrick 136061da546Spatrick /// Insert the default function argument struct 137061da546Spatrick /// 138061da546Spatrick /// \param[in] exe_ctx 139061da546Spatrick /// The execution context to insert the function and its arguments 140061da546Spatrick /// into. 141061da546Spatrick /// 142061da546Spatrick /// \param[in,out] args_addr_ref 143061da546Spatrick /// The address of the structure to write the arguments into. May 144061da546Spatrick /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 145061da546Spatrick /// and args_addr_ref is pointed to it. 146061da546Spatrick /// 147061da546Spatrick /// \param[in] diagnostic_manager 148061da546Spatrick /// The diagnostic manager to report errors to. 149061da546Spatrick /// 150061da546Spatrick /// \return 151061da546Spatrick /// True on success; false otherwise. 152061da546Spatrick bool WriteFunctionArguments(ExecutionContext &exe_ctx, 153061da546Spatrick lldb::addr_t &args_addr_ref, 154061da546Spatrick DiagnosticManager &diagnostic_manager); 155061da546Spatrick 156061da546Spatrick /// Insert an argument struct with a non-default function address and non- 157061da546Spatrick /// default argument values 158061da546Spatrick /// 159061da546Spatrick /// \param[in] exe_ctx 160061da546Spatrick /// The execution context to insert the function and its arguments 161061da546Spatrick /// into. 162061da546Spatrick /// 163061da546Spatrick /// \param[in,out] args_addr_ref 164061da546Spatrick /// The address of the structure to write the arguments into. May 165061da546Spatrick /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 166061da546Spatrick /// and args_addr_ref is pointed at it. 167061da546Spatrick /// 168061da546Spatrick /// \param[in] arg_values 169061da546Spatrick /// The values of the function's arguments. 170061da546Spatrick /// 171061da546Spatrick /// \param[in] diagnostic_manager 172061da546Spatrick /// The diagnostic manager to report errors to. 173061da546Spatrick /// 174061da546Spatrick /// \return 175061da546Spatrick /// True on success; false otherwise. 176061da546Spatrick bool WriteFunctionArguments(ExecutionContext &exe_ctx, 177061da546Spatrick lldb::addr_t &args_addr_ref, 178061da546Spatrick ValueList &arg_values, 179061da546Spatrick DiagnosticManager &diagnostic_manager); 180061da546Spatrick 181061da546Spatrick /// Run the function this FunctionCaller was created with. 182061da546Spatrick /// 183061da546Spatrick /// This is the full version. 184061da546Spatrick /// 185061da546Spatrick /// \param[in] exe_ctx 186061da546Spatrick /// The thread & process in which this function will run. 187061da546Spatrick /// 188061da546Spatrick /// \param[in] args_addr_ptr 189061da546Spatrick /// If nullptr, the function will take care of allocating & deallocating 190061da546Spatrick /// the wrapper 191061da546Spatrick /// args structure. Otherwise, if set to LLDB_INVALID_ADDRESS, a new 192061da546Spatrick /// structure 193061da546Spatrick /// will be allocated, filled and the address returned to you. You are 194061da546Spatrick /// responsible 195061da546Spatrick /// for deallocating it. And if passed in with a value other than 196061da546Spatrick /// LLDB_INVALID_ADDRESS, 197061da546Spatrick /// this should point to an already allocated structure with the values 198061da546Spatrick /// already written. 199061da546Spatrick /// 200061da546Spatrick /// \param[in] diagnostic_manager 201061da546Spatrick /// The diagnostic manager to report errors to. 202061da546Spatrick /// 203061da546Spatrick /// \param[in] options 204061da546Spatrick /// The options for this expression execution. 205061da546Spatrick /// 206061da546Spatrick /// \param[out] results 207061da546Spatrick /// The result value will be put here after running the function. 208061da546Spatrick /// 209061da546Spatrick /// \return 210061da546Spatrick /// Returns one of the ExpressionResults enum indicating function call 211061da546Spatrick /// status. 212061da546Spatrick lldb::ExpressionResults 213061da546Spatrick ExecuteFunction(ExecutionContext &exe_ctx, lldb::addr_t *args_addr_ptr, 214061da546Spatrick const EvaluateExpressionOptions &options, 215061da546Spatrick DiagnosticManager &diagnostic_manager, Value &results); 216061da546Spatrick 217061da546Spatrick /// Get a thread plan to run the function this FunctionCaller was created 218061da546Spatrick /// with. 219061da546Spatrick /// 220061da546Spatrick /// \param[in] exe_ctx 221061da546Spatrick /// The execution context to insert the function and its arguments 222061da546Spatrick /// into. 223061da546Spatrick /// 224061da546Spatrick /// \param[in] args_addr 225061da546Spatrick /// The address of the argument struct. 226061da546Spatrick /// 227061da546Spatrick /// \param[in] diagnostic_manager 228061da546Spatrick /// The diagnostic manager to report errors to. 229061da546Spatrick /// 230061da546Spatrick /// \return 231061da546Spatrick /// A ThreadPlan shared pointer for executing the function. 232061da546Spatrick lldb::ThreadPlanSP 233061da546Spatrick GetThreadPlanToCallFunction(ExecutionContext &exe_ctx, lldb::addr_t args_addr, 234061da546Spatrick const EvaluateExpressionOptions &options, 235061da546Spatrick DiagnosticManager &diagnostic_manager); 236061da546Spatrick 237061da546Spatrick /// Get the result of the function from its struct 238061da546Spatrick /// 239061da546Spatrick /// \param[in] exe_ctx 240061da546Spatrick /// The execution context to retrieve the result from. 241061da546Spatrick /// 242061da546Spatrick /// \param[in] args_addr 243061da546Spatrick /// The address of the argument struct. 244061da546Spatrick /// 245061da546Spatrick /// \param[out] ret_value 246061da546Spatrick /// The value returned by the function. 247061da546Spatrick /// 248061da546Spatrick /// \return 249061da546Spatrick /// True on success; false otherwise. 250061da546Spatrick bool FetchFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr, 251061da546Spatrick Value &ret_value); 252061da546Spatrick 253061da546Spatrick /// Deallocate the arguments structure 254061da546Spatrick /// 255061da546Spatrick /// \param[in] exe_ctx 256061da546Spatrick /// The execution context to insert the function and its arguments 257061da546Spatrick /// into. 258061da546Spatrick /// 259061da546Spatrick /// \param[in] args_addr 260061da546Spatrick /// The address of the argument struct. 261061da546Spatrick void DeallocateFunctionResults(ExecutionContext &exe_ctx, 262061da546Spatrick lldb::addr_t args_addr); 263061da546Spatrick 264061da546Spatrick /// Interface for ClangExpression 265061da546Spatrick 266061da546Spatrick /// Return the string that the parser should parse. Must be a full 267061da546Spatrick /// translation unit. Text()268061da546Spatrick const char *Text() override { return m_wrapper_function_text.c_str(); } 269061da546Spatrick 270061da546Spatrick /// Return the function name that should be used for executing the 271061da546Spatrick /// expression. Text() should contain the definition of this function. FunctionName()272061da546Spatrick const char *FunctionName() override { 273061da546Spatrick return m_wrapper_function_name.c_str(); 274061da546Spatrick } 275061da546Spatrick 276061da546Spatrick /// Return the object that the parser should use when registering local 277061da546Spatrick /// variables. May be nullptr if the Expression doesn't care. LocalVariables()278061da546Spatrick ExpressionVariableList *LocalVariables() { return nullptr; } 279061da546Spatrick 280061da546Spatrick /// Return true if validation code should be inserted into the expression. NeedsValidation()281061da546Spatrick bool NeedsValidation() override { return false; } 282061da546Spatrick 283061da546Spatrick /// Return true if external variables in the expression should be resolved. NeedsVariableResolution()284061da546Spatrick bool NeedsVariableResolution() override { return false; } 285061da546Spatrick GetArgumentValues()286061da546Spatrick ValueList GetArgumentValues() const { return m_arg_values; } 287061da546Spatrick 288061da546Spatrick protected: 289061da546Spatrick // Note: the parser needs to be destructed before the execution unit, so 290061da546Spatrick // declare the execution unit first. 291061da546Spatrick std::shared_ptr<IRExecutionUnit> m_execution_unit_sp; 292061da546Spatrick std::unique_ptr<ExpressionParser> 293061da546Spatrick m_parser; ///< The parser responsible for compiling the function. 294061da546Spatrick ///< This will get made in CompileFunction, so it is 295061da546Spatrick ///< safe to access it after that. 296061da546Spatrick 297061da546Spatrick lldb::ModuleWP m_jit_module_wp; 298061da546Spatrick std::string 299061da546Spatrick m_name; ///< The name of this clang function - for debugging purposes. 300061da546Spatrick 301061da546Spatrick Function *m_function_ptr; ///< The function we're going to call. May be 302061da546Spatrick ///nullptr if we don't have debug info for the 303061da546Spatrick ///function. 304061da546Spatrick Address m_function_addr; ///< If we don't have the FunctionSP, we at least 305061da546Spatrick ///need the address & return type. 306061da546Spatrick CompilerType m_function_return_type; ///< The opaque clang qual type for the 307061da546Spatrick ///function return type. 308061da546Spatrick 309061da546Spatrick std::string m_wrapper_function_name; ///< The name of the wrapper function. 310061da546Spatrick std::string 311061da546Spatrick m_wrapper_function_text; ///< The contents of the wrapper function. 312061da546Spatrick std::string m_wrapper_struct_name; ///< The name of the struct that contains 313061da546Spatrick ///the target function address, arguments, 314061da546Spatrick ///and result. 315061da546Spatrick std::list<lldb::addr_t> m_wrapper_args_addrs; ///< The addresses of the 316061da546Spatrick ///arguments to the wrapper 317061da546Spatrick ///function. 318061da546Spatrick 319061da546Spatrick bool m_struct_valid; ///< True if the ASTStructExtractor has populated the 320061da546Spatrick ///variables below. 321061da546Spatrick 322061da546Spatrick /// These values are populated by the ASTStructExtractor 323061da546Spatrick size_t m_struct_size; ///< The size of the argument struct, in bytes. 324061da546Spatrick std::vector<uint64_t> 325061da546Spatrick m_member_offsets; ///< The offset of each member in the struct, in bytes. 326061da546Spatrick uint64_t m_return_size; ///< The size of the result variable, in bytes. 327061da546Spatrick uint64_t m_return_offset; ///< The offset of the result variable in the 328061da546Spatrick ///struct, in bytes. 329061da546Spatrick 330061da546Spatrick ValueList m_arg_values; ///< The default values of the arguments. 331061da546Spatrick 332061da546Spatrick bool m_compiled; ///< True if the wrapper function has already been parsed. 333061da546Spatrick bool 334061da546Spatrick m_JITted; ///< True if the wrapper function has already been JIT-compiled. 335061da546Spatrick }; 336061da546Spatrick 337061da546Spatrick } // namespace lldb_private 338061da546Spatrick 339*dda28197Spatrick #endif // LLDB_EXPRESSION_FUNCTIONCALLER_H 340