LLDB  mainline
UtilityFunction.h
Go to the documentation of this file.
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 liblldb_UtilityFunction_h_
11 #define liblldb_UtilityFunction_h_
12 
13 #include <memory>
14 #include <string>
15 
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 public:
32  /// LLVM-style RTTI support.
33  static bool classof(const Expression *E) {
34  return E->getKind() == eKindUtilityFunction;
35  }
36 
37  /// Constructor
38  ///
39  /// \param[in] text
40  /// The text of the function. Must be a full translation unit.
41  ///
42  /// \param[in] name
43  /// The name of the function, as used in the text.
44  UtilityFunction(ExecutionContextScope &exe_scope, const char *text,
45  const char *name, ExpressionKind kind);
46 
47  ~UtilityFunction() override;
48 
49  /// Install the utility function into a process
50  ///
51  /// \param[in] diagnostic_manager
52  /// A diagnostic manager to print parse errors and warnings to.
53  ///
54  /// \param[in] exe_ctx
55  /// The execution context to install the utility function to.
56  ///
57  /// \return
58  /// True on success (no errors); false otherwise.
59  virtual bool Install(DiagnosticManager &diagnostic_manager,
60  ExecutionContext &exe_ctx) = 0;
61 
62  /// Check whether the given PC is inside the function
63  ///
64  /// Especially useful if the function dereferences nullptr to indicate a
65  /// failed assert.
66  ///
67  /// \param[in] pc
68  /// The program counter to check.
69  ///
70  /// \return
71  /// True if the program counter falls within the function's bounds;
72  /// false if not (or the function is not JIT compiled)
73  bool ContainsAddress(lldb::addr_t address) {
74  // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, so
75  // this always returns false if the function is not JIT compiled yet
76  return (address >= m_jit_start_addr && address < m_jit_end_addr);
77  }
78 
79  /// Return the string that the parser should parse. Must be a full
80  /// translation unit.
81  const char *Text() override { return m_function_text.c_str(); }
82 
83  /// Return the function name that should be used for executing the
84  /// expression. Text() should contain the definition of this function.
85  const char *FunctionName() override { return m_function_name.c_str(); }
86 
87  /// Return the object that the parser should use when registering local
88  /// variables. May be nullptr if the Expression doesn't care.
89  ExpressionVariableList *LocalVariables() { return nullptr; }
90 
91  /// Return true if validation code should be inserted into the expression.
92  bool NeedsValidation() override { return false; }
93 
94  /// Return true if external variables in the expression should be resolved.
95  bool NeedsVariableResolution() override { return false; }
96 
97  // This makes the function caller function. Pass in the ThreadSP if you have
98  // one available, compilation can end up calling code (e.g. to look up
99  // indirect functions) and we don't want this to wander onto another thread.
100  FunctionCaller *MakeFunctionCaller(const CompilerType &return_type,
101  const ValueList &arg_value_list,
102  lldb::ThreadSP compilation_thread,
103  Status &error);
104 
105  // This one retrieves the function caller that is already made. If you
106  // haven't made it yet, this returns nullptr
108 
109 protected:
110  std::shared_ptr<IRExecutionUnit> m_execution_unit_sp;
111  lldb::ModuleWP m_jit_module_wp;
112  std::string m_function_text; ///< The text of the function. Must be a
113  ///well-formed translation unit.
114  std::string m_function_name; ///< The name of the function.
115  std::unique_ptr<FunctionCaller> m_caller_up;
116 };
117 
118 } // namespace lldb_private
119 
120 #endif // liblldb_UtilityFunction_h_
ExpressionKind
Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
Definition: Expression.h:36
lldb::addr_t m_jit_start_addr
An expression might have a process, but it doesn&#39;t need to (e.g.
Definition: Expression.h:104
bool ContainsAddress(lldb::addr_t address)
Check whether the given PC is inside the function.
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
bool NeedsValidation() override
Return true if validation code should be inserted into the expression.
std::string m_function_text
The text of the function.
FunctionCaller * GetFunctionCaller()
static bool classof(const Expression *E)
LLVM-style RTTI support.
UtilityFunction(ExecutionContextScope &exe_scope, const char *text, const char *name, ExpressionKind kind)
Constructor.
Encapsulates a single expression for use in lldb.
Definition: Expression.h:33
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
ExpressionVariableList * LocalVariables()
Return the object that the parser should use when registering local variables.
ExpressionKind getKind() const
LLVM-style RTTI support.
Definition: Expression.h:94
virtual bool Install(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx)=0
Install the utility function into a process.
std::shared_ptr< IRExecutionUnit > m_execution_unit_sp
std::string m_function_name
The name of the function.
"lldb/Expression/ExpressionVariable.h" A list of variable references.
FunctionCaller * MakeFunctionCaller(const CompilerType &return_type, const ValueList &arg_value_list, lldb::ThreadSP compilation_thread, Status &error)
Encapsulates a function that can be called.
"lldb/Target/ExecutionContextScope.h" Inherit from this if your object can reconstruct its execution ...
const char * FunctionName() override
Return the function name that should be used for executing the expression.
lldb::addr_t m_jit_end_addr
The address of the JITted function within the JIT allocation.
Definition: Expression.h:107
uint64_t addr_t
Definition: lldb-types.h:83
const char * Text() override
Return the string that the parser should parse.
std::unique_ptr< FunctionCaller > m_caller_up
"lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that provides a function that i...
bool NeedsVariableResolution() override
Return true if external variables in the expression should be resolved.
An error handling class.
Definition: Status.h:44