//===-- IRForTarget.h ---------------------------------------------*- C++
//-*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_IRForTarget_h_
#define liblldb_IRForTarget_h_

#include "lldb/Core/ClangForward.h"
#include "lldb/Symbol/TaggedASTType.h"
#include "lldb/Utility/ConstString.h"
#include "lldb/Utility/Status.h"
#include "lldb/Utility/Stream.h"
#include "lldb/Utility/StreamString.h"
#include "lldb/lldb-public.h"
#include "llvm/IR/DerivedTypes.h"
#include "llvm/Pass.h"

#include <functional>
#include <map>

namespace llvm {
class BasicBlock;
class CallInst;
class Constant;
class ConstantInt;
class Function;
class GlobalValue;
class GlobalVariable;
class Instruction;
class Module;
class StoreInst;
class DataLayout;
class Value;
}

namespace lldb_private {
class ClangExpressionDeclMap;
class IRExecutionUnit;
class IRMemoryMap;
}

/// \class IRForTarget IRForTarget.h "lldb/Expression/IRForTarget.h"
/// Transforms the IR for a function to run in the target
///
/// Once an expression has been parsed and converted to IR, it can run in two
/// contexts: interpreted by LLDB as a DWARF location expression, or compiled
/// by the JIT and inserted into the target process for execution.
///
/// IRForTarget makes the second possible, by applying a series of
/// transformations to the IR which make it relocatable.  These
/// transformations are discussed in more detail next to their relevant
/// functions.
class IRForTarget : public llvm::ModulePass {
public:
  enum class LookupResult { Success, Fail, Ignore };

  /// Constructor
  ///
  /// \param[in] decl_map
  ///     The list of externally-referenced variables for the expression,
  ///     for use in looking up globals and allocating the argument
  ///     struct.  See the documentation for ClangExpressionDeclMap.
  ///
  /// \param[in] resolve_vars
  ///     True if the external variable references (including persistent
  ///     variables) should be resolved.  If not, only external functions
  ///     are resolved.
  ///
  /// \param[in] execution_unit
  ///     The holder for raw data associated with the expression.
  ///
  /// \param[in] error_stream
  ///     If non-NULL, a stream on which errors can be printed.
  ///
  /// \param[in] func_name
  ///     The name of the function to prepare for execution in the target.
  IRForTarget(lldb_private::ClangExpressionDeclMap *decl_map, bool resolve_vars,
              lldb_private::IRExecutionUnit &execution_unit,
              lldb_private::Stream &error_stream,
              const char *func_name = "$__lldb_expr");

  /// Destructor
  ~IRForTarget() override;

  /// Run this IR transformer on a single module
  ///
  /// Implementation of the llvm::ModulePass::runOnModule() function.
  ///
  /// \param[in] llvm_module
  ///     The module to run on.  This module is searched for the function
  ///     $__lldb_expr, and that function is passed to the passes one by
  ///     one.
  ///
  /// \return
  ///     True on success; false otherwise
  bool runOnModule(llvm::Module &llvm_module) override;

  /// Interface stub
  ///
  /// Implementation of the llvm::ModulePass::assignPassManager() function.
  void assignPassManager(llvm::PMStack &pass_mgr_stack,
                         llvm::PassManagerType pass_mgr_type =
                             llvm::PMT_ModulePassManager) override;

  /// Returns PMT_ModulePassManager
  ///
  /// Implementation of the llvm::ModulePass::getPotentialPassManagerType()
  /// function.
  llvm::PassManagerType getPotentialPassManagerType() const override;

private:
  /// Ensures that the current function's linkage is set to external.
  /// Otherwise the JIT may not return an address for it.
  ///
  /// \param[in] llvm_function
  ///     The function whose linkage is to be fixed.
  ///
  /// \return
  ///     True on success; false otherwise.
  bool FixFunctionLinkage(llvm::Function &llvm_function);

  /// A module-level pass to replace all function pointers with their
  /// integer equivalents.

  /// The top-level pass implementation
  ///
  /// \param[in] llvm_function
  ///     The function currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise.
  bool HasSideEffects(llvm::Function &llvm_function);

  /// A function-level pass to check whether the function has side
  /// effects.

  /// Get the address of a function, and a location to put the complete Value
  /// of the function if one is available.
  ///
  /// \param[in] function
  ///     The function to find the location of.
  ///
  /// \param[out] ptr
  ///     The location of the function in the target.
  ///
  /// \param[out] name
  ///     The resolved name of the function (matters for intrinsics).
  ///
  /// \param[out] value_ptr
  ///     A variable to put the function's completed Value* in, or NULL
  ///     if the Value* shouldn't be stored anywhere.
  ///
  /// \return
  ///     The pointer.
  LookupResult GetFunctionAddress(llvm::Function *function, uint64_t &ptr,
                                  lldb_private::ConstString &name,
                                  llvm::Constant **&value_ptr);

  /// A function-level pass to take the generated global value
  /// $__lldb_expr_result and make it into a persistent variable. Also see
  /// ASTResultSynthesizer.

  /// Find the NamedDecl corresponding to a Value.  This interface is exposed
  /// for the IR interpreter.
  ///
  /// \param[in] global_val
  ///     The global entity to search for
  ///
  /// \param[in] module
  ///     The module containing metadata to search
  ///
  /// \return
  ///     The corresponding variable declaration
public:
  static clang::NamedDecl *DeclForGlobal(const llvm::GlobalValue *global_val,
                                         llvm::Module *module);

private:
  clang::NamedDecl *DeclForGlobal(llvm::GlobalValue *global);

  /// Set the constant result variable m_const_result to the provided
  /// constant, assuming it can be evaluated.  The result variable will be
  /// reset to NULL later if the expression has side effects.
  ///
  /// \param[in] initializer
  ///     The constant initializer for the variable.
  ///
  /// \param[in] name
  ///     The name of the result variable.
  ///
  /// \param[in] type
  ///     The Clang type of the result variable.
  void MaybeSetConstantResult(llvm::Constant *initializer,
                              lldb_private::ConstString name,
                              lldb_private::TypeFromParser type);

  /// If the IR represents a cast of a variable, set m_const_result to the
  /// result of the cast.  The result variable will be reset to
  /// NULL latger if the expression has side effects.
  ///
  /// \param[in] type
  ///     The Clang type of the result variable.
  void MaybeSetCastResult(lldb_private::TypeFromParser type);

  /// The top-level pass implementation
  ///
  /// \param[in] llvm_function
  ///     The function currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise
  bool CreateResultVariable(llvm::Function &llvm_function);

  /// A module-level pass to find Objective-C constant strings and
  /// transform them to calls to CFStringCreateWithBytes.

  /// Rewrite a single Objective-C constant string.
  ///
  /// \param[in] NSStr
  ///     The constant NSString to be transformed
  ///
  /// \param[in] CStr
  ///     The constant C string inside the NSString.  This will be
  ///     passed as the bytes argument to CFStringCreateWithBytes.
  ///
  /// \return
  ///     True on success; false otherwise
  bool RewriteObjCConstString(llvm::GlobalVariable *NSStr,
                              llvm::GlobalVariable *CStr);

  /// The top-level pass implementation
  ///
  /// \return
  ///     True on success; false otherwise
  bool RewriteObjCConstStrings();

  /// A basic block-level pass to find all Objective-C method calls and
  /// rewrite them to use sel_registerName instead of statically allocated
  /// selectors.  The reason is that the selectors are created on the
  /// assumption that the Objective-C runtime will scan the appropriate
  /// section and prepare them.  This doesn't happen when code is copied into
  /// the target, though, and there's no easy way to induce the runtime to
  /// scan them.  So instead we get our selectors from sel_registerName.

  /// Replace a single selector reference
  ///
  /// \param[in] selector_load
  ///     The load of the statically-allocated selector.
  ///
  /// \return
  ///     True on success; false otherwise
  bool RewriteObjCSelector(llvm::Instruction *selector_load);

  /// The top-level pass implementation
  ///
  /// \param[in] basic_block
  ///     The basic block currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise
  bool RewriteObjCSelectors(llvm::BasicBlock &basic_block);

  /// A basic block-level pass to find all Objective-C class references that
  /// use the old-style Objective-C runtime and rewrite them to use
  /// class_getClass instead of statically allocated class references.

  /// Replace a single old-style class reference
  ///
  /// \param[in] class_load
  ///     The load of the statically-allocated selector.
  ///
  /// \return
  ///     True on success; false otherwise
  bool RewriteObjCClassReference(llvm::Instruction *class_load);

  /// The top-level pass implementation
  ///
  /// \param[in] basic_block
  ///     The basic block currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise
  bool RewriteObjCClassReferences(llvm::BasicBlock &basic_block);

  /// A basic block-level pass to find all newly-declared persistent
  /// variables and register them with the ClangExprDeclMap.  This allows them
  /// to be materialized and dematerialized like normal external variables.
  /// Before transformation, these persistent variables look like normal
  /// locals, so they have an allocation. This pass excises these allocations
  /// and makes references look like external references where they will be
  /// resolved -- like all other external references -- by ResolveExternals().

  /// Handle a single allocation of a persistent variable
  ///
  /// \param[in] persistent_alloc
  ///     The allocation of the persistent variable.
  ///
  /// \return
  ///     True on success; false otherwise
  bool RewritePersistentAlloc(llvm::Instruction *persistent_alloc);

  /// The top-level pass implementation
  ///
  /// \param[in] basic_block
  ///     The basic block currently being processed.
  bool RewritePersistentAllocs(llvm::BasicBlock &basic_block);

  /// A function-level pass to find all external variables and functions
  /// used in the IR.  Each found external variable is added to the struct,
  /// and each external function is resolved in place, its call replaced with
  /// a call to a function pointer whose value is the address of the function
  /// in the target process.

  /// Handle a single externally-defined variable
  ///
  /// \param[in] value
  ///     The variable.
  ///
  /// \return
  ///     True on success; false otherwise
  bool MaybeHandleVariable(llvm::Value *value);

  /// Handle a single externally-defined symbol
  ///
  /// \param[in] symbol
  ///     The symbol.
  ///
  /// \return
  ///     True on success; false otherwise
  bool HandleSymbol(llvm::Value *symbol);

  /// Handle a single externally-defined Objective-C class
  ///
  /// \param[in] classlist_reference
  ///     The reference, usually "01L_OBJC_CLASSLIST_REFERENCES_$_n"
  ///     where n (if present) is an index.
  ///
  /// \return
  ///     True on success; false otherwise
  bool HandleObjCClass(llvm::Value *classlist_reference);

  /// Handle all the arguments to a function call
  ///
  /// \param[in] call_inst
  ///     The call instruction.
  ///
  /// \return
  ///     True on success; false otherwise
  bool MaybeHandleCallArguments(llvm::CallInst *call_inst);

  /// Resolve variable references in calls to external functions
  ///
  /// \param[in] basic_block
  ///     The basic block currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise
  bool ResolveCalls(llvm::BasicBlock &basic_block);

  /// Remove calls to __cxa_atexit, which should never be generated by
  /// expressions.
  ///
  /// \param[in] basic_block
  ///     The basic block currently being processed.
  ///
  /// \return
  ///     True if the scan was successful; false if some operation
  ///     failed
  bool RemoveCXAAtExit(llvm::BasicBlock &basic_block);

  /// The top-level pass implementation
  ///
  /// \param[in] llvm_function
  ///     The function currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise
  bool ResolveExternals(llvm::Function &llvm_function);

  /// A basic block-level pass to excise guard variables from the code.
  /// The result for the function is passed through Clang as a static
  /// variable.  Static variables normally have guard variables to ensure that
  /// they are only initialized once.

  /// Rewrite a load to a guard variable to return constant 0.
  ///
  /// \param[in] guard_load
  ///     The load instruction to zero out.
  void TurnGuardLoadIntoZero(llvm::Instruction *guard_load);

  /// The top-level pass implementation
  ///
  /// \param[in] basic_block
  ///     The basic block currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise
  bool RemoveGuards(llvm::BasicBlock &basic_block);

  /// A function-level pass to make all external variable references
  /// point at the correct offsets from the void* passed into the function.
  /// ClangExpressionDeclMap::DoStructLayout() must be called beforehand, so
  /// that the offsets are valid.

  /// The top-level pass implementation
  ///
  /// \param[in] llvm_function
  ///     The function currently being processed.
  ///
  /// \return
  ///     True on success; false otherwise
  bool ReplaceVariables(llvm::Function &llvm_function);

  /// Flags
  bool m_resolve_vars; ///< True if external variable references and persistent
                       ///variable references should be resolved
  lldb_private::ConstString
      m_func_name; ///< The name of the function to translate
  lldb_private::ConstString
      m_result_name; ///< The name of the result variable ($0, $1, ...)
  lldb_private::TypeFromParser
      m_result_type;      ///< The type of the result variable.
  llvm::Module *m_module; ///< The module being processed, or NULL if that has
                          ///not been determined yet.
  std::unique_ptr<llvm::DataLayout> m_target_data; ///< The target data for the
                                                   ///module being processed, or
                                                   ///NULL if there is no
                                                   ///module.
  lldb_private::ClangExpressionDeclMap
      *m_decl_map; ///< The DeclMap containing the Decls
  llvm::FunctionCallee
      m_CFStringCreateWithBytes; ///< The address of the function
                                 /// CFStringCreateWithBytes, cast to the
                                 /// appropriate function pointer type
  llvm::FunctionCallee m_sel_registerName; ///< The address of the function
                                           /// sel_registerName, cast to the
                                           /// appropriate function pointer type
  llvm::FunctionCallee m_objc_getClass; ///< The address of the function
                                        /// objc_getClass, cast to the
                                        /// appropriate function pointer type
  llvm::IntegerType
      *m_intptr_ty; ///< The type of an integer large enough to hold a pointer.
  lldb_private::Stream
      &m_error_stream; ///< The stream on which errors should be printed
  lldb_private::IRExecutionUnit &
      m_execution_unit; ///< The execution unit containing the IR being created.

  llvm::StoreInst *m_result_store; ///< If non-NULL, the store instruction that
                                   ///writes to the result variable.  If
                                   /// m_has_side_effects is true, this is
                                   /// NULL.
  bool m_result_is_pointer; ///< True if the function's result in the AST is a
                            ///pointer (see comments in
                            /// ASTResultSynthesizer::SynthesizeBodyResult)

  /// A placeholder that will be replaced by a pointer to the final location of
  /// the static allocation.
  llvm::GlobalVariable *m_reloc_placeholder;

  class FunctionValueCache {
  public:
    typedef std::function<llvm::Value *(llvm::Function *)> Maker;

    FunctionValueCache(Maker const &maker);
    ~FunctionValueCache();
    llvm::Value *GetValue(llvm::Function *function);

  private:
    Maker const m_maker;
    typedef std::map<llvm::Function *, llvm::Value *> FunctionValueMap;
    FunctionValueMap m_values;
  };

  FunctionValueCache m_entry_instruction_finder;

  /// UnfoldConstant operates on a constant [Old] which has just been replaced
  /// with a value [New].  We assume that new_value has been properly placed
  /// early in the function, in front of the first instruction in the entry
  /// basic block [FirstEntryInstruction].
  ///
  /// UnfoldConstant reads through the uses of Old and replaces Old in those
  /// uses with New.  Where those uses are constants, the function generates
  /// new instructions to compute the result of the new, non-constant
  /// expression and places them before FirstEntryInstruction.  These
  /// instructions replace the constant uses, so UnfoldConstant calls itself
  /// recursively for those.
  ///
  /// \return
  ///     True on success; false otherwise
  static bool UnfoldConstant(llvm::Constant *old_constant,
                             llvm::Function *llvm_function,
                             FunctionValueCache &value_maker,
                             FunctionValueCache &entry_instruction_finder,
                             lldb_private::Stream &error_stream);

  /// Commit the allocation in m_data_allocator and use its final location to
  /// replace m_reloc_placeholder.
  ///
  /// \return
  ///     True on success; false otherwise
  bool CompleteDataAllocation();
};

#endif // liblldb_IRForTarget_h_