#include "PeiMain.h"

Data Structures
struct	PEI_FW_VOL_INSTANCE

Macros
#define	GET_OCCUPIED_SIZE(ActualSize, Alignment) ((ActualSize) + (((Alignment) - ((ActualSize) & ((Alignment) - 1))) & ((Alignment) - 1)))

#define	PEI_FW_VOL_SIGNATURE SIGNATURE_32('P','F','W','V')

#define	PEI_FW_VOL_INSTANCE_FROM_FV_THIS(a) CR(a, PEI_FW_VOL_INSTANCE, Fv, PEI_FW_VOL_SIGNATURE)

Functions
EFI_STATUS EFIAPI	PeiFfsFvPpiProcessVolume (IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI This, IN VOID Buffer, IN UINTN BufferSize, OUT EFI_PEI_FV_HANDLE *FvHandle)

EFI_STATUS EFIAPI	PeiFfsFvPpiFindFileByType (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)

EFI_STATUS EFIAPI	PeiFfsFvPpiFindFileByName (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)

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

EFI_STATUS EFIAPI	PeiFfsFvPpiFindSectionByType2 (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)

EFI_STATUS EFIAPI	PeiFfsFvPpiGetFileInfo (IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI This, IN EFI_PEI_FILE_HANDLE FileHandle, OUT EFI_FV_FILE_INFO FileInfo)

EFI_STATUS EFIAPI	PeiFfsFvPpiGetFileInfo2 (IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI This, IN EFI_PEI_FILE_HANDLE FileHandle, OUT EFI_FV_FILE_INFO2 FileInfo)

EFI_STATUS EFIAPI	PeiFfsFvPpiGetVolumeInfo (IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI This, IN EFI_PEI_FV_HANDLE FvHandle, OUT EFI_FV_INFO VolumeInfo)

PEI_CORE_FV_HANDLE *	FvHandleToCoreHandle (IN EFI_PEI_FV_HANDLE FvHandle)

EFI_STATUS	FindFileEx (IN CONST EFI_PEI_FV_HANDLE FvHandle, IN CONST EFI_GUID FileName OPTIONAL, IN EFI_FV_FILETYPE SearchType, IN OUT EFI_PEI_FILE_HANDLE FileHandle, IN OUT EFI_PEI_FILE_HANDLE *AprioriFile OPTIONAL)

EFI_STATUS	AddUnknownFormatFvInfo (IN PEI_CORE_INSTANCE PrivateData, IN EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI FvInfo2Ppi)

EFI_STATUS	FindUnknownFormatFvInfo (IN PEI_CORE_INSTANCE PrivateData, IN EFI_GUID Format, OUT VOID *FvInfo, OUT UINT32 FvInfoSize, OUT UINT32 *AuthenticationStatus)

EFI_STATUS EFIAPI	ThirdPartyFvPpiNotifyCallback (IN EFI_PEI_SERVICES *PeiServices, IN EFI_PEI_NOTIFY_DESCRIPTOR NotifyDescriptor, IN VOID *Ppi)

Detailed Description

The internal header file for firmware volume related definitions.

Copyright (c) 2009 - 2019, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file FwVol.h.

Macro Definition Documentation

◆ GET_OCCUPIED_SIZE

#define GET_OCCUPIED_SIZE	(	ActualSize,
		Alignment
	)	((ActualSize) + (((Alignment) - ((ActualSize) & ((Alignment) - 1))) & ((Alignment) - 1)))

Definition at line 14 of file FwVol.h.

◆ PEI_FW_VOL_INSTANCE_FROM_FV_THIS

#define PEI_FW_VOL_INSTANCE_FROM_FV_THIS ( a ) CR(a, PEI_FW_VOL_INSTANCE, Fv, PEI_FW_VOL_SIGNATURE)

Definition at line 25 of file FwVol.h.

◆ PEI_FW_VOL_SIGNATURE

#define PEI_FW_VOL_SIGNATURE SIGNATURE_32('P','F','W','V')

Definition at line 17 of file FwVol.h.

Function Documentation

◆ AddUnknownFormatFvInfo()

EFI_STATUS AddUnknownFormatFvInfo	(	IN PEI_CORE_INSTANCE *	PrivateData,
		IN EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI *	FvInfo2Ppi
	)

Report the information for a newly discovered FV in an unknown format.

If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for a third-party FV format, but the FV has been discovered, then the information of this FV will be cached into PEI_CORE_INSTANCE's UnknownFvInfo array.

Also a notification would be installed for unknown FV format GUID, if EFI_PEI_FIRMWARE_VOLUME_PPI is installed later by platform's PEIM, the original unknown FV will be processed by using new installed EFI_PEI_FIRMWARE_VOLUME_PPI.

Parameters

PrivateData	Point to instance of PEI_CORE_INSTANCE
FvInfo2Ppi	Point to FvInfo2 PPI.

Return values

EFI_OUT_OF_RESOURCES	The FV info array in PEI_CORE_INSTANCE has no more spaces.
EFI_SUCCESS	Success to add the information for unknown FV.

Definition at line 2248 of file FwVol.c.

◆ FindFileEx()

EFI_STATUS FindFileEx	(	IN CONST EFI_PEI_FV_HANDLE	FvHandle,
		IN CONST EFI_GUID *FileName	OPTIONAL,
		IN EFI_FV_FILETYPE	SearchType,
		IN OUT EFI_PEI_FILE_HANDLE *	FileHandle,
		IN OUT EFI_PEI_FILE_HANDLE *AprioriFile	OPTIONAL
	)

Given the input file pointer, search for the next matching file in the FFS volume as defined by SearchType. The search starts from FileHeader inside the Firmware Volume defined by FwVolHeader.

Parameters

FvHandle	Pointer to the FV header of the volume to search
FileName	File name
SearchType	Filter to find only files of this type. Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
FileHandle	This parameter must point to a valid FFS volume.
AprioriFile	Pointer to AprioriFile image in this FV if has

Returns: EFI_NOT_FOUND No files matching the search criteria were found

Return values

EFI_SUCCESS Success to search given file

Given the input file pointer, search for the first matching file in the FFS volume as defined by SearchType. The search starts from FileHeader inside the Firmware Volume defined by FwVolHeader. If SearchType is EFI_FV_FILETYPE_ALL, the first FFS file will return without check its file type. If SearchType is PEI_CORE_INTERNAL_FFS_FILE_DISPATCH_TYPE, the first PEIM, or COMBINED PEIM or FV file type FFS file will return.

Parameters

FvHandle	Pointer to the FV header of the volume to search
FileName	File name
SearchType	Filter to find only files of this type. Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
FileHandle	This parameter must point to a valid FFS volume.
AprioriFile	Pointer to AprioriFile image in this FV if has

Returns: EFI_NOT_FOUND No files matching the search criteria were found

Return values

EFI_SUCCESS Success to search given file

Definition at line 266 of file FwVol.c.

◆ FindUnknownFormatFvInfo()

EFI_STATUS FindUnknownFormatFvInfo	(	IN PEI_CORE_INSTANCE *	PrivateData,
		IN EFI_GUID *	Format,
		OUT VOID **	FvInfo,
		OUT UINT32 *	FvInfoSize,
		OUT UINT32 *	AuthenticationStatus
	)

Find the FV information according to FV format GUID.

This routine also will remove the FV information found by given FV format GUID from PrivateData->UnknownFvInfo[].

Parameters

PrivateData	Point to instance of PEI_CORE_INSTANCE
Format	Point to given FV format GUID
FvInfo	On return, the pointer of FV information buffer in given FV format GUID
FvInfoSize	On return, the size of FV information buffer.
AuthenticationStatus	On return, the authentication status of FV information buffer.

Return values

EFI_NOT_FOUND	The FV is not found for new installed EFI_PEI_FIRMWARE_VOLUME_PPI
EFI_SUCCESS	Success to find a FV which could be processed by new installed EFI_PEI_FIRMWARE_VOLUME_PPI.

Find the FV information according to third-party FV format GUID.

This routine also will remove the FV information found by given FV format GUID from PrivateData->UnknownFvInfo[].

Parameters

PrivateData	Point to instance of PEI_CORE_INSTANCE
Format	Point to given FV format GUID
FvInfo	On return, the pointer of FV information buffer
FvInfoSize	On return, the size of FV information buffer.
AuthenticationStatus	On return, the authentication status of FV information buffer.

Return values

EFI_NOT_FOUND	The FV is not found for new installed EFI_PEI_FIRMWARE_VOLUME_PPI
EFI_SUCCESS	Success to find a FV which could be processed by new installed EFI_PEI_FIRMWARE_VOLUME_PPI.

Definition at line 2304 of file FwVol.c.

◆ FvHandleToCoreHandle()

PEI_CORE_FV_HANDLE * FvHandleToCoreHandle ( IN EFI_PEI_FV_HANDLE FvHandle )

Convert the handle of FV to pointer of corresponding PEI_CORE_FV_HANDLE.

Parameters

FvHandle The handle of a FV.

Return values

NULL	if can not find.

Returns: Pointer of corresponding PEI_CORE_FV_HANDLE.

Definition at line 2114 of file FwVol.c.

◆ PeiFfsFvPpiFindFileByName()

EFI_STATUS EFIAPI PeiFfsFvPpiFindFileByName	(	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
	)

Find a file within a volume by its name.

This service searches for files with a specific name, within either the specified firmware volume or all firmware volumes.

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.

Return values

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

Definition at line 1735 of file FwVol.c.

◆ PeiFfsFvPpiFindFileByType()

EFI_STATUS EFIAPI PeiFfsFvPpiFindFileByType	(	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
	)

Finds the next file of the specified type.

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

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.

Return values

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

Definition at line 1698 of file FwVol.c.

◆ PeiFfsFvPpiFindSectionByType()

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

Find the next matching section in the firmware file.

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

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.

Return values

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

Definition at line 1998 of file FwVol.c.

◆ PeiFfsFvPpiFindSectionByType2()

EFI_STATUS EFIAPI PeiFfsFvPpiFindSectionByType2	(	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
	)

Find the next matching section in the firmware file.

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

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.

Return values

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

Definition at line 2035 of file FwVol.c.

◆ PeiFfsFvPpiGetFileInfo()

EFI_STATUS EFIAPI PeiFfsFvPpiGetFileInfo	(	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *	This,
		IN EFI_PEI_FILE_HANDLE	FileHandle,
		OUT EFI_FV_FILE_INFO *	FileInfo
	)

Returns information about a specific file.

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

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.

Return values

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

Definition at line 1800 of file FwVol.c.

◆ PeiFfsFvPpiGetFileInfo2()

EFI_STATUS EFIAPI PeiFfsFvPpiGetFileInfo2	(	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *	This,
		IN EFI_PEI_FILE_HANDLE	FileHandle,
		OUT EFI_FV_FILE_INFO2 *	FileInfo
	)

Returns information about a specific file.

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

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.

Return values

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

Definition at line 1891 of file FwVol.c.

◆ PeiFfsFvPpiGetVolumeInfo()

EFI_STATUS EFIAPI PeiFfsFvPpiGetVolumeInfo	(	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *	This,
		IN EFI_PEI_FV_HANDLE	FvHandle,
		OUT EFI_FV_INFO *	VolumeInfo
	)

This function returns information about the firmware volume.

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.

Return values

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

Definition at line 1936 of file FwVol.c.

◆ PeiFfsFvPpiProcessVolume()

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

Process a firmware volume and create a volume handle.

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_FIRMWARE_VOLUME_INFO_PPI.

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.

Return values

EFI_SUCCESS	Firmware volume handle created.
EFI_VOLUME_CORRUPTED	Volume was corrupt.

Definition at line 1641 of file FwVol.c.

◆ ThirdPartyFvPpiNotifyCallback()

EFI_STATUS EFIAPI ThirdPartyFvPpiNotifyCallback	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_PEI_NOTIFY_DESCRIPTOR *	NotifyDescriptor,
		IN VOID *	Ppi
	)

Notification callback function for EFI_PEI_FIRMWARE_VOLUME_PPI.

When a EFI_PEI_FIRMWARE_VOLUME_PPI is installed to support new FV format, this routine is called to process all discovered FVs in this format.

Parameters

PeiServices	An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation
NotifyDescriptor	Address of the notification descriptor data structure.
Ppi	Address of the PPI that was installed.

Return values

EFI_SUCCESS The notification callback is processed correctly.

Definition at line 2356 of file FwVol.c.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ GET_OCCUPIED_SIZE

◆ PEI_FW_VOL_INSTANCE_FROM_FV_THIS

◆ PEI_FW_VOL_SIGNATURE

Function Documentation

◆ AddUnknownFormatFvInfo()

◆ FindFileEx()

◆ FindUnknownFormatFvInfo()

◆ FvHandleToCoreHandle()

◆ PeiFfsFvPpiFindFileByName()

◆ PeiFfsFvPpiFindFileByType()

◆ PeiFfsFvPpiFindSectionByType()

◆ PeiFfsFvPpiFindSectionByType2()

◆ PeiFfsFvPpiGetFileInfo()

◆ PeiFfsFvPpiGetFileInfo2()

◆ PeiFfsFvPpiGetVolumeInfo()

◆ PeiFfsFvPpiProcessVolume()

◆ ThirdPartyFvPpiNotifyCallback()