#include "FaultTolerantWrite.h"

Functions
BOOLEAN	IsErasedFlashBuffer (IN UINT8 *Buffer, IN UINTN BufferSize)

EFI_STATUS	FtwEraseBlock (IN EFI_FTW_DEVICE FtwDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FvBlock, EFI_LBA Lba, UINTN NumberOfBlocks)

EFI_STATUS	FtwEraseSpareBlock (IN EFI_FTW_DEVICE *FtwDevice)

BOOLEAN	IsWorkingBlock (EFI_FTW_DEVICE FtwDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FvBlock, EFI_LBA Lba)

EFI_HANDLE	GetFvbByAddress (IN EFI_PHYSICAL_ADDRESS Address, OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock)

BOOLEAN	IsBootBlock (EFI_FTW_DEVICE FtwDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FvBlock)

EFI_STATUS	FlushSpareBlockToBootBlock (EFI_FTW_DEVICE *FtwDevice)

EFI_STATUS	FlushSpareBlockToTargetBlock (EFI_FTW_DEVICE FtwDevice, EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FvBlock, EFI_LBA Lba, UINTN BlockSize, UINTN NumberOfBlocks)

EFI_STATUS	FlushSpareBlockToWorkingBlock (EFI_FTW_DEVICE *FtwDevice)

EFI_STATUS	FtwUpdateFvState (IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock, IN UINTN BlockSize, IN EFI_LBA Lba, IN UINTN Offset, IN UINT8 NewBit)

EFI_STATUS	FtwGetLastWriteHeader (IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER FtwWorkSpaceHeader, IN UINTN FtwWorkSpaceSize, OUT EFI_FAULT_TOLERANT_WRITE_HEADER *FtwWriteHeader)

EFI_STATUS	FtwGetLastWriteRecord (IN EFI_FAULT_TOLERANT_WRITE_HEADER FtwWriteHeader, OUT EFI_FAULT_TOLERANT_WRITE_RECORD *FtwWriteRecord)

BOOLEAN	IsFirstRecordOfWrites (IN EFI_FAULT_TOLERANT_WRITE_HEADER FtwHeader, IN EFI_FAULT_TOLERANT_WRITE_RECORD FtwRecord)

BOOLEAN	IsLastRecordOfWrites (IN EFI_FAULT_TOLERANT_WRITE_HEADER FtwHeader, IN EFI_FAULT_TOLERANT_WRITE_RECORD FtwRecord)

EFI_STATUS	GetPreviousRecordOfWrites (IN EFI_FAULT_TOLERANT_WRITE_HEADER FtwHeader, IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD *FtwRecord)

EFI_STATUS	InitFtwDevice (OUT EFI_FTW_DEVICE **FtwData)

EFI_STATUS	FindFvbForFtw (IN OUT EFI_FTW_DEVICE *FtwDevice)

EFI_STATUS	InitFtwProtocol (IN OUT EFI_FTW_DEVICE *FtwDevice)

Detailed Description

Internal generic functions to operate flash block.

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

Definition in file FtwMisc.c.

Function Documentation

◆ FindFvbForFtw()

EFI_STATUS FindFvbForFtw ( IN OUT EFI_FTW_DEVICE * FtwDevice )

Find the proper Firmware Volume Block protocol for FTW operation.

Parameters

[in,out] FtwDevice Pointer to the FTW device structure

Return values

EFI_SUCCESS	Find the FVB protocol successfully.
EFI_NOT_FOUND	No proper FVB protocol was found.
EFI_ABORTED	Some data can not be got or be invalid.

Definition at line 1060 of file FtwMisc.c.

◆ FlushSpareBlockToBootBlock()

EFI_STATUS FlushSpareBlockToBootBlock ( EFI_FTW_DEVICE * FtwDevice )

Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE. Spare block is accessed by FTW working FVB protocol interface. Target block is accessed by FvBlock protocol interface.

FTW will do extra work on boot block update. FTW should depend on a protocol of EFI_ADDRESS_RANGE_SWAP_PROTOCOL, which is produced by a chipset driver. FTW updating boot block steps may be:

GetRangeLocation(), if the Range is inside the boot block, FTW know that boot block will be update. It shall add a FLAG in the working block.
When spare block is ready,
SetSwapState(SWAPPED)
erasing boot block,
programming boot block until the boot block is ok.
SetSwapState(UNSWAPPED) FTW shall not allow to update boot block when battery state is error.

Parameters

FtwDevice The private data of FTW driver

Return values

EFI_SUCCESS	Spare block content is copied to boot block
EFI_INVALID_PARAMETER	Input parameter error
EFI_OUT_OF_RESOURCES	Allocate memory error
EFI_ABORTED	The function could not complete successfully

Definition at line 309 of file FtwMisc.c.

◆ FlushSpareBlockToTargetBlock()

EFI_STATUS FlushSpareBlockToTargetBlock	(	EFI_FTW_DEVICE *	FtwDevice,
		EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	FvBlock,
		EFI_LBA	Lba,
		UINTN	BlockSize,
		UINTN	NumberOfBlocks
	)

Copy the content of spare block to a target block. Spare block is accessed by FTW backup FVB protocol interface. Target block is accessed by FvBlock protocol interface.

Parameters

FtwDevice	The private data of FTW driver
FvBlock	FVB Protocol interface to access target block
Lba	Lba of the target block
BlockSize	The size of the block
NumberOfBlocks	The number of consecutive blocks starting with Lba

Return values

EFI_SUCCESS	Spare block content is copied to target block
EFI_INVALID_PARAMETER	Input parameter error
EFI_OUT_OF_RESOURCES	Allocate memory error
EFI_ABORTED	The function could not complete successfully

Definition at line 478 of file FtwMisc.c.

◆ FlushSpareBlockToWorkingBlock()

EFI_STATUS FlushSpareBlockToWorkingBlock ( EFI_FTW_DEVICE * FtwDevice )

Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE. Spare block is accessed by FTW backup FVB protocol interface. LBA is FtwDevice->FtwSpareLba. Working block is accessed by FTW working FVB protocol interface. LBA is FtwDevice->FtwWorkBlockLba.

Since the working block header is important when FTW initializes, the state of the operation should be handled carefully. The Crc value is calculated without STATE element.

Parameters

FtwDevice The private data of FTW driver

Return values

EFI_SUCCESS	Spare block content is copied to target block
EFI_OUT_OF_RESOURCES	Allocate memory error
EFI_ABORTED	The function could not complete successfully

Definition at line 576 of file FtwMisc.c.

◆ FtwEraseBlock()

EFI_STATUS FtwEraseBlock	(	IN EFI_FTW_DEVICE *	FtwDevice,
		EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	FvBlock,
		EFI_LBA	Lba,
		UINTN	NumberOfBlocks
	)

To erase the block with specified blocks.

Parameters

FtwDevice	The private data of FTW driver
FvBlock	FVB Protocol interface
Lba	Lba of the firmware block
NumberOfBlocks	The number of consecutive blocks starting with Lba

Return values

EFI_SUCCESS	Block LBA is Erased successfully
Others	Error occurs

Definition at line 58 of file FtwMisc.c.

◆ FtwEraseSpareBlock()

EFI_STATUS FtwEraseSpareBlock ( IN EFI_FTW_DEVICE * FtwDevice )

Erase spare block.

Parameters

FtwDevice The private data of FTW driver

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.

Definition at line 91 of file FtwMisc.c.

◆ FtwGetLastWriteHeader()

EFI_STATUS FtwGetLastWriteHeader	(	IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *	FtwWorkSpaceHeader,
		IN UINTN	FtwWorkSpaceSize,
		OUT EFI_FAULT_TOLERANT_WRITE_HEADER **	FtwWriteHeader
	)

Get the last Write Header pointer. The last write header is the header whose 'complete' state hasn't been set. After all, this header may be a EMPTY header entry for next Allocate.

Parameters

FtwWorkSpaceHeader	Pointer of the working block header
FtwWorkSpaceSize	Size of the work space
FtwWriteHeader	Pointer to retrieve the last write header

Return values

EFI_SUCCESS	Get the last write record successfully
EFI_ABORTED	The FTW work space is damaged

Definition at line 800 of file FtwMisc.c.

◆ FtwGetLastWriteRecord()

EFI_STATUS FtwGetLastWriteRecord	(	IN EFI_FAULT_TOLERANT_WRITE_HEADER *	FtwWriteHeader,
		OUT EFI_FAULT_TOLERANT_WRITE_RECORD **	FtwWriteRecord
	)

Get the last Write Record pointer. The last write Record is the Record whose DestinationCompleted state hasn't been set. After all, this Record may be a EMPTY record entry for next write.

Parameters

FtwWriteHeader	Pointer to the write record header
FtwWriteRecord	Pointer to retrieve the last write record

Return values

EFI_SUCCESS	Get the last write record successfully
EFI_ABORTED	The FTW work space is damaged

Definition at line 854 of file FtwMisc.c.

◆ FtwUpdateFvState()

EFI_STATUS FtwUpdateFvState	(	IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	FvBlock,
		IN UINTN	BlockSize,
		IN EFI_LBA	Lba,
		IN UINTN	Offset,
		IN UINT8	NewBit
	)

Update a bit of state on a block device. The location of the bit is calculated by the (Lba, Offset, bit). Here bit is determined by the the name of a certain bit.

Parameters

FvBlock	FVB Protocol interface to access SrcBlock and DestBlock
BlockSize	The size of the block
Lba	Lba of a block
Offset	Offset on the Lba
NewBit	New value that will override the old value if it can be change

Return values

EFI_SUCCESS	A state bit has been updated successfully
Others	Access block device error. Notes: Assume all bits of State are inside the same BYTE.
EFI_ABORTED	Read block fail

Definition at line 743 of file FtwMisc.c.

◆ GetFvbByAddress()

EFI_HANDLE GetFvbByAddress	(	IN EFI_PHYSICAL_ADDRESS	Address,
		OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **	FvBlock
	)

Get firmware volume block by address.

Parameters

Address	Address specified the block
FvBlock	The block caller wanted

Return values

EFI_SUCCESS	The protocol instance if found.
EFI_NOT_FOUND	Block not found

Definition at line 147 of file FtwMisc.c.

◆ GetPreviousRecordOfWrites()

EFI_STATUS GetPreviousRecordOfWrites	(	IN EFI_FAULT_TOLERANT_WRITE_HEADER *	FtwHeader,
		IN OUT EFI_FAULT_TOLERANT_WRITE_RECORD **	FtwRecord
	)

To check if FtwRecord is the first record of FtwHeader.

Parameters

FtwHeader	Pointer to the write record header
FtwRecord	Pointer to retrieve the previous write record

Return values

EFI_ACCESS_DENIED	Input record is the first record, no previous record is return.
EFI_SUCCESS	The previous write record is found.

Definition at line 963 of file FtwMisc.c.

◆ InitFtwDevice()

EFI_STATUS InitFtwDevice ( OUT EFI_FTW_DEVICE ** FtwData )

Allocate private data for FTW driver and initialize it.

Parameters

[out] FtwData Pointer to the FTW device structure

Return values

EFI_SUCCESS	Initialize the FTW device successfully.
EFI_OUT_OF_RESOURCES	Allocate memory error
EFI_INVALID_PARAMETER	Workspace or Spare block does not exist

Definition at line 992 of file FtwMisc.c.

◆ InitFtwProtocol()

EFI_STATUS InitFtwProtocol ( IN OUT EFI_FTW_DEVICE * FtwDevice )

Initialization for Fault Tolerant Write protocol.

Parameters

[in,out] FtwDevice Pointer to the FTW device structure

Return values

EFI_SUCCESS	Initialize the FTW protocol successfully.
EFI_NOT_FOUND	No proper FVB protocol was found.

Definition at line 1236 of file FtwMisc.c.

◆ IsBootBlock()

BOOLEAN IsBootBlock	(	EFI_FTW_DEVICE *	FtwDevice,
		EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	FvBlock
	)

Is it in boot block?

Parameters

FtwDevice	The private data of FTW driver
FvBlock	Fvb protocol instance

Returns: A BOOLEAN value indicating in boot block or not.

Definition at line 220 of file FtwMisc.c.

◆ IsErasedFlashBuffer()

BOOLEAN IsErasedFlashBuffer	(	IN UINT8 *	Buffer,
		IN UINTN	BufferSize
	)

Check whether a flash buffer is erased.

Parameters

Buffer	Buffer to check
BufferSize	Size of the buffer

Returns: A BOOLEAN value indicating erased or not.

Definition at line 23 of file FtwMisc.c.

◆ IsFirstRecordOfWrites()

BOOLEAN IsFirstRecordOfWrites	(	IN EFI_FAULT_TOLERANT_WRITE_HEADER *	FtwHeader,
		IN EFI_FAULT_TOLERANT_WRITE_RECORD *	FtwRecord
	)

To check if FtwRecord is the first record of FtwHeader.

Parameters

FtwHeader	Pointer to the write record header
FtwRecord	Pointer to the write record

Return values

TRUE	FtwRecord is the first Record of the FtwHeader
FALSE	FtwRecord is not the first Record of the FtwHeader

Definition at line 909 of file FtwMisc.c.

◆ IsLastRecordOfWrites()

BOOLEAN IsLastRecordOfWrites	(	IN EFI_FAULT_TOLERANT_WRITE_HEADER *	FtwHeader,
		IN EFI_FAULT_TOLERANT_WRITE_RECORD *	FtwRecord
	)

To check if FtwRecord is the last record of FtwHeader. Because the FtwHeader has NumberOfWrites & PrivateDataSize, the FtwRecord can be determined if it is the last record of FtwHeader.

Parameters

FtwHeader	Pointer to the write record header
FtwRecord	Pointer to the write record

Return values

TRUE	FtwRecord is the last Record of the FtwHeader
FALSE	FtwRecord is not the last Record of the FtwHeader

Definition at line 937 of file FtwMisc.c.

◆ IsWorkingBlock()

BOOLEAN IsWorkingBlock	(	EFI_FTW_DEVICE *	FtwDevice,
		EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *	FvBlock,
		EFI_LBA	Lba
	)

Is it in working block?

Parameters

FtwDevice	The private data of FTW driver
FvBlock	Fvb protocol instance
Lba	The block specified

Returns: A BOOLEAN value indicating in working block or not.

Definition at line 115 of file FtwMisc.c.

Functions

Detailed Description

Function Documentation

◆ FindFvbForFtw()

◆ FlushSpareBlockToBootBlock()

◆ FlushSpareBlockToTargetBlock()

◆ FlushSpareBlockToWorkingBlock()

◆ FtwEraseBlock()

◆ FtwEraseSpareBlock()

◆ FtwGetLastWriteHeader()

◆ FtwGetLastWriteRecord()

◆ FtwUpdateFvState()

◆ GetFvbByAddress()

◆ GetPreviousRecordOfWrites()

◆ InitFtwDevice()

◆ InitFtwProtocol()

◆ IsBootBlock()

◆ IsErasedFlashBuffer()

◆ IsFirstRecordOfWrites()

◆ IsLastRecordOfWrites()

◆ IsWorkingBlock()