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