#include <Uefi.h>
#include <PiPei.h>
#include <Ppi/MasterBootMode.h>
#include <Ppi/BootInRecoveryMode.h>
#include <Ppi/RecoveryModule.h>
#include <Ppi/DeviceRecoveryModule.h>
#include <Ppi/FirmwareVolumeInfo.h>
#include <Guid/FirmwareFileSystem2.h>
#include <Guid/FmpCapsule.h>
#include <Guid/EdkiiSystemFmpCapsule.h>
#include <Library/DebugLib.h>
#include <Library/PeimEntryPoint.h>
#include <Library/PeiServicesLib.h>
#include <Library/HobLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/PcdLib.h>
#include "RecoveryModuleLoadPei.h"

Functions
EFI_STATUS EFIAPI	LoadRecoveryCapsule (IN EFI_PEI_SERVICES *PeiServices, IN EFI_PEI_RECOVERY_MODULE_PPI This)

EFI_STATUS	ParseRecoveryDataFile (IN UINT8 DataBuffer, IN UINTN BufferSize, IN OUT CONFIG_HEADER ConfigHeader, IN OUT RECOVERY_CONFIG_DATA **RecoveryArray)

BOOLEAN	IsSystemFmpImage (IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER *FmpImageHeader)

BOOLEAN	IsFmpCapsuleGuid (IN EFI_GUID *CapsuleGuid)

BOOLEAN	IsSystemFmpCapsuleImage (IN EFI_CAPSULE_HEADER *CapsuleHeader)

BOOLEAN	IsValidCapsuleHeader (IN EFI_CAPSULE_HEADER *CapsuleHeader, IN UINT64 CapsuleSize)

EFI_STATUS	ValidateFmpCapsule (IN EFI_CAPSULE_HEADER CapsuleHeader, OUT BOOLEAN IsSystemFmp OPTIONAL, OUT UINT16 *EmbeddedDriverCount OPTIONAL)

EFI_STATUS EFIAPI	InitializeRecoveryModule (IN EFI_PEI_FILE_HANDLE FileHandle, IN CONST EFI_PEI_SERVICES **PeiServices)

EFI_STATUS EFIAPI	CreateHobForRecoveryCapsule (IN VOID *FvImage, IN UINTN FvImageSize)

EFI_STATUS	RecoverImage (IN VOID SystemFirmwareImage, IN UINTN SystemFirmwareImageSize, IN VOID ConfigImage, IN UINTN ConfigImageSize)

EFI_STATUS	ProcessRecoveryImage (IN VOID *Image, IN UINTN Length)

EFI_STATUS	ProcessFmpCapsuleImage (IN EFI_CAPSULE_HEADER *CapsuleHeader, IN BOOLEAN IsSystemFmp)

EFI_STATUS EFIAPI	ProcessRecoveryCapsule (IN VOID *CapsuleBuffer, IN UINTN CapsuleSize)

Variables
EFI_PEI_RECOVERY_MODULE_PPI	mRecoveryPpi

EFI_PEI_PPI_DESCRIPTOR	mRecoveryPpiList

Detailed Description

Recovery module.

Caution: This module requires additional review when modified. This module will have external input - capsule image. This external input must be validated carefully to avoid security issue like buffer overflow, integer overflow.

ProcessRecoveryCapsule(), ProcessFmpCapsuleImage(), ProcessRecoveryImage(), ValidateFmpCapsule() will receive untrusted input and do basic validation.

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

Definition in file RecoveryModuleLoadPei.c.

Function Documentation

◆ CreateHobForRecoveryCapsule()

EFI_STATUS EFIAPI CreateHobForRecoveryCapsule	(	IN VOID *	FvImage,
		IN UINTN	FvImageSize
	)

Create hob and install FvInfo PPI for recovery capsule.

Parameters

[in]	FvImage	Points to the DXE FV image.
[in]	FvImageSize	The length of the DXE FV image in bytes.

Return values

EFI_SUCCESS	Create hob and install FvInfo PPI successfully.
EFI_VOLUME_CORRUPTED	The input data is not an FV.
EFI_OUT_OF_RESOURCES	No enough resource to process the input data.

Definition at line 424 of file RecoveryModuleLoadPei.c.

◆ InitializeRecoveryModule()

EFI_STATUS EFIAPI InitializeRecoveryModule	(	IN EFI_PEI_FILE_HANDLE	FileHandle,
		IN CONST EFI_PEI_SERVICES **	PeiServices
	)

Recovery module entrypoint

Parameters

[in]	FileHandle	Handle of the file being invoked.
[in]	PeiServices	Describes the list of possible PEI Services.

Returns: EFI_SUCCESS Recovery module is initialized.

Definition at line 395 of file RecoveryModuleLoadPei.c.

◆ IsFmpCapsuleGuid()

BOOLEAN IsFmpCapsuleGuid ( IN EFI_GUID * CapsuleGuid )

Return if this CapsuleGuid is a FMP capsule GUID or not.

Parameters

[in] CapsuleGuid A pointer to EFI_GUID

Returns: TRUE It is a FMP capsule GUID.; FALSE It is not a FMP capsule GUID.

Definition at line 135 of file RecoveryModuleLoadPei.c.

◆ IsSystemFmpCapsuleImage()

BOOLEAN IsSystemFmpCapsuleImage ( IN EFI_CAPSULE_HEADER * CapsuleHeader )

This function assumes the input Capsule image already passes basic check in ValidateFmpCapsule().

Criteria of system FMP capsule is: 1) FmpCapsuleHeader->EmbeddedDriverCount is 0. 2) FmpCapsuleHeader->PayloadItemCount is not 0. 3) All ImageHeader->UpdateImageTypeId matches PcdSystemFmpCapsuleImageTypeIdGuid.

Parameters

[in] CapsuleHeader Points to a capsule header.

Return values

TRUE	Input capsule is a correct system FMP capsule.
FALSE	Input capsule is not a correct system FMP capsule.

Definition at line 161 of file RecoveryModuleLoadPei.c.

◆ IsSystemFmpImage()

BOOLEAN IsSystemFmpImage ( IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER * FmpImageHeader )

Return if this FMP is a system FMP or a device FMP, based upon FmpImageInfo.

Parameters

[in] FmpImageHeader A pointer to EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER

Returns: TRUE It is a system FMP.; FALSE It is a device FMP.

Definition at line 106 of file RecoveryModuleLoadPei.c.

◆ IsValidCapsuleHeader()

BOOLEAN IsValidCapsuleHeader	(	IN EFI_CAPSULE_HEADER *	CapsuleHeader,
		IN UINT64	CapsuleSize
	)

Validate if it is valid capsule header

This function assumes the caller provided correct CapsuleHeader pointer and CapsuleSize.

This function validates the fields in EFI_CAPSULE_HEADER.

Parameters

[in]	CapsuleHeader	Points to a capsule header.
[in]	CapsuleSize	Size of the whole capsule image.

Definition at line 208 of file RecoveryModuleLoadPei.c.

◆ LoadRecoveryCapsule()

EFI_STATUS EFIAPI LoadRecoveryCapsule	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_PEI_RECOVERY_MODULE_PPI *	This
	)

Loads a DXE capsule from some media into memory and updates the HOB table with the DXE firmware volume information.

Parameters

[in]	PeiServices	General-purpose services that are available to every PEIM.
[in]	This	Indicates the EFI_PEI_RECOVERY_MODULE_PPI instance.

Return values

EFI_SUCCESS	The capsule was loaded correctly.
EFI_DEVICE_ERROR	A device error occurred.
EFI_NOT_FOUND	A recovery DXE capsule cannot be found.

Definition at line 753 of file RecoveryModuleLoadPei.c.

◆ ParseRecoveryDataFile()

EFI_STATUS ParseRecoveryDataFile	(	IN UINT8 *	DataBuffer,
		IN UINTN	BufferSize,
		IN OUT CONFIG_HEADER *	ConfigHeader,
		IN OUT RECOVERY_CONFIG_DATA **	RecoveryArray
	)

Parse Config data file to get the updated data array.

Parameters

[in]	DataBuffer	Config raw file buffer.
[in]	BufferSize	Size of raw buffer.
[in,out]	ConfigHeader	Pointer to the config header.
[in,out]	RecoveryArray	Pointer to the config of recovery data.

Return values

EFI_NOT_FOUND	No config data is found.
EFI_OUT_OF_RESOURCES	No enough memory is allocated.
EFI_SUCCESS	Parse the config file successfully.

Definition at line 31 of file ParseConfigProfile.c.

◆ ProcessFmpCapsuleImage()

EFI_STATUS ProcessFmpCapsuleImage	(	IN EFI_CAPSULE_HEADER *	CapsuleHeader,
		IN BOOLEAN	IsSystemFmp
	)

Process Firmware management protocol data capsule.

Caution: This function may receive untrusted input.

This function assumes the caller validated the capsule by using ValidateFmpCapsule(), so that all fields in EFI_CAPSULE_HEADER, EFI_FIRMWARE_MANAGEMENT_CAPSULE_HEADER and EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER are correct.

Parameters

[in]	CapsuleHeader	Points to a capsule header.
[in]	IsSystemFmp	If this capsule is a system FMP capsule.

Return values

EFI_SUCCESS	Process Capsule Image successfully.
EFI_UNSUPPORTED	Capsule image is not supported by the firmware.
EFI_VOLUME_CORRUPTED	FV volume in the capsule is corrupted.
EFI_OUT_OF_RESOURCES	Not enough memory.

Definition at line 637 of file RecoveryModuleLoadPei.c.

◆ ProcessRecoveryCapsule()

EFI_STATUS EFIAPI ProcessRecoveryCapsule	(	IN VOID *	CapsuleBuffer,
		IN UINTN	CapsuleSize
	)

Process recovery capsule image.

Caution: This function may receive untrusted input.

Parameters

[in]	CapsuleBuffer	The capsule image buffer.
[in]	CapsuleSize	The size of the capsule image in bytes.

Return values

EFI_SUCCESS	The recovery capsule is processed.
EFI_SECURITY_VIOLATION	The recovery capsule is not process because of security violation.
EFI_NOT_FOUND	The recovery capsule is not process because of unrecognization.

Definition at line 696 of file RecoveryModuleLoadPei.c.

◆ ProcessRecoveryImage()

EFI_STATUS ProcessRecoveryImage	(	IN VOID *	Image,
		IN UINTN	Length
	)

Process recovery image.

Caution: This function may receive untrusted input.

Parameters

[in]	Image	Points to the recovery image.
[in]	Length	The length of the recovery image in bytes.

Return values

EFI_SUCCESS	Process Recovery Image successfully.
EFI_SECURITY_VIOLATION	Recovery image is not processed due to security violation.

Definition at line 582 of file RecoveryModuleLoadPei.c.

◆ RecoverImage()

EFI_STATUS RecoverImage	(	IN VOID *	SystemFirmwareImage,
		IN UINTN	SystemFirmwareImageSize,
		IN VOID *	ConfigImage,
		IN UINTN	ConfigImageSize
	)

Create recovery context based upon System Firmware image and config file.

Parameters

[in]	SystemFirmwareImage	Points to the System Firmware image.
[in]	SystemFirmwareImageSize	The length of the System Firmware image in bytes.
[in]	ConfigImage	Points to the config file image.
[in]	ConfigImageSize	The length of the config file image in bytes.

Return values

EFI_SUCCESS Process Recovery Image successfully.

Definition at line 505 of file RecoveryModuleLoadPei.c.

◆ ValidateFmpCapsule()

EFI_STATUS ValidateFmpCapsule	(	IN EFI_CAPSULE_HEADER *	CapsuleHeader,
		OUT BOOLEAN *IsSystemFmp	OPTIONAL,
		OUT UINT16 *EmbeddedDriverCount	OPTIONAL
	)

Validate Fmp capsules layout.

Caution: This function may receive untrusted input.

This function assumes the caller validated the capsule by using IsValidCapsuleHeader(), so that all fields in EFI_CAPSULE_HEADER are correct. The capsule buffer size is CapsuleHeader->CapsuleImageSize.

This function validates the fields in EFI_FIRMWARE_MANAGEMENT_CAPSULE_HEADER and EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER.

Parameters

[in]	CapsuleHeader	Points to a capsule header.
[out]	IsSystemFmp	If it is a system FMP.
[out]	EmbeddedDriverCount	The EmbeddedDriverCount in the FMP capsule.

Return values

EFI_SUCCESS	Input capsule is a correct FMP capsule.
EFI_INVALID_PARAMETER	Input capsule is not a correct FMP capsule.

Current Init ImageHeader version is 3. UpdateHardwareInstance field was added in version 2 and ImageCapsuleSupport field was added in version 3

Definition at line 244 of file RecoveryModuleLoadPei.c.

Variable Documentation

◆ mRecoveryPpi

EFI_PEI_RECOVERY_MODULE_PPI mRecoveryPpi

Initial value:

= {
  LoadRecoveryCapsule
}

Definition at line 66 of file RecoveryModuleLoadPei.c.

◆ mRecoveryPpiList

EFI_PEI_PPI_DESCRIPTOR mRecoveryPpiList

Initial value:

= {
  (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
  &gEfiPeiRecoveryModulePpiGuid,
  &mRecoveryPpi
}

Definition at line 70 of file RecoveryModuleLoadPei.c.

Functions

Variables

Detailed Description

Function Documentation

◆ CreateHobForRecoveryCapsule()

◆ InitializeRecoveryModule()

◆ IsFmpCapsuleGuid()

◆ IsSystemFmpCapsuleImage()

◆ IsSystemFmpImage()

◆ IsValidCapsuleHeader()

◆ LoadRecoveryCapsule()

◆ ParseRecoveryDataFile()

◆ ProcessFmpCapsuleImage()

◆ ProcessRecoveryCapsule()

◆ ProcessRecoveryImage()

◆ RecoverImage()

◆ ValidateFmpCapsule()

Variable Documentation

◆ mRecoveryPpi

◆ mRecoveryPpiList