1 //===-- UtilityFunction.h ----------------------------------------*- C++ 2 //-*-===// 3 // 4 // The LLVM Compiler Infrastructure 5 // 6 // This file is distributed under the University of Illinois Open Source 7 // License. See LICENSE.TXT for details. 8 // 9 //===----------------------------------------------------------------------===// 10 11 #ifndef liblldb_UtilityFunction_h_ 12 #define liblldb_UtilityFunction_h_ 13 14 // C Includes 15 // C++ Includes 16 #include <memory> 17 #include <string> 18 19 // Other libraries and framework includes 20 // Project includes 21 #include "lldb/Expression/Expression.h" 22 #include "lldb/lldb-forward.h" 23 #include "lldb/lldb-private.h" 24 25 namespace lldb_private { 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 30 /// callable 31 /// 32 /// LLDB uses expressions for various purposes, notably to call functions 33 /// and as a backend for the expr command. UtilityFunction encapsulates 34 /// a self-contained function meant to be used from other code. Utility 35 /// functions can perform error-checking for ClangUserExpressions, 36 //---------------------------------------------------------------------- 37 class UtilityFunction : public Expression { 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, const char *text, 49 const char *name); 50 51 ~UtilityFunction() override; 52 53 //------------------------------------------------------------------ 54 /// Install the utility function into a process 55 /// 56 /// @param[in] diagnostic_manager 57 /// A diagnostic manager to print parse errors and warnings to. 58 /// 59 /// @param[in] exe_ctx 60 /// The execution context to install the utility function to. 61 /// 62 /// @return 63 /// True on success (no errors); false otherwise. 64 //------------------------------------------------------------------ 65 virtual bool Install(DiagnosticManager &diagnostic_manager, 66 ExecutionContext &exe_ctx) = 0; 67 68 //------------------------------------------------------------------ 69 /// Check whether the given PC is inside the function 70 /// 71 /// Especially useful if the function dereferences nullptr to indicate a 72 /// 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 ContainsAddress(lldb::addr_t address) { 83 // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, 84 // so this always returns false if the function is not JIT compiled yet 85 return (address >= m_jit_start_addr && address < m_jit_end_addr); 86 } 87 88 //------------------------------------------------------------------ 89 /// Return the string that the parser should parse. Must be a full 90 /// translation unit. 91 //------------------------------------------------------------------ 92 const char *Text() override { return m_function_text.c_str(); } 93 94 //------------------------------------------------------------------ 95 /// Return the function name that should be used for executing the 96 /// expression. Text() should contain the definition of this 97 /// function. 98 //------------------------------------------------------------------ 99 const char *FunctionName() override { return m_function_name.c_str(); } 100 101 //------------------------------------------------------------------ 102 /// Return the object that the parser should use when registering 103 /// local variables. May be nullptr if the Expression doesn't care. 104 //------------------------------------------------------------------ 105 ExpressionVariableList *LocalVariables() { return nullptr; } 106 107 //------------------------------------------------------------------ 108 /// Return true if validation code should be inserted into the 109 /// expression. 110 //------------------------------------------------------------------ 111 bool NeedsValidation() override { return false; } 112 113 //------------------------------------------------------------------ 114 /// Return true if external variables in the expression should be 115 /// resolved. 116 //------------------------------------------------------------------ 117 bool NeedsVariableResolution() override { return false; } 118 119 // This makes the function caller function. 120 // Pass in the ThreadSP if you have one available, compilation can end up 121 // calling code (e.g. to look up indirect 122 // functions) and we don't want this to wander onto another thread. 123 FunctionCaller *MakeFunctionCaller(const CompilerType &return_type, 124 const ValueList &arg_value_list, 125 lldb::ThreadSP compilation_thread, 126 Status &error); 127 128 // This one retrieves the function caller that is already made. If you 129 // haven't made it yet, this returns nullptr 130 FunctionCaller *GetFunctionCaller() { return m_caller_up.get(); } 131 132 protected: 133 std::shared_ptr<IRExecutionUnit> m_execution_unit_sp; 134 lldb::ModuleWP m_jit_module_wp; 135 std::string m_function_text; ///< The text of the function. Must be a 136 ///well-formed translation unit. 137 std::string m_function_name; ///< The name of the function. 138 std::unique_ptr<FunctionCaller> m_caller_up; 139 }; 140 141 } // namespace lldb_private 142 143 #endif // liblldb_UtilityFunction_h_ 144