MdeModulePkg: introduce PE/COFF image emulator protocol
authorArd Biesheuvel <ard.biesheuvel@linaro.org>
Fri, 10 Mar 2017 15:50:24 +0000 (16:50 +0100)
committerArd Biesheuvel <ard.biesheuvel@linaro.org>
Mon, 15 Apr 2019 01:35:41 +0000 (18:35 -0700)
Introduce a protocol that can be invoked by the image loading services
to execute foreign architecture PE/COFF images via an emulator.

Signed-off-by: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Reviewed-by: Michael D Kinney <michael.d.kinney@intel.com>
Reviewed-by: Hao Wu <hao.a.wu@intel.com>
MdeModulePkg/Include/Protocol/PeCoffImageEmulator.h [new file with mode: 0644]
MdeModulePkg/MdeModulePkg.dec

diff --git a/MdeModulePkg/Include/Protocol/PeCoffImageEmulator.h b/MdeModulePkg/Include/Protocol/PeCoffImageEmulator.h
new file mode 100644 (file)
index 0000000..29633e9
--- /dev/null
@@ -0,0 +1,107 @@
+/** @file\r
+  Copyright (c) 2019, Linaro, Ltd. All rights reserved.<BR>\r
+\r
+  This program and the accompanying materials are licensed and made available\r
+  under the terms and conditions of the BSD License which accompanies this\r
+  distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+#ifndef _PECOFF_IMAGE_EMULATOR_PROTOCOL_GUID_H_\r
+#define _PECOFF_IMAGE_EMULATOR_PROTOCOL_GUID_H_\r
+\r
+#define EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL_GUID \\r
+  { 0x96F46153, 0x97A7, 0x4793, { 0xAC, 0xC1, 0xFA, 0x19, 0xBF, 0x78, 0xEA, 0x97 } }\r
+\r
+typedef struct _EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL;\r
+\r
+/**\r
+  Check whether the emulator supports executing a certain PE/COFF image\r
+\r
+  @param[in] This         This pointer for EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL\r
+                          structure\r
+  @param[in] ImageType    Whether the image is an application, a boot time\r
+                          driver or a runtime driver.\r
+  @param[in] DevicePath   Path to device where the image originated\r
+                          (e.g., a PCI option ROM)\r
+\r
+  @retval TRUE            The image is supported by the emulator\r
+  @retval FALSE           The image is not supported by the emulator.\r
+**/\r
+typedef\r
+BOOLEAN\r
+(EFIAPI *EDKII_PECOFF_IMAGE_EMULATOR_IS_IMAGE_SUPPORTED) (\r
+  IN  EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL    *This,\r
+  IN  UINT16                                  ImageType,\r
+  IN  EFI_DEVICE_PATH_PROTOCOL                *DevicePath   OPTIONAL\r
+  );\r
+\r
+/**\r
+  Register a supported PE/COFF image with the emulator. After this call\r
+  completes successfully, the PE/COFF image may be started as usual, and\r
+  it is the responsibility of the emulator implementation that any branch\r
+  into the code section of the image (including returns from functions called\r
+  from the foreign code) is executed as if it were running on the machine\r
+  type it was built for.\r
+\r
+  @param[in]      This          This pointer for\r
+                                EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL structure\r
+  @param[in]      ImageBase     The base address in memory of the PE/COFF image\r
+  @param[in]      ImageSize     The size in memory of the PE/COFF image\r
+  @param[in,out]  EntryPoint    The entry point of the PE/COFF image. Passed by\r
+                                reference so that the emulator may modify it.\r
+\r
+  @retval EFI_SUCCESS           The image was registered with the emulator and\r
+                                can be started as usual.\r
+  @retval other                 The image could not be registered.\r
+\r
+  If the PE/COFF machine type or image type are not supported by the emulator,\r
+  then ASSERT().\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EDKII_PECOFF_IMAGE_EMULATOR_REGISTER_IMAGE) (\r
+  IN      EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL    *This,\r
+  IN      EFI_PHYSICAL_ADDRESS                    ImageBase,\r
+  IN      UINT64                                  ImageSize,\r
+  IN  OUT EFI_IMAGE_ENTRY_POINT                   *EntryPoint\r
+  );\r
+\r
+/**\r
+  Unregister a PE/COFF image that has been registered with the emulator.\r
+  This should be done before the image is unloaded from memory.\r
+\r
+  @param[in] This         This pointer for EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL\r
+                          structure\r
+  @param[in] ImageBase    The base address in memory of the PE/COFF image\r
+\r
+  @retval EFI_SUCCESS     The image was unregistered with the emulator.\r
+  @retval other           Image could not be unloaded.\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EDKII_PECOFF_IMAGE_EMULATOR_UNREGISTER_IMAGE) (\r
+  IN  EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL    *This,\r
+  IN  EFI_PHYSICAL_ADDRESS                    ImageBase\r
+  );\r
+\r
+#define EDKII_PECOFF_IMAGE_EMULATOR_VERSION         0x1\r
+\r
+typedef struct _EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL {\r
+  EDKII_PECOFF_IMAGE_EMULATOR_IS_IMAGE_SUPPORTED    IsImageSupported;\r
+  EDKII_PECOFF_IMAGE_EMULATOR_REGISTER_IMAGE        RegisterImage;\r
+  EDKII_PECOFF_IMAGE_EMULATOR_UNREGISTER_IMAGE      UnregisterImage;\r
+\r
+  // Protocol version implemented by the emulator\r
+  UINT32                                            Version;\r
+  // The machine type implemented by the emulator\r
+  UINT16                                            MachineType;\r
+} EDKII_PECOFF_IMAGE_EMULATOR_PROTOCOL;\r
+\r
+extern EFI_GUID gEdkiiPeCoffImageEmulatorProtocolGuid;\r
+\r
+#endif\r
index 22c6fc0..be84916 100644 (file)
 \r
   ## Include/Protocol/AtaAtapiPolicy.h\r
   gEdkiiAtaAtapiPolicyProtocolGuid = { 0xe59cd769, 0x5083, 0x4f26,{ 0x90, 0x94, 0x6c, 0x91, 0x9f, 0x91, 0x6c, 0x4e } }\r
+\r
+  ## Include/Protocol/PeCoffImageEmulator.h\r
+  gEdkiiPeCoffImageEmulatorProtocolGuid = { 0x96f46153, 0x97a7, 0x4793, { 0xac, 0xc1, 0xfa, 0x19, 0xbf, 0x78, 0xea, 0x97 } }\r
+\r
 #\r
 # [Error.gEfiMdeModulePkgTokenSpaceGuid]\r
 #   0x80000001 | Invalid value provided.\r