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 
20 namespace 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,
30 class UtilityFunction : public Expression {
31   // LLVM RTTI support
32   static char ID;
33 
34 public:
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 
113 protected:
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