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 inInstallProtocolInterface()
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 theAttributes
field of the firmware volume header. TypeEFI_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 theEFI_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.
//*************************************************
// 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:
Attribute |
Description |
---|---|
EFI_FVB2_READ_DISABLED_CAP |
|
EFI_FVB2_READ_ENABLED_CAP |
|
EFI_FVB2_READ_STATUS |
|
EFI_FVB2_WRITE_DISABLED_CAP |
|
EFI_FVB2_WRITE_ENABLED_CAP |
|
EFI_FVB2_WRITE_STATUS |
|
EFI_FVB2_LOCK_CAP |
|
EFI_FVB2_LOCK_STATUS |
|
EFI_FVB2_STICKY_WRITE |
|
EFI_FVB2_MEMORY_MAPPED |
|
EFI_FVB2_ERASE_POLARITY |
Value of all bits after erasure. See the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL. |
EFI_FVB2_READ_LOCK_CAP |
|
EFI_FVB2_READ_LOCK_STATUS |
|
EFI_FVB2_WRITE_LOCK_CAP |
|
EFI_FVB2_WRITE_LOCK_STATUS |
|
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 |
|
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 inTypes
. For example, the value 0x01010301 would indicate that there would be five total entries inTypes
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 byEFI_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
or
EFI_CERT_TYPE_RSA2048_SHA256_GUID
.
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 isEFI_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 inEFI_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 aSize
of 24 bytes, which issizeof(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 inAttributes
thenExtendedSize
exists andSize
must be set to zero. IfFFS_ATTRIB_LARGE_FILE
is not set thenEFI_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).
//******************************************************
// 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. TheState
andIntegrityCheck.Checksum.File
fields are assumed to be zero and the checksum is calculated such that the entire header sums to zero. TheIntegrityCheck.Checksum.Header
field is valid anytime theEFI_FILE_HEADER_VALID
bit is set in theState
field. See File Integrity and State for more details. If theFFS_ATTRIB_LARGE_FILE
bit of theAttributes
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 theAttributes
field is set to one, theIntegrityCheck.Checksum.File
field is an 8-bit checksum of the file data. If theFFS_ATTRIB_CHECKSUM
bit of theAttributes
field is cleared to zero, theIntegrityCheck.Checksum.File
field must be initialized with a value of 0xAA. TheIntegrityCheck.Checksum.File
field is valid any time theEFI_FILE_DATA_VALID
bit is set in theState
field. See File Integrity and State for more details.
Checksum
IntegrityCheck.
Checksum16
is the full 16 bits of theIntegrityCheck
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.
![_images/V3_Code_Definitions-2.png](_images/V3_Code_Definitions-2.png)
Fig. 3.1 Bit Allocation of FFS Attributes
¶
Bit Allocation Definitions provides descriptions of the fields in the above definition.
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 |
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_CHECKSUM |
Determines the interpretation of |
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.
Required Alignment (bytes) |
AlignmentValue in FFS |
FFS_ATTRIB_DATA _ALIGNMENT2 in FFS |
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 aSize
of 4 bytes.
Type
Declares the section type. Type
EFI_SECTION_TYPE
is defined in “Related Definitions” below.
ExtendedSize
If
Size
is 0xFFFFFF thenExtendedSize
contains the size of the section. IfSize
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.
//************************************************************
// 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.
//************************************************************
// CompressionType values
//************************************************************
#define EFI_NOT_COMPRESSED 0x00
#define EFI_STANDARD_COMPRESSION 0x01
Description of Fields for CompressionType describes the fields in the above definition.
Field |
Description |
---|---|
|
Indicates that the encapsulated section stream is not compressed. This type is useful to grouping sections together without requiring a decompressor. |
|
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 inInstallProtocolInterface()
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 about EFI_FV_FILETYPE_FREEFORM
files.
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 inInstallProtocolInterface()
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.
//*****************************************************
// 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.
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_AUTH _ STATUS_VALID |
Set to 1 if the section contains authentication data that is reported through the |
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
or
EFI_CERT_TYPE_RSA2048_SHA256_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 theFvFormat
. 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 theFvFormat
. 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 ServicesFfsFindNextVolume()
.
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
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
EFI_SUCCESS |
The file was found. |
EFI_NOT_FOUND |
The file was not found. |
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
EFI_SUCCESS |
File was found. |
EFI_NOT_FOUND |
File was not found. |
EFI_INVALID_PARAMETER |
|
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
EFI_SUCCESS |
File information returned. |
EFI_INVALID_PARAMETER |
If |
EFI_INVALID_PARAMETER |
If |
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
EFI_SUCCESS |
File information returned. |
EFI_INVALID_PARAMETER |
If |
EFI_INVALID_PARAMETER |
If |
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
EFI_SUCCESS |
Information returned successfully. |
EFI_INVALID_PARAMETER |
|
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.
|
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.
|
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 inFfsFindNextFile()
.
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
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 |
|
EFI_INVALID_PARAMETER |
|
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 thanEFI_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’sGuidedSectionHeader.Attributes
field has theEFI_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 thanEFI_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.
//************************************************************
// 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.
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 |
Status Codes Returned
EFI_SUCCESS |
The |
EFI_OUT_OF_RESOURCES |
The system has insufficient resources to process the request. |
EFI_INVALID_PARAMETER |
The GUID in |
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
EFI_SUCCESS |
The section was decompressed successfully. |
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 theGetNextFile()
API.
ParentHandle
Handle of the parent firmware volume. Type
EFI_HANDLE
is defined inInstallProtocolInterface()
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. TypeEFI_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.
//************************************************************
// 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.
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
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 anEFI_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. TypeEFI_FV_ATTRIBUTES
is defined inGetVolumeAttributes()
.
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
EFI_SUCCESS |
The requested firmware volume attributes were set and the resulting |
EFI_INVALID_PARAMETER |
|
EFI_INVALID_PARAMETER |
|
EFI_INVALID_PARAMETER |
|
EFI_INVALID_PARAMETER |
|
EFI_INVALID_PARAMETER |
|
EFI_ACCESS_DENIED |
Device is locked and does not allow attribute modification ( |
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 areEFI_GUID
s. A single firmware volume must not have two valid files with the same file nameEFI_GUID
. TypeEFI_GUID
is defined inInstallProtocolInterface()
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 theBufferSize
parameter.
FoundType
Pointer to a caller-allocated
EFI_FV_FILETYPE
. See Firmware File Types forEFI_FV_FILETYPE
related definitions.
FileAttributes
Pointer to a caller-allocated
EFI_FV_FILE_ATTRIBUTES
. TypeEFI_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” inEFI_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.
//************************************************************
// 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
![_images/V3_Code_Definitions-3.png](_images/V3_Code_Definitions-3.png)
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.
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
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 |
|
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. TypeEFI_GUID
is defined inInstallProtocolInterface()
in the Related Definitions for Firmware File Section.
SectionType
Indicates the section type to return.
SectionType
in conjunction withSectionInstance
indicates which section to return. TypeEFI_SECTION_TYPE
is defined inEFI_COMMON_SECTION_HEADER
.
SectionInstance
Indicates which instance of sections with a type of
SectionType
to return.SectionType
in conjunction withSectionInstance
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 theBufferSize
parameter.
AuthenticationStatus
Pointer to a caller-allocated
UINT32
in which the authentication status is returned. SeeEFI_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
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 |
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 ofFileData[]
represents a file to be written. TypeEFI_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.
//************************************************************
// 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.
Field |
Description |
---|---|
EFI_FV_UNRELIABLE_WRITE |
This value in the |
EFI_FV_RELIABLE_WRITE |
This value in the |
//************************************************************
// 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 inInstallProtocolInterface()
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 inReadFile()
.
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
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 |
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 toGetNextFile()
.
FileType
Pointer to a caller-allocated
EFI_FV_FILETYPE
. TheGetNextFile()
API can filter its search for files based on the value of the*FileType
input. A*FileType
input ofEFI_FV_FILETYPE_ALL
causesGetNextFile()
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. TypeEFI_GUID
is defined inInstallProtocolInterface()
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. TypeEFI_FV_FILE_ATTRIBUTES
is defined inReadFile()
.
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
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 |
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
EFI_SUCCESS |
The information was retrieved. |
EFI_UNSUPPORTED |
The |
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 |
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
EFI_SUCCESS |
The information was set. |
EFI_UNSUPPORTED |
The |
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 |
|
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 theEraseBlocks()
function description. TypeEFI_FVB_ERASE_POLARITY
is defined inEFI_FIRMWARE_VOLUME_HEADER
.
ParentHandle
Handle of the parent firmware volume. Type
EFI_HANDLE
is defined inInstallProtocolInterface()
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. TypeEFI_FVB_ATTRIBUTES_2
is defined inEFI_FIRMWARE_VOLUME_HEADER
.
Description
The GetAttributes()
function retrieves the attributes and
current settings of the block.
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 toEFI_FVB_ATTRIBUTES_2
that contains the desired firmware volume settings. On successful return, it contains the new settings of the firmware volume. TypeEFI_FVB_ATTRIBUTES_2
is defined inEFI_FIRMWARE_VOLUME_HEADER
.
Description
The SetAttributes()
function sets configurable firmware
volume attributes and returns the new settings of the firmware
volume.
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 fromGetPhysicalAddress()
, contains the base address of the firmware volume. TypeEFI_PHYSICAL_ADDRESS
is defined inAllocatePages()
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
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 theBLOCK_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 withLba
, is returned. All blocks in this range have a size ofBlockSize
.
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
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 theBLOCK_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
EFI_SUCCESS |
The firmware volume was read successfully and contents are in |
EFI_BAD_BUFFER_SIZE |
Read attempted across an LBA boundary. On output, |
EFI_ACCESS_DENIED |
The firmware volume is in the |
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 theBLOCK_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
EFI_SUCCESS |
The firmware volume was written successfully. |
EFI_BAD_BUFFER_SIZE |
The write was attempted across an LBA boundary. On output, |
EFI_ACCESS_DENIED |
The firmware volume is in the |
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 LBAA
UINTN
that indicates the number of blocks to erase
The list is terminated with an
EFI_LBA_LIST_TERMINATOR
. TypeEFI_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.
//*************************************************
// EFI_LBA_LIST_TERMINATOR
//*************************************************
#define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFF
Status Codes Returned
EFI_SUCCESS |
The erase request was successfully completed. |
EFI_ACCESS_DENIED |
The firmware volume is in the |
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 thanEFI_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’sGuidedSectionHeader.Attributes
field has theEFI_GUIDED_SECTION_AUTH_STATUS_VALID
bit as clear,*AuthenticationStatus
must return zero. Both local bits (19:16) and aggregate bits (3:0) inAuthenticationStatus
are returned byExtractSection()
. 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 thanEFI_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
EFI_SUCCESS |
The |
EFI_OUT_OF_RESOURCES |
The system has insufficient resources to process the request. |
EFI_INVALID_PARAMETER |
The GUID in |
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
.