xref: /openbsd-src/gnu/llvm/lldb/include/lldb/Expression/FunctionCaller.h (revision dda2819751e49c83612958492e38917049128b41)
1061da546Spatrick //===-- FunctionCaller.h ----------------------------------------*- C++ -*-===//
2061da546Spatrick //
3061da546Spatrick // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4061da546Spatrick // See https://llvm.org/LICENSE.txt for license information.
5061da546Spatrick // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6061da546Spatrick //
7061da546Spatrick //===----------------------------------------------------------------------===//
8061da546Spatrick 
9*dda28197Spatrick #ifndef LLDB_EXPRESSION_FUNCTIONCALLER_H
10*dda28197Spatrick #define LLDB_EXPRESSION_FUNCTIONCALLER_H
11061da546Spatrick 
12061da546Spatrick #include <list>
13061da546Spatrick #include <memory>
14061da546Spatrick #include <string>
15061da546Spatrick #include <vector>
16061da546Spatrick 
17061da546Spatrick #include "lldb/Core/Address.h"
18061da546Spatrick #include "lldb/Core/Value.h"
19061da546Spatrick #include "lldb/Expression/Expression.h"
20061da546Spatrick #include "lldb/Expression/ExpressionParser.h"
21061da546Spatrick #include "lldb/Symbol/CompilerType.h"
22061da546Spatrick 
23061da546Spatrick namespace lldb_private {
24061da546Spatrick 
25061da546Spatrick /// \class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h"
26061da546Spatrick /// Encapsulates a function that can be called.
27061da546Spatrick ///
28061da546Spatrick /// A given FunctionCaller object can handle a single function signature.
29061da546Spatrick /// Once constructed, it can set up any number of concurrent calls to
30061da546Spatrick /// functions with that signature.
31061da546Spatrick ///
32061da546Spatrick /// It performs the call by synthesizing a structure that contains the pointer
33061da546Spatrick /// to the function and the arguments that should be passed to that function,
34061da546Spatrick /// and producing a special-purpose JIT-compiled function that accepts a void*
35061da546Spatrick /// pointing to this struct as its only argument and calls the function in the
36061da546Spatrick /// struct with the written arguments.  This method lets Clang handle the
37061da546Spatrick /// vagaries of function calling conventions.
38061da546Spatrick ///
39061da546Spatrick /// The simplest use of the FunctionCaller is to construct it with a function
40061da546Spatrick /// representative of the signature you want to use, then call
41061da546Spatrick /// ExecuteFunction(ExecutionContext &, Stream &, Value &).
42061da546Spatrick ///
43061da546Spatrick /// If you need to reuse the arguments for several calls, you can call
44061da546Spatrick /// InsertFunction() followed by WriteFunctionArguments(), which will return
45061da546Spatrick /// the location of the args struct for the wrapper function in args_addr_ref.
46061da546Spatrick ///
47061da546Spatrick /// If you need to call the function on the thread plan stack, you can also
48061da546Spatrick /// call InsertFunction() followed by GetThreadPlanToCallFunction().
49061da546Spatrick ///
50061da546Spatrick /// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a
51061da546Spatrick /// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated
52061da546Spatrick /// and its address returned in that variable.
53061da546Spatrick ///
54061da546Spatrick /// Any of the methods that take arg_addr_ptr can be passed nullptr, and the
55061da546Spatrick /// argument space will be managed for you.
56061da546Spatrick class FunctionCaller : public Expression {
57061da546Spatrick   // LLVM RTTI support
58061da546Spatrick   static char ID;
59061da546Spatrick 
60061da546Spatrick public:
isA(const void * ClassID)61061da546Spatrick   bool isA(const void *ClassID) const override { return ClassID == &ID; }
classof(const Expression * obj)62061da546Spatrick   static bool classof(const Expression *obj) { return obj->isA(&ID); }
63061da546Spatrick 
64061da546Spatrick   /// Constructor
65061da546Spatrick   ///
66061da546Spatrick   /// \param[in] exe_scope
67061da546Spatrick   ///     An execution context scope that gets us at least a target and
68061da546Spatrick   ///     process.
69061da546Spatrick   ///
70061da546Spatrick   /// \param[in] return_type
71061da546Spatrick   ///     An opaque Clang QualType for the function result.  Should be
72061da546Spatrick   ///     defined in ast_context.
73061da546Spatrick   ///
74061da546Spatrick   /// \param[in] function_address
75061da546Spatrick   ///     The address of the function to call.
76061da546Spatrick   ///
77061da546Spatrick   /// \param[in] arg_value_list
78061da546Spatrick   ///     The default values to use when calling this function.  Can
79061da546Spatrick   ///     be overridden using WriteFunctionArguments().
80061da546Spatrick   FunctionCaller(ExecutionContextScope &exe_scope,
81061da546Spatrick                  const CompilerType &return_type,
82061da546Spatrick                  const Address &function_address,
83061da546Spatrick                  const ValueList &arg_value_list, const char *name);
84061da546Spatrick 
85061da546Spatrick   /// Destructor
86061da546Spatrick   ~FunctionCaller() override;
87061da546Spatrick 
88061da546Spatrick   /// Compile the wrapper function
89061da546Spatrick   ///
90061da546Spatrick   /// \param[in] thread_to_use_sp
91061da546Spatrick   ///     Compilation might end up calling functions.  Pass in the thread you
92061da546Spatrick   ///     want the compilation to use.  If you pass in an empty ThreadSP it will
93061da546Spatrick   ///     use the currently selected thread.
94061da546Spatrick   ///
95061da546Spatrick   /// \param[in] diagnostic_manager
96061da546Spatrick   ///     The diagnostic manager to report parser errors to.
97061da546Spatrick   ///
98061da546Spatrick   /// \return
99061da546Spatrick   ///     The number of errors.
100061da546Spatrick   virtual unsigned CompileFunction(lldb::ThreadSP thread_to_use_sp,
101061da546Spatrick                                    DiagnosticManager &diagnostic_manager) = 0;
102061da546Spatrick 
103061da546Spatrick   /// Insert the default function wrapper and its default argument struct
104061da546Spatrick   ///
105061da546Spatrick   /// \param[in] exe_ctx
106061da546Spatrick   ///     The execution context to insert the function and its arguments
107061da546Spatrick   ///     into.
108061da546Spatrick   ///
109061da546Spatrick   /// \param[in,out] args_addr_ref
110061da546Spatrick   ///     The address of the structure to write the arguments into.  May
111061da546Spatrick   ///     be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
112061da546Spatrick   ///     and args_addr_ref is pointed to it.
113061da546Spatrick   ///
114061da546Spatrick   /// \param[in] diagnostic_manager
115061da546Spatrick   ///     The diagnostic manager to report errors to.
116061da546Spatrick   ///
117061da546Spatrick   /// \return
118061da546Spatrick   ///     True on success; false otherwise.
119061da546Spatrick   bool InsertFunction(ExecutionContext &exe_ctx, lldb::addr_t &args_addr_ref,
120061da546Spatrick                       DiagnosticManager &diagnostic_manager);
121061da546Spatrick 
122061da546Spatrick   /// Insert the default function wrapper (using the JIT)
123061da546Spatrick   ///
124061da546Spatrick   /// \param[in] exe_ctx
125061da546Spatrick   ///     The execution context to insert the function and its arguments
126061da546Spatrick   ///     into.
127061da546Spatrick   ///
128061da546Spatrick   /// \param[in] diagnostic_manager
129061da546Spatrick   ///     The diagnostic manager to report errors to.
130061da546Spatrick   ///
131061da546Spatrick   /// \return
132061da546Spatrick   ///     True on success; false otherwise.
133061da546Spatrick   bool WriteFunctionWrapper(ExecutionContext &exe_ctx,
134061da546Spatrick                             DiagnosticManager &diagnostic_manager);
135061da546Spatrick 
136061da546Spatrick   /// Insert the default function argument struct
137061da546Spatrick   ///
138061da546Spatrick   /// \param[in] exe_ctx
139061da546Spatrick   ///     The execution context to insert the function and its arguments
140061da546Spatrick   ///     into.
141061da546Spatrick   ///
142061da546Spatrick   /// \param[in,out] args_addr_ref
143061da546Spatrick   ///     The address of the structure to write the arguments into.  May
144061da546Spatrick   ///     be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
145061da546Spatrick   ///     and args_addr_ref is pointed to it.
146061da546Spatrick   ///
147061da546Spatrick   /// \param[in] diagnostic_manager
148061da546Spatrick   ///     The diagnostic manager to report errors to.
149061da546Spatrick   ///
150061da546Spatrick   /// \return
151061da546Spatrick   ///     True on success; false otherwise.
152061da546Spatrick   bool WriteFunctionArguments(ExecutionContext &exe_ctx,
153061da546Spatrick                               lldb::addr_t &args_addr_ref,
154061da546Spatrick                               DiagnosticManager &diagnostic_manager);
155061da546Spatrick 
156061da546Spatrick   /// Insert an argument struct with a non-default function address and non-
157061da546Spatrick   /// default argument values
158061da546Spatrick   ///
159061da546Spatrick   /// \param[in] exe_ctx
160061da546Spatrick   ///     The execution context to insert the function and its arguments
161061da546Spatrick   ///     into.
162061da546Spatrick   ///
163061da546Spatrick   /// \param[in,out] args_addr_ref
164061da546Spatrick   ///     The address of the structure to write the arguments into.  May
165061da546Spatrick   ///     be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated
166061da546Spatrick   ///     and args_addr_ref is pointed at it.
167061da546Spatrick   ///
168061da546Spatrick   /// \param[in] arg_values
169061da546Spatrick   ///     The values of the function's arguments.
170061da546Spatrick   ///
171061da546Spatrick   /// \param[in] diagnostic_manager
172061da546Spatrick   ///     The diagnostic manager to report errors to.
173061da546Spatrick   ///
174061da546Spatrick   /// \return
175061da546Spatrick   ///     True on success; false otherwise.
176061da546Spatrick   bool WriteFunctionArguments(ExecutionContext &exe_ctx,
177061da546Spatrick                               lldb::addr_t &args_addr_ref,
178061da546Spatrick                               ValueList &arg_values,
179061da546Spatrick                               DiagnosticManager &diagnostic_manager);
180061da546Spatrick 
181061da546Spatrick   /// Run the function this FunctionCaller was created with.
182061da546Spatrick   ///
183061da546Spatrick   /// This is the full version.
184061da546Spatrick   ///
185061da546Spatrick   /// \param[in] exe_ctx
186061da546Spatrick   ///     The thread & process in which this function will run.
187061da546Spatrick   ///
188061da546Spatrick   /// \param[in] args_addr_ptr
189061da546Spatrick   ///     If nullptr, the function will take care of allocating & deallocating
190061da546Spatrick   ///     the wrapper
191061da546Spatrick   ///     args structure.  Otherwise, if set to LLDB_INVALID_ADDRESS, a new
192061da546Spatrick   ///     structure
193061da546Spatrick   ///     will be allocated, filled and the address returned to you.  You are
194061da546Spatrick   ///     responsible
195061da546Spatrick   ///     for deallocating it.  And if passed in with a value other than
196061da546Spatrick   ///     LLDB_INVALID_ADDRESS,
197061da546Spatrick   ///     this should point to an already allocated structure with the values
198061da546Spatrick   ///     already written.
199061da546Spatrick   ///
200061da546Spatrick   /// \param[in] diagnostic_manager
201061da546Spatrick   ///     The diagnostic manager to report errors to.
202061da546Spatrick   ///
203061da546Spatrick   /// \param[in] options
204061da546Spatrick   ///     The options for this expression execution.
205061da546Spatrick   ///
206061da546Spatrick   /// \param[out] results
207061da546Spatrick   ///     The result value will be put here after running the function.
208061da546Spatrick   ///
209061da546Spatrick   /// \return
210061da546Spatrick   ///     Returns one of the ExpressionResults enum indicating function call
211061da546Spatrick   ///     status.
212061da546Spatrick   lldb::ExpressionResults
213061da546Spatrick   ExecuteFunction(ExecutionContext &exe_ctx, lldb::addr_t *args_addr_ptr,
214061da546Spatrick                   const EvaluateExpressionOptions &options,
215061da546Spatrick                   DiagnosticManager &diagnostic_manager, Value &results);
216061da546Spatrick 
217061da546Spatrick   /// Get a thread plan to run the function this FunctionCaller was created
218061da546Spatrick   /// with.
219061da546Spatrick   ///
220061da546Spatrick   /// \param[in] exe_ctx
221061da546Spatrick   ///     The execution context to insert the function and its arguments
222061da546Spatrick   ///     into.
223061da546Spatrick   ///
224061da546Spatrick   /// \param[in] args_addr
225061da546Spatrick   ///     The address of the argument struct.
226061da546Spatrick   ///
227061da546Spatrick   /// \param[in] diagnostic_manager
228061da546Spatrick   ///     The diagnostic manager to report errors to.
229061da546Spatrick   ///
230061da546Spatrick   /// \return
231061da546Spatrick   ///     A ThreadPlan shared pointer for executing the function.
232061da546Spatrick   lldb::ThreadPlanSP
233061da546Spatrick   GetThreadPlanToCallFunction(ExecutionContext &exe_ctx, lldb::addr_t args_addr,
234061da546Spatrick                               const EvaluateExpressionOptions &options,
235061da546Spatrick                               DiagnosticManager &diagnostic_manager);
236061da546Spatrick 
237061da546Spatrick   /// Get the result of the function from its struct
238061da546Spatrick   ///
239061da546Spatrick   /// \param[in] exe_ctx
240061da546Spatrick   ///     The execution context to retrieve the result from.
241061da546Spatrick   ///
242061da546Spatrick   /// \param[in] args_addr
243061da546Spatrick   ///     The address of the argument struct.
244061da546Spatrick   ///
245061da546Spatrick   /// \param[out] ret_value
246061da546Spatrick   ///     The value returned by the function.
247061da546Spatrick   ///
248061da546Spatrick   /// \return
249061da546Spatrick   ///     True on success; false otherwise.
250061da546Spatrick   bool FetchFunctionResults(ExecutionContext &exe_ctx, lldb::addr_t args_addr,
251061da546Spatrick                             Value &ret_value);
252061da546Spatrick 
253061da546Spatrick   /// Deallocate the arguments structure
254061da546Spatrick   ///
255061da546Spatrick   /// \param[in] exe_ctx
256061da546Spatrick   ///     The execution context to insert the function and its arguments
257061da546Spatrick   ///     into.
258061da546Spatrick   ///
259061da546Spatrick   /// \param[in] args_addr
260061da546Spatrick   ///     The address of the argument struct.
261061da546Spatrick   void DeallocateFunctionResults(ExecutionContext &exe_ctx,
262061da546Spatrick                                  lldb::addr_t args_addr);
263061da546Spatrick 
264061da546Spatrick   /// Interface for ClangExpression
265061da546Spatrick 
266061da546Spatrick   /// Return the string that the parser should parse.  Must be a full
267061da546Spatrick   /// translation unit.
Text()268061da546Spatrick   const char *Text() override { return m_wrapper_function_text.c_str(); }
269061da546Spatrick 
270061da546Spatrick   /// Return the function name that should be used for executing the
271061da546Spatrick   /// expression.  Text() should contain the definition of this function.
FunctionName()272061da546Spatrick   const char *FunctionName() override {
273061da546Spatrick     return m_wrapper_function_name.c_str();
274061da546Spatrick   }
275061da546Spatrick 
276061da546Spatrick   /// Return the object that the parser should use when registering local
277061da546Spatrick   /// variables. May be nullptr if the Expression doesn't care.
LocalVariables()278061da546Spatrick   ExpressionVariableList *LocalVariables() { return nullptr; }
279061da546Spatrick 
280061da546Spatrick   /// Return true if validation code should be inserted into the expression.
NeedsValidation()281061da546Spatrick   bool NeedsValidation() override { return false; }
282061da546Spatrick 
283061da546Spatrick   /// Return true if external variables in the expression should be resolved.
NeedsVariableResolution()284061da546Spatrick   bool NeedsVariableResolution() override { return false; }
285061da546Spatrick 
GetArgumentValues()286061da546Spatrick   ValueList GetArgumentValues() const { return m_arg_values; }
287061da546Spatrick 
288061da546Spatrick protected:
289061da546Spatrick   // Note: the parser needs to be destructed before the execution unit, so
290061da546Spatrick   // declare the execution unit first.
291061da546Spatrick   std::shared_ptr<IRExecutionUnit> m_execution_unit_sp;
292061da546Spatrick   std::unique_ptr<ExpressionParser>
293061da546Spatrick       m_parser; ///< The parser responsible for compiling the function.
294061da546Spatrick                 ///< This will get made in CompileFunction, so it is
295061da546Spatrick                 ///< safe to access it after that.
296061da546Spatrick 
297061da546Spatrick   lldb::ModuleWP m_jit_module_wp;
298061da546Spatrick   std::string
299061da546Spatrick       m_name; ///< The name of this clang function - for debugging purposes.
300061da546Spatrick 
301061da546Spatrick   Function *m_function_ptr; ///< The function we're going to call. May be
302061da546Spatrick                             ///nullptr if we don't have debug info for the
303061da546Spatrick                             ///function.
304061da546Spatrick   Address m_function_addr;  ///< If we don't have the FunctionSP, we at least
305061da546Spatrick                             ///need the address & return type.
306061da546Spatrick   CompilerType m_function_return_type; ///< The opaque clang qual type for the
307061da546Spatrick                                        ///function return type.
308061da546Spatrick 
309061da546Spatrick   std::string m_wrapper_function_name; ///< The name of the wrapper function.
310061da546Spatrick   std::string
311061da546Spatrick       m_wrapper_function_text;       ///< The contents of the wrapper function.
312061da546Spatrick   std::string m_wrapper_struct_name; ///< The name of the struct that contains
313061da546Spatrick                                      ///the target function address, arguments,
314061da546Spatrick                                      ///and result.
315061da546Spatrick   std::list<lldb::addr_t> m_wrapper_args_addrs; ///< The addresses of the
316061da546Spatrick                                                 ///arguments to the wrapper
317061da546Spatrick                                                 ///function.
318061da546Spatrick 
319061da546Spatrick   bool m_struct_valid; ///< True if the ASTStructExtractor has populated the
320061da546Spatrick                        ///variables below.
321061da546Spatrick 
322061da546Spatrick   /// These values are populated by the ASTStructExtractor
323061da546Spatrick   size_t m_struct_size; ///< The size of the argument struct, in bytes.
324061da546Spatrick   std::vector<uint64_t>
325061da546Spatrick       m_member_offsets; ///< The offset of each member in the struct, in bytes.
326061da546Spatrick   uint64_t m_return_size;   ///< The size of the result variable, in bytes.
327061da546Spatrick   uint64_t m_return_offset; ///< The offset of the result variable in the
328061da546Spatrick                             ///struct, in bytes.
329061da546Spatrick 
330061da546Spatrick   ValueList m_arg_values; ///< The default values of the arguments.
331061da546Spatrick 
332061da546Spatrick   bool m_compiled; ///< True if the wrapper function has already been parsed.
333061da546Spatrick   bool
334061da546Spatrick       m_JITted; ///< True if the wrapper function has already been JIT-compiled.
335061da546Spatrick };
336061da546Spatrick 
337061da546Spatrick } // namespace lldb_private
338061da546Spatrick 
339*dda28197Spatrick #endif // LLDB_EXPRESSION_FUNCTIONCALLER_H
340