MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Include / Protocol / EbcVmTest.h

/** @file\r
  EBC VM Test protocol for test purposes.\r
\r
Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>\r
\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _EBC_VM_TEST_PROTOCOL_H_\r
#define _EBC_VM_TEST_PROTOCOL_H_\r
\r
//\r
// Define a protocol for an EBC VM test interface.\r
//\r
#define EFI_EBC_VM_TEST_PROTOCOL_GUID \\r
  { \\r
    0xAAEACCFD, 0xF27B, 0x4C17, { 0xB6, 0x10, 0x75, 0xCA, 0x1F, 0x2D, 0xFB, 0x52 } \\r
  }\r
\r
//\r
// Define for forward reference.\r
//\r
typedef struct _EFI_EBC_VM_TEST_PROTOCOL EFI_EBC_VM_TEST_PROTOCOL;\r
\r
//\r
// VM major/minor version\r
//\r
#define VM_MAJOR_VERSION  1\r
#define VM_MINOR_VERSION  0\r
\r
//\r
// Bits in the VM->StopFlags field\r
//\r
#define STOPFLAG_APP_DONE         0x0001\r
#define STOPFLAG_BREAKPOINT       0x0002\r
#define STOPFLAG_INVALID_BREAK    0x0004\r
#define STOPFLAG_BREAK_ON_CALLEX  0x0008\r
\r
//\r
// Masks for working with the VM flags register\r
//\r
#define VMFLAGS_CC        0x0001  // condition flag\r
#define VMFLAGS_STEP      0x0002  // step instruction mode\r
#define VMFLAGS_ALL_VALID (VMFLAGS_CC | VMFLAGS_STEP)\r
\r
//\r
// Macros for operating on the VM flags register\r
//\r
#define VMFLAG_SET(pVM, Flag)   (pVM->Flags |= (Flag))\r
#define VMFLAG_ISSET(pVM, Flag) ((pVM->Flags & (Flag)) ? 1 : 0)\r
#define VMFLAG_CLEAR(pVM, Flag) (pVM->Flags &= ~(Flag))\r
\r
//\r
// Define a macro to get the operand. Then we can change it to be either a\r
// direct read or have it call a function to read memory.\r
//\r
#define GETOPERANDS(pVM)  (UINT8) (*(UINT8 *) (pVM->Ip + 1))\r
#define GETOPCODE(pVM)    (UINT8) (*(UINT8 *) pVM->Ip)\r
\r
//\r
// Macros for operating on the VM GP registers\r
//\r
#define OPERAND1_REGDATA(pVM, Op) pVM->Gpr[OPERAND1_REGNUM (Op)]\r
#define OPERAND2_REGDATA(pVM, Op) pVM->Gpr[OPERAND2_REGNUM (Op)]\r
\r
//\r
// Bits of exception flags field of VM context\r
//\r
#define EXCEPTION_FLAG_FATAL    0x80000000  // can't continue\r
#define EXCEPTION_FLAG_ERROR    0x40000000  // bad, but try to continue\r
#define EXCEPTION_FLAG_WARNING  0x20000000  // harmless problem\r
#define EXCEPTION_FLAG_NONE     0x00000000  // for normal return\r
\r
///\r
/// instruction pointer for the VM\r
///\r
typedef UINT8   *VMIP;\r
\r
typedef INT64   VM_REGISTER;\r
typedef UINT32  EXCEPTION_FLAGS;\r
\r
typedef struct {\r
  VM_REGISTER       Gpr[8];                 ///< General purpose registers.\r
                                            ///< Flags register:\r
                                            ///<   0  Set to 1 if the result of the last compare was true\r
                                            ///<   1  Set to 1 if stepping\r
  UINT64            Flags;                  ///<   2..63 Reserved.\r
  VMIP              Ip;                     ///< Instruction pointer.\r
  UINTN             LastException;\r
  EXCEPTION_FLAGS   ExceptionFlags;         ///< to keep track of exceptions\r
  UINT32            StopFlags;\r
  UINT32            CompilerVersion;        ///< via break(6)\r
  UINTN             HighStackBottom;        ///< bottom of the upper stack\r
  UINTN             LowStackTop;            ///< top of the lower stack\r
  UINT64            StackRetAddr;           ///< location of final return address on stack\r
  UINTN             *StackMagicPtr;         ///< pointer to magic value on stack to detect corruption\r
  EFI_HANDLE        ImageHandle;            ///< for this EBC driver\r
  EFI_SYSTEM_TABLE  *SystemTable;           ///< for debugging only\r
  UINTN             LastAddrConverted;      ///< for debug\r
  UINTN             LastAddrConvertedValue; ///< for debug\r
  VOID              *FramePtr;\r
  VOID              *EntryPoint;            ///< entry point of EBC image\r
  UINTN             ImageBase;\r
  VOID              *StackPool;\r
  VOID              *StackTop;\r
} VM_CONTEXT;\r
\r
/**\r
  Given a pointer to a new VM context, execute one or more instructions. This\r
  function is only used for test purposes.\r
\r
  @param[in]      This              A pointer to the EFI_EBC_VM_TEST_PROTOCOL structure.\r
  @param[in]      VmPtr             A pointer to a VM context.\r
  @param[in, out] InstructionCount  A pointer to a UINTN value holding the number of\r
                                    instructions to execute. If it holds value of 0,\r
                                    then the instruction to be executed is 1.\r
\r
  @retval EFI_UNSUPPORTED       At least one of the opcodes is not supported.\r
  @retval EFI_SUCCESS           All of the instructions are executed successfully.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EBC_VM_TEST_EXECUTE) (\r
  IN EFI_EBC_VM_TEST_PROTOCOL         *This,\r
  IN VM_CONTEXT                       *VmPtr,\r
  IN OUT UINTN                        *InstructionCount\r
  );\r
\r
/**\r
  Convert AsmText to the instruction. This function is only used for test purposes.\r
\r
  @param[in]  This              A pointer to the EFI_EBC_VM_TEST_PROTOCOL structure.\r
  @param[in]  AsmText           A pointer to EBC ASM text code.\r
  @param[out] Buffer            Buffer to store the instruction.\r
  @param[out] BufferLen         Size of buffer that is required to store data.\r
\r
  @retval EFI_UNSUPPORTED       This functionality is unsupported.\r
  @retval EFI_SUCCESS           Successfully convert AsmText to the instruction.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EBC_VM_TEST_ASM) (\r
  IN EFI_EBC_VM_TEST_PROTOCOL         *This,\r
  IN CHAR16                           *AsmText,\r
  IN OUT INT8                         *Buffer,\r
  IN OUT UINTN                        *BufferLen\r
  );\r
\r
/**\r
  Dump the executed instruction. This function is only used for test purposes.\r
\r
  @param[in]  This              A pointer to the EFI_EBC_VM_TEST_PROTOCOL structure.\r
  @param[out] AsmText           Contain the disasm text.\r
  @param[out] Buffer            Buffer to store the instruction.\r
  @param[out] BufferLen         Size of buffer that is required to store data.\r
\r
  @retval EFI_UNSUPPORTED       This functionality is unsupported.\r
  @retval EFI_SUCCESS           Successfully dump the executed instruction.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EBC_VM_TEST_DASM) (\r
  IN EFI_EBC_VM_TEST_PROTOCOL         *This,\r
  IN OUT CHAR16                       *AsmText,\r
  IN OUT INT8                         *Buffer,\r
  IN OUT UINTN                        *Len\r
  );\r
\r
//\r
// Prototype for the actual EBC test protocol interface\r
//\r
struct _EFI_EBC_VM_TEST_PROTOCOL {\r
  EBC_VM_TEST_EXECUTE Execute;\r
  EBC_VM_TEST_ASM     Assemble;\r
  EBC_VM_TEST_DASM    Disassemble;\r
};\r
\r
extern EFI_GUID gEfiEbcVmTestProtocolGuid;\r
\r
#endif\r