#include <PiDxe.h>
#include <Protocol/EsrtManagement.h>
#include <Protocol/FirmwareManagementProgress.h>
#include <Library/BaseLib.h>
#include <Library/DebugLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiRuntimeServicesTableLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/UefiLib.h>
#include <Library/PcdLib.h>
#include <Library/HobLib.h>
#include <Library/ReportStatusCodeLib.h>
#include <Library/CapsuleLib.h>
#include <Library/DisplayUpdateProgressLib.h>
#include <IndustryStandard/WindowsUxCapsule.h>

Functions
BOOLEAN	IsFmpCapsule (IN EFI_CAPSULE_HEADER *CapsuleHeader)

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

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

BOOLEAN	IsCapsuleNameCapsule (IN EFI_CAPSULE_HEADER *CapsuleHeader)

EFI_PHYSICAL_ADDRESS *	ValidateCapsuleNameCapsuleIntegrity (IN EFI_CAPSULE_HEADER CapsuleHeader, OUT UINTN CapsuleNameNum)

EFI_STATUS EFIAPI	ProcessThisCapsuleImage (IN EFI_CAPSULE_HEADER CapsuleHeader, IN CHAR16 CapFileName OPTIONAL, OUT BOOLEAN *ResetRequired OPTIONAL)

EFI_STATUS EFIAPI	UpdateImageProgress (IN UINTN Completion)

VOID	InitCapsulePtr (VOID)

BOOLEAN	AreAllImagesProcessed (VOID)

VOID	PopulateCapsuleInConfigurationTable (VOID)

EFI_STATUS	ProcessTheseCapsules (IN BOOLEAN FirstRound)

VOID	DoResetSystem (VOID)

EFI_STATUS EFIAPI	ProcessCapsules (VOID)

Variables
EDKII_FIRMWARE_MANAGEMENT_PROGRESS_PROTOCOL *	mFmpProgress

BOOLEAN	mDxeCapsuleLibEndOfDxe

BOOLEAN	mNeedReset = FALSE

VOID **	mCapsulePtr

CHAR16 **	mCapsuleNamePtr

EFI_STATUS *	mCapsuleStatusArray

UINT32	mCapsuleTotalNumber

Detailed Description

DXE capsule process.

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.

ProcessCapsules(), ProcessTheseCapsules() 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 DxeCapsuleProcessLib.c.

Function Documentation

◆ AreAllImagesProcessed()

BOOLEAN AreAllImagesProcessed ( VOID )

This function returns if all capsule images are processed.

Return values

TRUE	All capsule images are processed.
FALSE	Not all capsule images are processed.

Definition at line 351 of file DxeCapsuleProcessLib.c.

◆ DoResetSystem()

VOID DoResetSystem ( VOID )

Do reset system.

Definition at line 630 of file DxeCapsuleProcessLib.c.

◆ InitCapsulePtr()

VOID InitCapsulePtr ( VOID )

This function initializes the mCapsulePtr, mCapsuleStatusArray and mCapsuleTotalNumber.

Definition at line 215 of file DxeCapsuleProcessLib.c.

◆ IsCapsuleNameCapsule()

BOOLEAN IsCapsuleNameCapsule ( IN EFI_CAPSULE_HEADER * CapsuleHeader )

Return if this capsule is a capsule name capsule, based upon CapsuleHeader.

Parameters

[in] CapsuleHeader A pointer to EFI_CAPSULE_HEADER

Return values

TRUE	It is a capsule name capsule.
FALSE	It is not a capsule name capsule.

Definition at line 125 of file DxeCapsuleLib.c.

◆ IsFmpCapsule()

BOOLEAN IsFmpCapsule ( IN EFI_CAPSULE_HEADER * CapsuleHeader )

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

Parameters

[in] CapsuleHeader A pointer to EFI_CAPSULE_HEADER

Return values

TRUE	It is a system FMP.
FALSE	It is a device FMP.

Definition at line 1473 of file DxeCapsuleLib.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.

Validate if it is valid capsule header

Caution: This function may receive untrusted input.

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 247 of file CapsuleApp.c.

◆ PopulateCapsuleInConfigurationTable()

VOID PopulateCapsuleInConfigurationTable ( VOID )

This function populates capsule in the configuration table.

Definition at line 370 of file DxeCapsuleProcessLib.c.

◆ ProcessCapsules()

EFI_STATUS EFIAPI ProcessCapsules ( VOID )

This routine is called to process capsules.

Caution: This function may receive untrusted input.

The capsules reported in EFI_HOB_UEFI_CAPSULE are processed. If there is no EFI_HOB_UEFI_CAPSULE, it means error occurs, force reset to normal boot path.

This routine should be called twice in BDS. 1) The first call must be before EndOfDxe. The system capsules is processed. If device capsule FMP protocols are exposted at this time and device FMP capsule has zero EmbeddedDriverCount, the device capsules are processed. Each individual capsule result is recorded in capsule record variable. System may reset in this function, if reset is required by capsule and all capsules are processed. If not all capsules are processed, reset will be defered to second call.

2) The second call must be after EndOfDxe and after ConnectAll, so that all device capsule FMP protocols are exposed. The system capsules are skipped. If the device capsules are NOT processed in first call, they are processed here. Each individual capsule result is recorded in capsule record variable. System may reset in this function, if reset is required by capsule processed in first call and second call.

Return values

EFI_SUCCESS	There is no error when processing capsules.
EFI_OUT_OF_RESOURCES	No enough resource to process capsules.

Definition at line 676 of file DxeCapsuleProcessLib.c.

◆ ProcessTheseCapsules()

EFI_STATUS ProcessTheseCapsules ( IN BOOLEAN FirstRound )

This routine is called to process capsules.

Caution: This function may receive untrusted input.

Each individual capsule result is recorded in capsule record variable.

Parameters

[in] FirstRound TRUE: First round. Need skip the FMP capsules with non zero EmbeddedDriverCount. FALSE: Process rest FMP capsules.

Return values

EFI_SUCCESS	There is no error when processing capsules.
EFI_OUT_OF_RESOURCES	No enough resource to process capsules.

Definition at line 500 of file DxeCapsuleProcessLib.c.

◆ ProcessThisCapsuleImage()

EFI_STATUS EFIAPI ProcessThisCapsuleImage	(	IN EFI_CAPSULE_HEADER *	CapsuleHeader,
		IN CHAR16 *CapFileName	OPTIONAL,
		OUT BOOLEAN *ResetRequired	OPTIONAL
	)

The firmware implements to process the capsule image.

Caution: This function may receive untrusted input.

Parameters

[in]	CapsuleHeader	Points to a capsule header.
[in]	CapFileName	Capsule file name.
[out]	ResetRequired	Indicates whether reset is required or not.

Return values

EFI_SUCESS	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 1553 of file DxeCapsuleLib.c.

◆ UpdateImageProgress()

EFI_STATUS EFIAPI UpdateImageProgress ( IN UINTN Completion )

Function indicate the current completion progress of the firmware update. Platform may override with own specific progress function.

Parameters

[in] Completion A value between 1 and 100 indicating the current completion progress of the firmware update

Return values

EFI_SUCESS	The capsule update progress was updated.
EFI_INVALID_PARAMETER	Completion is greater than 100%.

Definition at line 167 of file DxeCapsuleProcessLib.c.

◆ ValidateCapsuleNameCapsuleIntegrity()

EFI_PHYSICAL_ADDRESS * ValidateCapsuleNameCapsuleIntegrity	(	IN EFI_CAPSULE_HEADER *	CapsuleHeader,
		OUT UINTN *	CapsuleNameNum
	)

Check the integrity of the capsule name capsule. If the capsule is vaild, return the physical address of each capsule name string.

Parameters

[in]	CapsuleHeader	Pointer to the capsule header of a capsule name capsule.
[out]	CapsuleNameNum	Number of capsule name.

Return values

NULL	Capsule name capsule is not valid.
CapsuleNameBuf	Array of capsule name physical address.

Check the integrity of the capsule name capsule. If the capsule is vaild, return the physical address of each capsule name string.

This routine assumes the capsule has been validated by IsValidCapsuleHeader(), so capsule memory overflow is not going to happen in this routine.

Parameters

[in]	CapsuleHeader	Pointer to the capsule header of a capsule name capsule.
[out]	CapsuleNameNum	Number of capsule name.

Return values

NULL	Capsule name capsule is not valid.
CapsuleNameBuf	Array of capsule name physical address.

Definition at line 39 of file CapsuleOnDisk.c.

◆ ValidateFmpCapsule()

EFI_STATUS ValidateFmpCapsule	(	IN EFI_CAPSULE_HEADER *	CapsuleHeader,
		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.

This function need support nested FMP capsule.

Parameters

[in]	CapsuleHeader	Points to a capsule header.
[out]	EmbeddedDriverCount	The EmbeddedDriverCount in the FMP capsule.

Return values

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

Definition at line 204 of file DxeCapsuleLib.c.

Variable Documentation

◆ mCapsuleNamePtr

CHAR16** mCapsuleNamePtr

Definition at line 129 of file DxeCapsuleProcessLib.c.

◆ mCapsulePtr

VOID** mCapsulePtr

Definition at line 128 of file DxeCapsuleProcessLib.c.

◆ mCapsuleStatusArray

EFI_STATUS* mCapsuleStatusArray

Definition at line 130 of file DxeCapsuleProcessLib.c.

◆ mCapsuleTotalNumber

UINT32 mCapsuleTotalNumber

Definition at line 131 of file DxeCapsuleProcessLib.c.

◆ mDxeCapsuleLibEndOfDxe

BOOLEAN mDxeCapsuleLibEndOfDxe

extern

Definition at line 47 of file DxeCapsuleLib.c.

◆ mFmpProgress

EDKII_FIRMWARE_MANAGEMENT_PROGRESS_PROTOCOL* mFmpProgress

extern

Firmware Management Protocol instance that is initialized in the entry point from PCD settings.

Definition at line 36 of file FmpDxe.c.

◆ mNeedReset

BOOLEAN mNeedReset = FALSE

Definition at line 126 of file DxeCapsuleProcessLib.c.

Functions

Variables

Detailed Description

Function Documentation

◆ AreAllImagesProcessed()

◆ DoResetSystem()

◆ InitCapsulePtr()

◆ IsCapsuleNameCapsule()

◆ IsFmpCapsule()

◆ IsValidCapsuleHeader()

◆ PopulateCapsuleInConfigurationTable()

◆ ProcessCapsules()

◆ ProcessTheseCapsules()

◆ ProcessThisCapsuleImage()

◆ UpdateImageProgress()

◆ ValidateCapsuleNameCapsuleIntegrity()

◆ ValidateFmpCapsule()

Variable Documentation

◆ mCapsuleNamePtr

◆ mCapsulePtr

◆ mCapsuleStatusArray

◆ mCapsuleTotalNumber

◆ mDxeCapsuleLibEndOfDxe

◆ mFmpProgress

◆ mNeedReset