15. TE Image¶

15.1. Introduction¶

The Terse Executable (TE) image format was created as a mechanism to reduce the overhead of the PE/COFF headers in PE32/PE32+ images, resulting in a corresponding reduction of image sizes for executables running in the PI Architecture environment. Reducing image size provides an opportunity for use of a smaller system flash part.

TE images, both drivers and applications, are created as PE32 (or PE32+) executables. PE32 is a generic executable image format that is intended to support multiple target systems, processors, and operating systems. As a result, the headers in the image contain information that is not necessarily applicable to all target systems. In an effort to reduce image size, a new executable image header (TE) was created that includes only those fields from the PE/COFF headers required for execution under the PI Architecture. Since this header contains the information required for execution of the image, it can replace the PE/COFF headers from the original image. This specification defines the TE header, the fields in the header, and how they are used in the PI Architecture’s execution environment.

15.2. PE32 Headers¶

A PE file header, as described in the Microsoft Portable Executable and Common Object File Format Specification , contains an MS-DOS* stub, a PE signature, a COFF header, an optional header, and section headers. For successful execution, PEIMs in the PI Architecture require very little of the data from these headers, and in fact the MS-DOS stub and PE signature are not required at all.

See COFF Header Fields Required for TE Images and Optional Header Fields Required for TE Images for the necessary fields and their descriptions.

Table 15.1 COFF Header Fields Required for TE Images¶
COFF Header	Description
Machine	Target machine identifier 2 bytes in both COFF header and TE header
NumberOfSections	Number of sections section headers 2 bytes in COFF header 1 byte in TE header

Table 15.2 Optional Header Fields Required for TE Images¶
OPTIONAL Header	Description
AddressOfEntryPoint	Address of entry point relative to image base 4 bytes in both optional header and TE header
BaseOfCode	Offset from image base to the start of the code section 4 bytes in both optional header and TE header
ImageBase	Image s linked address 4 bytes in OptionalHeader32 8 bytes in OptionalHeader64 and 8 bytes in TE header
Subsystem	Subsystem required to run the image 2 bytes in optional header 1 byte in TE header

15.2.1. TE Header¶

Summary

To reduce the overhead of PE/COFF headers in the PI Architecture’s environment, a minimal (TE) header can be defined that includes only those fields required for execution in the PI Architecture. This header can then be used to replace the original headers at the start of the original image.

Prototype

typedef struct {
  UINT16                    Signature;
  UINT16                    Machine;
  UINT8                     NumberOfSections;
  UINT8                     Subsystem;
  UINT16                    StrippedSize;
  UINT32                    AddressOfEntryPoint;
  UINT32                    BaseOfCode;
  UINT64                    ImageBase;
  EFI_IMAGE_DATA_DIRECTORY  DataDirectory[2];
} EFI_TE_IMAGE_HEADER;

Parameters

Signature: TE image signature

Machine: Target machine, as specified in the original image’s file header

NumberOfSections: Number of sections, as specified in the original image’s file header

Subsystem: Target subsystem, as specified in the original optional header

StrippedSize: Number of bytes removed from the base of the original image

AddressOfEntryPoint: Address of the entry point to the driver, as specified in the original image’s optional header

BaseOfCode: Base of the code, as specified in the original image’s optional header

ImageBase: Image base, as specified in the original image’s optional header (0-extended to 64-bits for PE32 images)

DataDirectory: Directory entries for base relocations and the debug directory from the original image’s corresponding directory entries. See “Related Definitions” below.

Field Descrptions

In the EFI_TE_IMAGE HEADER , the Machine, NumberOfSections, Subsystem ``,``AddressOfEntryPoint, BaseOfCode, and ImageBase all come directly from the original PE headers to enable partial reconstitution of the original headers if necessary.

The 2-byte Signature should be set to EFI_TE_IMAGE_HEADER_SIGNATURE to designate the image as TE, as opposed to the “MZ” signature at the start of standard PE/COFF images.

The StrippedSize should be set to the number of bytes removed from the start of the original image, which will typically include the MS-DOS, COFF, and optional headers, as well as the section headers. This size can be used by image loaders and tools to make appropriate adjustments to the other fields in the TE image header. Note that StrippedSize does not take into account the size of the TE image header that will be added to the image. That is to say, the delta in the total image size when converted to TE is StrippedSize - sizeof (EFI_TE_IMAGE_HEADER). This will typically need to be taken into account by tools using the fields in the TE header.

The DataDirectory array contents are copied directly from the base relocations and debug directory entries in the original optional header data directories. This image format also assumes that file alignment is equal to section alignment.

//*****************************************************
//EFI_IMAGE_DATA_DIRECTORY
//*****************************************************
typedef struct {
  UINT32    VirtualAddress;
  UINT32    Size;
} EFI_IMAGE_DATA_DIRECTORY;
#define EFI_TE_IMAGE_DIRECTORY_ENTRY_BASERELOC    0
#define EFI_TE_IMAGE_DIRECTORY_ENTRY_DEBUG        1

#define EFI_TE_IMAGE_HEADER_SIGNATURE   0x5A56 // “VZ”