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 309