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 LLDB_EXPRESSION_FUNCTIONCALLER_H
10 #define LLDB_EXPRESSION_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  // LLVM RTTI support
58  static char ID;
59 
60 public:
61  bool isA(const void *ClassID) const override { return ClassID == &ID; }
62  static bool classof(const Expression *obj) { return obj->isA(&ID); }
63 
64  /// Constructor
65  ///
66  /// \param[in] exe_scope
67  /// An execution context scope that gets us at least a target and
68  /// process.
69  ///
70  /// \param[in] return_type
71  /// An opaque Clang QualType for the function result. Should be
72  /// defined in ast_context.
73  ///
74  /// \param[in] function_address
75  /// The address of the function to call.
76  ///
77  /// \param[in] arg_value_list
78  /// The default values to use when calling this function. Can
79  /// be overridden using WriteFunctionArguments().
81  const CompilerType &return_type,
82  const Address &function_address,
83  const ValueList &arg_value_list, const char *name);
84 
85  /// Destructor
86  ~FunctionCaller() override;
87 
88  /// Compile the wrapper function
89  ///
90  /// \param[in] thread_to_use_sp
91  /// Compilation might end up calling functions. Pass in the thread you
92  /// want the compilation to use. If you pass in an empty ThreadSP it will
93  /// use the currently selected thread.
94  ///
95  /// \param[in] diagnostic_manager
96  /// The diagnostic manager to report parser errors to.
97  ///
98  /// \return
99  /// The number of errors.
100  virtual unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp,
101  DiagnosticManager &diagnostic_manager) = 0;
102 
103  /// Insert the default function wrapper and its default argument struct
104  ///
105  /// \param[in] exe_ctx
106  /// The execution context to insert the function and its arguments
107  /// into.
108  ///
109  /// \param[in,out] args_addr_ref
110  /// The address of the structure to write the arguments into. May
111  /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
112  /// and args_addr_ref is pointed to it.
113  ///
114  /// \param[in] diagnostic_manager
115  /// The diagnostic manager to report errors to.
116  ///
117  /// \return
118  /// True on success; false otherwise.
119  bool InsertFunction(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref,
120  DiagnosticManager &diagnostic_manager);
121 
122  /// Insert the default function wrapper (using the JIT)
123  ///
124  /// \param[in] exe_ctx
125  /// The execution context to insert the function and its arguments
126  /// into.
127  ///
128  /// \param[in] diagnostic_manager
129  /// The diagnostic manager to report errors to.
130  ///
131  /// \return
132  /// True on success; false otherwise.
134  DiagnosticManager &diagnostic_manager);
135 
136  /// Insert the default function argument struct
137  ///
138  /// \param[in] exe_ctx
139  /// The execution context to insert the function and its arguments
140  /// into.
141  ///
142  /// \param[in,out] args_addr_ref
143  /// The address of the structure to write the arguments into. May
144  /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
145  /// and args_addr_ref is pointed to it.
146  ///
147  /// \param[in] diagnostic_manager
148  /// The diagnostic manager to report errors to.
149  ///
150  /// \return
151  /// True on success; false otherwise.
153  lldb::addr_t &args_addr_ref,
154  DiagnosticManager &diagnostic_manager);
155 
156  /// Insert an argument struct with a non-default function address and non-
157  /// default argument values
158  ///
159  /// \param[in] exe_ctx
160  /// The execution context to insert the function and its arguments
161  /// into.
162  ///
163  /// \param[in,out] args_addr_ref
164  /// The address of the structure to write the arguments into. May
165  /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
166  /// and args_addr_ref is pointed at it.
167  ///
168  /// \param[in] arg_values
169  /// The values of the function's arguments.
170  ///
171  /// \param[in] diagnostic_manager
172  /// The diagnostic manager to report errors to.
173  ///
174  /// \return
175  /// True on success; false otherwise.
177  lldb::addr_t &args_addr_ref,
178  ValueList &arg_values,
179  DiagnosticManager &diagnostic_manager);
180 
181  /// Run the function this FunctionCaller was created with.
182  ///
183  /// This is the full version.
184  ///
185  /// \param[in] exe_ctx
186  /// The thread & process in which this function will run.
187  ///
188  /// \param[in] args_addr_ptr
189  /// If nullptr, the function will take care of allocating & deallocating
190  /// the wrapper
191  /// args structure. Otherwise, if set to LLDB_INVALID_ADDRESS, a new
192  /// structure
193  /// will be allocated, filled and the address returned to you. You are
194  /// responsible
195  /// for deallocating it. And if passed in with a value other than
196  /// LLDB_INVALID_ADDRESS,
197  /// this should point to an already allocated structure with the values
198  /// already written.
199  ///
200  /// \param[in] diagnostic_manager
201  /// The diagnostic manager to report errors to.
202  ///
203  /// \param[in] options
204  /// The options for this expression execution.
205  ///
206  /// \param[out] results
207  /// The result value will be put here after running the function.
208  ///
209  /// \return
210  /// Returns one of the ExpressionResults enum indicating function call
211  /// status.
213  ExecuteFunction(ExecutionContext &exe_ctx, lldb::addr_t *args_addr_ptr,
214  const EvaluateExpressionOptions &options,
215  DiagnosticManager &diagnostic_manager, Value &results);
216 
217  /// Get a thread plan to run the function this FunctionCaller was created
218  /// with.
219  ///
220  /// \param[in] exe_ctx
221  /// The execution context to insert the function and its arguments
222  /// into.
223  ///
224  /// \param[in] args_addr
225  /// The address of the argument struct.
226  ///
227  /// \param[in] diagnostic_manager
228  /// The diagnostic manager to report errors to.
229  ///
230  /// \return
231  /// A ThreadPlan shared pointer for executing the function.
232  lldb::ThreadPlanSP
234  const EvaluateExpressionOptions &options,
235  DiagnosticManager &diagnostic_manager);
236 
237  /// Get the result of the function from its struct
238  ///
239  /// \param[in] exe_ctx
240  /// The execution context to retrieve the result from.
241  ///
242  /// \param[in] args_addr
243  /// The address of the argument struct.
244  ///
245  /// \param[out] ret_value
246  /// The value returned by the function.
247  ///
248  /// \return
249  /// True on success; false otherwise.
250  bool FetchFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr,
251  Value &ret_value);
252 
253  /// Deallocate the arguments structure
254  ///
255  /// \param[in] exe_ctx
256  /// The execution context to insert the function and its arguments
257  /// into.
258  ///
259  /// \param[in] args_addr
260  /// The address of the argument struct.
262  lldb::addr_t args_addr);
263 
264  /// Interface for ClangExpression
265 
266  /// Return the string that the parser should parse. Must be a full
267  /// translation unit.
268  const char *Text() override { return m_wrapper_function_text.c_str(); }
269 
270  /// Return the function name that should be used for executing the
271  /// expression. Text() should contain the definition of this function.
272  const char *FunctionName() override {
273  return m_wrapper_function_name.c_str();
274  }
275 
276  /// Return the object that the parser should use when registering local
277  /// variables. May be nullptr if the Expression doesn't care.
278  ExpressionVariableList *LocalVariables() { return nullptr; }
279 
280  /// Return true if validation code should be inserted into the expression.
281  bool NeedsValidation() override { return false; }
282 
283  /// Return true if external variables in the expression should be resolved.
284  bool NeedsVariableResolution() override { return false; }
285 
287 
288 protected:
289  // Note: the parser needs to be destructed before the execution unit, so
290  // declare the execution unit first.
291  std::shared_ptr<IRExecutionUnit> m_execution_unit_sp;
292  std::unique_ptr<ExpressionParser>
293  m_parser; ///< The parser responsible for compiling the function.
294  ///< This will get made in CompileFunction, so it is
295  ///< safe to access it after that.
296 
297  lldb::ModuleWP m_jit_module_wp;
299  m_name; ///< The name of this clang function - for debugging purposes.
300 
301  Function *m_function_ptr; ///< The function we're going to call. May be
302  ///nullptr if we don't have debug info for the
303  ///function.
304  Address m_function_addr; ///< If we don't have the FunctionSP, we at least
305  ///need the address & return type.
306  CompilerType m_function_return_type; ///< The opaque clang qual type for the
307  ///function return type.
308 
309  std::string m_wrapper_function_name; ///< The name of the wrapper function.
311  m_wrapper_function_text; ///< The contents of the wrapper function.
312  std::string m_wrapper_struct_name; ///< The name of the struct that contains
313  ///the target function address, arguments,
314  ///and result.
315  std::list<lldb::addr_t> m_wrapper_args_addrs; ///< The addresses of the
316  ///arguments to the wrapper
317  ///function.
318 
319  bool m_struct_valid; ///< True if the ASTStructExtractor has populated the
320  ///variables below.
321 
322  /// These values are populated by the ASTStructExtractor
323  size_t m_struct_size; ///< The size of the argument struct, in bytes.
324  std::vector<uint64_t>
325  m_member_offsets; ///< The offset of each member in the struct, in bytes.
326  uint64_t m_return_size; ///< The size of the result variable, in bytes.
327  uint64_t m_return_offset; ///< The offset of the result variable in the
328  ///struct, in bytes.
329 
330  ValueList m_arg_values; ///< The default values of the arguments.
331 
332  bool m_compiled; ///< True if the wrapper function has already been parsed.
333  bool
334  m_JITted; ///< True if the wrapper function has already been JIT-compiled.
335 };
336 
337 } // namespace lldb_private
338 
339 #endif // LLDB_EXPRESSION_FUNCTIONCALLER_H
lldb_private::ExecutionContext
Definition: ExecutionContext.h:292
lldb_private::Value
Definition: Value.h:38
lldb_private::FunctionCaller::m_wrapper_function_name
std::string m_wrapper_function_name
The name of the wrapper function.
Definition: FunctionCaller.h:309
lldb_private::FunctionCaller::m_function_ptr
Function * m_function_ptr
The function we're going to call.
Definition: FunctionCaller.h:301
lldb_private::FunctionCaller::m_return_offset
uint64_t m_return_offset
The offset of the result variable in the struct, in bytes.
Definition: FunctionCaller.h:327
lldb::ExpressionResults
ExpressionResults
The results of expression evaluation.
Definition: lldb-enumerations.h:270
lldb_private::FunctionCaller::WriteFunctionWrapper
bool WriteFunctionWrapper(ExecutionContext &exe_ctx, DiagnosticManager &diagnostic_manager)
Insert the default function wrapper (using the JIT)
Definition: FunctionCaller.cpp:63
lldb_private::FunctionCaller::m_name
std::string m_name
The name of this clang function - for debugging purposes.
Definition: FunctionCaller.h:299
lldb_private::EvaluateExpressionOptions
Definition: Target.h:262
lldb_private::FunctionCaller::m_jit_module_wp
lldb::ModuleWP m_jit_module_wp
Definition: FunctionCaller.h:297
lldb_private::ValueList
Definition: Value.h:157
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb_private::FunctionCaller::NeedsVariableResolution
bool NeedsVariableResolution() override
Return true if external variables in the expression should be resolved.
Definition: FunctionCaller.h:284
lldb_private::Expression::isA
virtual bool isA(const void *ClassID) const =0
lldb_private::FunctionCaller::m_wrapper_function_text
std::string m_wrapper_function_text
The contents of the wrapper function.
Definition: FunctionCaller.h:311
lldb_private::FunctionCaller::DeallocateFunctionResults
void DeallocateFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr)
Deallocate the arguments structure.
Definition: FunctionCaller.cpp:302
lldb_private::Function
Definition: Function.h:413
lldb_private::FunctionCaller::WriteFunctionArguments
bool WriteFunctionArguments(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref, DiagnosticManager &diagnostic_manager)
Insert the default function argument struct.
Definition: FunctionCaller.cpp:115
lldb_private::FunctionCaller::m_wrapper_struct_name
std::string m_wrapper_struct_name
The name of the struct that contains the target function address, arguments, and result.
Definition: FunctionCaller.h:312
lldb_private::ExecutionContextScope
Definition: ExecutionContextScope.h:32
lldb_private::FunctionCaller::InsertFunction
bool InsertFunction(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref, DiagnosticManager &diagnostic_manager)
Insert the default function wrapper and its default argument struct.
Definition: FunctionCaller.cpp:211
lldb_private::FunctionCaller::m_struct_size
size_t m_struct_size
These values are populated by the ASTStructExtractor.
Definition: FunctionCaller.h:323
lldb_private::FunctionCaller::m_return_size
uint64_t m_return_size
The size of the result variable, in bytes.
Definition: FunctionCaller.h:326
lldb_private::FunctionCaller::m_execution_unit_sp
std::shared_ptr< IRExecutionUnit > m_execution_unit_sp
Definition: FunctionCaller.h:291
lldb_private::FunctionCaller::GetArgumentValues
ValueList GetArgumentValues() const
Definition: FunctionCaller.h:286
lldb_private::FunctionCaller::m_arg_values
ValueList m_arg_values
The default values of the arguments.
Definition: FunctionCaller.h:330
lldb_private::ExpressionVariableList
Definition: ExpressionVariable.h:120
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:39
CompilerType.h
Address.h
lldb_private::FunctionCaller::FetchFunctionResults
bool FetchFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr, Value &ret_value)
Get the result of the function from its struct.
Definition: FunctionCaller.cpp:262
lldb_private::FunctionCaller::CompileFunction
virtual unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp, DiagnosticManager &diagnostic_manager)=0
Compile the wrapper function.
lldb_private::FunctionCaller::classof
static bool classof(const Expression *obj)
Definition: FunctionCaller.h:62
lldb_private::FunctionCaller::FunctionCaller
FunctionCaller(ExecutionContextScope &exe_scope, const CompilerType &return_type, const Address &function_address, const ValueList &arg_value_list, const char *name)
Constructor.
Definition: FunctionCaller.cpp:35
lldb_private::Address
Definition: Address.h:59
lldb_private::FunctionCaller::NeedsValidation
bool NeedsValidation() override
Return true if validation code should be inserted into the expression.
Definition: FunctionCaller.h:281
lldb_private::FunctionCaller::~FunctionCaller
~FunctionCaller() override
Destructor.
Definition: FunctionCaller.cpp:54
lldb_private::FunctionCaller::m_wrapper_args_addrs
std::list< lldb::addr_t > m_wrapper_args_addrs
The addresses of the arguments to the wrapper function.
Definition: FunctionCaller.h:315
lldb_private::FunctionCaller::m_parser
std::unique_ptr< ExpressionParser > m_parser
The parser responsible for compiling the function.
Definition: FunctionCaller.h:293
lldb_private::DiagnosticManager
Definition: DiagnosticManager.h:93
lldb_private::FunctionCaller::m_member_offsets
std::vector< uint64_t > m_member_offsets
The offset of each member in the struct, in bytes.
Definition: FunctionCaller.h:325
lldb_private::FunctionCaller::LocalVariables
ExpressionVariableList * LocalVariables()
Return the object that the parser should use when registering local variables.
Definition: FunctionCaller.h:278
lldb_private::CompilerType
Generic representation of a type in a programming language.
Definition: CompilerType.h:33
lldb_private::FunctionCaller::m_function_return_type
CompilerType m_function_return_type
The opaque clang qual type for the function return type.
Definition: FunctionCaller.h:306
lldb_private::FunctionCaller::m_function_addr
Address m_function_addr
If we don't have the FunctionSP, we at least need the address & return type.
Definition: FunctionCaller.h:304
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::FunctionCaller::ID
static char ID
Definition: FunctionCaller.h:58
lldb_private::FunctionCaller::ExecuteFunction
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.
Definition: FunctionCaller.cpp:313
lldb_private::FunctionCaller::m_JITted
bool m_JITted
True if the wrapper function has already been JIT-compiled.
Definition: FunctionCaller.h:334
lldb_private::FunctionCaller::GetThreadPlanToCallFunction
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.
Definition: FunctionCaller.cpp:228
ExpressionParser.h
lldb_private::FunctionCaller::m_compiled
bool m_compiled
True if the wrapper function has already been parsed.
Definition: FunctionCaller.h:332
lldb_private::FunctionCaller::isA
bool isA(const void *ClassID) const override
Definition: FunctionCaller.h:61
lldb_private::FunctionCaller::Text
const char * Text() override
Interface for ClangExpression.
Definition: FunctionCaller.h:268
lldb_private::FunctionCaller::FunctionName
const char * FunctionName() override
Return the function name that should be used for executing the expression.
Definition: FunctionCaller.h:272
Expression.h
lldb_private::Expression
Definition: Expression.h:33
Value.h
lldb_private::FunctionCaller
Definition: FunctionCaller.h:56
lldb_private::FunctionCaller::m_struct_valid
bool m_struct_valid
True if the ASTStructExtractor has populated the variables below.
Definition: FunctionCaller.h:319