3. Firmware Storage Code Definitions

3.1. Firmware Storage Code Definitions Introduction

This section provides the code definitions for:

• The PI Architecture Firmware Storage binary formats for volumes, file system, files, and file sections.

• The PEI interfaces that support firmware volumes, firmware file systems, firmware files, and firmware file sections.

• The DXE protocols that support firmware volumes, firmware file systems, firmware files, and firmware file sections.

3.2. Firmware Storage Formats

3.2.1. Firmware Volume

3.2.1.1. EFI_FIRMWARE_VOLUME_HEADER

Summary

Describes the features and layout of the firmware volume.

Prototype

typedef struct {
  UINT8                    ZeroVector[16];
  EFI_GUID                 FileSystemGuid;
  UINT64                   FvLength;
  UINT32                   Signature;
  EFI_FVB_ATTRIBUTES_2     Attributes;
  UINT16                   HeaderLength;
  UINT16                   Checksum;
  UINT16                   ExtHeaderOffset;
  UINT8                    Reserved[1];
  UINT8                    Revision;
  EFI_FV_BLOCK_MAP         BlockMap[];
} EFI_FIRMWARE_VOLUME_HEADER;

Parameters

ZeroVector

The first 16 bytes are reserved to allow for the reset vector of processors whose reset vector is at address 0.

FileSystemGuid

Declares the file system with which the firmware volume is formatted. Type EFI_GUID is defined in InstallProtocolInterface() in the Unified Extensible Firmware Interface Specification , version 2.0 (UEFI 2.0 specification).

FvLength

Length in bytes of the complete firmware volume, including the header.

Signature

Set to {'_','F','V','H'} .

Attributes

Declares capabilities and power-on defaults for the firmware volume. Current state is determined using the GetAttributes() function and is not maintained in the Attributes field of the firmware volume header. Type EFI_FVB_ATTRIBUTES_2 is defined in “Related Definitions” below.

HeaderLength

Length in bytes of the complete firmware volume header.

Checksum

A 16-bit checksum of the firmware volume header. A valid header sums to zero.

ExtHeaderOffset

Offset, relative to the start of the header, of the extended header (EFI_FIRMWARE_VOLUME_EXT_HEADER) or zero if there is no extended header. The extended header is followed by zero or more variable length extension entries. Each extension entry is prefixed with the EFI_FIRMWARE_VOLUME_EXT_ENTRY structure (see “Related Definitions” below), which defines the type and size of the extension entry. The extended header is always 32-bit aligned relative to the start of the FIRMWARE VOLUME.

If there is an instance of the EFI_FIRMWARE_VOLUME_EXT_HEADER , then the firmware shall build an instance of the Firmware Volume Media Device Path (ref Vol2, Section 8.2).

Reserved

In this version of the specification, this field must always be set to zero.

Revision

Set to 2. Future versions of this specification may define new header fields and will increment the Revision field accordingly.

FvBlockMap[]

An array of run-length encoded FvBlockMapEntry structures. The array is terminated with an entry of {0,0} .

FvBlockMapEntry.NumBlocks

The number of blocks in the run.

FvBlockMapEntry.BlockLength

The length of each block in the run.

Description

A firmware volume based on a block device begins with a header that describes the features and layout of the firmware volume. This header includes a description of the capabilities, state, and block map of the device.

The block map is a run-length-encoded array of logical block definitions. This design allows a reasonable mechanism of describing the block layout of typical firmware devices. Each block can be referenced by its logical block address (LBA). The LBA is a zero-based enumeration of all of the blocks–i.e., LBA 0 is the first block, LBA 1 is the second block, and LBA n is the (n-1) device.

The header is always located at the beginning of LBA 0.

Related Definitions

//*************************************************
// EFI_FVB_ATTRIBUTES_2
//*************************************************
typedef UINT32 EFI_FVB_ATTRIBUTES_2

// Attributes bit definitions
#define EFI_FVB2_READ_DISABLED_CAP   0x00000001
#define EFI_FVB2_READ_ENABLED_CAP    0x00000002
#define EFI_FVB2_READ_STATUS         0x00000004

#define EFI_FVB2_WRITE_DISABLED_CAP  0x00000008
#define EFI_FVB2_WRITE_ENABLED_CAP   0x00000010
#define EFI_FVB2_WRITE_STATUS        0x00000020

#define EFI_FVB2_LOCK_CAP            0x00000040
#define EFI_FVB2_LOCK_STATUS         0x00000080

#define EFI_FVB2_STICKY_WRITE        0x00000200
#define EFI_FVB2_MEMORY_MAPPED       0x00000400
#define EFI_FVB2_ERASE_POLARITY      0x00000800

#define EFI_FVB2_READ_LOCK_CAP       0x00001000
#define EFI_FVB2_READ_LOCK_STATUS    0x00002000

#define EFI_FVB2_WRITE_LOCK_CAP      0x00004000
#define EFI_FVB2_WRITE_LOCK_STATUS   0x00008000

#define EFI_FVB2_ALIGNMENT           0x001F0000
#define EFI_FVB2_WEAK_ALIGNMENT      0x80000000
#define EFI_FVB2_ALIGNMENT_1         0x00000000
#define EFI_FVB2_ALIGNMENT_2         0x00010000
#define EFI_FVB2_ALIGNMENT_4         0x00020000
#define EFI_FVB2_ALIGNMENT_8         0x00030000
#define EFI_FVB2_ALIGNMENT_16        0x00040000
#define EFI_FVB2_ALIGNMENT_32        0x00050000
#define EFI_FVB2_ALIGNMENT_64        0x00060000
#define EFI_FVB2_ALIGNMENT_128       0x00070000
#define EFI_FVB2_ALIGNMENT_256       0x00080000
#define EFI_FVB2_ALIGNMENT_512       0x00090000
#define EFI_FVB2_ALIGNMENT_1K        0x000A0000
#define EFI_FVB2_ALIGNMENT_2K        0x000B0000
#define EFI_FVB2_ALIGNMENT_4K        0x000C0000
#define EFI_FVB2_ALIGNMENT_8K        0x000D0000
#define EFI_FVB2_ALIGNMENT_16K       0x000E0000
#define EFI_FVB2_ALIGNMENT_32K       0x000F0000
#define EFI_FVB2_ALIGNMENT_64K       0x00100000
#define EFI_FVB2_ALIGNMENT_128K      0x00110000
#define EFI_FVB2_ALIGNMENT_256K      0x00120000
#define EFI_FVB2_ALIGNMENT_512K      0x00130000
#define EFI_FVB2_ALIGNMENT_1M        0x00140000
#define EFI_FVB2_ALIGNMENT_2M        0x00150000
#define EFI_FVB2_ALIGNMENT_4M        0x00160000
#define EFI_FVB2_ALIGNMENT_8M        0x00170000
#define EFI_FVB2_ALIGNMENT_16M       0x00180000
#define EFI_FVB2_ALIGNMENT_32M       0x00190000
#define EFI_FVB2_ALIGNMENT_64M       0x001A0000
#define EFI_FVB2_ALIGNMENT_128M      0x001B0000
#define EFI_FVB2_ALIGNMENT_256M      0x001C0000
#define EFI_FVB2_ALIGNMENT_512M      0x001D0000
#define EFI_FVB2_ALIGNMENT_1G        0x001E0000
#define EFI_FVB2_ALIGNMENT_2G        0x001F0000

Descriptions of EFI_FVB_ATTRIBUTES_2 describes the fields in the above definition:

Table 3.1 Descriptions of EFI_FVB_ATTRIBUTES_2

Attribute	Description
EFI_FVB2_READ_DISABLED_CAP	TRUE if reads from the firmware volume may be disabled.
EFI_FVB2_READ_ENABLED_CAP	TRUE if reads from the firmware volume may be enabled.
EFI_FVB2_READ_STATUS	TRUE if reads from the firmware volume are currently enabled.
EFI_FVB2_WRITE_DISABLED_CAP	TRUE if writes to the firmware volume may be disabled.
EFI_FVB2_WRITE_ENABLED_CAP	TRUE if writes to the firmware volume may be enabled.
EFI_FVB2_WRITE_STATUS	TRUE if writes to the firmware volume are currently enabled.
EFI_FVB2_LOCK_CAP	TRUE if firmware volume attributes may be locked down.
EFI_FVB2_LOCK_STATUS	TRUE if firmware volume attributes are currently locked down.
EFI_FVB2_STICKY_WRITE	TRUE if a block erase is required to transition bits from NOT EFI_FVB2_ERASE_POLARITY to EFI_FVB2_ERASE_POLARITY. That is, after erasure, a write may negate a bit in the EFI_FVB2_ERASE_POLARITY state, but a write cannot flip it back again. A block erase cycle is required to transition bits from the (NOT) EFI_FVB2_ERASE_POLARITY state back to the EFI_FVB2_ERASE_POLARITY state. See the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.
EFI_FVB2_MEMORY_MAPPED	TRUE if firmware volume is memory mapped.
EFI_FVB2_ERASE_POLARITY	Value of all bits after erasure. See the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.
EFI_FVB2_READ_LOCK_CAP	TRUE if the firmware volume’s read-status can be locked.
EFI_FVB2_READ_LOCK_STATUS	TRUE If the firmware volume’s read-status is locked.
EFI_FVB2_WRITE_LOCK_CAP	TRUE if the firmware volume’s write-status can be locked.
EFI_FVB2_WRITE_LOCK_STATUS	TRUE if the firmware volume’s write-status is locked.
EFI_FVB2_ALIGNMENT	The first byte of the firmware volume must be placed at an address which is an even multiple of 2^(this field). For example, a value of 5 in this field would mean a required alignment of 32 bytes.
EFI_FVB2_WEAK_ALIGNMENT	TRUE if the firmware volume can be less than the the highest file alignment value.

All other EFI_FVB_ATTRIBUTES_2 bits are reserved and must be zero.

typedef struct {
  UINT32 NumBlocks;
  UINT32 Length;
} EFI_FV_BLOCK_MAP;

NumBlocks

The number of sequential blocks which are of the same size.

Length

The size of the blocks.

typedef struct {
  EFI_GUID  FvName;
  UINT32    ExtHeaderSize;
} EFI_FIRMWARE_VOLUME_EXT_HEADER;

FvName

Firmware volume name.

ExtHeaderSize

Size of the rest of the extension header, including this structure.

After the extension header, there is an array of variable-length extension header entries, each prefixed with the EFI_FIRMWARE_VOLUME_EXT_ENTRY structure.

typedef struct {
  UINT16  ExtEntrySize;
  UINT16  ExtEntryType;
} EFI_FIRMWARE_VOLUME_EXT_ENTRY;

ExtEntrySize

Size of this header extension.

ExtEntryType

Type of the header. See EFI_FV_EXT_TYPE_x.

#define EFI_FV_EXT_TYPE_OEM_TYPE 0x01
typedef struct {
  EFI_FIRMWARE_VOLUME_EXT_ENTRY   Hdr;
  UINT32                          TypeMask;
  //EFI_GUID                      Types[];
} EFI_FIRMWARE_VOLUME_EXT_ENTRY_OEM_TYPE;

Hdr

Standard extension entry, with the type EFI_FV_EXT_TYPE_OEM_TYPE .

TypeMask

A bit mask, one bit for each file type between 0xC0 (bit 0) and 0xDF (bit 31). If a bit is ‘1’, then the GUID entry exists in Types . If a bit is ‘0’ then no GUID entry exists in Types . For example, the value 0x01010301 would indicate that there would be five total entries in Types for file types 0xC0 (bit 0), 0xC8 (bit 4), 0xC9 (bit 5), 0xD0 (bit 16), and 0xD8 (bit 24).

Types

An array of GUIDs, each GUID representing an OEM file type.

This extension header provides a mapping between a GUID and an OEM file type.

#define EFI_FV_EXT_TYPE_GUID_TYPE 0x0002
typedef struct {
  EFI_FIRMWARE_VOLUME_EXT_ENTRY   Hdr;
  EFI_GUID                        FormatType;
  //UINT8                         Data[];
} EFI_FIRMWARE_VOLUME_EXT_ENTRY_GUID_TYPE;

Hdr

Standard extension entry, with the type EFI_FV_EXT_TYPE_OEM_TYPE .

FormatType

Vendor-specific GUID

Length

Length of the data following this field

Data

An array of bytes of length Length.

This extension header EFI_FIRMWARE_VOLUME_EXT_ENTRY_GUID_TYPE provides a vendor-specific GUID FormatType type which includes a length and a successive series of data bytes. Values 0x00, 0x03..0xffff are reserved by the specification.

#define EFI_FV_EXT_TYPE_USED_SIZE_TYPE 0x03
  typedef struct {
    EFI_FIRMWARE_VOLUME_EXT_ENTRY Hdr;
    UINT32 UsedSize;
  } EFI_FIRMWARE_VOLUME_EXT_ENTRY_USED_SIZE_TYPE;

Hdr

Standard extension entry, with the type EFI_FV_EXT_TYPE_USED_SIZE_TYPE .

UsedSize

The number of bytes of the FV that are in uses. The remaining EFI_FIRMWARE_VOLUME_HEADER FvLength minus UsedSize bytes in the FV must contain the value implied by EFI_FVB2_ERASE_POLARITY.

The EFI_FIRMWARE_VOLUME_EXT_ENTRY_USED_SIZE_TYPE can be used to find out how many EFI_FVB2_ERASE_POLARITY bytes are at the end of the FV.

3.2.1.2. EFI Signed Firmware Volumes

There may be one or more headers with a FormatType of value EFI_FIRMWARE_CONTENTS_SIGNED_GUID.

A signed firmware volume is a cryptographic signature across the entire volume. To process the contents and verify the integrity of the volume, the EFI_FIRMWARE_VOLUME_EXT_ENTRY_GUID_TYPE Data[] shall contain an instance of WIN_CERTIFICATE_UEFI_GUID where the CertType = EFI_CERT_TYPE_PKCS7_GUID, EFI_CERT_TYPE_RSA2048_SHA256_GUID, EFI_CERT_TYPE_RSA3072_SHA384_GUID, EFI_CERT_TYPE_RSA4096_SHA512_GUID, EFI_CERT_TYPE_RSAPSS3072_SHA512_GUID, EFI_CERT_TYPE_RSAPSS4096_SHA512_GUID, EFI_CERT_TYPE_ECDSA_ECC_NIST_P256_SHA256_GUID, or EFI_CERT_TYPE_ECDSA_ECC_NIST_P384_SHA384_GUID.

Related Definitions

#define EFI_CERT_TYPE_RSA3072_SHA384_GUID {0xdf70754f, 0xcf85, 0x47de, {0xbb, 0x49, 0xd8, 0x36, 0x1d, 0x4b, 0xf0, 0xd5}}

#define EFI_CERT_TYPE_RSA4096_SHA512_GUID {0xeffa3c4c, 0x2181, 0x4ca2, {0xa3, 0xe6, 0xad, 0xdb, 0x8b, 0x68, 0x52, 0x98}}

#define EFI_CERT_TYPE_RSAPSS3072_SHA384_GUID {0x1bbe9dda, 0x965f, 0x4b1a, {0x92, 0xce, 0xe9, 0x4e, 0x19, 0xe5, 0x61, 0x28}}

#define EFI_CERT_TYPE_RSAPSS4096_SHA512_GUID {0xa2743703, 0xf28c, 0x416c, {0xb2, 0xed, 0xc6, 0x76, 0x27, 0x57, 0x89, 0x90}}

#define EFI_CERT_TYPE_ECDSA_ECC_NIST_P256_SHA256_GUID {0x7c6c3269, 0xc9fb, 0x4762, {0x81, 0xe1, 0x55, 0x40, 0x21, 0xf7, 0x76, 0x6e}}

#define EFI_CERT_TYPE_ECDSA_ECC_NIST_P384_SHA384_GUID {0x216afe76, 0x18fe, 0x4d68, {0x83, 0x72, 0x55, 0xbc, 0xf9, 0x9b, 0x6f, 0x65}}

typedef struct _EFI_CERT_BLOCK_RSA_3072_SHA384 {
  EFI_GUID HashType;
  UINT8 PublicKey[384];
  UINT8 Signature[384];
} EFI_CERT_BLOCK_RSA_3072_SHA384

PublicKey   The RSA exponent e for this structure is 0x10001.

Signature   This signature block is PKCS 1 version 1.5 formatted.

typedef struct _EFI_CERT_BLOCK_RSA_4096_SHA512 {
  EFI_GUID HashType;
  UINT8 PublicKey[512];
  UINT8 Signature[512];
} EFI_CERT_BLOCK_RSA_4096_SHA512;

PublicKey   The RSA exponent e for this structure is 0x10001.

Signature   This signature block is PKCS 1 version 1.5 formatted.

typedef struct _EFI_CERT_BLOCK_ECDSA_NIST_P256_SHA256 {
  EFI_GUID HashType;
  UINT8 PublicKey[64];
  UINT8 Signature[64];
} EFI_CERT_BLOCK_ECDSA_NIST_P256_SHA256;

PublicKey   The public key is ECDSA public key (x, y). The bytes order of x and y is big endian. The first 32 bytes are x, the second 32 bytes are y.

Signature   This signature block is FIPS 186-4 defined ECDSA signature (r, s). The byte order of r and s is big endian. The first 32 bytes are r, the second 32 bytes are s.

typedef struct _EFI_CERT_BLOCK_ECDSA_NIST_P384_SHA384 {
  EFI_GUID HashType;
  UINT8 PublicKey[96];
  UINT8 Signature[96];
} EFI_CERT_BLOCK_ECDSA_NIST_P384_SHA384;

PublicKey   The public key is ECDSA public key (x, y). The bytes order of x and y is big endian. The first 48 bytes are x, the second 48 bytes are y.

Signature   This signature block is FIPS 186-4 defined ECDSA signature (r, s). The byte order of r and s is big endian. The first 48 bytes are r, the second 48 bytes are s.

Description

The WIN_CERTIFICATE_UEFI_GUID certificate type allows new types of certificates to be developed for driver authentication without requiring a new certificate type. The CertType defines the format of the CertData, which length is defined by the size of the certificate less the fixed size of the WIN_CERTIFICATE_UEFI_GUID structure. Besides UEFI defined EFI_CERT_TYPE_PKCS7_GUID or EFI_CERT_TYPE_RSA2048_SHA256_GUID, this specification adds below CertType:

• If CertType is EFI_CERT_TYPE_RSA3072_SHA384_GUID or EFI_CERT_TYPE_RSAPSS3072_SHA384_GUID, then the structure which follows has the format specified by EFI_CERT_BLOCK_RSA_3072_SHA384.

• If CertType is EFI_CERT_TYPE_RSA4096_SHA512_GUID or EFI_CERT_TYPE_RSAPSS4096_SHA512_GUID, then the structure which follows has the format specified by EFI_CERT_BLOCK_RSA_4096_SHA512.

• If CertType is EFI_CERT_TYPE_ECDSA_ECC_NIST_P256_SHA256_GUID, then the structure which follows has the format specified by EFI_CERT_BLOCK_ECDSA_NIST_P256_SHA256.

• If CertType is EFI_CERT_TYPE_ECDSA_ECC_NIST_P384_SHA384_GUID, then the structure which follows has the format specified by EFI_CERT_BLOCK_ECDSA_NIST_P384_SHA384.

3.2.2. Firmware File System

3.2.2.1. EFI_FIRMWARE_FILE_SYSTEM2_GUID

Summary

The firmware volume header contains a data field for the file system GUID. See the EFI_FIRMWARE_VOLUME_HEADER for more information on the firmware volume header.

GUID

// {8C8CE578-8A3D-4f1c-9935-896185C32DD3}
#define EFI_FIRMWARE_FILE_SYSTEM2_GUID \
  { 0x8c8ce578, 0x8a3d, 0x4f1c, \
  0x99, 0x35, 0x89, 0x61, 0x85, 0xc3, 0x2d, 0xd3 }

3.2.2.2. EFI_FIRMWARE_FILE_SYSTEM3_GUID

Summary

The firmware volume header contains a data field for the file system GUID. See the EFI_FIRMWARE_VOLUME_HEADER for more information on the firmware volume header.

EFI_FIRMWARE_FILE_SYSTEM3_GUID indicates support for FFS_ATTRIB_LARGE_SIZE and thus support for files 16MB or larger. EFI_FIRMWARE_FILE_SYSTEM2_GUID volume does not contain large files. Files 16 MB or larger use a EFI_FFS_FILE_HEADER2 and smaller files use EFI_FFS_FILE_HEADER. EFI_FIRMWARE_FILE_SYSTEM2_GUID allows backward compatibility with previous versions of this specification

GUID

// {5473C07A-3DCB-4dca-BD6F-1E9689E7349A}
#define EFI_FIRMWARE_FILE_SYSTEM3_GUID \
  { 0x5473c07a, 0x3dcb, 0x4dca, \
  { 0xbd, 0x6f, 0x1e, 0x96, 0x89, 0xe7, 0x34, 0x9a } }

3.2.2.3. EFI_FFS_VOLUME_TOP_FILE_GUID

Summary

A Volume Top File (VTF) is a file that must be located such that the last byte of the file is also the last byte of the firmware volume. Regardless of the file type, a VTF must have the file name GUID of EFI_FFS_VOLUME_TOP_FILE_GUID as defined below.

GUID

// {1BA0062E-C779-4582-8566-336AE8F78F09}

#define EFI_FFS_VOLUME_TOP_FILE_GUID \
  { 0x1BA0062E, 0xC779, 0x4582, 0x85, 0x66, 0x33, 0x6A, \
  0xE8, 0xF7, 0x8F, 0x9 }

3.2.3. Firmware File

3.2.3.1. EFI_FFS_FILE_HEADER

Summary

Each file begins with a header that describes the state and contents of the file. The header is 8-byte aligned with respect to the beginning of the firmware volume.

Prototype

typedef struct {
  EFI_GUID                 Name;
  EFI_FFS_INTEGRITY_CHECK  IntegrityCheck;
  EFI_FV_FILETYPE          Type;
  EFI_FFS_FILE_ATTRIBUTES  Attributes;
  UINT8                    Size[3];
  EFI_FFS_FILE_STATE       State;
} EFI_FFS_FILE_HEADER;

typedef struct {
  EFI_GUID                 Name;
  EFI_FFS_INTEGRITY_CHECK  IntegrityCheck;
  EFI_FV_FILETYPE          Type;
  EFI_FFS_FILE_ATTRIBUTES  Attributes;
  UINT8                    Size[3];
  EFI_FFS_FILE_STATE       State;
  UINT64                   ExtendedSize;
} EFI_FFS_FILE_HEADER2;

Parameters

Name

This GUID is the file name. It is used to uniquely identify the file. There may be only one instance of a file with the file name GUID of Name in any given firmware volume, except if the file type is EFI_FV_FILETYPE_FFS_PAD .

IntegrityCheck

Used to verify the integrity of the file. Type EFI_FFS_INTEGRITY_CHECK is defined in “Related Definitions” below.

Type

Identifies the type of file. Type EFI_FV_FILETYPE is defined in “Related Definitions,” below. FFS-specific file types are defined in EFI_FV_FILETYPE_FFS_PAD .

Attributes

Declares various file attribute bits. Type EFI_FFS_FILE_ATTRIBUTES is defined in “Related Definitions” below.

Size

The length of the file in bytes, including the FFS header. The length of the file data is either ( Size - sizeof(EFI_FFS_FILE_HEADER)) . This calculation means a zero-length file has a Size of 24 bytes, which is sizeof(EFI_FFS_FILE_HEADER) .

Size is not required to be a multiple of 8 bytes. Given a file F, the next file header is located at the next 8-byte aligned firmware volume offset following the last byte of the file F.

State

Used to track the state of the file throughout the life of the file from creation to deletion. Type EFI_FFS_FILE_STATE is defined in “Related Definitions” below. See File Integrity and State for an explanation of how these bits are used.

ExtendedSize

If FFS_ATTRIB_LARGE_FILE is set in Attributes then ExtendedSize exists and Size must be set to zero. If FFS_ATTRIB_LARGE_FILE is not set then EFI_FFS_FILE_HEADER is used.

Description

The file header may use one of two structures to define the file. If the size of the file is larger than 0xFFFFFF the EFI_FFS_FILE_HEADER2 structure must be used, otherwise the EFI_FFS_FILE_HEADER structure must be used. The structure used is determined by the FFS_ATTRIB_LARGE_FILE attribute in the Attributes member. Note that all of the structure elements other than ExtendedSize are the same in the two structures. The ExtendedSize member is used instead of the Size member when the EFI_FFS_FILE_HEADER2 structure is used ( FFS_ATTRIB_LARGE_FILE is set).

Related Definitions

//******************************************************
// EFI_FFS_INTEGRITY_CHECK
//******************************************************
typedef union {
  struct {
    UINT8            Header;
    UINT8            File;
  }                  Checksum;
  UINT16             Checksum16;
} EFI_FFS_INTEGRITY_CHECK;

Header

The IntegrityCheck.Checksum.Header field is an 8-bit checksum of the file header. The State and IntegrityCheck.Checksum.File fields are assumed to be zero and the checksum is calculated such that the entire header sums to zero. The IntegrityCheck.Checksum.Header field is valid anytime the EFI_FILE_HEADER_VALID bit is set in the State field. See File Integrity and State for more details. If the FFS_ATTRIB_LARGE_FILE bit of the Attributes field is set the header size is sizeof ( EFI_FFS_FILE_HEADER2 ), if it is clear the header size is sizeof ( EFI_FFS_FILE_HEADER ).

File

If the FFS_ATTRIB_CHECKSUM (see definition below) bit of the Attributes field is set to one, the IntegrityCheck.Checksum.File field is an 8-bit checksum of the file data. If the FFS_ATTRIB_CHECKSUM bit of the Attributes field is cleared to zero, the IntegrityCheck.Checksum.File field must be initialized with a value of 0xAA. The IntegrityCheck.Checksum.File field is valid any time the EFI_FILE_DATA_VALID bit is set in the State field. See File Integrity and State for more details.

Checksum

IntegrityCheck. Checksum16 is the full 16 bits of the IntegrityCheck field.

//************************************************************
// EFI_FV_FILETYPE
//************************************************************
typedef UINT8 EFI_FV_FILETYPE;

//************************************************************
// EFI_FFS_FILE_ATTRIBUTES
//************************************************************
typedef UINT8 EFI_FFS_FILE_ATTRIBUTES;

// FFS File Attributes
#define FFS_ATTRIB_LARGE_FILE             0x01
#define FFS_ATTRIB_FIXED                  0x04
#define FFS_ATTRIB_DATA_ALIGNMENT         0x38
#define FFS_ATTRIB_CHECKSUM               0x40

Bit Allocation of FFS Attributes depicts the bit allocation of the Attributes field in an FFS file’s header.

Fig. 3.1 Bit Allocation of FFS Attributes

Bit Allocation Definitions provides descriptions of the fields in the above definition.

Table 3.2 Bit Allocation Definitions

Value	Definition
FFS_ATTRIB_FIXED	Indicates that the file may not be moved from its present location.
FFS_ATTRIB_LARGE_FILE	Indicates that large files are supported and the EFI_FFS_FILE_HEADER2 is in use.
FFS_ATTRIB_DATA_ALIGNMENT and FFS_ATTRIB_DATA_ALIGNMENT2	Indicates that the beginning of the file data (not the file header) must be aligned on a particular boundary relative to the firmware volume base. The three bits in this field are an enumeration of alignment possibilities. The firmware volume interface allows alignments based on powers of two from byte alignment to 16MiB alignment. FFS does not support this full range. The table below maps all FFS supported alignments to FFS_ATTRIB_DATA_ALIGNMENT and FFS_ATTRIB_DATA_ALIGNMENT2 values and firmware volume interface alignment values. No other alignments are supported by FFS. When a file with an alignment requirement is created, a pad file may need to be created before it to ensure proper data alignment. See EFI_FV_FILETYPE_FFS_PAD for more information regarding pad files
FFS_ATTRIB_CHECKSUM	Determines the interpretation of IntegrityCheck.Checksum.File. See the IntegrityCheck definition above for specific usage.

Supported FFS Alignments maps all FFS-supported alignments to FFS_ATTRIB_DATA_ALIGNMENT and FFS_ATTRIB_DATA_ALIGNMENT2 values and firmware volume interface alignment values.

Table 3.3 Supported FFS Alignments

Required Alignment (bytes)	AlignmentValue in FFS Attributes Field	FFS_ATTRIB_DATA _ALIGNMENT2 in FFS Attributes Field	Alignment Value in Firmware Volume Interfaces
1	0	0	0
16	1	0	4
128	2	0	7
512	3	0	9
1KiB	4	0	10
4KiB	5	0	12
32KiB	6	0	15
64KiB	7	0	16
128KiB	0	1	17
256KiB	1	1	18
512KiB	2	1	19
1MiB	3	1	20
2MiB	4	1	21
4MiB	5	1	22
8MiB	6	1	23
16MiB	7	1	24

//************************************************************
// EFI_FFS_FILE_STATE
//************************************************************
typedef UINT8 EFI_FFS_FILE_STATE;

// FFS File State Bits
#define EFI_FILE_HEADER_CONSTRUCTION      0x01
#define EFI_FILE_HEADER_VALID             0x02
#define EFI_FILE_DATA_VALID               0x04
#define EFI_FILE_MARKED_FOR_UPDATE        0x08
#define EFI_FILE_DELETED                  0x10
#define EFI_FILE_HEADER_INVALID           0x20

All other State bits are reserved and must be set to EFI_FVB_ERASE_POLARITY . See File Integrity and State for an explanation of how these bits are used. Type EFI_FVB_ERASE_POLARITY is defined in EFI_FIRMWARE_VOLUME_HEADER.

3.2.4. Firmware File Section

3.2.4.1. EFI_COMMON_SECTION_HEADER

Summary

Defines the common header for all the section types.

Prototype

typedef struct {
  UINT8                    Size[3];
  EFI_SECTION_TYPE         Type;
} EFI_COMMON_SECTION_HEADER;

typedef struct {
  UINT8                    Size[3];
  EFI_SECTION_TYPE         Type;
  UINT32                   ExtendedSize;
} EFI_COMMON_SECTION_HEADER2;

Parameters

Size

A 24-bit unsigned integer that contains the total size of the section in bytes, including the EFI_COMMON_SECTION_HEADER . For example, a zero-length section has a Size of 4 bytes.

Type

Declares the section type. Type EFI_SECTION_TYPE is defined in “Related Definitions” below.

ExtendedSize

If Size is 0xFFFFFF then ExtendedSize contains the size of the section. If Size is not equal to 0xFFFFFF then this field does not exist.

Description

The type EFI_COMMON_SECTION_HEADER defines the common header for all the section types.

If Size is 0xFFFFFF the size of the section header is sizeof (EFI_COMMON_SECTION_HEADER2). If Size is not equal to 0xFFFFFF then the size of the section header is sizeof (EFI_COMMON_SECTION_HEADER).

The EFI_COMMON_SECTION_HEADER2 structure is only used if the section is too large to be described using EFI_COMMON_SECTION_HEADER . Large sections using EFI_COMMON_SECTION_HEADER2 can only exist in a file using EFI_FFS_FILE_HEADER2 , the FFS_ATTRIB_LARGE_FILE attribute in the file header is set.

Related Definitions

//************************************************************
// EFI_SECTION_TYPE
//************************************************************
typedef UINT8 EFI_SECTION_TYPE;

//************************************************************
// The section type EFI_SECTION_ALL is a pseudo type. It is
// used as a wild card when retrieving sections. The section
// type EFI_SECTION_ALL matches all section types.
//************************************************************
#define EFI_SECTION_ALL                      0x00

//************************************************************
// Encapsulation section Type values
//************************************************************
#define EFI_SECTION_COMPRESSION              0x01
#define EFI_SECTION_GUID_DEFINED             0x02
#define EFI_SECTION_DISPOSABLE               0x03

//************************************************************
// Leaf section Type values
//************************************************************
#define EFI_SECTION_PE32                     0x10
#define EFI_SECTION_PIC                      0x11
#define EFI_SECTION_TE                       0x12
#define EFI_SECTION_DXE_DEPEX                0x13
#define EFI_SECTION_VERSION                  0x14
#define EFI_SECTION_USER_INTERFACE           0x15
#define EFI_SECTION_COMPATIBILITY16          0x16
#define EFI_SECTION_FIRMWARE_VOLUME_IMAGE    0x17
#define EFI_SECTION_FREEFORM_SUBTYPE_GUID    0x18
#define EFI_SECTION_RAW                      0x19
#define EFI_SECTION_PEI_DEPEX                0x1B
#define EFI_SECTION_MM_DEPEX                 0x1C

All other values are reserved for future use.

3.2.5. Firmware File Section Types

3.2.5.1. EFI_SECTION_COMPATIBILITY16

Summary

A leaf section type that contains an IA-32 16-bit executable image.

Prototype

typedef EFI_COMMON_SECTION_HEADER  EFI_COMPATIBILITY16_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_COMPATIBILITY16_SECTION2;

Description

A Compatibility16 image section is a leaf section that contains an IA-32 16-bit executable image. IA-32 16-bit legacy code that may be included in PI Architecture firmware is stored in a 16-bit executable image. EFI_COMPATIBILITY16_SECTION2 is used if the section is 16MB or larger.

3.2.5.2. EFI_SECTION_COMPRESSION

Summary

An encapsulation section type in which the section data is compressed.

Prototype

typedef struct {
  EFI_COMMON_SECTION_HEADER  CommonHeader;
  UINT32                     UncompressedLength;
  UINT8                      CompressionType;
} EFI_COMPRESSION_SECTION;

typedef struct {
  EFI_COMMON_SECTION_HEADER2 CommonHeader;
  UINT32                     UncompressedLength;
  UINT8                      CompressionType;
} EFI_COMPRESSION_SECTION2;

Parameters

CommonHeader

Usual common section header. CommonHeader.Type = EFI_SECTION_COMPRESSION .

UncompressedLength

UINT32 that indicates the size of the section data after decompression.

CompressionType

Indicates which compression algorithm is used.

Description

A compression section is an encapsulation section in which the section data is compressed. To process the contents and extract the enclosed section stream, the section data must be decompressed using the decompressor indicated by the CompressionType parameter. The decompressed image is then interpreted as a section stream. EFI_COMPRESSION_SECTION2 is used if the section is 16MB or larger.

Related Definitions

//************************************************************
// CompressionType values
//************************************************************
#define EFI_NOT_COMPRESSED         0x00
#define EFI_STANDARD_COMPRESSION   0x01

Description of Fields for CompressionType describes the fields in the above definition.

Table 3.4 Description of Fields for CompressionType

Field	Description
EFI_NOT_COMPRESSED	Indicates that the encapsulated section stream is not compressed. This type is useful to grouping sections together without requiring a decompressor.
EFI_STANDARD_COMPRESSION	Indicates that the encapsulated section stream is compressed using the compression standard defined by the UEFI 2.0 specification.

3.2.5.3. EFI_SECTION_DISPOSABLE

Summary

An encapsulation section type in which the section data is disposable.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_DISPOSABLE_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_DISPOSABLE_SECTION2;

Parameters

None

Description

A disposable section is an encapsulation section in which the section data may be disposed of during the process of creating or updating a firmware image without significant impact on the usefulness of the file. The Type field in the section header is set to EFI_SECTION_DISPOSABLE . This allows optional or descriptive data to be included with the firmware file which can be removed in order to conserve space. The contents of this section are implementation specific, but might contain debug data or detailed integration instructions. EFI_DISPOSABLE_SECTION2 is used if the section is 16MB or larger.

3.2.5.4. EFI_SECTION_DXE_DEPEX

Summary

A leaf section type that is used to determine the dispatch order for a DXE driver.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_DXE_DEPEX_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_DXE_DEPEX_SECTION2;

Description

The DXE dependency expression section is a leaf section that contains a dependency expression that is used to determine the dispatch order for a DXE driver. See the Platform Initialization Driver Execution Environment Core Interface Specification for details regarding the format of the dependency expression. EFI_DXE_DEPEX_SECTION2 must be used if the section is 16MB or larger.

3.2.5.5. EFI_SECTION_FIRMWARE_VOLUME_IMAGE

Summary

A leaf section type that contains a PI Firmware Volume.

Prototype

typedef EFI_COMMON_SECTION_HEADER
EFI_FIRMWARE_VOLUME_IMAGE_SECTION;

typedef EFI_COMMON_SECTION_HEADER2
EFI_FIRMWARE_VOLUME_IMAGE_SECTION2;

Description

A firmware volume image section is a leaf section that contains a PI Firmware Volume Image. EFI_FIRMWARE_VOLUME_IMAGE_SECTION2 must be used if the section is 16MB or larger.

3.2.5.6. EFI_SECTION_FREEFORM_SUBTYPE_GUID

Summary

A leaf section type that contains a single EFI_GUID in the header to describe the raw data.

Prototype

typedef struct {
  EFI_COMMON_SECTION_HEADER CommonHeader;
  EFI_GUID                  SubTypeGuid;
} EFI_FREEFORM_SUBTYPE_GUID_SECTION;

typedef struct {
  EFI_COMMON_SECTION_HEADER2 CommonHeader;
  EFI_GUID                   SubTypeGuid;
} EFI_FREEFORM_SUBTYPE_GUID_SECTION2;

Parameters

CommonHeader

Common section header. CommonHeader.Type = EFI_SECTION_FREEFORM_SUBTYPE_GUID .

SubtypeGuid

This GUID is defined by the creator of the file. It is a vendor-defined file type. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

Description

A free-form subtype GUID section is a leaf section that contains a single EFI_GUID in the header to describe the raw data. It is typically used in files of type EFI_FV_FILETYPE_FREEFORM to provide an extensibility mechanism for file types. The section can also be used in other file types as an alternative to raw section(EFI_SECTION_RAW) as it provides the ability to tag section with a unique GUID. See EFI_FV_FILETYPE_FREEFORM for more details.

3.2.5.7. EFI_SECTION_GUID_DEFINED

Summary

An encapsulation section type in which the method of encapsulation is defined by an identifying GUID.

Prototype

typedef struct {
  EFI_COMMON_SECTION_HEADER  CommonHeader;
  EFI_GUID                   SectionDefinitionGuid;
  UINT16                     DataOffset;
  UINT16                     Attributes;
  //                         GuidSpecificHeaderFields;
} EFI_GUID_DEFINED_SECTION;

typedef struct {
  EFI_COMMON_SECTION_HEADER2 CommonHeader;
  EFI_GUID                   SectionDefinitionGuid;
  UINT16                     DataOffset;
  UINT16                     Attributes;
  //                         GuidSpecificHeaderFields;
} EFI_GUID_DEFINED_SECTION2;

Parameters

CommonHeader

Common section header. CommonHeader.Type = EFI_SECTION_GUID_DEFINED.

SectionDefinitionGuid

GUID that defines the format of the data that follows. It is a vendor-defined section type. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

DataOffset

Contains the offset in bytes from the beginning of the common header to the first byte of the data.

Attributes

Bit field that declares some specific characteristics of the section contents. The bits are defined in “Related Definitions” below.

GuidSpecificHeaderFields

Zero or more bytes of data that are defined by the section’s GUID. An example of this data would be a digital signature and manifest.

Data

Zero or more bytes of arbitrary data. The format of the data is defined by SectionDefinitionGuid .

Description

A GUID-defined section contains a section-type-specific header that contains an identifying GUID, followed by an arbitrary amount of data. It is an encapsulation section in which the method of encapsulation is defined by the GUID. A matching instance of EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL (DXE) or EFI_GUIDED_SECTION_EXTRACTION_PPI (PEI) is required to extract the contents of this encapsulation section.

The GUID-defined section enables custom encapsulation section types for any purpose. One commonly expected use is creating an encapsulation section to enable a cryptographic authentication of the section contents. EFI_GUID_DEFINED_SECTION2 must be used if the section is 16MB or larger.

Related Definitions

//*****************************************************
// Bit values for GuidedSectionHeader.Attributes
//*****************************************************
#define EFI_GUIDED_SECTION_PROCESSING_REQUIRED     0x01
#define EFI_GUIDED_SECTION_AUTH_STATUS_VALID       0x02

Descriptions of Fields for GuidedSectionHeader.Attributes describes the fields in the above definition.

Table 3.5 Descriptions of Fields for GuidedSectionHeader.Attributes

Field	Description
EFI_GUIDED_SECTION _PROCESSING_REQUIRED	Set to 1 if the section requires processing to obtain meaningful data from the section contents. Processing would be required, for example, if the section contents were encrypted or compressed. If the EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit is cleared to zero, it is possible to retrieve the section’s contents without processing in the absence of an associated instance of the EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL (DXE) or EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI (PEI). In this case, the beginning of the encapsulated section stream is indicated by the value of DataOffset.
EFI_GUIDED_SECTION _AUTH_STATUS_VALID	Set to 1 if the section contains authentication data that is reported through the AuthenticationStatus parameter returned from the GUIDed Section Extraction Protocol. If the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit is clear, the AuthenticationStatus parameter is not used.

All other bits are reserved and must be set to zero. Together, the EFI_GUIDED_SECTION_PROCESSING_REQUIRED and EFI_GUIDED_SECTION_AUTH_STATUS_VALID bits provide the necessary data to set the proper bits of the AuthenticationStatus output parameter in the event that no EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL is available and the data is still returned.

EFI Signed Sections

For EFI_GUID_DEFINED_SECTION and EFI_GUID_DEFINED_SECTION2 there is a SectionDefinitionGuid of type EFI_FIRMWARE_CONTENTS_SIGNED_GUID. The GuidSpecificHeaderFields shall include an entry SignatureInfo of type WIN_CERTIFICATE_UEFI_GUID.

#define EFI_FIRMWARE_CONTENTS_SIGNED_GUID \
| { 0xf9d89e8, 0x9259, 0x4f76, \
| { 0xa5, 0xaf, 0xc, 0x89, 0xe3, 0x40, 0x23, 0xdf } }

The signed section is an encapsulation section in which the section data is cryptographically signed. To process the contents and extract the enclosed section stream, the section data integrity must be accessed by evaluating the enclosed data via the cryptographic information in the SignatureInfo. The CertType = EFI_CERT_TYPE_PKCS7_GUID, EFI_CERT_TYPE_RSA2048_SHA256_GUID, EFI_CERT_TYPE_RSA3072_SHA384_GUID, EFI_CERT_TYPE_RSA4096_SHA512_GUID, EFI_CERT_TYPE_RSAPSS3072_SHA512_GUID, EFI_CERT_TYPE_RSAPSS4096_SHA512_GUID, EFI_CERT_TYPE_ECDSA_ECC_NIST_P256_SHA256_GUID, or EFI_CERT_TYPE_ECDSA_ECC_NIST_P384_SHA384_GUID.

The signed image is then interpreted as a section stream. EFI_GUID_DEFINED_SECTION2 is used if the section is 16MB or larger.

3.2.5.8. EFI_SECTION_PE32

Summary

A leaf section type that contains a complete PE32+ image.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_PE32_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_PE32_SECTION2;

Description

The PE32+ image section is a leaf section that contains a complete PE32+ image. Normal UEFI executables are stored within PE32+ images. EFI_PE32_SECTION2 must be used if the section is 16MB or larger.

3.2.5.9. EFI_SECTION_PEI_DEPEX

Summary

A leaf section type that is used to determine dispatch order for a PEIM.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_PEI_DEPEX_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_PEI_DEPEX_SECTION2;

Description

The PEI dependency expression section is a leaf section that contains a dependency expression that is used to determine dispatch order for a PEIM. See the Platform Initialization Pre-EFI Initialization Core Interface Specification for details regarding the format of the dependency expression. EFI_PEI_DEPEX_SECTION2 must be used if the section is 16MB or larger.

3.2.5.10. EFI_SECTION_PIC

Summary

A leaf section type that contains a position-independent-code (PIC) image.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_PIC_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_PIC_SECTION2;

Description

A PIC image section is a leaf section that contains a position-independent-code (PIC) image.

In addition to normal PE32+ images that contain relocation information, PEIM executables may be PIC and are referred to as PIC images. A PIC image is the same as a PE32+ image except that all relocation information has been stripped from the image and the image can be moved and will execute correctly without performing any relocation or other fix-ups. EFI_PIC_SECTION2 must be used if the section is 16MB or larger.

3.2.5.11. EFI_SECTION_RAW

Summary

A leaf section type that contains an array of zero or more bytes.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_RAW_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_RAW_SECTION2;

Description

A raw section is a leaf section that contains an array of zero or more bytes. No particular formatting of these bytes is implied by this section type. EFI_RAW_SECTION2 must be used if the section is 16MB or larger.

3.2.5.12. EFI_SECTION_MM_DEPEX

Summary

A leaf section type that is used to determine the dispatch order for an MM driver.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_MM_DEPEX_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_MM_DEPEX_SECTION2;

Description

The MM dependency expression section is a leaf section that contains a dependency expression that is used to determine the dispatch order for MM drivers. Before the MMRAM invocation of the MM driver’s entry point, this dependency expression must evaluate to TRUE. See the Platform Initialization Specification, Volume 2 for details regarding the format of the dependency expression.

The dependency expression may refer to protocols installed in either the UEFI or the MM protocol database. EFI_MM_DEPEX_SECTION2 must be used if the section is 16MB or larger.

3.2.5.13. EFI_SECTION_TE

Summary

A leaf section that contains a Terse Executable (TE) image.

Prototype

typedef EFI_COMMON_SECTION_HEADER EFI_TE_SECTION;
typedef EFI_COMMON_SECTION_HEADER2 EFI_TE_SECTION2;

Description

The terse executable section is a leaf section that contains a Terse Executable (TE) image. A TE image is an executable image format specific to the PI Architecture that is used for storing executable images in a smaller amount of space than would be required by a full PE32+ image. Only PEI Foundation and PEIM files may contain a TE section. EFI_TE_SECTION2 must be used if the section is 16MB or larger.

3.2.5.14. EFI_SECTION_USER_INTERFACE

Summary

A leaf section type that contains a Unicode string that contains a human-readable file name.

Prototype

typedef struct {
  EFI_COMMON_SECTION_HEADER  CommonHeader;
  CHAR16                     FileNameString[];
} EFI_USER_INTERFACE_SECTION;

typedef struct {
  EFI_COMMON_SECTION_HEADER2 CommonHeader;
  CHAR16                     FileNameString[];
} EFI_USER_INTERFACE_SECTION2;

Description

The user interface file name section is a leaf section that contains a Unicode string that contains a human-readable file name.

This section is optional and is not required for any file types. There must never be more than one user interface file name section contained within a file. EFI_USER_INTERFACE_SECTION2 must be used if the section is 16MB or larger.

3.2.5.15. EFI_SECTION_VERSION

Summary

A leaf section type that contains a numeric build number and an optional Unicode string that represents the file revision.

Prototype

typedef struct {
  EFI_COMMON_SECTION_HEADER  CommonHeader;
  UINT16                     BuildNumber;
  CHAR16                     VersionString[];
} EFI_VERSION_SECTION;

typedef struct {
  EFI_COMMON_SECTION_HEADER2 CommonHeader;
  UINT16                     BuildNumber;
  CHAR16                     VersionString[];
} EFI_VERSION_SECTION2;

Parameters

CommonHeader

Common section header. CommonHeader.Type = EFI_SECTION_VERSION .

BuildNumber

A UINT16 that represents a particular build. Subsequent builds have monotonically increasing build numbers relative to earlier builds.

VersionString

A null-terminated Unicode string that contains a text representation of the version. If there is no text representation of the version, then an empty string must be provided.

Description

A version section is a leaf section that contains a numeric build number and an optional Unicode string that represents the file revision.

To facilitate versioning of PEIMs, DXE drivers, and other files, a version section may be included in a file. There must never be more than one version section contained within a file. EFI_VERSION_SECTION2 must be used if the section is 16MB or larger.

3.3. PEI

3.3.1. EFI_PEI_FIRMWARE_VOLUME_INFO_PPI

Summary

Provides location and format of a firmware volume.

GUID

#define EFI_PEI_FIRMWARE_VOLUME_INFO_PPI_GUID \
  { 0x49edb1c1, 0xbf21, 0x4761, \
  0xbb, 0x12, 0xeb, 0x0, 0x31, 0xaa, 0xbb, 0x39 }

Prototype

typedef struct _EFI_PEI_FIRMWARE_VOLUME_INFO_PPI {
  EFI_GUID   FvFormat;
  VOID       *FvInfo;
  UINT32     FvInfoSize;
  EFI_GUID   *ParentFvName;
  EFI_GUID   *ParentFileName;
} EFI_PEI_FIRMWARE_VOLUME_INFO_PPI ;

Parameters

FvFormat

Unique identifier of the format of the memory-mapped firmware volume.

FvInfo

Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. The format of this buffer is specific to the FvFormat . For memory-mapped firmware volumes, this typically points to the first byte of the firmware volume.

FvInfoSize

Size of the data provided by FvInfo . For memory-mapped firmware volumes, this is typically the size of the firmware volume.

ParentFvName, ParentFileName

If the firmware volume originally came from a firmware file, then these point to the parent firmware volume name and firmware volume file. If it did not originally come from a firmware file, these should be NULL .

Description

This PPI describes the location and format of a firmware volume. The FvFormat can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format.

3.3.2. EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI

Summary

Provides location and format of a firmware volume.

GUID

#define EFI_PEI_FIRMWARE_VOLUME_INFO_PPI2_GUID \
{ 0xea7ca24b, 0xded5, 0x4dad, \
0xa3, 0x89, 0xbf, 0x82, 0x7e, 0x8f, 0x9b, 0x38 }

Prototype

typedef struct _EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI {
  EFI_GUID     FvFormat;
  VOID         *FvInfo;
  UINT32       FvInfoSize;
  EFI_GUID     *ParentFvName;
  EFI_GUID     *ParentFileName;
  UINT32       AuthenticationStatus;
} EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI ;

Parameters

FvFormat

Unique identifier of the format of the memory-mapped firmware volume.

FvInfo

Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. The format of this buffer is specific to the FvFormat . For memory-mapped firmware volumes, this typically points to the first byte of the firmware volume.

FvInfoSize

Size of the data provided by FvInfo . For memory-mapped firmware volumes, this is typically the size of the firmware volume.

ParentFvName, ParentFileName

If the firmware volume originally came from a firmware file, then these point to the parent firmware volume name and firmware volume file. If it did not originally come from a firmware file, these should be NULL.

AuthenticationStatus

Authentication status.

Description

This PPI describes the location, format and authentication status of a firmware volume. The FvFormat can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format.

3.3.3. PEI Firmware Volume PPI

3.3.3.1. EFI_PEI_FIRMWARE_VOLUME_PPI

Summary

Provides functions for accessing a memory-mapped firmware volume of a specific format.

GUID

The GUID for this PPI is the same as the firmware volume format GUID.

Prototype

typedef struct _EFI_PEI_FIRMWARE_VOLUME_PPI {
  EFI_PEI_FV_PROCESS_FV        ProcessVolume;
  EFI_PEI_FV_FIND_FILE_TYPE    FindFileByType;
  EFI_PEI_FV_FIND_FILE_NAME    FindFileByName;
  EFI_PEI_FV_GET_FILE_INFO     GetFileInfo;
  EFI_PEI_FV_GET_INFO          GetVolumeInfo;
  EFI_PEI_FV_FIND_SECTION      FindSectionByType;
  EFI_PEI_FV_GET_FILE_INFO2    GetFileInfo2;
  EFI_PEI_FV_FIND_SECTION2     FindSectionByType2;
  UINT32                       Signature;
  UINT32                       Revision;
} EFI_PEI_FIRMWARE_VOLUME_PPI;

Parameters

ProcessVolume

Process a firmware volume and create a volume handle.

FindFileByType

Find all files of a specific type.

FindFileByName

Find the file with a specific name.

GetFileInfo

Return the information about a specific file

GetVolumeInfo

Return the firmware volume attributes.

FindSectionByType

Find the first section of a specific type.

GetFileInfo2

Return the information with authentication status about a specific file.

FindSectionByType2

Find the section with authentication status of a specific type.

Signature

Signature is used to keep backward-compatibility, set to {‘P’,’F’,’V’,’P’}.

Revision

Revision for further extension.

# define EFI_PEI_FIRMWARE_VOLUME_PPI_REVISION 0x00010030

3.3.3.2. EFI_PEI_FIRMWARE_VOLUME_PPI.ProcessVolume()

Summary

Process a firmware volume and create a volume handle.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_PROCESS_FV) (
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
  IN VOID                                *Buffer,
  IN UINTN                               BufferSize,
  OUT EFI_PEI_FV_HANDLE                  *FvHandle
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI .

Buffer

Points to the start of the buffer.

BufferSize

Size of the buffer.

FvHandle

Points to the returned firmware volume handle. The firmware volume handle must be unique within the system. The type EFI_PEI_FV_HANDLE is defined in the PEI Services FfsFindNextVolume().

Description

Create a volume handle from the information in the buffer. For memory-mapped firmware volumes, Buffer and BufferSize refer to the start of the firmware volume and the firmware volume size. For non memory-mapped firmware volumes, this points to a buffer which contains the necessary information for creating the firmware volume handle. Normally, these values are derived from the EFI_PEI_FIRMWARE_VOLUME_INFO_PPI .

Status Codes Returned

Table 3.6 Status Codes Returned

EFI_SUCCESS	Firmware volume handle created.
EFI_VOLUME_CORRUPTED	Volume was corrupt.

3.3.3.3. EFI_PEI_FIRMWARE_VOLUME_PPI.FindFileByType()

Summary

Finds the next file of the specified type.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_FIND_FILE_TYPE) (
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,
  IN EFI_FV_FILETYPE                   SearchType,
  IN EFI_PEI_FV_HANDLE                 FvHandle,
  IN OUT EFI_PEI_FILE_HANDLE           *FileHandle
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI.

SearchType

A filter to find only files of this type. Type EFI_FV_FILETYPE_ALL causes no filtering to be done.

FvHandle

Handle of firmware volume in which to search.

FileHandle

Points to the current handle from which to begin searching or NULL to start at the beginning of the firmware volume. Updated upon return to reflect the file found.

Description

This service enables PEI modules to discover additional firmware files. The FileHandle must be unique within the system.

Status Codes Returned

Table 3.7 Status Codes Returned

EFI_SUCCESS	The file was found.
EFI_NOT_FOUND	The file was not found. FileHandle contains NULL.

3.3.3.4. EFI_PEI_FIRMWARE_VOLUME_PPI.FindFileByName()

Summary

Find a file within a volume by its name.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_FIND_FILE_NAME) (
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
  IN CONST EFI_GUID                      *FileName,
  IN EFI_PEI_FV_HANDLE                   *FvHandle,
  OUT EFI_PEI_FILE_HANDLE                *FileHandle
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI.

FileName

A pointer to the name of the file to find within the firmware volume.

FvHandle

Upon entry, the pointer to the firmware volume to search or NULL if all firmware volumes should be searched. Upon exit, the actual firmware volume in which the file was found.

FileHandle

Upon exit, points to the found file’s handle or NULL if it could not be found.

Description

This service searches for files with a specific name, within either the specified firmware volume or all firmware volumes. The behavior of files with file types EFI_FV_FILETYPE_FFS_MIN and EFI_FV_FILETYPE_FFS_MAX depends on the firmware file system. For more information on the specific behavior for the standard PI firmware file system, see section 1.1.4.1.6 of the PI Specification, Volume 3.

Status Codes Returned

Table 3.8 Status Codes Returned

EFI_SUCCESS	File was found.
EFI_NOT_FOUND	File was not found.
EFI_INVALID_PARAMETER	FileHandle or FileName was NULL.

3.3.3.5. EFI_PEI_FIRMWARE_VOLUME_PPI.GetFileInfo()

Summary

Returns information about a specific file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_GET_FILE_INFO) (
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
  IN EFI_PEI_FILE_HANDLE                 FileHandle,
  OUT EFI_FV_FILE_INFO                   *FileInfo
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI.

FileHandle

Handle of the file.

FileInfo

Upon exit, points to the file’s information.

Description

This function returns information about a specific file, including its file name, type, attributes, starting address and size.

Status Codes Returned

Table 3.9 Status Codes Returned

EFI_SUCCESS	File information returned.
EFI_INVALID_PARAMETER	If FileHandle does not represent a valid file.
EFI_INVALID_PARAMETER	If FileInfo is NULL

3.3.3.6. EFI_PEI_FIRMWARE_VOLUME_PPI.GetFileInfo2()

Summary

Returns information about a specific file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_GET_FILE_INFO2) (
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,
  IN EFI_PEI_FILE_HANDLE               FileHandle,
  OUT EFI_FV_FILE_INFO2                *FileInfo
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI.

FileHandle

Handle of the file.

FileInfo

Upon exit, points to the file’s information.

Description

This function returns information about a specific file, including its file name, type, attributes, starting address and size.

Status Codes Returned

Table 3.10 Status Codes Returned

EFI_SUCCESS	File information returned.
EFI_INVALID_PARAMETER	If FileHandle does not represent a valid file.
EFI_INVALID_PARAMETER	If FileInfo is NULL

3.3.3.7. EFI_PEI_FIRMWARE_VOLUME_PPI.GetVolumeInfo()

Summary

Return information about the firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_GET_INFO)(
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI  *This,
  IN EFI_PEI_FV_HANDLE                  FvHandle,
  OUT EFI_FV_INFO                       *VolumeInfo
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI.

FvHandle

Handle to the firmware handle.

VolumeInfo

Points to the returned firmware volume information.

Description

This function returns information about the firmware volume.

Status Codes Returned

Table 3.11 Status Codes Returned

EFI_SUCCESS	Information returned successfully.
EFI_INVALID_PARAMETER	FvHandle does not indicate a valid firmware volume or VolumeInfo is NULL.

3.3.3.8. EFI_PEI_FIRMWARE_VOLUME_PPI.FindSectionByType()

Summary

Find the next matching section in the firmware file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_FIND_SECTION) (
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
  IN EFI_SECTION_TYPE                    SearchType,
  IN EFI_PEI_FILE_HANDLE                 FileHandle,
  OUT VOID                               **SectionData
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI.

SearchType

A filter to find only sections of this type.

FileHandle

Handle of firmware file in which to search.

SectionData

Updated upon return to point to the section found.

Description

This service enables PEI modules to discover sections of a given type within a valid file.

Status Codes Returned

EFI_SUCCESS	Section was found.
EFI_NOT_FOUND	Section of the specified type was not found. SectionData contains NULL.

3.3.3.9. EFI_PEI_FIRMWARE_VOLUME_PPI.FindSectionByType2()

Summary

Find the next matching section in the firmware file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FV_FIND_SECTION2) (
  IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
  IN EFI_SECTION_TYPE                    SearchType,
  IN UINTN                               SearchInstance,
  IN EFI_PEI_FILE_HANDLE                 FileHandle,
  OUT VOID                               **SectionData
  OUT UINT32                             *AuthenticationStatus
  );

Parameters

This

Points to this instance of the EFI_PEI_FIRMWARE_VOLUME_PPI.

SearchType

A filter to find only sections of this type.

SearchInstance

A filter to find the specific instance of sections.

FileHandle

Handle of firmware file in which to search.

SectionData

Updated upon return to point to the section found.

AuthenticationStatus

Updated upon return to point to the authentication status for this section.

Description

This service enables PEI modules to discover sections of a given instance and type within a valid file.

Status Codes Returned

EFI_SUCCESS	Section was found.
EFI_NOT_FOUND	Section of the specified type was not found. SectionData contains NULL.

3.3.4. PEI Load File PPI

3.3.4.1. EFI_PEI_LOAD_FILE_PPI

Summary

Installed by a PEIM that supports the Load File PPI.

GUID

#define EFI_PEI_LOAD_FILE_PPI_GUID \
  { 0xb9e0abfe, 0x5979, 0x4914, \
  0x97, 0x7f, 0x6d, 0xee, 0x78, 0xc2, 0x78, 0xa6 }

Prototype

typedef struct _EFI_PEI_LOAD_FILE_PPI {
 EFI_PEI_LOAD_FILE  LoadFile;
} EFI_PEI_LOAD_FILE_PPI;

Parameters

LoadFile

Loads a PEIM into memory for subsequent execution. See the LoadFile() function description.

Description

This PPI is a pointer to the Load File service. This service will be published by a PEIM. The PEI Foundation will use this service to launch the known PEI module images.

3.3.4.2. EFI_PEI_LOAD_FILE_PPI.LoadFile()

Summary

Loads a PEIM into memory for subsequent execution.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_LOAD_FILE) (
  IN CONST EFI_PEI_LOAD_FILE_PPI   *This,
  IN EFI_PEI_FILE_HANDLE           FileHandle,
  OUT EFI_PHYSICAL_ADDRESS         *ImageAddress,
  OUT UINT64                       *ImageSize,
  OUT EFI_PHYSICAL_ADDRESS         *EntryPoint,
  OUT UINT32                       *AuthenticationState
  );

Parameters

This

Interface pointer that implements the Load File PPI instance.

FileHandle

File handle of the file to load. Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile().

ImageAddress

Pointer to the address of the loaded image.

ImageSize

Pointer to the size of the loaded image.

EntryPoint

Pointer to the entry point of the image.

AuthenticationState

On exit, points to the attestation authentication state of the image or 0 if no attestation was performed. The format of AuthenticationState is defined in EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI.ExtractSection().

Description

This service is the single member function of EFI_LOAD_FILE_PPI . This service separates image loading and relocating from the PEI Foundation. For example, if there are compressed images or images that need to be relocated into memory for performance reasons, this service performs that transformation. This service is very similar to the EFI_LOAD_FILE_PROTOCOL in the UEFI 2.0 specification. The abstraction allows for an implementation of the LoadFile() service to support different image types in the future. There may be more than one instance of this PPI in the system. For example, the PEI Foundation might support only XIP images natively, but another PEIM might contain support for relocatable images. There must be an LoadFile() instance that at least supports the PE/COFF and Terse Executable (TE) image format.

For sectioned files, this function should use FfsFindSectionData in order to find the executable image section.

This service must support loading of XIP images with or without copying them to a permanent memory. If the image within the specified file cannot be loaded because it must be copied into memory (either because the FV is not memory mapped or because the image contains relocations), and the permanent memory is not available, the function will return EFI_NOT_SUPPORTED . If permanent memory is available, then the PEIM should be loaded into permanent memory unless the image is not relocatable. If the image cannot be loaded into permanent memory due to insufficient amount of the available permanent memory, the function will return EFI_WARN_BUFFER_TOO_SMALL in case of XIP image, and EFI_OUT_OF_RESOURCES in case of non-XIP image. When EFI_WARN_BUFFER_TOO_SMALL is returned, all the output parameters are valid and the image can be invoked.

Any behavior PEIM which requires to be executed from code permanent memory should include wait for EFI_PEI_PERMANENT_MEMORY_INSTALLED_PPI and EFI_PEI_LOAD_FILE_PPI to be installed.

Status Codes Returned

Table 3.12 Status Codes Returned

EFI_SUCCESS	The image was loaded successfully.
EFI_OUT_OF_RESOURCES	There was not enough memory.
EFI_LOAD_ERROR	There was no supported image in the file.
EFI_INVALID_PARAMETER	FileHandle was not a valid firmware file handle.
EFI_INVALID_PARAMETER	EntryPoint was NULL.
EFI_UNSUPPORTED	An image requires relocations or is not memory mapped.
EFI_WARN_BUFFER_TOO_SMALL	There is not enough heap to allocate the requested size. This will not prevent the XIP image from being invoked.

3.3.5. PEI Guided Section Extraction PPI

3.3.5.1. EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI

Summary

If a GUID-defined section is encountered when doing section extraction, the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance calls the appropriate instance of the GUIDed Section Extraction PPI to extract the section stream contained therein.

GUID

Typically, protocol interface structures are identified by associating them with a GUID. Each instance of a protocol with a given GUID must have the same interface structure. While all instances of the GUIDed Section Extraction PPI must have the same interface structure, they do not all have the same GUID. The GUID that is associated with an instance of the GUIDed Section Extraction Protocol is used to correlate it with the GUIDed section type that it is intended to process.

PPI Structure

typedef struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI {
  EFI_PEI_EXTRACT_GUIDED_SECTION     ExtractSection;
} EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI;

Parameters

ExtractSection

Takes the GUIDed section as input and produces the section stream data. See the ExtractSection() function description.

3.3.5.2. EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI.ExtractSection()

Summary

Processes the input section and returns the data contained therein along with the authentication status.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_EXTRACT_GUIDED_SECTION)(
  IN CONST EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI  *This,
  IN CONST VOID                            *InputSection,
  OUT VOID                                 **OutputBuffer,
  OUT UINTN                                *OutputSize,
  OUT UINT32                               *AuthenticationStatus
  );

Parameters

This

Indicates the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI instance.

InputSection

Buffer containing the input GUIDed section to be processed.

OutputBuffer

*OutputBuffer is allocated from PEI permanent memory and contains the new section stream.

OutputSize

A pointer to a caller-allocated UINTN in which the size of *OutputBuffer allocation is stored. If the function returns anything other than EFI_SUCCESS , the value of *OutputSize is undefined.

AuthenticationStatus

A pointer to a caller-allocated UINT32 that indicates the authentication status of the output buffer. If the input section’s GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear, *AuthenticationStatus must return zero. These bits reflect the status of the extraction operation. If the function returns anything other than EFI_SUCCESS , the value of *AuthenticationStatus is undefined.

Description

The ExtractSection() function processes the input section and returns a pointer to the section contents. If the section being extracted does not require processing (if the section’s GuidedSectionHeader.Attributes has the EFI_GUIDED_SECTION_PROCESSING_REQUIRED field cleared), then OutputBuffer is just updated to point to the start of the section’s contents. Otherwise, *Buffer must be allocated from PEI permanent memory.

If the section being extracted contains authentication information (the section’s GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values returned in AuthenticationStatus must reflect the results of the authentication operation.

If the section contains other encapsulation sections, their contents do not need to be extracted or decompressed.

Related Definitions

//************************************************************
// Bit values for AuthenticationStatus
//************************************************************
#define EFI_AUTH_STATUS_PLATFORM_OVERRIDE  0x01
#define EFI_AUTH_STATUS_IMAGE_SIGNED       0x02
#define EFI_AUTH_STATUS_NOT_TESTED         0x04
#define EFI_AUTH_STATUS_TEST_FAILED        0x08

// all other bits are reserved and must be 0

The bit definitions above lead to the evaluations of AuthenticationStatus : in AuthenticationStatus Bit Definitions.

Table 3.13 AuthenticationStatus Bit Definitions

Bit	Definition
xx00	Image was not signed.
xxx1	Platform security policy override. Assumes same meaning as 0010 (the image was signed, the signature was tested, and the signature passed authentication test).
0010	Image was signed, the signature was tested, and the signature passed authentication test.
0110	Image was signed and the signature was not tested. This can occur if there is no GUIDed Section Extraction Protocol available to process a GUID-defined section, but it was still possible to retrieve the data from the GUID-defined section directly.
1010	Image was signed, the signature was tested, and the signature failed the authentication test.
1110	To generate this code, there must be at least two layers of GUIDed encapsulations. In one layer, the AuthenticationStatus was returned as 0110; in another layer, it was returned as 1010. When these two results are OR ed together, the aggregate result is 1110.

Status Codes Returned

Table 3.14 Status Codes Returned

EFI_SUCCESS	The InputSection was successfully processed and the section contents were returned.
EFI_OUT_OF_RESOURCES	The system has insufficient resources to process the request.
EFI_INVALID_PARAMETER	The GUID in InputSection does not match this instance of the GUIDed Section Extraction PPI.

3.3.6. PEI Decompress PPI

3.3.6.1. EFI_PEI_DECOMPRESS_PPI

Summary

Provides decompression services to the PEI Foundatoin.

GUID

#define EFI_PEI_DECOMPRESS_PPI_GUID \
  { 0x1a36e4e7, 0xfab6, 0x476a, \
  { 0x8e, 0x75, 0x69, 0x5a, 0x5, 0x76, 0xfd, 0xd7 } }

PPI Structure

typedef struct _EFI_PEI_DECOMPRESS_PPI {
  EFI_PEI_DECOMPRESS_DECOMPRESS   Decompress;
} EFI_PEI_DECOMPRESS_PPI;

Members

Decompress

Decompress a single compression section in a firmware file. See Decompress() for more information.

Description

This PPI’s single member function decompresses a compression encapsulated section. It is used by the PEI Foundation to process sectioned files. Prior to the installation of this PPI, compression sections will be ignored.

3.3.6.2. EFI_PEI_DECOMPRESS_PPI.Decompress()

Summary

Decompress a single section.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_DECOMPRESS_DECOMPRESS)(
  IN CONST EFI_PEI_DECOMPRESS_PPI      *This,
  IN CONST EFI_COMPRESSION_SECTION     *InputSection,
  OUT VOID                             **OutputBuffer,
  OUT UINTN                            *OutputSize
  );

Parameters

This

Points to this instance of the EFI_PEI_DECOMPRESS_PEI PPI .

InputSection

Points to the compressed section.

OutputBuffer

Holds the returned pointer to the decompressed sections.

OutputSize

Holds the returned size of the decompress section streams.

Description

Decompresses the data in a compressed section and returns it as a series of standard PI Firmware File Sections. The required memory is allocated from permanent memory.

Status Codes Returned

Table 3.15 Status Codes Returned

EFI_SUCCESS	The section was decompressed successfully. OutputBuffer contains the resulting data and OutputSize contains the resulting size.
EFI_OUT_OF_RESOURCES	Unable to allocate sufficient memory to hold the decompressed data.
EFI_UNSUPPORTED	The compression type specified in the compression header is unsupported.

3.4. DXE

3.4.1. Firmware Volume2 Protocol

3.4.1.1. EFI_FIRMWARE_VOLUME2_PROTOCOL

Summary

The Firmware Volume Protocol provides file-level access to the firmware volume. Each firmware volume driver must produce an instance of the Firmware Volume Protocol if the firmware volume is to be visible to the system during the DXE phase. The Firmware Volume Protocol also provides mechanisms for determining and modifying some attributes of the firmware volume.

GUID

#define EFI_FIRMWARE_VOLUME2_PROTOCOL_GUID \
  { 0x220e73b6, 0x6bdb, 0x4413, 0x84, 0x5, 0xb9, 0x74, \
  0xb1, 0x8, 0x61, 0x9a }

Protocol Interface Structure

typedef struct_EFI_FIRMWARE_VOLUME_PROTOCOL {
  EFI_FV_GET_ATTRIBUTES       GetVolumeAttributes;
  EFI_FV_SET_ATTRIBUTES       SetVolumeAttributes;
  EFI_FV_READ_FILE            ReadFile;
  EFI_FV_READ_SECTION         ReadSection;
  EFI_FV_WRITE_FILE           WriteFile;
  EFI_FV_GET_NEXT_FILE        GetNextFile;
  UINT32                      KeySize;
  EFI_HANDLE                  ParentHandle;
  EFI_FV_GET_INFO             GetInfo;
  EFI_FV_SET_INFO             SetInfo;
} EFI_FIRMWARE_VOLUME2_PROTOCOL;

Parameters

GetVolumeAttributes

Retrieves volume capabilities and current settings. See the GetVolumeAttributes() function description.

SetVolumeAttributes

Modifies the current settings of the firmware volume. See the SetVolumeAttributes() function description.

ReadFile

Reads an entire file from the firmware volume. See the ReadFile() function description.

ReadSection

Reads a single section from a file into a buffer. See the ReadSection() function description.

WriteFile

Writes an entire file into the firmware volume. See the WriteFile() function description.

GetNextFile

Provides service to allow searching the firmware volume. See the GetNextFile() function description.

KeySize

Data field that indicates the size in bytes of the Key input buffer for the GetNextFile() API.

ParentHandle

Handle of the parent firmware volume. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

GetInfo

Gets the requested file or volume information. See the GetInfo() function description.

SetInfo

Sets the requested file information. See the SetInfo() function description.

Description

The Firmware Volume Protocol contains the file-level abstraction to the firmware volume as well as some firmware volume attribute reporting and configuration services. The Firmware Volume Protocol is the interface used by all parts of DXE that are not directly involved with managing the firmware volume itself. This abstraction allows many varied types of firmware volume implementations. A firmware volume may be a flash device or it may be a file in the UEFI system partition, for example. This level of firmware volume implementation detail is not visible to the consumers of the Firmware Volume Protocol.

3.4.1.2. EFI_FIRMWARE_VOLUME2_PROTOCOL.GetVolumeAttributes()

Summary

Returns the attributes and current settings of the firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FV_GET_ATTRIBUTES) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
  OUT EFI_FV_ATTRIBUTES             *FvAttributes
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.

FvAttributes

Pointer to an EFI_FV_ATTRIBUTES in which the attributes and current settings are returned. Type EFI_FV_ATTRIBUTES is defined in “Related Definitions” below.

Description

Because of constraints imposed by the underlying firmware storage, an instance of the Firmware Volume Protocol may not be to able to support all possible variations of this architecture. These constraints and the current state of the firmware volume are exposed to the caller using the GetVolumeAttributes() function.

GetVolumeAttributes() is callable only from EFI_TPL_NOTIFY and below. Behavior of GetVolumeAttributes() at any EFI_TPL above EFI_TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

Related Definitions

//************************************************************
// EFI_FV_ATTRIBUTES
//************************************************************
typedef UINT64 EFI_FV_ATTRIBUTES;

//************************************************************
// EFI_FV_ATTRIBUTES bit definitions
//************************************************************

// EFI_FV_ATTRIBUTES bit semantics
#define EFI_FV2_READ_DISABLE_CAP       0x0000000000000001
#define EFI_FV2_READ_ENABLE_CAP        0x0000000000000002
#define EFI_FV2_READ_STATUS            0x0000000000000004

#define EFI_FV2_WRITE_DISABLE_CAP      0x0000000000000008
#define EFI_FV2_WRITE_ENABLE_CAP       0x0000000000000010
#define EFI_FV2_WRITE_STATUS           0x0000000000000020

#define EFI_FV2_LOCK_CAP               0x0000000000000040
#define EFI_FV2_LOCK_STATUS            0x0000000000000080
#define EFI_FV2_WRITE_POLICY_RELIABLE  0x0000000000000100

#define EFI_FV2_READ_LOCK_CAP          0x0000000000001000
#define EFI_FV2_READ_LOCK_STATUS       0x0000000000002000
#define EFI_FV2_WRITE_LOCK_CAP         0x0000000000004000
#define EFI_FV2_WRITE_LOCK_STATUS      0x0000000000008000
#define EFI_FV2_ALIGNMENT              0x00000000001F0000

#define EFI_FV2_ALIGNMENT_1            0x0000000000000000
#define EFI_FV2_ALIGNMENT_2            0x0000000000010000
#define EFI_FV2_ALIGNMENT_4            0x0000000000020000
#define EFI_FV2_ALIGNMENT_8            0x0000000000030000
#define EFI_FV2_ALIGNMENT_16           0x0000000000040000
#define EFI_FV2_ALIGNMENT_32           0x0000000000050000
#define EFI_FV2_ALIGNMENT_64           0x0000000000060000
#define EFI_FV2_ALIGNMENT_128          0x0000000000070000
#define EFI_FV2_ALIGNMENT_256          0x0000000000080000
#define EFI_FV2_ALIGNMENT_512          0x0000000000090000
#define EFI_FV2_ALIGNMENT_1K           0x00000000000A0000
#define EFI_FV2_ALIGNMENT_2K           0x00000000000B0000
#define EFI_FV2_ALIGNMENT_4K           0x00000000000C0000
#define EFI_FV2_ALIGNMENT_8K           0x00000000000D0000
#define EFI_FV2_ALIGNMENT_16K          0x00000000000E0000
#define EFI_FV2_ALIGNMENT_32K          0x00000000000F0000
#define EFI_FV2_ALIGNMENT_64K          0x0000000000100000
#define EFI_FV2_ALIGNMENT_128K         0x0000000000110000
#define EFI_FV2_ALIGNMENT_256K         0x0000000000120000
#define EFI_FV2_ALIGNMENT_512K         0x0000000000130000
#define EFI_FV2_ALIGNMENT_1M           0x0000000000140000
#define EFI_FV2_ALIGNMENT_2M           0x0000000000150000
#define EFI_FV2_ALIGNMENT_4M           0x0000000000160000
#define EFI_FV2_ALIGNMENT_8M           0x0000000000170000
#define EFI_FV2_ALIGNMENT_16M          0x0000000000180000
#define EFI_FV2_ALIGNMENT_32M          0x0000000000190000
#define EFI_FV2_ALIGNMENT_64M          0x00000000001A0000
#define EFI_FV2_ALIGNMENT_128M         0x00000000001B0000
#define EFI_FV2_ALIGNMENT_256M         0x00000000001C0000
#define EFI_FV2_ALIGNMENT_512M         0x00000000001D0000
#define EFI_FV2_ALIGNMENT_1G           0x00000000001E0000
#define EFI_FV2_ALIGNMENT_2G           0x00000000001F0000

Descriptions of Fields for EFI_FV_ATTRIBUTES describes the fields in the above definition.

Table 3.16 Descriptions of Fields for EFI_FV_ATTRIBUTES

Field	Description
EFI_FV_READ_DISABLED_CAP	Set to 1 if it is possible to disable reads from the firmware volume.
EFI_FV_READ_ENABLED_CAP	Set to 1 if it is possible to enable reads from the firmware volume.
EFI_FV_READ_STATUS	Indicates the current read state of the firmware volume. Set to 1 if reads from the firmware volume are enabled.
EFI_FV_WRITE_DISABLED_CAP	Set to 1 if it is possible to disable writes to the firmware volume.
EFI_FV_WRITE_ENABLED_CAP	Set to 1 if it is possible to enable writes to the firmware volume.
EFI_FV_WRITE_STATUS	Indicates the current state of the firmware volume. Set to 1 if writes to the firmware volume are enabled.
EFI_FV_LOCK_CAP	Set to 1 if it is possible to lock firmware volume read write attributes.
EFI_FV_LOCK_STATUS	Set to 1 if firmware volume attributes are locked down.
EFI_FV_WRITE_POLICY_RELIABLE	Set to 1 if the firmware volume supports “reliable” writes.
EFI_FV_READ_LOCK_CAP	Set to 1 if it is possible to lock the read status for the firmware volume.
EFI_FV_READ_LOCK_STATUS	Indicates the current read lock state of the firmware volume. Set to 1 if the read lock is currently enabled.
EFI_FV_WRITE_LOCK_CAP	Set to 1 if it is possible to lock the write status for the firmware volume.
EFI_FV_WRITE_LOCK_STATUS	Indicates the current write lock state of the firmware volume. Set to 1 if the write lock is currently enabled.
EFI_FV_ALIGNMENT	The first byte of the firmware volume must be at an address which is an even multiple of the alignment specified.

All other bits are reserved and are cleared to zero.

Status Codes Returned

Table 3.17 Status Codes Returned

EFI_SUCCESS

The firmware volume attributes were returned.

3.4.1.3. EFI_FIRMWARE_VOLUME2_PROTOCOL.SetVolumeAttributes()

Summary

Modifies the current settings of the firmware volume according to the input parameter.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FV_SET_ATTRIBUTES) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
  IN OUT EFI_FV_ATTRIBUTES         *FvAttributes
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.

FvAttributes

On input, FvAttributes is a pointer to an EFI_FV_ATTRIBUTES containing the desired firmware volume settings. On successful return, it contains the new settings of the firmware volume. On unsuccessful return, FvAttributes is not modified and the firmware volume settings are not changed. Type EFI_FV_ATTRIBUTES is defined in GetVolumeAttributes() .

Description

The SetVolumeAttributes() function is used to set configurable firmware volume attributes. Only EFI_FV_READ_STATUS , EFI_FV_WRITE_STATUS , and EFI_FV_LOCK_STATUS may be modified, and then only in accordance with the declared capabilities. All other bits of *FvAttributes are ignored on input. On successful return, all bits of *FvAttributes are valid and it contains the completed EFI_FV_ATTRIBUTES for the volume.

To modify an attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES is set to the desired value on input. The EFI_FV_LOCK_STATUS bit does not affect the ability to read or write the firmware volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it prevents further modification to all the attribute bits.

SetVolumeAttributes() is callable only from EFI_TPL_NOTIFY and below. Behavior of SetVolumeAttributes() at any EFI_TPL above EFI_TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

Status Codes Returned

Table 3.18 Status Codes Returned

EFI_SUCCESS	The requested firmware volume attributes were set and the resulting EFI_FV_ATTRIBUTES is returned in FvAttributes.
EFI_INVALID_PARAMETER	FvAttributes:EFI_FV_READ_STATUS is set to 1 on input, but the device does not support enabling reads (FvAttributes:EFI_FV_READ_ENABLE_CAP is clear on return from GetVolumeAttributes()). Actual volume attributes are unchanged.
EFI_INVALID_PARAMETER	FvAttributes:EFI_FV_READ_STATUS is cleared to 0 on input, but the device does not support disabling reads (FvAttributes:EFI_FV_READ_DISABLE_CAP is clear on return from GetVolumeAttributes()). Actual volume attributes are unchanged.
EFI_INVALID_PARAMETER	FvAttributes:EFI_FV_WRITE_STATUS is set to 1 on input, but the device does not support enabling writes (FvAttributes:EFI_FV_WRITE_ENABLE_CAP is clear on return from GetVolumeAttributes()). Actual volume attributes are unchanged.
EFI_INVALID_PARAMETER	FvAttributes:EFI_FV_WRITE_STATUS is cleared to 0 on input, but the device does not support disabling writes (FvAttributes:EFI_FV_WRITE_DISABLE_CAP is clear on return from GetVolumeAttributes()). Actual volume attributes are unchanged.
EFI_INVALID_PARAMETER	FvAttributes:EFI_FV_LOCK_STATUS is set on input, but the device does not support locking (FvAttributes:EFI_FV_LOCK_CAP is clear on return from GetVolumeAttributes()). Actual volume attributes are unchanged.
EFI_ACCESS_DENIED	Device is locked and does not allow attribute modification (FvAttributes:EFI_FV_LOCK_STATUS is set on return from GetVolumeAttributes()). Actual volume attributes are unchanged.

3.4.1.4. EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadFile()

Summary

Retrieves a file and/or file information from the firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FV_READ_FILE) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
  IN CONST EFI_GUID                *NameGuid,
  IN OUT VOID                      **Buffer,
  IN OUT UINTN                     *BufferSize,
  OUT EFI_FV_FILETYPE              *FoundType,
  OUT EFI_FV_FILE_ATTRIBUTES       *FileAttributes,
  OUT UINT32                       *AuthenticationStatus
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.

NameGuid

Pointer to an EFI_GUID , which is the file name. All firmware file names are EFI_GUID s. A single firmware volume must not have two valid files with the same file name EFI_GUID . Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

Buffer

Pointer to a pointer to a buffer in which the file contents are returned, not including the file header. See “Description” below for more details on the use of the Buffer parameter.

BufferSize

Pointer to a caller-allocated UINTN . It indicates the size of the memory represented by *Buffer . See “Description” below for more details on the use of the BufferSize parameter.

FoundType

Pointer to a caller-allocated EFI_FV_FILETYPE . See Firmware File Types for EFI_FV_FILETYPE related definitions.

FileAttributes

Pointer to a caller-allocated EFI_FV_FILE_ATTRIBUTES . Type EFI_FV_FILE_ATTRIBUTES is defined in “Related Definitions” below.

AuthenticationStatus

Pointer to a caller-allocated UINT32 in which the authentication status is returned. See “Related Definitions” in EFI_SECTION_EXTRACTION_PROCOCOL.ExtractSection() for more information.

Description

ReadFile() is used to retrieve any file from a firmware volume during the DXE phase. The actual binary encoding of the file in the firmware volume media may be in any arbitrary format as long as it does the following:

• It is accessed using the Firmware Volume Protocol.

• The image that is returned follows the image format defined in Code Definitions: PI Firmware File Format.

If the input value of Buffer==NULL , it indicates the caller is requesting only that the type, attributes, and size of the file be returned and that there is no output buffer. In this case, the following occurs:

• *BufferSize is returned with the size that is required to successfully complete the read.

• The output parameters *FoundType and *FileAttributes are returned with valid values.

• The returned value of *AuthenticationStatus is undefined.

If the input value of Buffer!=NULL , the output buffer is specified by a double indirection of the Buffer parameter. The input value of *Buffer is used to determine if the output buffer is caller allocated or is dynamically allocated by ReadFile() .

If the input value of *Buffer!=NULL , it indicates the output buffer is caller allocated. In this case, the input value of *BufferSize indicates the size of the caller-allocated output buffer. If the output buffer is not large enough to contain the entire requested output, it is filled up to the point that the output buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned, and then *BufferSize is returned with the size required to successfully complete the read. All other output parameters are returned with valid values.

If the input value of *Buffer==NULL , it indicates the output buffer is to be allocated by ReadFile() . In this case, ReadFile() will allocate an appropriately sized buffer from boot services pool memory, which will be returned in *Buffer . The size of the new buffer is returned in *BufferSize and all other output parameters are returned with valid values.

ReadFile() is callable only from EFI_TPL_NOTIFY and below. Behavior of ReadFile() at any EFI_TPL above EFI_TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

The behavior of files with file types EFI_FV_FILETYPE_FFS_MIN and EFI_FV_FILETYPE_FFS_MAX depends on the firmware file system. For more information on the specific behavior for the standard PI firmware file system, see section 1.1.4.1.6 of the PI Specification, Volume 3.

Related Definitions

//************************************************************
// EFI_FV_FILE_ATTRIBUTES
//************************************************************
typedef UINT32 EFI_FV_FILE_ATTRIBUTES;

#define EFI_FV_FILE_ATTRIB_ALIGNMENT         0x0000001F
#define EFI_FV_FILE_ATTRIB_FIXED             0x00000100
#define EFI_FV_FILE_ATTRIB_MEMORY_MAPPED     0x00000200

Fig. 3.2 EFI_FV_FILE_ATTRIBUTES-fields

This value is returned by EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadFile() and the PEI Service FfsGetFileInfo(). It is not the same as EFI_FFS_FILE_ATTRIBUTES.

The Reserved field must be set to zero.

The EFI_FV_FILE_ATTRIB_ALIGNMENT field indicates that the beginning of the file data (not the file header) must be aligned on a particular boundary relative to the beginning of the firmware volume. This alignment only makes sense for block-oriented firmware volumes. This field is an enumeration of alignment possibilities. The allowable alignments are powers of two from byte alignment to 2GB alignment. The supported alignments are described in Supported Alignments for EFI_FV_FILE_ATTRIB_ALIGNMENT. All other values are reserved.

Table 3.19 Supported Alignments for EFI_FV_FILE_ATTRIB_ALIGNMENT

Required Alignment (bytes)	Alignment Value in Attributes Field
1	0
2	1
4	2
8	3
16	4
32	5
64	6
128	7
256	8
512	9
1KiB	10
2KiB	11
4KiB	12
8KiB	13
16KiB	14
32KiB	15
64KiB	16
128 KiB	17
256 KiB	18
512 KiB	19
1 MiB	20
2 MiB	21
4 MiB	22
8 MiB	23
16 MiB	24
32 MiB	25
64 MiB	26
128 MiB	27
256 MiB	28
512 MiB	29
1 GiB	30
2 GiB	31

The EFI_FV_FILE_ATTRIB_FIXED attribute indicates that the file has a fixed location and should not be moved (1) or may be moved to any address consistent with the alignment specified in EFI_FV_FILE_ATTRIB_ALIGNMENT.

The EFI_FV_FILE_ATTRIB_MEMORY_MAPPED attribute indicates that the file is memory mapped in the firmware volume and thus its contents may be accessed directly. If this is clear, then Buffer is invalid. This value can be derived from the EFI_FV_ATTRIBUTES value returned by EFI_FIRMWARE_VOLUME2_PROTOCOL.GetVolumeAttributes() or the PEI Service FfsGetVolumeInfo().

Status Codes Returned

Table 3.20 Status Codes Returned

EFI_SUCCESS	The call completed successfully.
EFI_WARN_BUFFER_TOO_SMALL	The buffer is too small to contain the requested output. The buffer is filled and the output is truncated.
EFI_OUT_OF_RESOURCES	An allocation failure occurred.
EFI_NOT_FOUND	Name was not found in the firmware volume.
EFI_DEVICE_ERROR	A hardware error occurred when attempting to access the firmware volume.
EFI_ACCESS_DENIED	The firmware volume is configured to disallow reads.

3.4.1.5. EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection()

Summary

Locates the requested section within a file and returns it in a buffer.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FV_READ_SECTION) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
  IN CONST EFI_GUID                *NameGuid,
  IN EFI_SECTION_TYPE              SectionType,
  IN UINTN                         SectionInstance,
  IN OUT VOID                      **Buffer,
  IN OUT UINTN                     *BufferSize,
  OUT UINT32                       *AuthenticationStatus
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.

NameGuid

Pointer to an EFI_GUID , which indicates the file name from which the requested section will be read. Type EFI_GUID is defined in InstallProtocolInterface() in the Related Definitions for Firmware File Section.

SectionType

Indicates the section type to return. SectionType in conjunction with SectionInstance indicates which section to return. Type EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER .

SectionInstance

Indicates which instance of sections with a type of SectionType to return. SectionType in conjunction with SectionInstance indicates which section to return. SectionInstance is zero based.

Buffer

Pointer to a pointer to a buffer in which the section contents are returned, not including the section header. See “Description” below for more details on the usage of the Buffer parameter.

BufferSize

Pointer to a caller-allocated UINTN . It indicates the size of the memory represented by *Buffer . See “Description” below for more details on the usage of the BufferSize parameter.

AuthenticationStatus

Pointer to a caller-allocated UINT32 in which the authentication status is returned. See EFI_SECTION_EXTRACTION_PROCOCOL.GetSection() for more information.

Description

ReadSection() is used to retrieve a specific section from a file within a firmware volume. The section returned is determined using a depth-first, left-to-right search algorithm through all sections found in the specified file. See Firmware File Sections for more details about sections.

The output buffer is specified by a double indirection of the Buffer parameter. The input value of *Buffer is used to determine if the output buffer is caller allocated or is dynamically allocated by ReadSection().

If the input value of *Buffer!=NULL , it indicates that the output buffer is caller allocated. In this case, the input value of *BufferSize indicates the size of the caller-allocated output buffer. If the output buffer is not large enough to contain the entire requested output, it is filled up to the point that the output buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned, and then *BufferSize is returned with the size that is required to successfully complete the read. All other output parameters are returned with valid values.

If the input value of *Buffer==NULL , it indicates the output buffer is to be allocated by ReadSection() . In this case, ReadSection() will allocate an appropriately sized buffer from boot services pool memory, which will be returned in *Buffer . The size of the new buffer is returned in *BufferSize and all other output parameters are returned with valid values.

ReadSection() is callable only from EFI_TPL_NOTIFY and below. Behavior of ReadSection() at any EFI_TPL above EFI_TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

Status Codes Returned

Table 3.21 Status Codes Returned

EFI_SUCCESS	The call completed successfully.
EFI_WARN_BUFFER _ TOO_SMALL	The caller allocated buffer is too small to contain the requested output. The buffer is filled and the output is truncated.
EFI_OUT_OF_RESOURCES	An allocation failure occurred.
EFI_NOT_FOUND	The requested file was not found in the firmware volume.
EFI_NOT_FOUND	The requested section was not found in the specified file.
EFI_DEVICE_ERROR	A hardware error occurred when attempting to access the firmware volume.
EFI_ACCESS_DENIED	The firmware volume is configured to disallow reads.
EFI_PROTOCOL_ERROR	The requested section was not found, but the file could not be fully parsed because a required EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL was not found. It is possible the requested section exists within the file and could be successfully extracted once the required EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL is published.

3.4.1.6. EFI_FIRMWARE_VOLUME2_PROTOCOL.WriteFile()

Summary

Writes one or more files to the firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FV_WRITE_FILE) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
  IN UINT32                        NumberOfFiles,
  IN EFI_FV_WRITE_POLICY           WritePolicy,
  IN EFI_FV_WRITE_FILE_DATA        *FileData
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.

NumberOfFiles

Indicates the number of elements in the array pointed to by FileData.

WritePolicy

Indicates the level of reliability for the write in the event of a power failure or other system failure during the write operation. Type EFI_FV_WRITE_POLICY is defined in “Related Definitions” below.

FileData

Pointer to an array of EFI_FV_WRITE_FILE_DATA . Each element of FileData[] represents a file to be written. Type EFI_FV_WRITE_FILE_DATA is defined in “Related Definitions” below.

Description

WriteFile() is used to write one or more files to a firmware volume. Each file to be written is described by an EFI_FV_WRITE_FILE_DATA structure.

The caller must ensure that any required alignment for all files listed in the FileData array is compatible with the firmware volume. Firmware volume capabilities can be determined using the GetVolumeAttributes() call.

Similarly, if the WritePolicy is set to EFI_FV_RELIABLE_WRITE , the caller must check the firmware volume capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the firmware volume. EFI_FV_UNRELIABLE_WRITE must always be supported.

Writing a file with a size of zero (FileData[n].BufferSize == 0) deletes the file from the firmware volume if it exists. Deleting a file must be done one at a time. Deleting a file as part of a multiple file write is not allowed. WriteFile() is callable only from EFI_TPL_NOTIFY and below. Behavior of WriteFile() at any EFI_TPL above EFI_TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

Related Definitions

//************************************************************
// EFI_FV_WRITE_POLICY
//************************************************************
typedef UINT32 EFI_FV_WRITE_POLICY

#define EFI_FV_UNRELIABLE_WRITE  0x00000000
#define EFI_FV_RELIABLE_WRITE    0x00000001

All other values of EFI_FV_WRITE_POLICY are reserved. Description of fields for EFI_FV_WRITE_POLICY describes the fields in the above definition.

Table 3.22 Description of fields for EFI_FV_WRITE_POLICY

Field	Description
EFI_FV_UNRELIABLE_WRITE	This value in the WritePolicy parameter indicates that there is no required reliability if a power failure or other system failure occurs during a write operation. Updates may leave a combination of old and new files. Data loss, including complete loss of all files involved, is also permissible. In essence, no guarantees are made regarding what files will be present following a system failure during a write with a WritePolicy of EFI_FV_UNRELIABLE_WRITE. The advantage of this mode is that it can be implemented to use much less space in the storage media. Space-constrained firmware volumes may be able to support writes where it would be otherwise impossible.
EFI_FV_RELIABLE_WRITE	This value in the WritePolicy parameter indicates that, on the next initialization of the firmware volume following a power failure or other system failure during a write, all files listed in the FileData array are completely written and are valid, or none is written and the state of the firmware volume is the same as it was before the write operation was attempted.

//************************************************************
// EFI_FV_WRITE_FILE_DATA
//************************************************************
typedef struct {
  EFI_GUID                      *NameGuid,
  EFI_FV_FILETYPE               Type,
  EFI_FV_FILE_ATTRIBUTES        FileAttributes
  VOID                          *Buffer,
  UINT32                        BufferSize
} EFI_FV_WRITE_FILE_DATA;

NameGuid

Pointer to a GUID, which is the file name to be written. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

Type

Indicates the type of file to be written. Type EFI_FV_FILETYPE is defined in “Related Definitions” of EFI_FFS_FILE_HEADER..

FileAttributes

Indicates the attributes for the file to be written. Type EFI_FV_FILE_ATTRIBUTES is defined in ReadFile() .

Buffer

Pointer to a buffer containing the file to be written.

BufferSize

Indicates the size of the file image contained in Buffer .

Status Codes Returned

Table 3.23 Status Codes Returned

EFI_SUCCESS	The write completed successfully.
EFI_OUT_OF_RESOURCES	The firmware volume does not have enough free space to storefile(s).
EFI_DEVICE_ERROR	A hardware error occurred when attempting to access the firmware volume.
EFI_WRITE_PROTECTED	The firmware volume is configured to disallow writes.
EFI_NOT_FOUND	A delete was requested but the requested file was not found in the firmware volume.
EFI_INVALID_PARAMETER	A delete was requested with a multiple file write.
EFI_INVALID_PARAMETER	An unsupported WritePolicy was requested.
EFI_INVALID_PARAMETER	An unknown file type was specifiedspecified or the specified file type is not supported by the firmware file system.
EFI_INVALID_PARAMETER	A file system specific error has occurred.

Other than EFI_DEVICE_ERROR , all error codes imply the firmware volume has not been modified. In the case of EFI_DEVICE_ERROR , the firmware volume may have been corrupted and appropriate repair steps must be taken.

3.4.1.7. EFI_FIRMWARE_VOLUME2_PROTOCOL.GetNextFile()

Summary

Retrieves information about the next file in the firmware volume store that matches the search criteria.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FV_GET_NEXT_FILE) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
  IN OUT VOID                      *Key,
  IN OUT EFI_FV_FILETYPE           *FileType,
  OUT EFI_GUID                     *NameGuid,
  OUT EFI_FV_FILE_ATTRIBUTES       *Attributes,
  OUT UINTN                        *Size
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.

Key

Pointer to a caller-allocated buffer that contains implementation-specific data that is used to track where to begin the search for the next file. The size of the buffer must be at least This->KeySize bytes long. To re-initialize the search and begin from the beginning of the firmware volume, the entire buffer must be cleared to zero. Other than clearing the buffer to initiate a new search, the caller must not modify the data in the buffer between calls to GetNextFile() .

FileType

Pointer to a caller-allocated EFI_FV_FILETYPE . The GetNextFile() API can filter its search for files based on the value of the *FileType input. A *FileType input of EFI_FV_FILETYPE_ALL causes GetNextFile() to search for files of all types. If a file is found, the file’s type is returned in *FileType . *FileType is not modified if no file is found. See“Related Definitions” of EFI_FFS_FILE_HEADER..

NameGuid

Pointer to a caller-allocated EFI_GUID . If a matching file is found, the file’s name is returned in *NameGuid . If no matching file is found, *NameGuid is not modified. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

Attributes

Pointer to a caller-allocated EFI_FV_FILE_ATTRIBUTES . If a matching file is found, the file’s attributes are returned in *Attributes . If no matching file is found, *Attributes is not modified. Type EFI_FV_FILE_ATTRIBUTES is defined in ReadFile() .

Size

Pointer to a caller-allocated UINTN . If a matching file is found, the file’s size is returned in *Size . If no matching file is found, *Size is not modified.

Description

GetNextFile() is the interface that is used to search a firmware volume for a particular file. It is called successively until the desired file is located or the function returns EFI_NOT_FOUND.

To filter uninteresting files from the output, the type of file to search for may be specified in *FileType. For example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of this type will be returned in the output. If *FileType is EFI_FV_FILETYPE_ALL , no filtering of file types is done.The behavior of files with file types EFI_FV_FILETYPE_FFS_MIN and EFI_FV_FILETYPE_FFS_MAX depends on the firmware file system. For more information on the specific behavior for the standard PI firmware file system, see section 1.1.4.1.6 of the PI Specification, Volume 3.

The Key parameter is used to indicate a starting point of the search. If the buffer *Key is completely initialized to zero, the search re-initialized and starts at the beginning. Subsequent calls to GetNextFile() must maintain the value of *Key returned by the immediately previous call. The actual contents of *Key are implementation specific and no semantic content is implied.

GetNextFile() is callable only from EFI_TPL_NOTIFY and below. Behavior of GetNextFile() at any EFI_TPL above EFI_TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

Status Codes Returned

Table 3.24 Status Codes Returned

EFI_SUCCESS	The output parameters are filled with data obtained from the first matching file that was found.
EFI_NOT_FOUND	No files of type FileType were found.
EFI_DEVICE_ERROR	A hardware error occurred when attempting to access the firmware volume.
EFI_ACCESS_DENIED	The firmware volume is configured to disallow reads.

3.4.1.8. EFI_FIRMWARE_VOLUME2_PROTOCOL.GetInfo()

Summary

Return information about a firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FV_GET_INFO) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
  IN CONST EFI_GUID                        *InformationType,
  IN OUT UINTN                             *BufferSize,
  OUT VOID                                 *Buffer
  );

Parameters

This

A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL instance that is the file handle the requested information is for.

InformationType

The type identifier for the information being requested. Type EFI_GUID is defined in the UEFI 2.0 specification.

BufferSize

On input, the size of Buffer. On output, the amount of data returned in Buffer . In both cases, the size is measured in bytes.

Buffer

A pointer to the data buffer to return. The buffer’s type is indicated by InformationType.

Description

The GetInfo() function returns information of type InformationType for the requested firmware volume. If the volume does not support the requested information type, then EFI_UNSUPPORTED is returned. If the buffer is not large enough to hold the requested structure, EFI_BUFFER_TOO_SMALL is returned and the BufferSize is set to the size of buffer that is required to make the request. The information types defined by this specification are required information types that all file systems must support.

Status Codes Returned

Table 3.25 Status Codes Returned

EFI_SUCCESS	The information was retrieved.
EFI_UNSUPPORTED	The InformationType is not known.
EFI_NO_MEDIA	The device has no medium.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_BUFFER_TOO_SMALL	The BufferSize is too small to read the current directory entry. BufferSize has been updated with the size needed to complete the request.

3.4.1.9. EFI_FIRMWARE_VOLUME2_PROTOCOL.SetInfo()

Summary

Sets information about a firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FV_SET_INFO) (
  IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
  IN CONST EFI_GUID                      *InformationType,
  IN UINTN                               BufferSize,
  IN CONST VOID                          *Buffer
  );

Parameters

This

A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL instance that is the file handle the information is for.

InformationType

The type identifier for the information being set. Type EFI_GUID is defined in the UEFI 2.0 specification.

BufferSize

The size, in bytes, of Buffer .

Buffer

A pointer to the data buffer to write. The buffer’s type is indicated by InformationType .

Description

The SetInfo() function sets information of type InformationType on the requested firmware volume.

Status Codes Returned

Table 3.26 Status Codes Returned

EFI_SUCCESS	The information was set.
EFI_UNSUPPORTED	The InformationType is not known.
EFI_NO_MEDIA	The device has no medium.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The media is read only.
EFI_VOLUME_FULL	The volume is full.
EFI_BAD_BUFFER_SIZE	BufferSize is smaller than the size of the type indicated by InformationType.

3.4.2. Firmware Volume Block2 Protocol

3.4.2.1. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL

Summary

This optional protocol provides control over block-oriented firmware devices.

GUID

//{8F644FA9-E850-4db1-9CE2-0B44698E8DA4}
#define EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL_GUID \
  {0x8f644fa9, 0xe850, 0x4db1, 0x9c, 0xe2, 0xb, 0x44, \
  0x69, 0x8e, 0x8d, 0xa4}

Protocol Interface Structure

typedef struct _EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL {
  EFI_FVB_GET_ATTRIBUTES                GetAttributes;
  EFI_FVB_SET_ATTRIBUTES                SetAttributes;
  EFI_FVB_GET_PHYSICAL_ADDRESS          GetPhysicalAddress;
  EFI_FVB_GET_BLOCK_SIZE                GetBlockSize;
  EFI_FVB_READ                          Read;
  EFI_FVB_WRITE                         Write;
  EFI_FVB_ERASE_BLOCKS                  EraseBlocks;
  EFI_HANDLE                            ParentHandle;
} EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL;

Parameters

GetAttributes

Retrieves the current volume attributes. See the GetAttributes() function description.

SetAttributes

Sets the current volume attributes. See the SetAttributes() function description.

GetPhysicalAddress

Retrieves the memory-mapped address of the firmware volume. See the GetPhysicalAddress() function description.

GetBlockSize

Retrieves the size for a specific block. Also returns the number of consecutive similarly sized blocks. See the GetBlockSize() function description.

Read

Reads n bytes into a buffer from the firmware volume hardware. See the Read() function description.

Write

Writes n bytes from a buffer into the firmware volume hardware. See the Write() function description.

EraseBlocks

Erases specified block(s) and sets all values as indicated by the EFI_FVB_ERASE_POLARITY bit. See the EraseBlocks() function description. Type EFI_FVB_ERASE_POLARITY is defined in EFI_FIRMWARE_VOLUME_HEADER .

ParentHandle

Handle of the parent firmware volume. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

Description

The Firmware Volume Block Protocol is the low-level interface to a firmware volume. File-level access to a firmware volume should not be done using the Firmware Volume Block Protocol. Normal access to a firmware volume must use the Firmware Volume Protocol. Typically, only the file system driver that produces the Firmware Volume Protocol will bind to the Firmware Volume Block Protocol.

The Firmware Volume Block Protocol provides the following:

• Byte-level read/write functionality.

• Block-level erase functionality.

• It further exposes device-hardening features, such as may be required to protect the firmware from unwanted overwriting and/or erasure.

• It is useful to layer a file system driver on top of the Firmware Volume Block Protocol. This file system driver produces the Firmware Volume Protocol, which provides file-level access to a firmware volume. The Firmware Volume Protocol abstracts the file system that is used to format the firmware volume and the hardware device-hardening features that may be present.

3.4.2.2. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.GetAttributes()

Summary

Returns the attributes and current settings of the firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FVB_GET_ATTRIBUTES) (
  IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL   *This,
  OUT EFI_FVB_ATTRIBUTES_2                       *Attributes
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.

Attributes

Pointer to EFI_FVB_ATTRIBUTES_2 in which the attributes and current settings are returned. Type EFI_FVB_ATTRIBUTES_2 is defined in EFI_FIRMWARE_VOLUME_HEADER .

Description

The GetAttributes() function retrieves the attributes and current settings of the block.

Status Codes Returned

Table 3.27 Status Codes Returned

EFI_SUCCESS

The firmware volume attributes were returned.

3.4.2.3. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.SetAttributes()

Summary

Modifies the current settings of the firmware volume according to the input parameter.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FVB_SET_ATTRIBUTES) (
  IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL   *This,
  IN OUT EFI_FVB_ATTRIBUTES_2                    *Attributes
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.

Attributes

On input, Attributes is a pointer to EFI_FVB_ATTRIBUTES_2 that contains the desired firmware volume settings. On successful return, it contains the new settings of the firmware volume. Type EFI_FVB_ATTRIBUTES_2 is defined in EFI_FIRMWARE_VOLUME_HEADER .

Description

The SetAttributes() function sets configurable firmware volume attributes and returns the new settings of the firmware volume.

Status Codes Returned

Table 3.28 Status Codes Returned

EFI_SUCCESS	The firmware volume attributes were returned.
EFI_INVALID_PARAMETER	The attributes requested are in conflict with the capabilities as declared in the firmware volume header.

3.4.2.4. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.GetPhysicalAddress()

Summary

Retrieves the physical address of a memory-mapped firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS) (
  IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL   *This,
  OUT EFI_PHYSICAL_ADDRESS                       *Address
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.

Address

Pointer to a caller-allocated EFI_PHYSICAL_ADDRESS that, on successful return from GetPhysicalAddress() , contains the base address of the firmware volume. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 specification.

Description

The GetPhysicalAddress() function retrieves the base address of a memory-mapped firmware volume. This function should be called only for memory-mapped firmware volumes.

Status Codes Returned

Table 3.29 Status Codes Returned

EFI_SUCCESS	The firmware volume base address is returned.
EFI_UNSUPPORTED	The firmware volume is not memory mapped.

3.4.2.5. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.GetBlockSize()

Summary

Retrieves the size in bytes of a specific block within a firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FVB_GET_BLOCK_SIZE) (
  IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL   *This,
  IN EFI_LBA                                     Lba,
  OUT UINTN                                      *BlockSize,
  OUT UINTN                                      *NumberOfBlocks
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.

Lba

Indicates the block for which to return the size. Type EFI_LBA is defined in the BLOCK_IO Protocol (section 11.6) in the UEFI 2.0 specification.

BlockSize

Pointer to a caller-allocated UINTN in which the size of the block is returned.

NumberOfBlocks

Pointer to a caller-allocated UINTN in which the number of consecutive blocks, starting with Lba , is returned. All blocks in this range have a size of BlockSize .

Description

The GetBlockSize() function retrieves the size of the requested block. It also returns the number of additional blocks with the identical size. The GetBlockSize() function is used to retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).

Status Codes Returned

Table 3.30 Status Codes Returned

EFI_SUCCESS	The firmware volume base address is returned.
EFI_INVALID_PARAMETER	The requested LBA is out of range.

3.4.2.6. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.Read()

Summary

Reads the specified number of bytes into a buffer from the specified block.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FVB_READ) (
  IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL   *This,
  IN EFI_LBA                                     Lba,
  IN UINTN                                       Offset,
  IN OUT UINTN                                   *NumBytes,
  OUT UINT8                                      *Buffer,
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.

Lba

The starting logical block index from which to read. Type EFI_LBA is defined in the BLOCK_IO Protocol (section 11.6) in the UEFI 2.0 specification.

Offset

Offset into the block at which to begin reading.

NumBytes

Pointer to a UINTN . At entry, *NumBytes contains the total size of the buffer. At exit, *NumBytes contains the total number of bytes read.

Buffer

Pointer to a caller-allocated buffer that will be used to hold the data that is read.

Description

The Read() function reads the requested number of bytes from the requested block and stores them in the provided buffer.

Implementations should be mindful that the firmware volume might be in the ReadDisabled state. If it is in this state, the Read() function must return the status code EFI_ACCESS_DENIED without modifying the contents of the buffer.

The Read() function must also prevent spanning block boundaries. If a read is requested that would span a block boundary, the read must read up to the boundary but not beyond. The output parameter NumBytes must be set to correctly indicate the number of bytes actually read. The caller must be aware that a read may be partially completed.

Status Codes Returned

Table 3.31 Status Codes Returned

EFI_SUCCESS	The firmware volume was read successfully and contents are in Buffer.
EFI_BAD_BUFFER_SIZE	Read attempted across an LBA boundary. On output, NumBytes contains the total number of bytes returned in Buffer.
EFI_ACCESS_DENIED	The firmware volume is in the ReadDisabled state.
EFI_DEVICE_ERROR	The block device is not functioning correctly and could not be read.

3.4.2.7. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.Write()

Summary

Writes the specified number of bytes from the input buffer to the block.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FVB_WRITE) (
  IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL   *This,
  IN EFI_LBA                                     Lba,
  IN UINTN                                       Offset,
  IN OUT UINTN                                   *NumBytes,
  IN UINT8                                       *Buffer
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.

Lba

The starting logical block index to write to. Type EFI_LBA is defined in the BLOCK_IO Protocol (section 11.6) in the UEFI 2.0 specification.

Offset

Offset into the block at which to begin writing.

NumBytes

Pointer to a UINTN . At entry, *NumBytes contains the total size of the buffer. At exit, *NumBytes contains the total number of bytes actually written.

Buffer

Pointer to a caller-allocated buffer that contains the source for the write.

Description

The Write() function writes the specified number of bytes from the provided buffer to the specified block and offset.

If the firmware volume is sticky write, the caller must ensure that all the bits of the specified range to write are in the EFI_FVB_ERASE_POLARITY state before calling the Write() function, or else the result will be unpredictable. This unpredictability arises because, for a sticky-write firmware volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY state but it cannot flip it back again. In general, before calling the Write() function, the caller should call the EraseBlocks() function first to erase the specified block to write. A block erase cycle will transition bits from the (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state.

Implementations should be mindful that the firmware volume might be in the WriteDisabled state. If it is in this state, the Write() function must return the status code EFI_ACCESS_DENIED without modifying the contents of the firmware volume.

The Write() function must also prevent spanning block boundaries. If a write is requested that spans a block boundary, the write must store up to the boundary but not beyond. The output parameter NumBytes must be set to correctly indicate the number of bytes actually written. The caller must be aware that a write may be partially completed.

All writes, partial or otherwise, must be fully flushed to the hardware before the Write() service returns.

Status Codes Returned

Table 3.32 Status Codes Returned

EFI_SUCCESS	The firmware volume was written successfully.
EFI_BAD_BUFFER_SIZE	The write was attempted across an LBA boundary. On output, NumBytes contains the total number of bytes actually written.
EFI_ACCESS_DENIED	The firmware volume is in the WriteDisabled state.
EFI_DEVICE_ERROR	The block device is malfunctioning and could not be written.

3.4.2.8. EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.EraseBlocks()

Summary

Erases and initializes a firmware volume block.

Prototype

typedef
EFI_STATUS
(EFIAPI * EFI_FVB_ERASE_BLOCKS) (
  IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This,
  ...
  );

Parameters

This

Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.

...

The variable argument list is a list of tuples. Each tuple describes a range of LBAs to erase and consists of the following:

• An EFI_LBA that indicates the starting LBA

• A UINTN that indicates the number of blocks to erase

The list is terminated with an EFI_LBA_LIST_TERMINATOR. Type EFI_LBA_LIST_TERMINATOR is defined in “Related Definitions” below.

For example, the following indicates that two ranges of blocks (5-7 and 10-11) are to be erased:

EraseBlocks (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);

Description

The EraseBlocks() function erases one or more blocks as denoted by the variable argument list. The entire parameter list of blocks must be verified before erasing any blocks. If a block is requested that does not exist within the associated firmware volume (it has a larger index than the last block of the firmware volume), the EraseBlocks() function must return the status code EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.

Implementations should be mindful that the firmware volume might be in the WriteDisabled state. If it is in this state, the EraseBlocks() function must return the status code EFI_ACCESS_DENIED without modifying the contents of the firmware volume.

All calls to EraseBlocks() must be fully flushed to the hardware before the EraseBlocks() service returns.

Related Definitions

//*************************************************
// EFI_LBA_LIST_TERMINATOR
//*************************************************
#define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFF

Status Codes Returned

Table 3.33 Status Codes Returned

EFI_SUCCESS	The erase request was successfully completed.
EFI_ACCESS_DENIED	The firmware volume is in the WriteDisabled state.
EFI_DEVICE_ERROR	The block device is not functioning correctly and could not be written. The firmware device may have been partially erased.
EFI_INVALID_PARAMETER	One or more of the LBAs listed in the variable argument list do not exist in the firmware volume.

3.4.3. Guided Section Extraction Protocol

3.4.3.1. EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL

Summary

If a GUID-defined section is encountered when doing section extraction, the section extraction driver calls the appropriate instance of the GUIDed Section Extraction Protocol to extract the section stream contained therein.

GUID

Typically, protocol interface structures are identified by associating them with a GUID. Each instance of a protocol with a given GUID must have the same interface structure. While all instances of the GUIDed Section Extraction Protocol must have the same interface structure, they do not all have the same GUID. The GUID that is associated with an instance of the GUIDed Section Extraction Protocol is used to correlate it with the GUIDed section type that it is intended to process.

Protocol Interface Structure

typedef struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL {
  EFI_EXTRACT_GUIDED_SECTION      ExtractSection;
} EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL;

Parameters

ExtractSection

Takes the GUIDed section as input and produces the section stream data. See the ExtractSection() function description.

3.4.3.2. EFI_GUIDED_SECTION_EXTRACTION_PROCOCOL.ExtractSection()

Summary

Processes the input section and returns the data contained therein along with the authentication status.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_EXTRACT_GUIDED_SECTION)(
  IN CONST EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL  *This,
  IN CONST VOID              *InputSection,
  OUT VOID                   **OutputBuffer,
  OUT UINTN                  *OutputSize,
  OUT UINT32                 *AuthenticationStatus
  );

Parameters

This

Indicates the EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.

InputSection

Buffer containing the input GUIDed section to be processed.

OutputBuffer

*OutputBuffer is allocated from boot services pool memory and contains the new section stream. The caller is responsible for freeing this buffer.

OutputSize

A pointer to a caller-allocated UINTN in which the size of *OutputBuffer allocation is stored. If the function returns anything other than EFI_SUCCESS , the value of *OutputSize is undefined.

AuthenticationStatus

A pointer to a caller-allocated UINT32 that indicates the authentication status of the output buffer. If the input section’s GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear, *AuthenticationStatus must return zero. Both local bits (19:16) and aggregate bits (3:0) in AuthenticationStatus are returned by ExtractSection(). These bits reflect the status of the extraction operation. The bit pattern in both regions must be the same, as the local and aggregate authentication statuses have equivalent meaning at this level. If the function returns anything other than EFI_SUCCESS , the value of *AuthenticationStatus is undefined.

Description

The ExtractSection() function processes the input section and allocates a buffer from the pool in which it returns the section contents.

If the section being extracted contains authentication information (the section’s GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values returned in AuthenticationStatus must reflect the results of the authentication operation.

Depending on the algorithm and size of the encapsulated data, the time that is required to do a full authentication may be prohibitively long for some classes of systems. To indicate this, use EFI_SECURITY_POLICY_PROTOCOL_GUID , which may be published by the security policy driver (see the Platform Initialization Driver Execution Environment Core Interface Specification for more details and the GUID definition). If the EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle database, then, if possible, full authentication should be skipped and the section contents simply returned in the OutputBuffer . In this case, the EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus must be set on return. See “Related Definitions” in EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI.ExtractSection() for the definition of type EFI_AUTH_STATUS_PLATFORM_OVERRIDE.

ExtractSection() is callable only from EFI_TPL_NOTIFY and below. Behavior of ExtractSection() at any EFI_TPL above EFI_TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

Status Codes Returned

Table 3.34 Status Codes Returned

EFI_SUCCESS	The InputSection was successfully processed and the section contents were returned.
EFI_OUT_OF_RESOURCES	The system has insufficient resources to process the request.
EFI_INVALID_PARAMETER	The GUID in InputSection does not match this instance of the GUIDed Section Extraction Protocol.

3.5. SMM

3.5.1. SMM Firmware Volume Protocol

3.5.1.1. EFI_SMM_FIRMWARE_VOLUME_PROTOCOL

Summary

The Firmware Volume Protocol provides file-level access to the firmware volume in SMM.

GUID

#define EFI_SMM_FIRMWARE_VOLUME_PROTOCOL_GUID { \
  0x19e9da84, 0x72b, 0x4274, 0xb3, 0x2e, 0xc, 0x8, 0x2, 0xe7,
0x17, 0xa5 \
}

Prototype

Same as EFI_FIRMWARE_VOLUME2_PROTOCOL;

Description

The Firmware Volume Protocol provides file-level access to the firmware volume in SMM.

The function API is same as DXE version EFI_FIRMWARE_VOLUME2_PROTOCOL.

3.5.2. SMM Firmware Volume Block Protocol

3.5.2.1. EFI_SMM_FIRMWARE_VOLUME_BLOCK_PROTOCOL

Summary

This optional protocol provides control over block-oriented firmware devices in SMM.

GUID

#define EFI_SMM_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID { \
  0xd326d041, 0xbd31, 0x4c01, 0xb5, 0xa8, 0x62, 0x8b, 0xe8, 0x7f,
0x06, 0x53 \
}

Prototype

Same as EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL;

Description

This optional protocol provides control over block-oriented firmware devices in SMM.

The function API is same as DXE version EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL.