LLDB  mainline
FunctionCaller.h
Go to the documentation of this file.
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"
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().
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.
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.
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.
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.
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
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.
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 
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_
lldb::ExpressionResults ExecuteFunction(ExecutionContext &exe_ctx, lldb::addr_t *args_addr_ptr, const EvaluateExpressionOptions &options, DiagnosticManager &diagnostic_manager, Value &results)
Run the function this FunctionCaller was created with.
std::string m_wrapper_function_text
The contents of the wrapper function.
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
void DeallocateFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr)
Deallocate the arguments structure.
size_t m_struct_size
These values are populated by the ASTStructExtractor.
~FunctionCaller() override
Destructor.
std::unique_ptr< ExpressionParser > m_parser
The parser responsible for compiling the function.
bool m_compiled
True if the wrapper function has already been parsed.
bool m_JITted
True if the wrapper function has already been JIT-compiled.
A class that describes a function.
Definition: Function.h:323
Encapsulates a single expression for use in lldb.
Definition: Expression.h:33
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
bool FetchFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr, Value &ret_value)
Get the result of the function from its struct.
std::shared_ptr< IRExecutionUnit > m_execution_unit_sp
ExpressionKind getKind() const
LLVM-style RTTI support.
Definition: Expression.h:94
const char * FunctionName() override
Return the function name that should be used for executing the expression.
bool WriteFunctionArguments(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref, DiagnosticManager &diagnostic_manager)
Insert the default function argument struct.
static bool classof(const Expression *E)
LLVM-style RTTI support.
bool NeedsValidation() override
Return true if validation code should be inserted into the expression.
"lldb/Expression/ExpressionVariable.h" A list of variable references.
bool WriteFunctionWrapper(ExecutionContext &exe_ctx, DiagnosticManager &diagnostic_manager)
Insert the default function wrapper (using the JIT)
Encapsulates a function that can be called.
std::list< lldb::addr_t > m_wrapper_args_addrs
The addresses of the arguments to the wrapper function.
std::string m_wrapper_function_name
The name of the wrapper function.
"lldb/Target/ExecutionContextScope.h" Inherit from this if your object can reconstruct its execution ...
FunctionCaller(ExecutionContextScope &exe_scope, const CompilerType &return_type, const Address &function_address, const ValueList &arg_value_list, const char *name)
Constructor.
uint64_t m_return_size
The size of the result variable, in bytes.
lldb::ThreadPlanSP GetThreadPlanToCallFunction(ExecutionContext &exe_ctx, lldb::addr_t args_addr, const EvaluateExpressionOptions &options, DiagnosticManager &diagnostic_manager)
Get a thread plan to run the function this FunctionCaller was created with.
A section + offset based address class.
Definition: Address.h:80
Function * m_function_ptr
The function we&#39;re going to call.
ValueList GetArgumentValues() const
Address m_function_addr
If we don&#39;t have the FunctionSP, we at least need the address & return type.
const char * Text() override
Interface for ClangExpression.
std::string m_wrapper_struct_name
The name of the struct that contains the target function address, arguments, and result.
bool InsertFunction(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref, DiagnosticManager &diagnostic_manager)
Insert the default function wrapper and its default argument struct.
std::vector< uint64_t > m_member_offsets
The offset of each member in the struct, in bytes.
uint64_t addr_t
Definition: lldb-types.h:83
virtual unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp, DiagnosticManager &diagnostic_manager)=0
Compile the wrapper function.
ValueList m_arg_values
The default values of the arguments.
bool NeedsVariableResolution() override
Return true if external variables in the expression should be resolved.
ExpressionVariableList * LocalVariables()
Return the object that the parser should use when registering local variables.
std::string m_name
The name of this clang function - for debugging purposes.
uint64_t m_return_offset
The offset of the result variable in the struct, in bytes.
bool m_struct_valid
True if the ASTStructExtractor has populated the variables below.
CompilerType m_function_return_type
The opaque clang qual type for the function return type.