Data Structures
struct	FFS_FILE_LIST_ENTRY

struct	FV_DEVICE

Macros
#define	FV2_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '2')

#define	FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)

Functions
EFI_STATUS EFIAPI	FvGetVolumeAttributes (IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL This, OUT EFI_FV_ATTRIBUTES Attributes)

EFI_STATUS EFIAPI	FvSetVolumeAttributes (IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL This, IN OUT EFI_FV_ATTRIBUTES Attributes)

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

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

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

EFI_STATUS EFIAPI	FvWriteFile (IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL This, IN UINT32 NumberOfFiles, IN EFI_FV_WRITE_POLICY WritePolicy, IN EFI_FV_WRITE_FILE_DATA FileData)

EFI_STATUS EFIAPI	FvGetVolumeInfo (IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL This, IN CONST EFI_GUID InformationType, IN OUT UINTN BufferSize, OUT VOID Buffer)

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

BOOLEAN	IsBufferErased (IN UINT8 ErasePolarity, IN VOID *InBuffer, IN UINTN BufferSize)

EFI_FFS_FILE_STATE	GetFileState (IN UINT8 ErasePolarity, IN EFI_FFS_FILE_HEADER *FfsHeader)

VOID	SetFileState (IN UINT8 State, IN EFI_FFS_FILE_HEADER *FfsHeader)

BOOLEAN	IsValidFfsHeader (IN UINT8 ErasePolarity, IN EFI_FFS_FILE_HEADER FfsHeader, OUT EFI_FFS_FILE_STATE FileState)

BOOLEAN	IsValidFfsFile (IN UINT8 ErasePolarity, IN EFI_FFS_FILE_HEADER *FfsHeader)

Detailed Description

Firmware File System protocol. Layers on top of Firmware Block protocol to produce a file abstraction of FV based files.

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

Definition in file FwVolDriver.h.

Macro Definition Documentation

◆ FV2_DEVICE_SIGNATURE

#define FV2_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '2')

Definition at line 13 of file FwVolDriver.h.

◆ FV_DEVICE_FROM_THIS

#define FV_DEVICE_FROM_THIS ( a ) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)

Definition at line 45 of file FwVolDriver.h.

Function Documentation

◆ FvGetNextFile()

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

Given the input key, search for the next matching file in the volume.

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
Key	Key is a 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 reinitialize the search and begin from the beginning of the firmware volume, the entire buffer must be cleared to zero. Other than clearing the buffer to initiate a new search, the caller must not modify the data in the buffer between calls to GetNextFile().
FileType	FileType is a pointer to a caller allocated EFI_FV_FILETYPE. The GetNextFile() API can filter it's search for files based on the value of FileType input. A FileType input of 0 causes GetNextFile() to search for files of all types. If a file is found, the file's type is returned in *FileType. FileType is not modified if no file is found.
NameGuid	NameGuid is a pointer to a caller allocated EFI_GUID. If a file is found, the file's name is returned in NameGuid. NameGuid is not modified if no file is found.
Attributes	Attributes is a pointer to a caller allocated EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's attributes are returned in Attributes. Attributes is not modified if no file is found.
Size	Size is a pointer to a caller allocated UINTN. If a file is found, the file's size is returned in Size. Size is not modified if no file is found.

Return values

EFI_SUCCESS	Successfully find the file.
EFI_DEVICE_ERROR	Device error.
EFI_ACCESS_DENIED	Fv could not read.
EFI_NOT_FOUND	No matching file found.
EFI_INVALID_PARAMETER	Invalid parameter

Given the input key, search for the next matching file in the volume.

Parameters

This	Indicates the calling context.
Key	Key is a 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 reinitialize the search and begin from the beginning of the firmware volume, the entire buffer must be cleared to zero. Other than clearing the buffer to initiate a new search, the caller must not modify the data in the buffer between calls to GetNextFile().
FileType	FileType is a pointer to a caller allocated EFI_FV_FILETYPE. The GetNextFile() API can filter it's search for files based on the value of FileType input. A FileType input of 0 causes GetNextFile() to search for files of all types. If a file is found, the file's type is returned in *FileType. FileType is not modified if no file is found.
NameGuid	NameGuid is a pointer to a caller allocated EFI_GUID. If a file is found, the file's name is returned in NameGuid. NameGuid is not modified if no file is found.
Attributes	Attributes is a pointer to a caller allocated EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's attributes are returned in Attributes. Attributes is not modified if no file is found.
Size	Size is a pointer to a caller allocated UINTN. If a file is found, the file's size is returned in Size. Size is not modified if no file is found.

Return values

EFI_SUCCESS	Successfully find the file.
EFI_DEVICE_ERROR	Device error.
EFI_ACCESS_DENIED	Fv could not read.
EFI_NOT_FOUND	No matching file found.
EFI_INVALID_PARAMETER	Invalid parameter

Definition at line 115 of file FwVolRead.c.

◆ FvGetVolumeAttributes()

EFI_STATUS EFIAPI FvGetVolumeAttributes	(	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *	This,
		OUT EFI_FV_ATTRIBUTES *	Attributes
	)

Retrieves attributes, insures positive polarity of attribute bits, returns resulting attributes in output parameter.

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
Attributes	output buffer which contains attributes.

Return values

EFI_SUCCESS Successfully got volume attributes.

Retrieves attributes, insures positive polarity of attribute bits, returns resulting attributes in output parameter.

Parameters

This	Calling context
Attributes	output buffer which contains attributes

Return values

EFI_SUCCESS Successfully got volume attributes

Definition at line 24 of file FwVolAttrib.c.

◆ FvGetVolumeInfo()

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

Return information of type InformationType for the requested firmware volume.

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
InformationType	InformationType for requested.
BufferSize	On input, size of Buffer.On output, the amount of data returned in Buffer.
Buffer	A poniter to the data buffer to return.

Return values

EFI_SUCCESS Successfully got volume Information.

Definition at line 87 of file FwVolAttrib.c.

◆ FvReadFile()

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

Locates a file in the firmware volume and copies it to the supplied buffer.

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
NameGuid	Pointer to an EFI_GUID, which is the filename.
Buffer	Buffer is a pointer to pointer to a buffer in which the file or section contents or are returned.
BufferSize	BufferSize is a pointer to caller allocated UINTN. On input BufferSize indicates the size in bytes of the memory region pointed to by Buffer. On output, BufferSize contains the number of bytes required to read the file.
FoundType	FoundType is a pointer to a caller allocated EFI_FV_FILETYPE that on successful return from Read() contains the type of file read. This output reflects the file type irrespective of the value of the SectionType input.
FileAttributes	FileAttributes is a pointer to a caller allocated EFI_FV_FILE_ATTRIBUTES. On successful return from Read(), FileAttributes contains the attributes of the file read.
AuthenticationStatus	AuthenticationStatus is a pointer to a caller allocated UINTN in which the authentication status is returned.

Return values

EFI_SUCCESS	Successfully read to memory buffer.
EFI_WARN_BUFFER_TOO_SMALL	Buffer too small.
EFI_NOT_FOUND	Not found.
EFI_DEVICE_ERROR	Device error.
EFI_ACCESS_DENIED	Could not read.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Not enough buffer to be allocated.

Locates a file in the firmware volume and copies it to the supplied buffer.

Parameters

This	Indicates the calling context.
NameGuid	Pointer to an EFI_GUID, which is the filename.
Buffer	Buffer is a pointer to pointer to a buffer in which the file or section contents or are returned.
BufferSize	BufferSize is a pointer to caller allocated UINTN. On input BufferSize indicates the size in bytes of the memory region pointed to by Buffer. On output, BufferSize contains the number of bytes required to read the file.
FoundType	FoundType is a pointer to a caller allocated EFI_FV_FILETYPE that on successful return from Read() contains the type of file read. This output reflects the file type irrespective of the value of the SectionType input.
FileAttributes	FileAttributes is a pointer to a caller allocated EFI_FV_FILE_ATTRIBUTES. On successful return from Read(), FileAttributes contains the attributes of the file read.
AuthenticationStatus	AuthenticationStatus is a pointer to a caller allocated UINTN in which the authentication status is returned.

Return values

EFI_SUCCESS	Successfully read to memory buffer.
EFI_WARN_BUFFER_TOO_SMALL	Buffer too small.
EFI_NOT_FOUND	Not found.
EFI_DEVICE_ERROR	Device error.
EFI_ACCESS_DENIED	Could not read.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Not enough buffer to be allocated.

Definition at line 268 of file FwVolRead.c.

◆ FvReadFileSection()

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

Locates a section in a given FFS File and copies it to the supplied buffer (not including section header).

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
NameGuid	Pointer to an EFI_GUID, which is the filename.
SectionType	Indicates the section type to return.
SectionInstance	Indicates which instance of sections with a type of SectionType to return.
Buffer	Buffer is a pointer to pointer to a buffer in which the file or section contents or are returned.
BufferSize	BufferSize is a pointer to caller allocated UINTN.
AuthenticationStatus	AuthenticationStatus is a pointer to a caller allocated UINT32 in which the authentication status is returned.

Return values

EFI_SUCCESS	Successfully read the file section into buffer.
EFI_WARN_BUFFER_TOO_SMALL	Buffer too small.
EFI_NOT_FOUND	Section not found.
EFI_DEVICE_ERROR	Device error.
EFI_ACCESS_DENIED	Could not read.
EFI_INVALID_PARAMETER	Invalid parameter.

Locates a section in a given FFS File and copies it to the supplied buffer (not including section header).

Parameters

This	Indicates the calling context.
NameGuid	Pointer to an EFI_GUID, which is the filename.
SectionType	Indicates the section type to return.
SectionInstance	Indicates which instance of sections with a type of SectionType to return.
Buffer	Buffer is a pointer to pointer to a buffer in which the file or section contents or are returned.
BufferSize	BufferSize is a pointer to caller allocated UINTN.
AuthenticationStatus	AuthenticationStatus is a pointer to a caller allocated UINT32 in which the authentication status is returned.

Return values

EFI_SUCCESS	Successfully read the file section into buffer.
EFI_WARN_BUFFER_TOO_SMALL	Buffer too small.
EFI_NOT_FOUND	Section not found.
EFI_DEVICE_ERROR	Device error.
EFI_ACCESS_DENIED	Could not read.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 432 of file FwVolRead.c.

◆ FvSetVolumeAttributes()

EFI_STATUS EFIAPI FvSetVolumeAttributes	(	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *	This,
		IN OUT EFI_FV_ATTRIBUTES *	Attributes
	)

Sets current attributes for volume

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
Attributes	At input, contains attributes to be set. At output contains new value of FV.

Return values

EFI_UNSUPPORTED Could not be set.

Sets current attributes for volume

Parameters

This	Calling context
Attributes	At input, contains attributes to be set. At output contains new value of FV

Return values

EFI_UNSUPPORTED Could not be set.

Definition at line 64 of file FwVolAttrib.c.

◆ FvSetVolumeInfo()

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

Set information of type InformationType for the requested firmware volume.

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
InformationType	InformationType for requested.
BufferSize	On input, size of Buffer.On output, the amount of data returned in Buffer.
Buffer	A poniter to the data buffer to return.

Return values

EFI_SUCCESS Successfully set volume Information.

Definition at line 112 of file FwVolAttrib.c.

◆ FvWriteFile()

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

Writes one or more files to the firmware volume.

Parameters

This	Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
NumberOfFiles	Number of files.
WritePolicy	WritePolicy indicates the level of reliability for the write in the event of a power failure or other system failure during the write operation.
FileData	FileData is an pointer to an array of EFI_FV_WRITE_DATA. Each element of array FileData represents a file to be written.

Return values

EFI_SUCCESS	Files successfully written to firmware volume
EFI_OUT_OF_RESOURCES	Not enough buffer to be allocated.
EFI_DEVICE_ERROR	Device error.
EFI_WRITE_PROTECTED	Write protected.
EFI_NOT_FOUND	Not found.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_UNSUPPORTED	This function not supported.

Writes one or more files to the firmware volume.

Parameters

This	Indicates the calling context.
NumberOfFiles	Number of files.
WritePolicy	WritePolicy indicates the level of reliability for the write in the event of a power failure or other system failure during the write operation.
FileData	FileData is an pointer to an array of EFI_FV_WRITE_DATA. Each element of array FileData represents a file to be written.

Return values

EFI_SUCCESS	Files successfully written to firmware volume
EFI_OUT_OF_RESOURCES	Not enough buffer to be allocated.
EFI_DEVICE_ERROR	Device error.
EFI_WRITE_PROTECTED	Write protected.
EFI_NOT_FOUND	Not found.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_UNSUPPORTED	This function not supported.

Definition at line 35 of file FwVolWrite.c.

◆ GetFileState()

EFI_FFS_FILE_STATE GetFileState	(	IN UINT8	ErasePolarity,
		IN EFI_FFS_FILE_HEADER *	FfsHeader
	)

Get the FFS file state by checking the highest bit set in the header's state field.

Parameters

ErasePolarity	Erase polarity attribute of the firmware volume
FfsHeader	Points to the FFS file header

Returns: FFS File state

Returns the highest bit set of the State field

Parameters

ErasePolarity	Erase Polarity as defined by EFI_FVB2_ERASE_POLARITY in the Attributes field.
FfsHeader	Pointer to FFS File Header

Return values

the	highest bit in the State field

Returns the file state set by the highest zero bit in the State field

Parameters

ErasePolarity	Erase Polarity as defined by EFI_FVB2_ERASE_POLARITY in the Attributes field.
FfsHeader	Pointer to FFS File Header.

Return values

EFI_FFS_FILE_STATE File state is set by the highest none zero bit in the header State field.

Returns the highest bit set of the State field

Parameters

ErasePolarity	Erase Polarity as defined by EFI_FVB_ERASE_POLARITY in the Attributes field.
FfsHeader	Pointer to FFS File Header.

Returns: the highest bit in the State field

Definition at line 44 of file DebugAgentSymbolsBaseLib.c.

◆ IsBufferErased()

BOOLEAN IsBufferErased	(	IN UINT8	ErasePolarity,
		IN VOID *	InBuffer,
		IN UINTN	BufferSize
	)

Check if a block of buffer is erased.

Parameters

ErasePolarity	Erase polarity attribute of the firmware volume
InBuffer	The buffer to be checked
BufferSize	Size of the buffer in bytes

Return values

TRUE	The block of buffer is erased
FALSE	The block of buffer is not erased

Check if a block of buffer is erased.

Parameters

[in]	ErasePolarity	Erase polarity attribute of the firmware volume
[in]	InBuffer	The buffer to be checked
[in]	BufferSize	Size of the buffer in bytes

Return values

TRUE	The block of buffer is erased
FALSE	The block of buffer is not erased

Definition at line 56 of file Ffs.c.

◆ IsValidFfsFile()

BOOLEAN IsValidFfsFile	(	IN UINT8	ErasePolarity,
		IN EFI_FFS_FILE_HEADER *	FfsHeader
	)

Check if it's a valid FFS file. Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.

Parameters

ErasePolarity	Erase polarity attribute of the firmware volume
FfsHeader	Points to the FFS file to be checked

Return values

TRUE	Valid FFS file
FALSE	Invalid FFS file

Definition at line 187 of file Ffs.c.

◆ IsValidFfsHeader()

BOOLEAN IsValidFfsHeader	(	IN UINT8	ErasePolarity,
		IN EFI_FFS_FILE_HEADER *	FfsHeader,
		OUT EFI_FFS_FILE_STATE *	FileState
	)

Check if it's a valid FFS file header.

Parameters

ErasePolarity	Erase polarity attribute of the firmware volume
FfsHeader	Points to the FFS file header to be checked
FileState	FFS file state to be returned

Return values

TRUE	Valid FFS file header
FALSE	Invalid FFS file header

Definition at line 150 of file Ffs.c.

◆ SetFileState()

VOID SetFileState	(	IN UINT8	State,
		IN EFI_FFS_FILE_HEADER *	FfsHeader
	)

Set the FFS file state.

Parameters

State	The state to be set.
FfsHeader	Points to the FFS file header

Returns: None.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ FV2_DEVICE_SIGNATURE

◆ FV_DEVICE_FROM_THIS

Function Documentation

◆ FvGetNextFile()

◆ FvGetVolumeAttributes()

◆ FvGetVolumeInfo()

◆ FvReadFile()

◆ FvReadFileSection()

◆ FvSetVolumeAttributes()

◆ FvSetVolumeInfo()

◆ FvWriteFile()

◆ GetFileState()

◆ IsBufferErased()

◆ IsValidFfsFile()

◆ IsValidFfsHeader()

◆ SetFileState()