#include <Guid/EventGroup.h>
#include <Guid/FirmwareFileSystem2.h>
#include <Guid/SystemNvDataGuid.h>
#include <Guid/VariableFormat.h>
#include <Protocol/DevicePath.h>
#include <Protocol/FirmwareVolumeBlock.h>
#include <Library/UefiDriverEntryPoint.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiLib.h>
#include <Library/BaseLib.h>
#include <Library/DebugLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/IoLib.h>
#include <Library/CacheMaintenanceLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/PcdLib.h>
#include <Library/FlashDeviceLib.h>
#include <Library/DevicePathLib.h>
#include <Library/HobLib.h>
#include <Library/DxeServicesLib.h>
#include <Guid/NvVariableInfoGuid.h>
#include <Register/ArchitecturalMsr.h>

Data Structures
struct	EFI_FW_VOL_INSTANCE

struct	FWB_GLOBAL

struct	FV_PIWG_DEVICE_PATH

struct	FV_MEMMAP_DEVICE_PATH

struct	EFI_FW_VOL_BLOCK_DEVICE

Macros
#define	EFI_FVB2_CAPABILITIES

#define	EFI_FVB2_STATUS (EFI_FVB2_READ_STATUS \| EFI_FVB2_WRITE_STATUS \| EFI_FVB2_LOCK_STATUS)

#define	FVB_DEVICE_FROM_THIS(a) CR(a, EFI_FW_VOL_BLOCK_DEVICE, FwVolBlockInstance, FVB_DEVICE_SIGNATURE)

#define	FVB_EXTEND_DEVICE_FROM_THIS(a) CR(a, EFI_FW_VOL_BLOCK_DEVICE, FvbExtension, FVB_DEVICE_SIGNATURE)

#define	FVB_DEVICE_SIGNATURE SIGNATURE_32('F','V','B','C')

Functions
EFI_FIRMWARE_VOLUME_HEADER *	GetFvHeaderTemplate (VOID)

EFI_STATUS	InitVariableStore (VOID)

EFI_STATUS EFIAPI	FvbProtocolGetAttributes (IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL This, OUT EFI_FVB_ATTRIBUTES_2 Attributes)

EFI_STATUS EFIAPI	FvbProtocolSetAttributes (IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL This, IN OUT EFI_FVB_ATTRIBUTES_2 Attributes)

EFI_STATUS EFIAPI	FvbProtocolGetPhysicalAddress (IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL This, OUT EFI_PHYSICAL_ADDRESS Address)

EFI_STATUS EFIAPI	FvbProtocolGetBlockSize (IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL This, IN EFI_LBA Lba, OUT UINTN BlockSize, OUT UINTN *NumOfBlocks)

EFI_STATUS EFIAPI	FvbProtocolRead (IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL This, IN EFI_LBA Lba, IN UINTN Offset, IN OUT UINTN NumBytes, OUT UINT8 *Buffer)

EFI_STATUS EFIAPI	FvbProtocolWrite (IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL This, IN EFI_LBA Lba, IN UINTN Offset, IN OUT UINTN NumBytes, IN UINT8 *Buffer)

EFI_STATUS EFIAPI	FvbProtocolEraseBlocks (IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,...)

EFI_FW_VOL_INSTANCE *	GetFvbInstance (IN UINTN Instance)

EFI_STATUS	InstallFvbProtocol (IN EFI_FW_VOL_INSTANCE *FwhInstance, IN UINTN InstanceNum)

EFI_STATUS	FvbInitialize (VOID)

Variables
FWB_GLOBAL	mFvbModuleGlobal

EFI_FW_VOL_BLOCK_DEVICE	mFvbDeviceTemplate

FV_MEMMAP_DEVICE_PATH	mFvMemmapDevicePathTemplate

FV_PIWG_DEVICE_PATH	mFvPIWGDevicePathTemplate

Detailed Description

The header file for Firmware volume block driver.

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

Definition in file FvbService.h.

Macro Definition Documentation

◆ EFI_FVB2_CAPABILITIES

#define EFI_FVB2_CAPABILITIES

Value:

                              (EFI_FVB2_READ_DISABLED_CAP |\
                              EFI_FVB2_READ_ENABLED_CAP | \
                              EFI_FVB2_WRITE_DISABLED_CAP | \
                              EFI_FVB2_WRITE_ENABLED_CAP | \
                              EFI_FVB2_LOCK_CAP \
                              )

Definition at line 39 of file FvbService.h.

◆ EFI_FVB2_STATUS

#define EFI_FVB2_STATUS (EFI_FVB2_READ_STATUS | EFI_FVB2_WRITE_STATUS | EFI_FVB2_LOCK_STATUS)

Definition at line 46 of file FvbService.h.

◆ FVB_DEVICE_FROM_THIS

#define FVB_DEVICE_FROM_THIS ( a ) CR(a, EFI_FW_VOL_BLOCK_DEVICE, FwVolBlockInstance, FVB_DEVICE_SIGNATURE)

Definition at line 67 of file FvbService.h.

◆ FVB_DEVICE_SIGNATURE

#define FVB_DEVICE_SIGNATURE SIGNATURE_32('F','V','B','C')

Definition at line 69 of file FvbService.h.

◆ FVB_EXTEND_DEVICE_FROM_THIS

#define FVB_EXTEND_DEVICE_FROM_THIS ( a ) CR(a, EFI_FW_VOL_BLOCK_DEVICE, FvbExtension, FVB_DEVICE_SIGNATURE)

Definition at line 68 of file FvbService.h.

Function Documentation

◆ FvbInitialize()

EFI_STATUS FvbInitialize ( VOID )

The function does the necessary initialization work for Firmware Volume Block Driver.

Return values

EFI_SUCCESS This funtion always return EFI_SUCCESS. It will ASSERT on errors.

Definition at line 996 of file FvbService.c.

◆ FvbProtocolEraseBlocks()

EFI_STATUS EFIAPI FvbProtocolEraseBlocks	(	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	This,
			...
	)

Erases and initializes a firmware volume block.

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.

Parameters

This	Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
...	The variable argument list is a list of tuples. Each tuple describes a range of LBAs to erase and consists of the following: An EFI_LBA that indicates the starting LBA A UINTN that indicates the number of blocks to erase

The list is terminated with an EFI_LBA_LIST_TERMINATOR. 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);

Return values

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

This function erases one or more blocks as denoted by the variable argument list. The entire parameter list of blocks must be verified prior to 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 EraseBlock() function must return EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.

Parameters

[in]	This	Calling context
[in]	...	Starting LBA followed by Number of Lba to erase. a -1 to terminate the list.

Return values

EFI_SUCCESS	The erase request was successfully completed
EFI_ACCESS_DENIED	The firmware volume is in the WriteDisabled state
EFI_DEVICE_ERROR	The block device is not functioning correctly and could not be written. Firmware device may have been partially erased

Definition at line 873 of file FWBlockService.c.

◆ FvbProtocolGetAttributes()

EFI_STATUS EFIAPI FvbProtocolGetAttributes	(	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	This,
		OUT EFI_FVB_ATTRIBUTES_2 *	Attributes
	)

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

Parameters

This	Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
Attributes	Pointer to EFI_FVB_ATTRIBUTES_2 in which the attributes and current settings are returned. Type EFI_FVB_ATTRIBUTES_2 is defined in EFI_FIRMWARE_VOLUME_HEADER.

Return values

EFI_SUCCESS The firmware volume attributes were returned.

Retrieves Volume attributes. No polarity translations are done.

Parameters

[in]	This	Calling context
[out]	Attributes	Output buffer which contains attributes

Return values

EFI_SUCCESS The function always return successfully.

Definition at line 817 of file FWBlockService.c.

◆ FvbProtocolGetBlockSize()

EFI_STATUS EFIAPI FvbProtocolGetBlockSize	(	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	This,
		IN EFI_LBA	Lba,
		OUT UINTN *	BlockSize,
		OUT UINTN *	NumOfBlocks
	)

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

Parameters

This	Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
Lba	Indicates the block for which to return the size.
BlockSize	Pointer to a caller-allocated UINTN in which the size of the block is returned.
NumberOfBlocks	Pointer to a caller-allocated UINTN in which the number of consecutive blocks, starting with Lba, is returned. All blocks in this range have a size of BlockSize.

Return values

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

Retrieve the size of a logical block

Parameters

[in]	This	Calling context
[in]	Lba	Indicates which block to return the size for.
[out]	BlockSize	A pointer to a caller allocated UINTN in which the size of the block is returned
[out]	NumOfBlocks	A pointer to a caller allocated UINTN in which the number of consecutive blocks starting with Lba is returned. All blocks in this range have a size of BlockSize

Return values

EFI_SUCCESS The function always return successfully.

Definition at line 772 of file FWBlockService.c.

◆ FvbProtocolGetPhysicalAddress()

EFI_STATUS EFIAPI FvbProtocolGetPhysicalAddress	(	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	This,
		OUT EFI_PHYSICAL_ADDRESS *	Address
	)

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

Parameters

This	Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
Address	Pointer to a caller-allocated EFI_PHYSICAL_ADDRESS that, on successful return from GetPhysicalAddress(), contains the base address of the firmware volume.

Return values

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

Retrieves the physical address of the device.

Parameters

[in]	This	A pointer to EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL.
[out]	Address	Output buffer containing the address.

Return values

EFI_SUCCESS	The function always return successfully.
EFI_INVALID_PARAMETER	Instance not found.

Definition at line 740 of file FWBlockService.c.

◆ FvbProtocolRead()

EFI_STATUS EFIAPI FvbProtocolRead	(	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	This,
		IN EFI_LBA	Lba,
		IN UINTN	Offset,
		IN OUT UINTN *	NumBytes,
		OUT UINT8 *	Buffer
	)

Reads data beginning at Lba:Offset from FV. The Read terminates either when *NumBytes of data have been read, or when a block boundary is reached. *NumBytes is updated to reflect the actual number of bytes written. The write opertion does not include erase. This routine will attempt to write only the specified bytes. If the writes do not stick, it will return an error.

Parameters

[in]	This	Calling context
[in]	Lba	Block in which to begin write
[in]	Offset	Offset in the block at which to begin write
[in,out]	NumBytes	On input, indicates the requested write size. On output, indicates the actual number of bytes written
[out]	Buffer	Buffer containing source data for the write.

Returns:

Return values

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

Definition at line 858 of file FvbService.c.

◆ FvbProtocolSetAttributes()

EFI_STATUS EFIAPI FvbProtocolSetAttributes	(	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	This,
		IN OUT EFI_FVB_ATTRIBUTES_2 *	Attributes
	)

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

Parameters

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

Return values

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.

Sets Volume attributes. No polarity translations are done.

Parameters

[in]	This	Calling context
[in,out]	Attributes	Output buffer which contains attributes

Return values

EFI_SUCCESS The function always return successfully.

Definition at line 845 of file FWBlockService.c.

◆ FvbProtocolWrite()

EFI_STATUS EFIAPI FvbProtocolWrite	(	IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	This,
		IN EFI_LBA	Lba,
		IN UINTN	Offset,
		IN OUT UINTN *	NumBytes,
		IN UINT8 *	Buffer
	)

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

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

Parameters

This	Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance.
Lba	The starting logical block index to write to.
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.

Return values

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

Writes data beginning at Lba:Offset from FV. The write terminates either when *NumBytes of data have been written, or when a block boundary is reached. *NumBytes is updated to reflect the actual number of bytes written. The write opertion does not include erase. This routine will attempt to write only the specified bytes. If the writes do not stick, it will return an error.

Parameters

[in]	This	Calling context
[in]	Lba	Block in which to begin write
[in]	Offset	Offset in the block at which to begin write
[in,out]	NumBytes	On input, indicates the requested write size. On output, indicates the actual number of bytes written
[in]	Buffer	Buffer containing source data for the write.

Return values

EFI_SUCCESS	The firmware volume was written successfully
EFI_BAD_BUFFER_SIZE	Write attempted across a LBA boundary. On output, NumBytes contains the total number of bytes actually written
EFI_ACCESS_DENIED	The firmware volume is in the WriteDisabled state
EFI_DEVICE_ERROR	The block device is not functioning correctly and could not be written
EFI_INVALID_PARAMETER	NumBytes or Buffer are NULL

Definition at line 967 of file FWBlockService.c.

◆ GetFvbInstance()

EFI_FW_VOL_INSTANCE * GetFvbInstance ( IN UINTN Instance )

Get the pointer to EFI_FW_VOL_INSTANCE from the buffer pointed by mFvbModuleGlobal.FvInstance based on a index. Each EFI_FW_VOL_INSTANCE is with variable length as we have a block map at the end of the EFI_FIRMWARE_VOLUME_HEADER.

Parameters

[in] Instance The index of the EFI_FW_VOL_INSTANCE.

Returns: A pointer to EFI_FW_VOL_INSTANCE.

Definition at line 91 of file FvbService.c.

◆ GetFvHeaderTemplate()

EFI_FIRMWARE_VOLUME_HEADER * GetFvHeaderTemplate ( VOID )

Get a heathy FV header used for variable store recovery

Return values

The	FV header.

Definition at line 136 of file FvbInfo.c.

◆ InitVariableStore()

EFI_STATUS InitVariableStore ( VOID )

Initialize the variable store

Return values

EFI_SUCCESS if initialize the store success.

Definition at line 63 of file FvbInfo.c.

◆ InstallFvbProtocol()

EFI_STATUS InstallFvbProtocol	(	IN EFI_FW_VOL_INSTANCE *	FwhInstance,
		IN UINTN	InstanceNum
	)

The function installs EFI_SMM_FIRMWARE_VOLUME_BLOCK protocol for each FV in the system.

Parameters

[in]	FwhInstance	The pointer to a FW volume instance structure, which contains the information about one FV.
[in]	InstanceNum	The instance number which can be used as a ID to locate this FwhInstance in other functions.

Return values

EFI_SUCESS	Installed successfully.
Else	Did not install successfully.

Definition at line 28 of file FvbServiceSmm.c.

Variable Documentation

◆ mFvbDeviceTemplate

EFI_FW_VOL_BLOCK_DEVICE mFvbDeviceTemplate

extern

Definition at line 32 of file FWBlockService.c.

◆ mFvbModuleGlobal

FWB_GLOBAL mFvbModuleGlobal

extern

Definition at line 28 of file FWBlockService.c.

◆ mFvMemmapDevicePathTemplate

FV_MEMMAP_DEVICE_PATH mFvMemmapDevicePathTemplate

extern

Definition at line 15 of file FwVolBlock.c.

◆ mFvPIWGDevicePathTemplate

FV_PIWG_DEVICE_PATH mFvPIWGDevicePathTemplate

extern

Definition at line 39 of file FwVolBlock.c.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ EFI_FVB2_CAPABILITIES

◆ EFI_FVB2_STATUS

◆ FVB_DEVICE_FROM_THIS

◆ FVB_DEVICE_SIGNATURE

◆ FVB_EXTEND_DEVICE_FROM_THIS

Function Documentation

◆ FvbInitialize()

◆ FvbProtocolEraseBlocks()

◆ FvbProtocolGetAttributes()

◆ FvbProtocolGetBlockSize()

◆ FvbProtocolGetPhysicalAddress()

◆ FvbProtocolRead()

◆ FvbProtocolSetAttributes()

◆ FvbProtocolWrite()

◆ GetFvbInstance()

◆ GetFvHeaderTemplate()

◆ InitVariableStore()

◆ InstallFvbProtocol()

Variable Documentation

◆ mFvbDeviceTemplate

◆ mFvbModuleGlobal

◆ mFvMemmapDevicePathTemplate

◆ mFvPIWGDevicePathTemplate