MdeModulePkg/Include/Protocol/EbcVmTest.h

   1 /** @file
   2   EBC VM Test protocol for test purposes.
   3
   4 Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>
   5
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _EBC_VM_TEST_PROTOCOL_H_
  11 #define _EBC_VM_TEST_PROTOCOL_H_
  12
  13 //
  14 // Define a protocol for an EBC VM test interface.
  15 //
  16 #define EFI_EBC_VM_TEST_PROTOCOL_GUID \
  17   { \
  18     0xAAEACCFD, 0xF27B, 0x4C17, { 0xB6, 0x10, 0x75, 0xCA, 0x1F, 0x2D, 0xFB, 0x52 } \
  19   }
  20
  21 //
  22 // Define for forward reference.
  23 //
  24 typedef struct _EFI_EBC_VM_TEST_PROTOCOL EFI_EBC_VM_TEST_PROTOCOL;
  25
  26 //
  27 // VM major/minor version
  28 //
  29 #define VM_MAJOR_VERSION  1
  30 #define VM_MINOR_VERSION  0
  31
  32 //
  33 // Bits in the VM->StopFlags field
  34 //
  35 #define STOPFLAG_APP_DONE         0x0001
  36 #define STOPFLAG_BREAKPOINT       0x0002
  37 #define STOPFLAG_INVALID_BREAK    0x0004
  38 #define STOPFLAG_BREAK_ON_CALLEX  0x0008
  39
  40 //
  41 // Masks for working with the VM flags register
  42 //
  43 #define VMFLAGS_CC         0x0001 // condition flag
  44 #define VMFLAGS_STEP       0x0002 // step instruction mode
  45 #define VMFLAGS_ALL_VALID  (VMFLAGS_CC | VMFLAGS_STEP)
  46
  47 //
  48 // Macros for operating on the VM flags register
  49 //
  50 #define VMFLAG_SET(pVM, Flag)    (pVM->Flags |= (Flag))
  51 #define VMFLAG_ISSET(pVM, Flag)  ((pVM->Flags & (Flag)) ? 1 : 0)
  52 #define VMFLAG_CLEAR(pVM, Flag)  (pVM->Flags &= ~(Flag))
  53
  54 //
  55 // Define a macro to get the operand. Then we can change it to be either a
  56 // direct read or have it call a function to read memory.
  57 //
  58 #define GETOPERANDS(pVM)  (UINT8) (*(UINT8 *) (pVM->Ip + 1))
  59 #define GETOPCODE(pVM)    (UINT8) (*(UINT8 *) pVM->Ip)
  60
  61 //
  62 // Macros for operating on the VM GP registers
  63 //
  64 #define OPERAND1_REGDATA(pVM, Op)  pVM->Gpr[OPERAND1_REGNUM (Op)]
  65 #define OPERAND2_REGDATA(pVM, Op)  pVM->Gpr[OPERAND2_REGNUM (Op)]
  66
  67 //
  68 // Bits of exception flags field of VM context
  69 //
  70 #define EXCEPTION_FLAG_FATAL    0x80000000  // can't continue
  71 #define EXCEPTION_FLAG_ERROR    0x40000000  // bad, but try to continue
  72 #define EXCEPTION_FLAG_WARNING  0x20000000  // harmless problem
  73 #define EXCEPTION_FLAG_NONE     0x00000000  // for normal return
  74
  75 ///
  76 /// instruction pointer for the VM
  77 ///
  78 typedef UINT8 *VMIP;
  79
  80 typedef INT64  VM_REGISTER;
  81 typedef UINT32 EXCEPTION_FLAGS;
  82
  83 typedef struct {
  84   VM_REGISTER         Gpr[8];               ///< General purpose registers.
  85                                             ///< Flags register:
  86                                             ///<   0  Set to 1 if the result of the last compare was true
  87                                             ///<   1  Set to 1 if stepping
  88   UINT64              Flags;                ///<   2..63 Reserved.
  89   VMIP                Ip;                   ///< Instruction pointer.
  90   UINTN               LastException;
  91   EXCEPTION_FLAGS     ExceptionFlags;       ///< to keep track of exceptions
  92   UINT32              StopFlags;
  93   UINT32              CompilerVersion;        ///< via break(6)
  94   UINTN               HighStackBottom;        ///< bottom of the upper stack
  95   UINTN               LowStackTop;            ///< top of the lower stack
  96   UINT64              StackRetAddr;           ///< location of final return address on stack
  97   UINTN               *StackMagicPtr;         ///< pointer to magic value on stack to detect corruption
  98   EFI_HANDLE          ImageHandle;            ///< for this EBC driver
  99   EFI_SYSTEM_TABLE    *SystemTable;           ///< for debugging only
 100   UINTN               LastAddrConverted;      ///< for debug
 101   UINTN               LastAddrConvertedValue; ///< for debug
 102   VOID                *FramePtr;
 103   VOID                *EntryPoint;          ///< entry point of EBC image
 104   UINTN               ImageBase;
 105   VOID                *StackPool;
 106   VOID                *StackTop;
 107 } VM_CONTEXT;
 108
 109 /**
 110   Given a pointer to a new VM context, execute one or more instructions. This
 111   function is only used for test purposes.
 112
 113   @param[in]      This              A pointer to the EFI_EBC_VM_TEST_PROTOCOL structure.
 114   @param[in]      VmPtr             A pointer to a VM context.
 115   @param[in, out] InstructionCount  A pointer to a UINTN value holding the number of
 116                                     instructions to execute. If it holds value of 0,
 117                                     then the instruction to be executed is 1.
 118
 119   @retval EFI_UNSUPPORTED       At least one of the opcodes is not supported.
 120   @retval EFI_SUCCESS           All of the instructions are executed successfully.
 121
 122 **/
 123 typedef
 124 EFI_STATUS
 125 (EFIAPI *EBC_VM_TEST_EXECUTE)(
 126   IN EFI_EBC_VM_TEST_PROTOCOL         *This,
 127   IN VM_CONTEXT                       *VmPtr,
 128   IN OUT UINTN                        *InstructionCount
 129   );
 130
 131 /**
 132   Convert AsmText to the instruction. This function is only used for test purposes.
 133
 134   @param[in]  This              A pointer to the EFI_EBC_VM_TEST_PROTOCOL structure.
 135   @param[in]  AsmText           A pointer to EBC ASM text code.
 136   @param[out] Buffer            Buffer to store the instruction.
 137   @param[out] BufferLen         Size of buffer that is required to store data.
 138
 139   @retval EFI_UNSUPPORTED       This functionality is unsupported.
 140   @retval EFI_SUCCESS           Successfully convert AsmText to the instruction.
 141
 142 **/
 143 typedef
 144 EFI_STATUS
 145 (EFIAPI *EBC_VM_TEST_ASM)(
 146   IN EFI_EBC_VM_TEST_PROTOCOL         *This,
 147   IN CHAR16                           *AsmText,
 148   IN OUT INT8                         *Buffer,
 149   IN OUT UINTN                        *BufferLen
 150   );
 151
 152 /**
 153   Dump the executed instruction. This function is only used for test purposes.
 154
 155   @param[in]  This              A pointer to the EFI_EBC_VM_TEST_PROTOCOL structure.
 156   @param[out] AsmText           Contain the disasm text.
 157   @param[out] Buffer            Buffer to store the instruction.
 158   @param[out] BufferLen         Size of buffer that is required to store data.
 159
 160   @retval EFI_UNSUPPORTED       This functionality is unsupported.
 161   @retval EFI_SUCCESS           Successfully dump the executed instruction.
 162
 163 **/
 164 typedef
 165 EFI_STATUS
 166 (EFIAPI *EBC_VM_TEST_DASM)(
 167   IN EFI_EBC_VM_TEST_PROTOCOL         *This,
 168   IN OUT CHAR16                       *AsmText,
 169   IN OUT INT8                         *Buffer,
 170   IN OUT UINTN                        *Len
 171   );
 172
 173 //
 174 // Prototype for the actual EBC test protocol interface
 175 //
 176 struct _EFI_EBC_VM_TEST_PROTOCOL {
 177   EBC_VM_TEST_EXECUTE    Execute;
 178   EBC_VM_TEST_ASM        Assemble;
 179   EBC_VM_TEST_DASM       Disassemble;
 180 };
 181
 182 extern EFI_GUID  gEfiEbcVmTestProtocolGuid;
 183
 184 #endif