MdeModulePkg/Include/Protocol/EbcVmTest.h

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