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(ClassID: &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 | |