MdePkg/Include/Protocol/Ebc.h

   1 /** @file
   2   Describes the protocol interface to the EBC interpreter.
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __EFI_EBC_PROTOCOL_H__
  10 #define __EFI_EBC_PROTOCOL_H__
  11
  12 #define EFI_EBC_INTERPRETER_PROTOCOL_GUID \
  13   { \
  14     0x13AC6DD1, 0x73D0, 0x11D4, {0xB0, 0x6B, 0x00, 0xAA, 0x00, 0xBD, 0x6D, 0xE7 } \
  15   }
  16
  17 //
  18 // Define OPCODES
  19 //
  20 #define OPCODE_BREAK    0x00
  21 #define OPCODE_JMP      0x01
  22 #define OPCODE_JMP8     0x02
  23 #define OPCODE_CALL     0x03
  24 #define OPCODE_RET      0x04
  25 #define OPCODE_CMPEQ    0x05
  26 #define OPCODE_CMPLTE   0x06
  27 #define OPCODE_CMPGTE   0x07
  28 #define OPCODE_CMPULTE  0x08
  29 #define OPCODE_CMPUGTE  0x09
  30 #define OPCODE_NOT      0x0A
  31 #define OPCODE_NEG      0x0B
  32 #define OPCODE_ADD      0x0C
  33 #define OPCODE_SUB      0x0D
  34 #define OPCODE_MUL      0x0E
  35 #define OPCODE_MULU     0x0F
  36 #define OPCODE_DIV      0x10
  37 #define OPCODE_DIVU     0x11
  38 #define OPCODE_MOD      0x12
  39 #define OPCODE_MODU     0x13
  40 #define OPCODE_AND      0x14
  41 #define OPCODE_OR       0x15
  42 #define OPCODE_XOR      0x16
  43 #define OPCODE_SHL      0x17
  44 #define OPCODE_SHR      0x18
  45 #define OPCODE_ASHR     0x19
  46 #define OPCODE_EXTNDB   0x1A
  47 #define OPCODE_EXTNDW   0x1B
  48 #define OPCODE_EXTNDD   0x1C
  49 #define OPCODE_MOVBW    0x1D
  50 #define OPCODE_MOVWW    0x1E
  51 #define OPCODE_MOVDW    0x1F
  52 #define OPCODE_MOVQW    0x20
  53 #define OPCODE_MOVBD    0x21
  54 #define OPCODE_MOVWD    0x22
  55 #define OPCODE_MOVDD    0x23
  56 #define OPCODE_MOVQD    0x24
  57 #define OPCODE_MOVSNW   0x25  // Move signed natural with word index
  58 #define OPCODE_MOVSND   0x26  // Move signed natural with dword index
  59 //
  60 // #define OPCODE_27         0x27
  61 //
  62 #define OPCODE_MOVQQ    0x28  // Does this go away?
  63 #define OPCODE_LOADSP   0x29
  64 #define OPCODE_STORESP  0x2A
  65 #define OPCODE_PUSH     0x2B
  66 #define OPCODE_POP      0x2C
  67 #define OPCODE_CMPIEQ   0x2D
  68 #define OPCODE_CMPILTE  0x2E
  69 #define OPCODE_CMPIGTE  0x2F
  70 #define OPCODE_CMPIULTE 0x30
  71 #define OPCODE_CMPIUGTE 0x31
  72 #define OPCODE_MOVNW    0x32
  73 #define OPCODE_MOVND    0x33
  74 //
  75 // #define OPCODE_34         0x34
  76 //
  77 #define OPCODE_PUSHN  0x35
  78 #define OPCODE_POPN   0x36
  79 #define OPCODE_MOVI   0x37
  80 #define OPCODE_MOVIN  0x38
  81 #define OPCODE_MOVREL 0x39
  82
  83 //
  84 // Bit masks for opcode encodings
  85 //
  86 #define OPCODE_M_OPCODE       0x3F  // bits of interest for first level decode
  87 #define OPCODE_M_IMMDATA      0x80
  88 #define OPCODE_M_IMMDATA64    0x40
  89 #define OPCODE_M_64BIT        0x40  // for CMP
  90 #define OPCODE_M_RELADDR      0x10  // for CALL instruction
  91 #define OPCODE_M_CMPI32_DATA  0x80  // for CMPI
  92 #define OPCODE_M_CMPI64       0x40  // for CMPI 32 or 64 bit comparison
  93 #define OPERAND_M_MOVIN_N     0x80
  94 #define OPERAND_M_CMPI_INDEX  0x10
  95
  96 //
  97 // Masks for instructions that encode presence of indexes for operand1 and/or
  98 // operand2.
  99 //
 100 #define OPCODE_M_IMMED_OP1  0x80
 101 #define OPCODE_M_IMMED_OP2  0x40
 102
 103 //
 104 // Bit masks for operand encodings
 105 //
 106 #define OPERAND_M_INDIRECT1 0x08
 107 #define OPERAND_M_INDIRECT2 0x80
 108 #define OPERAND_M_OP1       0x07
 109 #define OPERAND_M_OP2       0x70
 110
 111 //
 112 // Masks for data manipulation instructions
 113 //
 114 #define DATAMANIP_M_64      0x40  // 64-bit width operation
 115 #define DATAMANIP_M_IMMDATA 0x80
 116
 117 //
 118 // For MOV instructions, need a mask for the opcode when immediate
 119 // data applies to R2.
 120 //
 121 #define OPCODE_M_IMMED_OP2  0x40
 122
 123 //
 124 // The MOVI/MOVIn instructions use bit 6 of operands byte to indicate
 125 // if an index is present. Then bits 4 and 5 are used to indicate the width
 126 // of the move.
 127 //
 128 #define MOVI_M_IMMDATA    0x40
 129 #define MOVI_M_DATAWIDTH  0xC0
 130 #define MOVI_DATAWIDTH16  0x40
 131 #define MOVI_DATAWIDTH32  0x80
 132 #define MOVI_DATAWIDTH64  0xC0
 133 #define MOVI_M_MOVEWIDTH  0x30
 134 #define MOVI_MOVEWIDTH8   0x00
 135 #define MOVI_MOVEWIDTH16  0x10
 136 #define MOVI_MOVEWIDTH32  0x20
 137 #define MOVI_MOVEWIDTH64  0x30
 138
 139 //
 140 // Masks for CALL instruction encodings
 141 //
 142 #define OPERAND_M_RELATIVE_ADDR 0x10
 143 #define OPERAND_M_NATIVE_CALL   0x20
 144
 145 //
 146 // Masks for decoding push/pop instructions
 147 //
 148 #define PUSHPOP_M_IMMDATA 0x80  // opcode bit indicating immediate data
 149 #define PUSHPOP_M_64      0x40  // opcode bit indicating 64-bit operation
 150 //
 151 // Mask for operand of JMP instruction
 152 //
 153 #define JMP_M_RELATIVE    0x10
 154 #define JMP_M_CONDITIONAL 0x80
 155 #define JMP_M_CS          0x40
 156
 157 //
 158 // Macros to determine if a given operand is indirect
 159 //
 160 #define OPERAND1_INDIRECT(op) ((op) & OPERAND_M_INDIRECT1)
 161 #define OPERAND2_INDIRECT(op) ((op) & OPERAND_M_INDIRECT2)
 162
 163 //
 164 // Macros to extract the operands from second byte of instructions
 165 //
 166 #define OPERAND1_REGNUM(op)       ((op) & OPERAND_M_OP1)
 167 #define OPERAND2_REGNUM(op)       (((op) & OPERAND_M_OP2) >> 4)
 168
 169 #define OPERAND1_CHAR(op)         ('0' + OPERAND1_REGNUM (op))
 170 #define OPERAND2_CHAR(op)         ('0' + OPERAND2_REGNUM (op))
 171
 172 //
 173 // Condition masks usually for byte 1 encodings of code
 174 //
 175 #define CONDITION_M_CONDITIONAL 0x80
 176 #define CONDITION_M_CS          0x40
 177
 178 ///
 179 /// Protocol Guid Name defined in spec.
 180 ///
 181 #define EFI_EBC_PROTOCOL_GUID EFI_EBC_INTERPRETER_PROTOCOL_GUID
 182
 183 ///
 184 /// Define for forward reference.
 185 ///
 186 typedef struct _EFI_EBC_PROTOCOL EFI_EBC_PROTOCOL;
 187
 188 /**
 189   Creates a thunk for an EBC entry point, returning the address of the thunk.
 190
 191   A PE32+ EBC image, like any other PE32+ image, contains an optional header that specifies the
 192   entry point for image execution. However, for EBC images, this is the entry point of EBC
 193   instructions, so is not directly executable by the native processor. Therefore, when an EBC image is
 194   loaded, the loader must call this service to get a pointer to native code (thunk) that can be executed,
 195   which will invoke the interpreter to begin execution at the original EBC entry point.
 196
 197   @param  This          A pointer to the EFI_EBC_PROTOCOL instance.
 198   @param  ImageHandle   Handle of image for which the thunk is being created.
 199   @param  EbcEntryPoint Address of the actual EBC entry point or protocol service the thunk should call.
 200   @param  Thunk         Returned pointer to a thunk created.
 201
 202   @retval EFI_SUCCESS            The function completed successfully.
 203   @retval EFI_INVALID_PARAMETER  Image entry point is not 2-byte aligned.
 204   @retval EFI_OUT_OF_RESOURCES   Memory could not be allocated for the thunk.
 205 **/
 206 typedef
 207 EFI_STATUS
 208 (EFIAPI *EFI_EBC_CREATE_THUNK)(
 209   IN EFI_EBC_PROTOCOL           *This,
 210   IN EFI_HANDLE                 ImageHandle,
 211   IN VOID                       *EbcEntryPoint,
 212   OUT VOID                      **Thunk
 213   );
 214
 215 /**
 216   Called prior to unloading an EBC image from memory.
 217
 218   This function is called after an EBC image has exited, but before the image is actually unloaded. It
 219   is intended to provide the interpreter with the opportunity to perform any cleanup that may be
 220   necessary as a result of loading and executing the image.
 221
 222   @param  This          A pointer to the EFI_EBC_PROTOCOL instance.
 223   @param  ImageHandle   Image handle of the EBC image that is being unloaded from memory.
 224
 225   @retval EFI_SUCCESS            The function completed successfully.
 226   @retval EFI_INVALID_PARAMETER  Image handle is not recognized as belonging
 227                                  to an EBC image that has been executed.
 228 **/
 229 typedef
 230 EFI_STATUS
 231 (EFIAPI *EFI_EBC_UNLOAD_IMAGE)(
 232   IN EFI_EBC_PROTOCOL           *This,
 233   IN EFI_HANDLE                 ImageHandle
 234   );
 235
 236 /**
 237   This is the prototype for the Flush callback routine. A pointer to a routine
 238   of this type is passed to the EBC EFI_EBC_REGISTER_ICACHE_FLUSH protocol service.
 239
 240   @param  Start  The beginning physical address to flush from the processor's instruction cache.
 241   @param  Length The number of bytes to flush from the processor's instruction cache.
 242
 243   @retval EFI_SUCCESS            The function completed successfully.
 244
 245 **/
 246 typedef
 247 EFI_STATUS
 248 (EFIAPI *EBC_ICACHE_FLUSH)(
 249   IN EFI_PHYSICAL_ADDRESS     Start,
 250   IN UINT64                   Length
 251   );
 252
 253 /**
 254   Registers a callback function that the EBC interpreter calls to flush
 255   the processor instruction cache following creation of thunks.
 256
 257   @param  This       A pointer to the EFI_EBC_PROTOCOL instance.
 258   @param  Flush      Pointer to a function of type EBC_ICACH_FLUSH.
 259
 260   @retval EFI_SUCCESS            The function completed successfully.
 261
 262 **/
 263 typedef
 264 EFI_STATUS
 265 (EFIAPI *EFI_EBC_REGISTER_ICACHE_FLUSH)(
 266   IN EFI_EBC_PROTOCOL           *This,
 267   IN EBC_ICACHE_FLUSH           Flush
 268   );
 269
 270 /**
 271   Called to get the version of the interpreter.
 272
 273   This function is called to get the version of the loaded EBC interpreter. The value and format of the
 274   returned version is identical to that returned by the EBC BREAK 1 instruction.
 275
 276   @param  This       A pointer to the EFI_EBC_PROTOCOL instance.
 277   @param  Version    Pointer to where to store the returned version of the interpreter.
 278
 279   @retval EFI_SUCCESS            The function completed successfully.
 280   @retval EFI_INVALID_PARAMETER  Version pointer is NULL.
 281
 282 **/
 283 typedef
 284 EFI_STATUS
 285 (EFIAPI *EFI_EBC_GET_VERSION)(
 286   IN EFI_EBC_PROTOCOL           *This,
 287   IN OUT UINT64                 *Version
 288   );
 289
 290 ///
 291 /// The EFI EBC protocol provides services to load and execute EBC images, which will typically be
 292 /// loaded into option ROMs. The image loader will load the EBC image, perform standard relocations,
 293 /// and invoke the CreateThunk() service to create a thunk for the EBC image's entry point. The
 294 /// image can then be run using the standard EFI start image services.
 295 ///
 296 struct _EFI_EBC_PROTOCOL {
 297   EFI_EBC_CREATE_THUNK          CreateThunk;
 298   EFI_EBC_UNLOAD_IMAGE          UnloadImage;
 299   EFI_EBC_REGISTER_ICACHE_FLUSH RegisterICacheFlush;
 300   EFI_EBC_GET_VERSION           GetVersion;
 301 };
 302
 303 //
 304 // Extern the global EBC protocol GUID
 305 //
 306 extern EFI_GUID gEfiEbcProtocolGuid;
 307
 308 #endif