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 /// Protocol Guid Name defined in spec. 25 /// 26 #define EFI_EBC_PROTOCOL_GUID EFI_EBC_INTERPRETER_PROTOCOL_GUID 27 28 /// 29 /// Define for forward reference. 30 /// 31 typedef struct _EFI_EBC_PROTOCOL EFI_EBC_PROTOCOL; 32 33 /** 34 Creates a thunk for an EBC entry point, returning the address of the thunk. 35 36 A PE32+ EBC image, like any other PE32+ image, contains an optional header that specifies the 37 entry point for image execution. However, for EBC images, this is the entry point of EBC 38 instructions, so is not directly executable by the native processor. Therefore, when an EBC image is 39 loaded, the loader must call this service to get a pointer to native code (thunk) that can be executed, 40 which will invoke the interpreter to begin execution at the original EBC entry point. 41 42 @param This A pointer to the EFI_EBC_PROTOCOL instance. 43 @param ImageHandle Handle of image for which the thunk is being created. 44 @param EbcEntryPoint Address of the actual EBC entry point or protocol service the thunk should call. 45 @param Thunk Returned pointer to a thunk created. 46 47 @retval EFI_SUCCESS The function completed successfully. 48 @retval EFI_INVALID_PARAMETER Image entry point is not 2-byte aligned. 49 @retval EFI_OUT_OF_RESOURCES Memory could not be allocated for the thunk. 50 **/ 51 typedef 52 EFI_STATUS 53 (EFIAPI *EFI_EBC_CREATE_THUNK)( 54 IN EFI_EBC_PROTOCOL *This, 55 IN EFI_HANDLE ImageHandle, 56 IN VOID *EbcEntryPoint, 57 OUT VOID **Thunk 58 ); 59 60 /** 61 Called prior to unloading an EBC image from memory. 62 63 This function is called after an EBC image has exited, but before the image is actually unloaded. It 64 is intended to provide the interpreter with the opportunity to perform any cleanup that may be 65 necessary as a result of loading and executing the image. 66 67 @param This A pointer to the EFI_EBC_PROTOCOL instance. 68 @param ImageHandle Image handle of the EBC image that is being unloaded from memory. 69 70 @retval EFI_SUCCESS The function completed successfully. 71 @retval EFI_INVALID_PARAMETER Image handle is not recognized as belonging 72 to an EBC image that has been executed. 73 **/ 74 typedef 75 EFI_STATUS 76 (EFIAPI *EFI_EBC_UNLOAD_IMAGE)( 77 IN EFI_EBC_PROTOCOL *This, 78 IN EFI_HANDLE ImageHandle 79 ); 80 81 /** 82 This is the prototype for the Flush callback routine. A pointer to a routine 83 of this type is passed to the EBC EFI_EBC_REGISTER_ICACHE_FLUSH protocol service. 84 85 @param Start The beginning physical address to flush from the processor's instruction cache. 86 @param Length The number of bytes to flush from the processor's instruction cache. 87 88 @retval EFI_SUCCESS The function completed successfully. 89 90 **/ 91 typedef 92 EFI_STATUS 93 (EFIAPI *EBC_ICACHE_FLUSH)( 94 IN EFI_PHYSICAL_ADDRESS Start, 95 IN UINT64 Length 96 ); 97 98 /** 99 Registers a callback function that the EBC interpreter calls to flush 100 the processor instruction cache following creation of thunks. 101 102 @param This A pointer to the EFI_EBC_PROTOCOL instance. 103 @param Flush Pointer to a function of type EBC_ICACH_FLUSH. 104 105 @retval EFI_SUCCESS The function completed successfully. 106 107 **/ 108 typedef 109 EFI_STATUS 110 (EFIAPI *EFI_EBC_REGISTER_ICACHE_FLUSH)( 111 IN EFI_EBC_PROTOCOL *This, 112 IN EBC_ICACHE_FLUSH Flush 113 ); 114 115 /** 116 Called to get the version of the interpreter. 117 118 This function is called to get the version of the loaded EBC interpreter. The value and format of the 119 returned version is identical to that returned by the EBC BREAK 1 instruction. 120 121 @param This A pointer to the EFI_EBC_PROTOCOL instance. 122 @param Version Pointer to where to store the returned version of the interpreter. 123 124 @retval EFI_SUCCESS The function completed successfully. 125 @retval EFI_INVALID_PARAMETER Version pointer is NULL. 126 127 **/ 128 typedef 129 EFI_STATUS 130 (EFIAPI *EFI_EBC_GET_VERSION)( 131 IN EFI_EBC_PROTOCOL *This, 132 IN OUT UINT64 *Version 133 ); 134 135 /// 136 /// The EFI EBC protocol provides services to load and execute EBC images, which will typically be 137 /// loaded into option ROMs. The image loader will load the EBC image, perform standard relocations, 138 /// and invoke the CreateThunk() service to create a thunk for the EBC image's entry point. The 139 /// image can then be run using the standard EFI start image services. 140 /// 141 struct _EFI_EBC_PROTOCOL { 142 EFI_EBC_CREATE_THUNK CreateThunk; 143 EFI_EBC_UNLOAD_IMAGE UnloadImage; 144 EFI_EBC_REGISTER_ICACHE_FLUSH RegisterICacheFlush; 145 EFI_EBC_GET_VERSION GetVersion; 146 }; 147 148 // 149 // Extern the global EBC protocol GUID 150 // 151 extern EFI_GUID gEfiEbcProtocolGuid; 152 153 #endif 154