1//===-- UtilityFunction.h ----------------------------------------*- C++
2//-*-===//
3//
4// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5// See https://llvm.org/LICENSE.txt for license information.
6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef LLDB_EXPRESSION_UTILITYFUNCTION_H
11#define LLDB_EXPRESSION_UTILITYFUNCTION_H
12
13#include <memory>
14#include <string>
15
16#include "lldb/Expression/Expression.h"
17#include "lldb/lldb-forward.h"
18#include "lldb/lldb-private.h"
19
20namespace lldb_private {
21
22/// \class UtilityFunction UtilityFunction.h
23/// "lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that
24/// provides a function that is callable
25///
26/// LLDB uses expressions for various purposes, notably to call functions
27/// and as a backend for the expr command.  UtilityFunction encapsulates a
28/// self-contained function meant to be used from other code.  Utility
29/// functions can perform error-checking for ClangUserExpressions,
30class UtilityFunction : public Expression {
31  // LLVM RTTI support
32  static char ID;
33
34public:
35  bool isA(const void *ClassID) const override { return ClassID == &ID; }
36  static bool classof(const Expression *obj) { return obj->isA(&ID); }
37
38  /// Constructor
39  ///
40  /// \param[in] text
41  ///     The text of the function.  Must be a full translation unit.
42  ///
43  /// \param[in] name
44  ///     The name of the function, as used in the text.
45  ///
46  /// \param[in] enable_debugging
47  ///     Enable debugging of this function.
48  UtilityFunction(ExecutionContextScope &exe_scope, std::string text,
49                  std::string name, bool enable_debugging);
50
51  ~UtilityFunction() override;
52
53  /// Install the utility function into a process
54  ///
55  /// \param[in] diagnostic_manager
56  ///     A diagnostic manager to print parse errors and warnings to.
57  ///
58  /// \param[in] exe_ctx
59  ///     The execution context to install the utility function to.
60  ///
61  /// \return
62  ///     True on success (no errors); false otherwise.
63  virtual bool Install(DiagnosticManager &diagnostic_manager,
64                       ExecutionContext &exe_ctx) = 0;
65
66  /// Check whether the given address is inside the function
67  ///
68  /// Especially useful if the function dereferences nullptr to indicate a
69  /// failed assert.
70  ///
71  /// \param[in] address
72  ///     The address to check.
73  ///
74  /// \return
75  ///     True if the address falls within the function's bounds;
76  ///     false if not (or the function is not JIT compiled)
77  bool ContainsAddress(lldb::addr_t address) {
78    // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, so
79    // this always returns false if the function is not JIT compiled yet
80    return (address >= m_jit_start_addr && address < m_jit_end_addr);
81  }
82
83  /// Return the string that the parser should parse.  Must be a full
84  /// translation unit.
85  const char *Text() override { return m_function_text.c_str(); }
86
87  /// Return the function name that should be used for executing the
88  /// expression.  Text() should contain the definition of this function.
89  const char *FunctionName() override { return m_function_name.c_str(); }
90
91  /// Return the object that the parser should use when registering local
92  /// variables. May be nullptr if the Expression doesn't care.
93  ExpressionVariableList *LocalVariables() { return nullptr; }
94
95  /// Return true if validation code should be inserted into the expression.
96  bool NeedsValidation() override { return false; }
97
98  /// Return true if external variables in the expression should be resolved.
99  bool NeedsVariableResolution() override { return false; }
100
101  // This makes the function caller function. Pass in the ThreadSP if you have
102  // one available, compilation can end up calling code (e.g. to look up
103  // indirect functions) and we don't want this to wander onto another thread.
104  FunctionCaller *MakeFunctionCaller(const CompilerType &return_type,
105                                     const ValueList &arg_value_list,
106                                     lldb::ThreadSP compilation_thread,
107                                     Status &error);
108
109  // This one retrieves the function caller that is already made.  If you
110  // haven't made it yet, this returns nullptr
111  FunctionCaller *GetFunctionCaller() { return m_caller_up.get(); }
112
113protected:
114  std::shared_ptr<IRExecutionUnit> m_execution_unit_sp;
115  lldb::ModuleWP m_jit_module_wp;
116  /// The text of the function.  Must be a well-formed translation unit.
117  std::string m_function_text;
118  /// The name of the function.
119  std::string m_function_name;
120  std::unique_ptr<FunctionCaller> m_caller_up;
121};
122
123} // namespace lldb_private
124
125#endif // LLDB_EXPRESSION_UTILITYFUNCTION_H
126