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

   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   //------------------------------------------------------------------
 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   //------------------------------------------------------------------
 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   //------------------------------------------------------------------
 317   ExpressionVariableList *LocalVariables() { return nullptr; }
 318
 319   //------------------------------------------------------------------
 320   /// Return true if validation code should be inserted into the expression.
 321   //------------------------------------------------------------------
 322   bool NeedsValidation() override { return false; }
 323
 324   //------------------------------------------------------------------
 325   /// Return true if external variables in the expression should be resolved.
 326   //------------------------------------------------------------------
 327   bool NeedsVariableResolution() override { return false; }
 328
 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_