2 Describes the protocol interface to the EBC interpreter.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #ifndef __EFI_EBC_PROTOCOL_H__
10 #define __EFI_EBC_PROTOCOL_H__
12 #define EFI_EBC_INTERPRETER_PROTOCOL_GUID \
14 0x13AC6DD1, 0x73D0, 0x11D4, {0xB0, 0x6B, 0x00, 0xAA, 0x00, 0xBD, 0x6D, 0xE7 } \
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
60 // #define OPCODE_27 0x27
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
75 // #define OPCODE_34 0x34
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
84 // Bit masks for opcode encodings
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
97 // Masks for instructions that encode presence of indexes for operand1 and/or
100 #define OPCODE_M_IMMED_OP1 0x80
101 #define OPCODE_M_IMMED_OP2 0x40
104 // Bit masks for operand encodings
106 #define OPERAND_M_INDIRECT1 0x08
107 #define OPERAND_M_INDIRECT2 0x80
108 #define OPERAND_M_OP1 0x07
109 #define OPERAND_M_OP2 0x70
112 // Masks for data manipulation instructions
114 #define DATAMANIP_M_64 0x40 // 64-bit width operation
115 #define DATAMANIP_M_IMMDATA 0x80
118 // For MOV instructions, need a mask for the opcode when immediate
119 // data applies to R2.
121 #define OPCODE_M_IMMED_OP2 0x40
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
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
140 // Masks for CALL instruction encodings
142 #define OPERAND_M_RELATIVE_ADDR 0x10
143 #define OPERAND_M_NATIVE_CALL 0x20
146 // Masks for decoding push/pop instructions
148 #define PUSHPOP_M_IMMDATA 0x80 // opcode bit indicating immediate data
149 #define PUSHPOP_M_64 0x40 // opcode bit indicating 64-bit operation
151 // Mask for operand of JMP instruction
153 #define JMP_M_RELATIVE 0x10
154 #define JMP_M_CONDITIONAL 0x80
155 #define JMP_M_CS 0x40
158 // Macros to determine if a given operand is indirect
160 #define OPERAND1_INDIRECT(op) ((op) & OPERAND_M_INDIRECT1)
161 #define OPERAND2_INDIRECT(op) ((op) & OPERAND_M_INDIRECT2)
164 // Macros to extract the operands from second byte of instructions
166 #define OPERAND1_REGNUM(op) ((op) & OPERAND_M_OP1)
167 #define OPERAND2_REGNUM(op) (((op) & OPERAND_M_OP2) >> 4)
169 #define OPERAND1_CHAR(op) ('0' + OPERAND1_REGNUM (op))
170 #define OPERAND2_CHAR(op) ('0' + OPERAND2_REGNUM (op))
173 // Condition masks usually for byte 1 encodings of code
175 #define CONDITION_M_CONDITIONAL 0x80
176 #define CONDITION_M_CS 0x40
179 /// Protocol Guid Name defined in spec.
181 #define EFI_EBC_PROTOCOL_GUID EFI_EBC_INTERPRETER_PROTOCOL_GUID
184 /// Define for forward reference.
186 typedef struct _EFI_EBC_PROTOCOL EFI_EBC_PROTOCOL
;
189 Creates a thunk for an EBC entry point, returning the address of the thunk.
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.
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.
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.
208 (EFIAPI
*EFI_EBC_CREATE_THUNK
)(
209 IN EFI_EBC_PROTOCOL
*This
,
210 IN EFI_HANDLE ImageHandle
,
211 IN VOID
*EbcEntryPoint
,
216 Called prior to unloading an EBC image from memory.
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.
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.
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.
231 (EFIAPI
*EFI_EBC_UNLOAD_IMAGE
)(
232 IN EFI_EBC_PROTOCOL
*This
,
233 IN EFI_HANDLE ImageHandle
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.
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.
243 @retval EFI_SUCCESS The function completed successfully.
248 (EFIAPI
*EBC_ICACHE_FLUSH
)(
249 IN EFI_PHYSICAL_ADDRESS Start
,
254 Registers a callback function that the EBC interpreter calls to flush
255 the processor instruction cache following creation of thunks.
257 @param This A pointer to the EFI_EBC_PROTOCOL instance.
258 @param Flush Pointer to a function of type EBC_ICACH_FLUSH.
260 @retval EFI_SUCCESS The function completed successfully.
265 (EFIAPI
*EFI_EBC_REGISTER_ICACHE_FLUSH
)(
266 IN EFI_EBC_PROTOCOL
*This
,
267 IN EBC_ICACHE_FLUSH Flush
271 Called to get the version of the interpreter.
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.
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.
279 @retval EFI_SUCCESS The function completed successfully.
280 @retval EFI_INVALID_PARAMETER Version pointer is NULL.
285 (EFIAPI
*EFI_EBC_GET_VERSION
)(
286 IN EFI_EBC_PROTOCOL
*This
,
287 IN OUT UINT64
*Version
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.
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
;
304 // Extern the global EBC protocol GUID
306 extern EFI_GUID gEfiEbcProtocolGuid
;