contrib/llvm/tools/lldb/include/lldb/Expression/FunctionCaller.h

   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
  23 namespace 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.
  56 class FunctionCaller : public Expression {
  57 public:
  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
 299 protected:
 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_