1 //===-- UtilityFunction.h ----------------------------------------*- C++ -*-===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 10 #ifndef liblldb_UtilityFunction_h_ 11 #define liblldb_UtilityFunction_h_ 12 13 // C Includes 14 // C++ Includes 15 #include <memory> 16 #include <string> 17 18 // Other libraries and framework includes 19 // Project includes 20 #include "lldb/lldb-forward.h" 21 #include "lldb/lldb-private.h" 22 #include "lldb/Expression/Expression.h" 23 24 namespace lldb_private 25 { 26 27 //---------------------------------------------------------------------- 28 /// @class UtilityFunction UtilityFunction.h "lldb/Expression/UtilityFunction.h" 29 /// @brief Encapsulates a bit of source code that provides a function that is callable 30 /// 31 /// LLDB uses expressions for various purposes, notably to call functions 32 /// and as a backend for the expr command. UtilityFunction encapsulates 33 /// a self-contained function meant to be used from other code. Utility 34 /// functions can perform error-checking for ClangUserExpressions, 35 //---------------------------------------------------------------------- 36 class UtilityFunction : public Expression 37 { 38 public: 39 //------------------------------------------------------------------ 40 /// Constructor 41 /// 42 /// @param[in] text 43 /// The text of the function. Must be a full translation unit. 44 /// 45 /// @param[in] name 46 /// The name of the function, as used in the text. 47 //------------------------------------------------------------------ 48 UtilityFunction (ExecutionContextScope &exe_scope, 49 const char *text, 50 const char *name); 51 52 ~UtilityFunction() override; 53 54 //------------------------------------------------------------------ 55 /// Install the utility function into a process 56 /// 57 /// @param[in] error_stream 58 /// A stream to print parse errors and warnings to. 59 /// 60 /// @param[in] exe_ctx 61 /// The execution context to install the utility function to. 62 /// 63 /// @return 64 /// True on success (no errors); false otherwise. 65 //------------------------------------------------------------------ 66 virtual bool 67 Install (Stream &error_stream, ExecutionContext &exe_ctx) = 0; 68 69 //------------------------------------------------------------------ 70 /// Check whether the given PC is inside the function 71 /// 72 /// Especially useful if the function dereferences nullptr to indicate a failed 73 /// assert. 74 /// 75 /// @param[in] pc 76 /// The program counter to check. 77 /// 78 /// @return 79 /// True if the program counter falls within the function's bounds; 80 /// false if not (or the function is not JIT compiled) 81 //------------------------------------------------------------------ 82 bool 83 ContainsAddress (lldb::addr_t address) 84 { 85 // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, 86 // so this always returns false if the function is not JIT compiled yet 87 return (address >= m_jit_start_addr && address < m_jit_end_addr); 88 } 89 90 //------------------------------------------------------------------ 91 /// Return the string that the parser should parse. Must be a full 92 /// translation unit. 93 //------------------------------------------------------------------ 94 const char * 95 Text() override 96 { 97 return m_function_text.c_str(); 98 } 99 100 //------------------------------------------------------------------ 101 /// Return the function name that should be used for executing the 102 /// expression. Text() should contain the definition of this 103 /// function. 104 //------------------------------------------------------------------ 105 const char * 106 FunctionName() override 107 { 108 return m_function_name.c_str(); 109 } 110 111 //------------------------------------------------------------------ 112 /// Return the object that the parser should use when registering 113 /// local variables. May be nullptr if the Expression doesn't care. 114 //------------------------------------------------------------------ 115 ExpressionVariableList * 116 LocalVariables () 117 { 118 return nullptr; 119 } 120 121 //------------------------------------------------------------------ 122 /// Return true if validation code should be inserted into the 123 /// expression. 124 //------------------------------------------------------------------ 125 bool 126 NeedsValidation() override 127 { 128 return false; 129 } 130 131 //------------------------------------------------------------------ 132 /// Return true if external variables in the expression should be 133 /// resolved. 134 //------------------------------------------------------------------ 135 bool 136 NeedsVariableResolution() override 137 { 138 return false; 139 } 140 141 // This makes the function caller function. 142 FunctionCaller * 143 MakeFunctionCaller(const CompilerType &return_type, const ValueList &arg_value_list, Error &error); 144 145 // This one retrieves the function caller that is already made. If you haven't made it yet, this returns nullptr 146 FunctionCaller * 147 GetFunctionCaller() 148 { 149 return m_caller_up.get(); 150 } 151 152 protected: 153 std::shared_ptr<IRExecutionUnit> m_execution_unit_sp; 154 lldb::ModuleWP m_jit_module_wp; 155 std::string m_function_text; ///< The text of the function. Must be a well-formed translation unit. 156 std::string m_function_name; ///< The name of the function. 157 std::unique_ptr<FunctionCaller> m_caller_up; 158 }; 159 160 } // namespace lldb_private 161 162 #endif // liblldb_UtilityFunction_h_ 163