lldb/Expression/UtilityFunction.h

0001 //===-- UtilityFunction.h ----------------------------------------*- C++
0002 //-*-===//
0003 //
0004 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0005 // See https://llvm.org/LICENSE.txt for license information.
0006 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0007 //
0008 //===----------------------------------------------------------------------===//
0009
0010 #ifndef LLDB_EXPRESSION_UTILITYFUNCTION_H
0011 #define LLDB_EXPRESSION_UTILITYFUNCTION_H
0012
0013 #include <memory>
0014 #include <string>
0015
0016 #include "lldb/Expression/Expression.h"
0017 #include "lldb/lldb-forward.h"
0018 #include "lldb/lldb-private.h"
0019
0020 namespace lldb_private {
0021
0022 /// \class UtilityFunction UtilityFunction.h
0023 /// "lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that
0024 /// provides a function that is callable
0025 ///
0026 /// LLDB uses expressions for various purposes, notably to call functions
0027 /// and as a backend for the expr command.  UtilityFunction encapsulates a
0028 /// self-contained function meant to be used from other code.  Utility
0029 /// functions can perform error-checking for ClangUserExpressions,
0030 class UtilityFunction : public Expression {
0031   // LLVM RTTI support
0032   static char ID;
0033
0034 public:
0035   bool isA(const void *ClassID) const override { return ClassID == &ID; }
0036   static bool classof(const Expression *obj) { return obj->isA(&ID); }
0037
0038   /// Constructor
0039   ///
0040   /// \param[in] text
0041   ///     The text of the function.  Must be a full translation unit.
0042   ///
0043   /// \param[in] name
0044   ///     The name of the function, as used in the text.
0045   ///
0046   /// \param[in] enable_debugging
0047   ///     Enable debugging of this function.
0048   UtilityFunction(ExecutionContextScope &exe_scope, std::string text,
0049                   std::string name, bool enable_debugging);
0050
0051   ~UtilityFunction() override;
0052
0053   /// Install the utility function into a process
0054   ///
0055   /// \param[in] diagnostic_manager
0056   ///     A diagnostic manager to print parse errors and warnings to.
0057   ///
0058   /// \param[in] exe_ctx
0059   ///     The execution context to install the utility function to.
0060   ///
0061   /// \return
0062   ///     True on success (no errors); false otherwise.
0063   virtual bool Install(DiagnosticManager &diagnostic_manager,
0064                        ExecutionContext &exe_ctx) = 0;
0065
0066   /// Check whether the given address is inside the function
0067   ///
0068   /// Especially useful if the function dereferences nullptr to indicate a
0069   /// failed assert.
0070   ///
0071   /// \param[in] address
0072   ///     The address to check.
0073   ///
0074   /// \return
0075   ///     True if the address falls within the function's bounds;
0076   ///     false if not (or the function is not JIT compiled)
0077   bool ContainsAddress(lldb::addr_t address) {
0078     // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, so
0079     // this always returns false if the function is not JIT compiled yet
0080     return (address >= m_jit_start_addr && address < m_jit_end_addr);
0081   }
0082
0083   /// Return the string that the parser should parse.  Must be a full
0084   /// translation unit.
0085   const char *Text() override { return m_function_text.c_str(); }
0086
0087   /// Return the function name that should be used for executing the
0088   /// expression.  Text() should contain the definition of this function.
0089   const char *FunctionName() override { return m_function_name.c_str(); }
0090
0091   /// Return the object that the parser should use when registering local
0092   /// variables. May be nullptr if the Expression doesn't care.
0093   ExpressionVariableList *LocalVariables() { return nullptr; }
0094
0095   /// Return true if validation code should be inserted into the expression.
0096   bool NeedsValidation() override { return false; }
0097
0098   /// Return true if external variables in the expression should be resolved.
0099   bool NeedsVariableResolution() override { return false; }
0100
0101   // This makes the function caller function. Pass in the ThreadSP if you have
0102   // one available, compilation can end up calling code (e.g. to look up
0103   // indirect functions) and we don't want this to wander onto another thread.
0104   FunctionCaller *MakeFunctionCaller(const CompilerType &return_type,
0105                                      const ValueList &arg_value_list,
0106                                      lldb::ThreadSP compilation_thread,
0107                                      Status &error);
0108
0109   // This one retrieves the function caller that is already made.  If you
0110   // haven't made it yet, this returns nullptr
0111   FunctionCaller *GetFunctionCaller() { return m_caller_up.get(); }
0112
0113 protected:
0114   std::shared_ptr<IRExecutionUnit> m_execution_unit_sp;
0115   lldb::ModuleWP m_jit_module_wp;
0116   /// The text of the function.  Must be a well-formed translation unit.
0117   std::string m_function_text;
0118   /// The name of the function.
0119   std::string m_function_name;
0120   std::unique_ptr<FunctionCaller> m_caller_up;
0121 };
0122
0123 } // namespace lldb_private
0124
0125 #endif // LLDB_EXPRESSION_UTILITYFUNCTION_H