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