FunctionCaller.h revision 360660
1//===-- FunctionCaller.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_FunctionCaller_h_ 10#define liblldb_FunctionCaller_h_ 11 12#include <list> 13#include <memory> 14#include <string> 15#include <vector> 16 17#include "lldb/Core/Address.h" 18#include "lldb/Core/Value.h" 19#include "lldb/Expression/Expression.h" 20#include "lldb/Expression/ExpressionParser.h" 21#include "lldb/Symbol/CompilerType.h" 22 23namespace lldb_private { 24 25/// \class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h" 26/// Encapsulates a function that can be called. 27/// 28/// A given FunctionCaller object can handle a single function signature. 29/// Once constructed, it can set up any number of concurrent calls to 30/// functions with that signature. 31/// 32/// It performs the call by synthesizing a structure that contains the pointer 33/// to the function and the arguments that should be passed to that function, 34/// and producing a special-purpose JIT-compiled function that accepts a void* 35/// pointing to this struct as its only argument and calls the function in the 36/// struct with the written arguments. This method lets Clang handle the 37/// vagaries of function calling conventions. 38/// 39/// The simplest use of the FunctionCaller is to construct it with a function 40/// representative of the signature you want to use, then call 41/// ExecuteFunction(ExecutionContext &, Stream &, Value &). 42/// 43/// If you need to reuse the arguments for several calls, you can call 44/// InsertFunction() followed by WriteFunctionArguments(), which will return 45/// the location of the args struct for the wrapper function in args_addr_ref. 46/// 47/// If you need to call the function on the thread plan stack, you can also 48/// call InsertFunction() followed by GetThreadPlanToCallFunction(). 49/// 50/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a 51/// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated 52/// and its address returned in that variable. 53/// 54/// Any of the methods that take arg_addr_ptr can be passed nullptr, and the 55/// argument space will be managed for you. 56class FunctionCaller : public Expression { 57public: 58 /// LLVM-style RTTI support. 59 static bool classof(const Expression *E) { 60 return E->getKind() == eKindFunctionCaller; 61 } 62 63 /// Constructor 64 /// 65 /// \param[in] exe_scope 66 /// An execution context scope that gets us at least a target and 67 /// process. 68 /// 69 /// \param[in] ast_context 70 /// The AST context to evaluate argument types in. 71 /// 72 /// \param[in] return_qualtype 73 /// An opaque Clang QualType for the function result. Should be 74 /// defined in ast_context. 75 /// 76 /// \param[in] function_address 77 /// The address of the function to call. 78 /// 79 /// \param[in] arg_value_list 80 /// The default values to use when calling this function. Can 81 /// be overridden using WriteFunctionArguments(). 82 FunctionCaller(ExecutionContextScope &exe_scope, 83 const CompilerType &return_type, 84 const Address &function_address, 85 const ValueList &arg_value_list, const char *name); 86 87 /// Destructor 88 ~FunctionCaller() override; 89 90 /// Compile the wrapper function 91 /// 92 /// \param[in] thread_to_use_sp 93 /// Compilation might end up calling functions. Pass in the thread you 94 /// want the compilation to use. If you pass in an empty ThreadSP it will 95 /// use the currently selected thread. 96 /// 97 /// \param[in] diagnostic_manager 98 /// The diagnostic manager to report parser errors to. 99 /// 100 /// \return 101 /// The number of errors. 102 virtual unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp, 103 DiagnosticManager &diagnostic_manager) = 0; 104 105 /// Insert the default function wrapper and its default argument struct 106 /// 107 /// \param[in] exe_ctx 108 /// The execution context to insert the function and its arguments 109 /// into. 110 /// 111 /// \param[in,out] args_addr_ref 112 /// The address of the structure to write the arguments into. May 113 /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 114 /// and args_addr_ref is pointed to it. 115 /// 116 /// \param[in] diagnostic_manager 117 /// The diagnostic manager to report errors to. 118 /// 119 /// \return 120 /// True on success; false otherwise. 121 bool InsertFunction(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref, 122 DiagnosticManager &diagnostic_manager); 123 124 /// Insert the default function wrapper (using the JIT) 125 /// 126 /// \param[in] exe_ctx 127 /// The execution context to insert the function and its arguments 128 /// into. 129 /// 130 /// \param[in] diagnostic_manager 131 /// The diagnostic manager to report errors to. 132 /// 133 /// \return 134 /// True on success; false otherwise. 135 bool WriteFunctionWrapper(ExecutionContext &exe_ctx, 136 DiagnosticManager &diagnostic_manager); 137 138 /// Insert the default function argument struct 139 /// 140 /// \param[in] exe_ctx 141 /// The execution context to insert the function and its arguments 142 /// into. 143 /// 144 /// \param[in,out] args_addr_ref 145 /// The address of the structure to write the arguments into. May 146 /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 147 /// and args_addr_ref is pointed to it. 148 /// 149 /// \param[in] diagnostic_manager 150 /// The diagnostic manager to report errors to. 151 /// 152 /// \return 153 /// True on success; false otherwise. 154 bool WriteFunctionArguments(ExecutionContext &exe_ctx, 155 lldb::addr_t &args_addr_ref, 156 DiagnosticManager &diagnostic_manager); 157 158 /// Insert an argument struct with a non-default function address and non- 159 /// default argument values 160 /// 161 /// \param[in] exe_ctx 162 /// The execution context to insert the function and its arguments 163 /// into. 164 /// 165 /// \param[in,out] args_addr_ref 166 /// The address of the structure to write the arguments into. May 167 /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 168 /// and args_addr_ref is pointed at it. 169 /// 170 /// \param[in] arg_values 171 /// The values of the function's arguments. 172 /// 173 /// \param[in] diagnostic_manager 174 /// The diagnostic manager to report errors to. 175 /// 176 /// \return 177 /// True on success; false otherwise. 178 bool WriteFunctionArguments(ExecutionContext &exe_ctx, 179 lldb::addr_t &args_addr_ref, 180 ValueList &arg_values, 181 DiagnosticManager &diagnostic_manager); 182 183 /// Run the function this FunctionCaller was created with. 184 /// 185 /// This is the full version. 186 /// 187 /// \param[in] exe_ctx 188 /// The thread & process in which this function will run. 189 /// 190 /// \param[in] args_addr_ptr 191 /// If nullptr, the function will take care of allocating & deallocating 192 /// the wrapper 193 /// args structure. Otherwise, if set to LLDB_INVALID_ADDRESS, a new 194 /// structure 195 /// will be allocated, filled and the address returned to you. You are 196 /// responsible 197 /// for deallocating it. And if passed in with a value other than 198 /// LLDB_INVALID_ADDRESS, 199 /// this should point to an already allocated structure with the values 200 /// already written. 201 /// 202 /// \param[in] diagnostic_manager 203 /// The diagnostic manager to report errors to. 204 /// 205 /// \param[in] options 206 /// The options for this expression execution. 207 /// 208 /// \param[out] results 209 /// The result value will be put here after running the function. 210 /// 211 /// \return 212 /// Returns one of the ExpressionResults enum indicating function call 213 /// status. 214 lldb::ExpressionResults 215 ExecuteFunction(ExecutionContext &exe_ctx, lldb::addr_t *args_addr_ptr, 216 const EvaluateExpressionOptions &options, 217 DiagnosticManager &diagnostic_manager, Value &results); 218 219 /// Get a thread plan to run the function this FunctionCaller was created 220 /// with. 221 /// 222 /// \param[in] exe_ctx 223 /// The execution context to insert the function and its arguments 224 /// into. 225 /// 226 /// \param[in] func_addr 227 /// The address of the function in the target process. 228 /// 229 /// \param[in] args_addr 230 /// The address of the argument struct. 231 /// 232 /// \param[in] diagnostic_manager 233 /// The diagnostic manager to report errors to. 234 /// 235 /// \param[in] stop_others 236 /// True if other threads should pause during execution. 237 /// 238 /// \param[in] unwind_on_error 239 /// True if the thread plan may simply be discarded if an error occurs. 240 /// 241 /// \return 242 /// A ThreadPlan shared pointer for executing the function. 243 lldb::ThreadPlanSP 244 GetThreadPlanToCallFunction(ExecutionContext &exe_ctx, lldb::addr_t args_addr, 245 const EvaluateExpressionOptions &options, 246 DiagnosticManager &diagnostic_manager); 247 248 /// Get the result of the function from its struct 249 /// 250 /// \param[in] exe_ctx 251 /// The execution context to retrieve the result from. 252 /// 253 /// \param[in] args_addr 254 /// The address of the argument struct. 255 /// 256 /// \param[out] ret_value 257 /// The value returned by the function. 258 /// 259 /// \return 260 /// True on success; false otherwise. 261 bool FetchFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr, 262 Value &ret_value); 263 264 /// Deallocate the arguments structure 265 /// 266 /// \param[in] exe_ctx 267 /// The execution context to insert the function and its arguments 268 /// into. 269 /// 270 /// \param[in] args_addr 271 /// The address of the argument struct. 272 void DeallocateFunctionResults(ExecutionContext &exe_ctx, 273 lldb::addr_t args_addr); 274 275 /// Interface for ClangExpression 276 277 /// Return the string that the parser should parse. Must be a full 278 /// translation unit. 279 const char *Text() override { return m_wrapper_function_text.c_str(); } 280 281 /// Return the function name that should be used for executing the 282 /// expression. Text() should contain the definition of this function. 283 const char *FunctionName() override { 284 return m_wrapper_function_name.c_str(); 285 } 286 287 /// Return the object that the parser should use when registering local 288 /// variables. May be nullptr if the Expression doesn't care. 289 ExpressionVariableList *LocalVariables() { return nullptr; } 290 291 /// Return true if validation code should be inserted into the expression. 292 bool NeedsValidation() override { return false; } 293 294 /// Return true if external variables in the expression should be resolved. 295 bool NeedsVariableResolution() override { return false; } 296 297 ValueList GetArgumentValues() const { return m_arg_values; } 298 299protected: 300 // Note: the parser needs to be destructed before the execution unit, so 301 // declare the execution unit first. 302 std::shared_ptr<IRExecutionUnit> m_execution_unit_sp; 303 std::unique_ptr<ExpressionParser> 304 m_parser; ///< The parser responsible for compiling the function. 305 ///< This will get made in CompileFunction, so it is 306 ///< safe to access it after that. 307 308 lldb::ModuleWP m_jit_module_wp; 309 std::string 310 m_name; ///< The name of this clang function - for debugging purposes. 311 312 Function *m_function_ptr; ///< The function we're going to call. May be 313 ///nullptr if we don't have debug info for the 314 ///function. 315 Address m_function_addr; ///< If we don't have the FunctionSP, we at least 316 ///need the address & return type. 317 CompilerType m_function_return_type; ///< The opaque clang qual type for the 318 ///function return type. 319 320 std::string m_wrapper_function_name; ///< The name of the wrapper function. 321 std::string 322 m_wrapper_function_text; ///< The contents of the wrapper function. 323 std::string m_wrapper_struct_name; ///< The name of the struct that contains 324 ///the target function address, arguments, 325 ///and result. 326 std::list<lldb::addr_t> m_wrapper_args_addrs; ///< The addresses of the 327 ///arguments to the wrapper 328 ///function. 329 330 bool m_struct_valid; ///< True if the ASTStructExtractor has populated the 331 ///variables below. 332 333 /// These values are populated by the ASTStructExtractor 334 size_t m_struct_size; ///< The size of the argument struct, in bytes. 335 std::vector<uint64_t> 336 m_member_offsets; ///< The offset of each member in the struct, in bytes. 337 uint64_t m_return_size; ///< The size of the result variable, in bytes. 338 uint64_t m_return_offset; ///< The offset of the result variable in the 339 ///struct, in bytes. 340 341 ValueList m_arg_values; ///< The default values of the arguments. 342 343 bool m_compiled; ///< True if the wrapper function has already been parsed. 344 bool 345 m_JITted; ///< True if the wrapper function has already been JIT-compiled. 346}; 347 348} // namespace lldb_private 349 350#endif // liblldb_FunctionCaller_h_ 351