MdePkg/Include/Protocol/Ebc.h

   1 /** @file
   2   Describes the protocol interface to the EBC interpreter.
   3
   4   Copyright (c) 2006 - 2008, Intel Corporation
   5   All rights reserved. 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   This routine is called by the core firmware to provide the EBC driver with
 100   a function to call to flush the CPU's instruction cache following creation
 101   of a thunk. It is not required.
 102
 103   @param  This       A pointer to the EFI_EBC_PROTOCOL instance.
 104   @param  Flush      Pointer to a function of type EBC_ICACH_FLUSH.
 105
 106   @retval EFI_SUCCESS            The function completed successfully.
 107
 108 **/
 109 typedef
 110 EFI_STATUS
 111 (EFIAPI *EFI_EBC_REGISTER_ICACHE_FLUSH)(
 112   IN EFI_EBC_PROTOCOL           *This,
 113   IN EBC_ICACHE_FLUSH           Flush
 114   );
 115
 116 /**
 117   Called to get the version of the interpreter.
 118
 119   This function is called to get the version of the loaded EBC interpreter. The value and format of the
 120   returned version is identical to that returned by the EBC BREAK 1 instruction.
 121
 122   @param  This       A pointer to the EFI_EBC_PROTOCOL instance.
 123   @param  Version Pointer to where to store the returned version of the interpreter.
 124
 125   @retval EFI_SUCCESS            The function completed successfully.
 126   @retval EFI_INVALID_PARAMETER  Version pointer is NULL.
 127
 128 **/
 129 typedef
 130 EFI_STATUS
 131 (EFIAPI *EFI_EBC_GET_VERSION)(
 132   IN EFI_EBC_PROTOCOL           *This,
 133   IN OUT UINT64                 *Version
 134   );
 135
 136 //
 137 // Prototype for the actual EBC protocol interface
 138 //
 139 /**
 140   This protocol provides the services that allow execution of EBC images.
 141
 142   @par Protocol Description:
 143   The EFI EBC protocol provides services to load and execute EBC images, which will typically be
 144   loaded into option ROMs. The image loader will load the EBC image, perform standard relocations,
 145   and invoke the CreateThunk() service to create a thunk for the EBC image's entry point. The
 146   image can then be run using the standard EFI start image services.
 147
 148   @param CreateThunk
 149   Creates a thunk for an EBC image entry point or protocol service,
 150   and returns a pointer to the thunk.
 151
 152   @param UnloadImage
 153   Called when an EBC image is unloaded to allow the interpreter to
 154   perform any cleanup associated with the image execution.
 155
 156   @param RegisterICacheFlush
 157   Called to register a callback function that the EBC interpreter can
 158   call to flush the processor instruction cache after creating thunks.
 159
 160   @param GetVersion
 161   Called to get the version of the associated EBC interpreter.
 162
 163 **/
 164 struct _EFI_EBC_PROTOCOL {
 165   EFI_EBC_CREATE_THUNK          CreateThunk;
 166   EFI_EBC_UNLOAD_IMAGE          UnloadImage;
 167   EFI_EBC_REGISTER_ICACHE_FLUSH RegisterICacheFlush;
 168   EFI_EBC_GET_VERSION           GetVersion;
 169 };
 170
 171 //
 172 // Extern the global EBC protocol GUID
 173 //
 174 extern EFI_GUID gEfiEbcProtocolGuid;
 175
 176 #endif