//===-- EmulateInstruction.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 LLDB_CORE_EMULATEINSTRUCTION_H

#define LLDB_CORE_EMULATEINSTRUCTION_H

#include <optional>

#include <string>

#include "lldb/Core/Address.h"

#include "lldb/Core/Opcode.h"

#include "lldb/Core/PluginInterface.h"

#include "lldb/Utility/ArchSpec.h"

#include "lldb/lldb-defines.h"

#include "lldb/lldb-enumerations.h"

#include "lldb/lldb-private-enumerations.h"

#include "lldb/lldb-private-types.h"

#include "lldb/lldb-types.h"

#include <cstddef>

#include <cstdint>

namespace lldb_private {

class OptionValueDictionary;

class RegisterContext;

class RegisterValue;

class Stream;

class Target;

class UnwindPlan;

/// \class EmulateInstruction EmulateInstruction.h

/// "lldb/Core/EmulateInstruction.h"

/// A class that allows emulation of CPU opcodes.

///

/// This class is a plug-in interface that is accessed through the standard

/// static FindPlugin function call in the EmulateInstruction class. The

/// FindPlugin takes a target triple and returns a new object if there is a

/// plug-in that supports the architecture and OS. Four callbacks and a baton

/// are provided. The four callbacks are read register, write register, read

/// memory and write memory.

///

/// This class is currently designed for these main use cases: - Auto

/// generation of Call Frame Information (CFI) from assembly code - Predicting

/// single step breakpoint locations - Emulating instructions for breakpoint

/// traps

///

/// Objects can be asked to read an instruction which will cause a call to the

/// read register callback to get the PC, followed by a read memory call to

/// read the opcode. If ReadInstruction () returns true, then a call to

/// EmulateInstruction::EvaluateInstruction () can be made. At this point the

/// EmulateInstruction subclass will use all of the callbacks to emulate an

/// instruction.

///

/// Clients that provide the callbacks can either do the read/write

/// registers/memory to actually emulate the instruction on a real or virtual

/// CPU, or watch for the EmulateInstruction::Context which is context for the

/// read/write register/memory which explains why the callback is being

/// called. Examples of a context are: "pushing register 3 onto the stack at

/// offset -12", or "adjusting stack pointer by -16". This extra context

/// allows the generation of

/// CFI information from assembly code without having to actually do

/// the read/write register/memory.

///

/// Clients must be prepared that not all instructions for an Instruction Set

/// Architecture (ISA) will be emulated.

///

/// Subclasses at the very least should implement the instructions that save

/// and restore registers onto the stack and adjustment to the stack pointer.

/// By just implementing a few instructions for an ISA that are the typical

/// prologue opcodes, you can then generate CFI using a class that will soon

/// be available.

///

/// Implementing all of the instructions that affect the PC can then allow

/// single step prediction support.

///

/// Implementing all of the instructions allows for emulation of opcodes for

/// breakpoint traps and will pave the way for "thread centric" debugging. The

/// current debugging model is "process centric" where all threads must be

/// stopped when any thread is stopped; when hitting software breakpoints we

/// must disable the breakpoint by restoring the original breakpoint opcode,

/// single stepping and restoring the breakpoint trap. If all threads were

/// allowed to run then other threads could miss the breakpoint.

///

/// This class centralizes the code that usually is done in separate code

/// paths in a debugger (single step prediction, finding save restore

/// locations of registers for unwinding stack frame variables) and emulating

/// the instruction is just a bonus.

class EmulateInstruction : public PluginInterface {

public:

  static EmulateInstruction *FindPlugin(const ArchSpec &arch,

                                        InstructionType supported_inst_type,

                                        const char *plugin_name);

  enum ContextType {

    eContextInvalid = 0,

    // Read an instruction opcode from memory

    eContextReadOpcode,

    // Usually used for writing a register value whose source value is an

    // immediate

    eContextImmediate,

    // Exclusively used when saving a register to the stack as part of the

    // prologue

    eContextPushRegisterOnStack,

    // Exclusively used when restoring a register off the stack as part of the

    // epilogue

    eContextPopRegisterOffStack,

    // Add or subtract a value from the stack

    eContextAdjustStackPointer,

    // Adjust the frame pointer for the current frame

    eContextSetFramePointer,

    // Typically in an epilogue sequence.  Copy the frame pointer back into the

    // stack pointer, use SP for CFA calculations again.

    eContextRestoreStackPointer,

    // Add or subtract a value from a base address register (other than SP)

    eContextAdjustBaseRegister,

    // Add or subtract a value from the PC or store a value to the PC.

    eContextAdjustPC,

    // Used in WriteRegister callbacks to indicate where the

    eContextRegisterPlusOffset,

    // Used in WriteMemory callback to indicate where the data came from

    eContextRegisterStore,

    eContextRegisterLoad,

    // Used when performing a PC-relative branch where the

    eContextRelativeBranchImmediate,

    // Used when performing an absolute branch where the

    eContextAbsoluteBranchRegister,

    // Used when performing a supervisor call to an operating system to provide

    // a service:

    eContextSupervisorCall,

    // Used when performing a MemU operation to read the PC-relative offset

    // from an address.

    eContextTableBranchReadMemory,

    // Used when random bits are written into a register

    eContextWriteRegisterRandomBits,

    // Used when random bits are written to memory

    eContextWriteMemoryRandomBits,

    eContextArithmetic,

    eContextAdvancePC,

    eContextReturnFromException

  };

  enum InfoType {

    eInfoTypeRegisterPlusOffset,

    eInfoTypeRegisterPlusIndirectOffset,

    eInfoTypeRegisterToRegisterPlusOffset,

    eInfoTypeRegisterToRegisterPlusIndirectOffset,

    eInfoTypeRegisterRegisterOperands,

    eInfoTypeOffset,

    eInfoTypeRegister,

    eInfoTypeImmediate,

    eInfoTypeImmediateSigned,

    eInfoTypeAddress,

    eInfoTypeISAAndImmediate,

    eInfoTypeISAAndImmediateSigned,

    eInfoTypeISA,

    eInfoTypeNoArgs

  };

  struct Context {

    ContextType type = eContextInvalid;

  private:

    enum InfoType info_type = eInfoTypeNoArgs;

  public:

    enum InfoType GetInfoType() const { return info_type; }

    union ContextInfo {

      struct RegisterPlusOffset {

        RegisterInfo reg;      // base register

        int64_t signed_offset; // signed offset added to base register

      } RegisterPlusOffset;

      struct RegisterPlusIndirectOffset {

        RegisterInfo base_reg;   // base register number

        RegisterInfo offset_reg; // offset register kind

      } RegisterPlusIndirectOffset;

      struct RegisterToRegisterPlusOffset {

        RegisterInfo data_reg; // source/target register for data

        RegisterInfo base_reg; // base register for address calculation

        int64_t offset;        // offset for address calculation

      } RegisterToRegisterPlusOffset;

      struct RegisterToRegisterPlusIndirectOffset {

        RegisterInfo base_reg;   // base register for address calculation

        RegisterInfo offset_reg; // offset register for address calculation

        RegisterInfo data_reg;   // source/target register for data

      } RegisterToRegisterPlusIndirectOffset;

      struct RegisterRegisterOperands {

        RegisterInfo

            operand1; // register containing first operand for binary op

        RegisterInfo

            operand2; // register containing second operand for binary op

      } RegisterRegisterOperands;

      int64_t signed_offset; // signed offset by which to adjust self (for

                             // registers only)

      RegisterInfo reg; // plain register

      uint64_t unsigned_immediate; // unsigned immediate value

      int64_t signed_immediate;    // signed immediate value

      lldb::addr_t address; // direct address

      struct ISAAndImmediate {

        uint32_t isa;

        uint32_t unsigned_data32; // immediate data

      } ISAAndImmediate;

      struct ISAAndImmediateSigned {

        uint32_t isa;

        int32_t signed_data32; // signed immediate data

      } ISAAndImmediateSigned;

      uint32_t isa;

    } info;

    static_assert(std::is_trivial<ContextInfo>::value,

                  "ContextInfo must be trivial.");

    Context() = default;

    void SetRegisterPlusOffset(RegisterInfo base_reg, int64_t signed_offset) {

      info_type = eInfoTypeRegisterPlusOffset;

      info.RegisterPlusOffset.reg = base_reg;

      info.RegisterPlusOffset.signed_offset = signed_offset;

    }

    void SetRegisterPlusIndirectOffset(RegisterInfo base_reg,

                                       RegisterInfo offset_reg) {

      info_type = eInfoTypeRegisterPlusIndirectOffset;

      info.RegisterPlusIndirectOffset.base_reg = base_reg;

      info.RegisterPlusIndirectOffset.offset_reg = offset_reg;

    }

    void SetRegisterToRegisterPlusOffset(RegisterInfo data_reg,

                                         RegisterInfo base_reg,

                                         int64_t offset) {

      info_type = eInfoTypeRegisterToRegisterPlusOffset;

      info.RegisterToRegisterPlusOffset.data_reg = data_reg;

      info.RegisterToRegisterPlusOffset.base_reg = base_reg;

      info.RegisterToRegisterPlusOffset.offset = offset;

    }

    void SetRegisterToRegisterPlusIndirectOffset(RegisterInfo base_reg,

                                                 RegisterInfo offset_reg,

                                                 RegisterInfo data_reg) {

      info_type = eInfoTypeRegisterToRegisterPlusIndirectOffset;

      info.RegisterToRegisterPlusIndirectOffset.base_reg = base_reg;

      info.RegisterToRegisterPlusIndirectOffset.offset_reg = offset_reg;

      info.RegisterToRegisterPlusIndirectOffset.data_reg = data_reg;

    }

    void SetRegisterRegisterOperands(RegisterInfo op1_reg,

                                     RegisterInfo op2_reg) {

      info_type = eInfoTypeRegisterRegisterOperands;

      info.RegisterRegisterOperands.operand1 = op1_reg;

      info.RegisterRegisterOperands.operand2 = op2_reg;

    }

    void SetOffset(int64_t signed_offset) {

      info_type = eInfoTypeOffset;

      info.signed_offset = signed_offset;

    }

    void SetRegister(RegisterInfo reg) {

      info_type = eInfoTypeRegister;

      info.reg = reg;

    }

    void SetImmediate(uint64_t immediate) {

      info_type = eInfoTypeImmediate;

      info.unsigned_immediate = immediate;

    }

    void SetImmediateSigned(int64_t signed_immediate) {

      info_type = eInfoTypeImmediateSigned;

      info.signed_immediate = signed_immediate;

    }

    void SetAddress(lldb::addr_t address) {

      info_type = eInfoTypeAddress;

      info.address = address;

    }

    void SetISAAndImmediate(uint32_t isa, uint32_t data) {

      info_type = eInfoTypeISAAndImmediate;

      info.ISAAndImmediate.isa = isa;

      info.ISAAndImmediate.unsigned_data32 = data;

    }

    void SetISAAndImmediateSigned(uint32_t isa, int32_t data) {

      info_type = eInfoTypeISAAndImmediateSigned;

      info.ISAAndImmediateSigned.isa = isa;

      info.ISAAndImmediateSigned.signed_data32 = data;

    }

    void SetISA(uint32_t isa) {

      info_type = eInfoTypeISA;

      info.isa = isa;

    }

    void SetNoArgs() { info_type = eInfoTypeNoArgs; }

    void Dump(Stream &s, EmulateInstruction *instruction) const;

  };

  typedef size_t (*ReadMemoryCallback)(EmulateInstruction *instruction,

                                       void *baton, const Context &context,

                                       lldb::addr_t addr, void *dst,

                                       size_t length);

  typedef size_t (*WriteMemoryCallback)(EmulateInstruction *instruction,

                                        void *baton, const Context &context,

                                        lldb::addr_t addr, const void *dst,

                                        size_t length);

  typedef bool (*ReadRegisterCallback)(EmulateInstruction *instruction,

                                       void *baton,

                                       const RegisterInfo *reg_info,

                                       RegisterValue &reg_value);

  typedef bool (*WriteRegisterCallback)(EmulateInstruction *instruction,

                                        void *baton, const Context &context,

                                        const RegisterInfo *reg_info,

                                        const RegisterValue &reg_value);

  // Type to represent the condition of an instruction. The UINT32 value is

  // reserved for the unconditional case and all other value can be used in an

  // architecture dependent way.

  typedef uint32_t InstructionCondition;

  static const InstructionCondition UnconditionalCondition = UINT32_MAX;

  EmulateInstruction(const ArchSpec &arch);

  ~EmulateInstruction() override = default;

  // Mandatory overrides

  virtual bool

  SupportsEmulatingInstructionsOfType(InstructionType inst_type) = 0;

  virtual bool SetTargetTriple(const ArchSpec &arch) = 0;

  virtual bool ReadInstruction() = 0;

  virtual bool EvaluateInstruction(uint32_t evaluate_options) = 0;

  virtual InstructionCondition GetInstructionCondition() {

    return UnconditionalCondition;

  }

  virtual bool TestEmulation(Stream &out_stream, ArchSpec &arch,

                             OptionValueDictionary *test_data) = 0;

  virtual std::optional<RegisterInfo>

  GetRegisterInfo(lldb::RegisterKind reg_kind, uint32_t reg_num) = 0;

  // Optional overrides

  virtual bool SetInstruction(const Opcode &insn_opcode,

                              const Address &inst_addr, Target *target);

  virtual bool CreateFunctionEntryUnwind(UnwindPlan &unwind_plan);

  static const char *TranslateRegister(lldb::RegisterKind reg_kind,

                                       uint32_t reg_num, std::string &reg_name);

  // RegisterInfo variants

  std::optional<RegisterValue> ReadRegister(const RegisterInfo &reg_info);

  uint64_t ReadRegisterUnsigned(const RegisterInfo &reg_info,

                                uint64_t fail_value, bool *success_ptr);

  bool WriteRegister(const Context &context, const RegisterInfo &ref_info,

                     const RegisterValue &reg_value);

  bool WriteRegisterUnsigned(const Context &context,

                             const RegisterInfo &reg_info, uint64_t reg_value);

  // Register kind and number variants

  bool ReadRegister(lldb::RegisterKind reg_kind, uint32_t reg_num,

                    RegisterValue &reg_value);

  bool WriteRegister(const Context &context, lldb::RegisterKind reg_kind,

                     uint32_t reg_num, const RegisterValue &reg_value);

  uint64_t ReadRegisterUnsigned(lldb::RegisterKind reg_kind, uint32_t reg_num,

                                uint64_t fail_value, bool *success_ptr);

  bool WriteRegisterUnsigned(const Context &context,

                             lldb::RegisterKind reg_kind, uint32_t reg_num,

                             uint64_t reg_value);

  size_t ReadMemory(const Context &context, lldb::addr_t addr, void *dst,

                    size_t dst_len);

  uint64_t ReadMemoryUnsigned(const Context &context, lldb::addr_t addr,

                              size_t byte_size, uint64_t fail_value,

                              bool *success_ptr);

  bool WriteMemory(const Context &context, lldb::addr_t addr, const void *src,

                   size_t src_len);

  bool WriteMemoryUnsigned(const Context &context, lldb::addr_t addr,

                           uint64_t uval, size_t uval_byte_size);

  uint32_t GetAddressByteSize() const { return m_arch.GetAddressByteSize(); }

  lldb::ByteOrder GetByteOrder() const { return m_arch.GetByteOrder(); }

  const Opcode &GetOpcode() const { return m_opcode; }

  lldb::addr_t GetAddress() const { return m_addr; }

  const ArchSpec &GetArchitecture() const { return m_arch; }

  static size_t ReadMemoryFrame(EmulateInstruction *instruction, void *baton,

                                const Context &context, lldb::addr_t addr,

                                void *dst, size_t length);

  static size_t WriteMemoryFrame(EmulateInstruction *instruction, void *baton,

                                 const Context &context, lldb::addr_t addr,

                                 const void *dst, size_t length);

  static bool ReadRegisterFrame(EmulateInstruction *instruction, void *baton,

                                const RegisterInfo *reg_info,

                                RegisterValue &reg_value);

  static bool WriteRegisterFrame(EmulateInstruction *instruction, void *baton,

                                 const Context &context,

                                 const RegisterInfo *reg_info,

                                 const RegisterValue &reg_value);

  static size_t ReadMemoryDefault(EmulateInstruction *instruction, void *baton,

                                  const Context &context, lldb::addr_t addr,

                                  void *dst, size_t length);

  static size_t WriteMemoryDefault(EmulateInstruction *instruction, void *baton,

                                   const Context &context, lldb::addr_t addr,

                                   const void *dst, size_t length);

  static bool ReadRegisterDefault(EmulateInstruction *instruction, void *baton,

                                  const RegisterInfo *reg_info,

                                  RegisterValue &reg_value);

  static bool WriteRegisterDefault(EmulateInstruction *instruction, void *baton,

                                   const Context &context,

                                   const RegisterInfo *reg_info,

                                   const RegisterValue &reg_value);

  void SetBaton(void *baton);

  void SetCallbacks(ReadMemoryCallback read_mem_callback,

                    WriteMemoryCallback write_mem_callback,

                    ReadRegisterCallback read_reg_callback,

                    WriteRegisterCallback write_reg_callback);

  void SetReadMemCallback(ReadMemoryCallback read_mem_callback);

  void SetWriteMemCallback(WriteMemoryCallback write_mem_callback);

  void SetReadRegCallback(ReadRegisterCallback read_reg_callback);

  void SetWriteRegCallback(WriteRegisterCallback write_reg_callback);

  static bool GetBestRegisterKindAndNumber(const RegisterInfo *reg_info,

                                           lldb::RegisterKind &reg_kind,

                                           uint32_t &reg_num);

  static uint32_t GetInternalRegisterNumber(RegisterContext *reg_ctx,

                                            const RegisterInfo &reg_info);

protected:

  ArchSpec m_arch;

  void *m_baton = nullptr;

  ReadMemoryCallback m_read_mem_callback = &ReadMemoryDefault;

  WriteMemoryCallback m_write_mem_callback = &WriteMemoryDefault;

  ReadRegisterCallback m_read_reg_callback = &ReadRegisterDefault;

  WriteRegisterCallback m_write_reg_callback = &WriteRegisterDefault;

  lldb::addr_t m_addr = LLDB_INVALID_ADDRESS;

  Opcode m_opcode;

private:

  // For EmulateInstruction only

  EmulateInstruction(const EmulateInstruction &) = delete;

  const EmulateInstruction &operator=(const EmulateInstruction &) = delete;

};

} // namespace lldb_private

#endif // LLDB_CORE_EMULATEINSTRUCTION_H