MdeModulePkg/Include/Protocol/PeCoffImageEmulator.h

   1 /** @file
   2   Copyright (c) 2019, Linaro, Ltd. All rights reserved.<BR>
   3
   4   This program and the accompanying materials are licensed and made available
   5   under the terms and conditions of the BSD License which accompanies this
   6   distribution.  The full text of the license may be found at
   7   http://opensource.org/licenses/bsd-license.php
   8
   9   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 **/
  13
  14 #ifndef _PECOFF_IMAGE_EMULATOR_PROTOCOL_GUID_H_
  15 #define _PECOFF_IMAGE_EMULATOR_PROTOCOL_GUID_H_
  16
  17 #define EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL_GUID \
  18   { 0x96F46153, 0x97A7, 0x4793, { 0xAC, 0xC1, 0xFA, 0x19, 0xBF, 0x78, 0xEA, 0x97 } }
  19
  20 typedef struct _EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL;
  21
  22 /**
  23   Check whether the emulator supports executing a certain PE/COFF image
  24
  25   @param[in] This         This pointer for EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL
  26                           structure
  27   @param[in] ImageType    Whether the image is an application, a boot time
  28                           driver or a runtime driver.
  29   @param[in] DevicePath   Path to device where the image originated
  30                           (e.g., a PCI option ROM)
  31
  32   @retval TRUE            The image is supported by the emulator
  33   @retval FALSE           The image is not supported by the emulator.
  34 **/
  35 typedef
  36 BOOLEAN
  37 (EFIAPI *EDKII_PECOFF_IMAGE_EMULATOR_IS_IMAGE_SUPPORTED) (
  38   IN  EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL    *This,
  39   IN  UINT16                                  ImageType,
  40   IN  EFI_DEVICE_PATH_PROTOCOL                *DevicePath   OPTIONAL
  41   );
  42
  43 /**
  44   Register a supported PE/COFF image with the emulator. After this call
  45   completes successfully, the PE/COFF image may be started as usual, and
  46   it is the responsibility of the emulator implementation that any branch
  47   into the code section of the image (including returns from functions called
  48   from the foreign code) is executed as if it were running on the machine
  49   type it was built for.
  50
  51   @param[in]      This          This pointer for
  52                                 EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL structure
  53   @param[in]      ImageBase     The base address in memory of the PE/COFF image
  54   @param[in]      ImageSize     The size in memory of the PE/COFF image
  55   @param[in,out]  EntryPoint    The entry point of the PE/COFF image. Passed by
  56                                 reference so that the emulator may modify it.
  57
  58   @retval EFI_SUCCESS           The image was registered with the emulator and
  59                                 can be started as usual.
  60   @retval other                 The image could not be registered.
  61
  62   If the PE/COFF machine type or image type are not supported by the emulator,
  63   then ASSERT().
  64 **/
  65 typedef
  66 EFI_STATUS
  67 (EFIAPI *EDKII_PECOFF_IMAGE_EMULATOR_REGISTER_IMAGE) (
  68   IN      EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL    *This,
  69   IN      EFI_PHYSICAL_ADDRESS                    ImageBase,
  70   IN      UINT64                                  ImageSize,
  71   IN  OUT EFI_IMAGE_ENTRY_POINT                   *EntryPoint
  72   );
  73
  74 /**
  75   Unregister a PE/COFF image that has been registered with the emulator.
  76   This should be done before the image is unloaded from memory.
  77
  78   @param[in] This         This pointer for EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL
  79                           structure
  80   @param[in] ImageBase    The base address in memory of the PE/COFF image
  81
  82   @retval EFI_SUCCESS     The image was unregistered with the emulator.
  83   @retval other           Image could not be unloaded.
  84 **/
  85 typedef
  86 EFI_STATUS
  87 (EFIAPI *EDKII_PECOFF_IMAGE_EMULATOR_UNREGISTER_IMAGE) (
  88   IN  EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL    *This,
  89   IN  EFI_PHYSICAL_ADDRESS                    ImageBase
  90   );
  91
  92 #define EDKII_PECOFF_IMAGE_EMULATOR_VERSION         0x1
  93
  94 typedef struct _EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL {
  95   EDKII_PECOFF_IMAGE_EMULATOR_IS_IMAGE_SUPPORTED    IsImageSupported;
  96   EDKII_PECOFF_IMAGE_EMULATOR_REGISTER_IMAGE        RegisterImage;
  97   EDKII_PECOFF_IMAGE_EMULATOR_UNREGISTER_IMAGE      UnregisterImage;
  98
  99   // Protocol version implemented by the emulator
 100   UINT32                                            Version;
 101   // The machine type implemented by the emulator
 102   UINT16                                            MachineType;
 103 } EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL;
 104
 105 extern EFI_GUID gEdkiiPeCoffImageEmulatorProtocolGuid;
 106
 107 #endif