TianoCore EDK2 master
Loading...
Searching...
No Matches
DxeCapsuleLib.c File Reference

Go to the source code of this file.

Functions

VOID InitCapsuleVariable (VOID)
 
EFI_STATUS RecordCapsuleStatusVariable (IN EFI_CAPSULE_HEADER *CapsuleHeader, IN EFI_STATUS CapsuleStatus)
 
EFI_STATUS RecordFmpCapsuleStatusVariable (IN EFI_CAPSULE_HEADER *CapsuleHeader, IN EFI_STATUS CapsuleStatus, IN UINTN PayloadIndex, IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER *ImageHeader, IN EFI_DEVICE_PATH_PROTOCOL *FmpDevicePath OPTIONAL, IN CHAR16 *CapFileName OPTIONAL)
 
EFI_STATUS EFIAPI UpdateImageProgress (IN UINTN Completion)
 
BOOLEAN IsCapsuleNameCapsule (IN EFI_CAPSULE_HEADER *CapsuleHeader)
 
BOOLEAN IsFmpCapsuleGuid (IN EFI_GUID *CapsuleGuid)
 
BOOLEAN IsValidCapsuleHeader (IN EFI_CAPSULE_HEADER *CapsuleHeader, IN UINT64 CapsuleSize)
 
EFI_STATUS ValidateFmpCapsule (IN EFI_CAPSULE_HEADER *CapsuleHeader, OUT UINT16 *EmbeddedDriverCount OPTIONAL)
 
EFI_STATUS DisplayCapsuleImage (IN EFI_CAPSULE_HEADER *CapsuleHeader)
 
VOID DumpFmpImageInfo (IN UINTN ImageInfoSize, IN EFI_FIRMWARE_IMAGE_DESCRIPTOR *ImageInfo, IN UINT32 DescriptorVersion, IN UINT8 DescriptorCount, IN UINTN DescriptorSize, IN UINT32 PackageVersion, IN CHAR16 *PackageVersionName)
 
VOID DumpFmpCapsule (IN EFI_CAPSULE_HEADER *CapsuleHeader)
 
VOID DumpAllFmpInfo (VOID)
 
EFI_STATUS GetFmpHandleBufferByType (IN EFI_GUID *UpdateImageTypeId, IN UINT64 UpdateHardwareInstance, OUT UINTN *NoHandles OPTIONAL, OUT EFI_HANDLE **HandleBuf OPTIONAL, OUT BOOLEAN **ResetRequiredBuf OPTIONAL)
 
UINT32 GetFmpImageInfoDescriptorVer (IN EFI_HANDLE Handle)
 
EFI_STATUS SetFmpImageData (IN EFI_HANDLE Handle, IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER *ImageHeader, IN UINTN PayloadIndex)
 
EFI_STATUS StartFmpImage (IN VOID *ImageBuffer, IN UINTN ImageSize)
 
VOID RecordFmpCapsuleStatus (IN EFI_HANDLE Handle OPTIONAL, IN EFI_CAPSULE_HEADER *CapsuleHeader, IN EFI_STATUS CapsuleStatus, IN UINTN PayloadIndex, IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER *ImageHeader, IN CHAR16 *CapFileName OPTIONAL)
 
EFI_STATUS ProcessFmpCapsuleImage (IN EFI_CAPSULE_HEADER *CapsuleHeader, IN CHAR16 *CapFileName OPTIONAL, OUT BOOLEAN *ResetRequired OPTIONAL)
 
BOOLEAN IsNestedFmpCapsule (IN EFI_CAPSULE_HEADER *CapsuleHeader)
 
BOOLEAN IsFmpCapsule (IN EFI_CAPSULE_HEADER *CapsuleHeader)
 
EFI_STATUS EFIAPI SupportCapsuleImage (IN EFI_CAPSULE_HEADER *CapsuleHeader)
 
EFI_STATUS EFIAPI ProcessThisCapsuleImage (IN EFI_CAPSULE_HEADER *CapsuleHeader, IN CHAR16 *CapFileName OPTIONAL, OUT BOOLEAN *ResetRequired OPTIONAL)
 
EFI_STATUS EFIAPI ProcessCapsuleImage (IN EFI_CAPSULE_HEADER *CapsuleHeader)
 
VOID EFIAPI DxeCapsuleLibEndOfDxe (IN EFI_EVENT Event, IN VOID *Context)
 
EFI_STATUS EFIAPI DxeCapsuleLibConstructor (IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)
 
EFI_STATUS EFIAPI DxeCapsuleLibDestructor (IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)
 

Variables

EFI_SYSTEM_RESOURCE_TABLEmEsrtTable = NULL
 
BOOLEAN mDxeCapsuleLibEndOfDxe = FALSE
 
EFI_EVENT mDxeCapsuleLibEndOfDxeEvent = NULL
 
EDKII_FIRMWARE_MANAGEMENT_PROGRESS_PROTOCOLmFmpProgress = NULL
 
BOOLEAN mDxeCapsuleLibIsExitBootService = FALSE
 

Detailed Description

DXE capsule library.

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.

SupportCapsuleImage(), ProcessCapsuleImage(), IsValidCapsuleHeader(), ValidateFmpCapsule(), and DisplayCapsuleImage() receives untrusted input and performs basic validation.

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

Definition in file DxeCapsuleLib.c.

Function Documentation

◆ DisplayCapsuleImage()

EFI_STATUS DisplayCapsuleImage ( IN EFI_CAPSULE_HEADER CapsuleHeader)

Those capsules supported by the firmwares.

Caution: This function may receive untrusted input.

Parameters
[in]CapsuleHeaderPoints to a capsule header.
Return values
EFI_SUCESSInput capsule is supported by firmware.
EFI_UNSUPPORTEDInput capsule is not supported by the firmware.

Definition at line 348 of file DxeCapsuleLib.c.

◆ DumpAllFmpInfo()

VOID DumpAllFmpInfo ( VOID  )

Dump all FMP information.

Definition at line 555 of file DxeCapsuleLib.c.

◆ DumpFmpCapsule()

VOID DumpFmpCapsule ( IN EFI_CAPSULE_HEADER CapsuleHeader)

Dump a non-nested FMP capsule.

Parameters
[in]CapsuleHeaderA pointer to CapsuleHeader

Definition at line 511 of file DxeCapsuleLib.c.

◆ DumpFmpImageInfo()

VOID DumpFmpImageInfo ( IN UINTN  ImageInfoSize,
IN EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageInfo,
IN UINT32  DescriptorVersion,
IN UINT8  DescriptorCount,
IN UINTN  DescriptorSize,
IN UINT32  PackageVersion,
IN CHAR16 *  PackageVersionName 
)

Dump FMP information.

Parameters
[in]ImageInfoSizeThe size of ImageInfo, in bytes.
[in]ImageInfoA pointer to EFI_FIRMWARE_IMAGE_DESCRIPTOR.
[in]DescriptorVersionThe version of EFI_FIRMWARE_IMAGE_DESCRIPTOR.
[in]DescriptorCountThe count of EFI_FIRMWARE_IMAGE_DESCRIPTOR.
[in]DescriptorSizeThe size of an individual EFI_FIRMWARE_IMAGE_DESCRIPTOR, in bytes.
[in]PackageVersionThe version of package.
[in]PackageVersionNameThe version name of package.

Definition at line 458 of file DxeCapsuleLib.c.

◆ DxeCapsuleLibConstructor()

EFI_STATUS EFIAPI DxeCapsuleLibConstructor ( IN EFI_HANDLE  ImageHandle,
IN EFI_SYSTEM_TABLE SystemTable 
)

The constructor function.

Parameters
[in]ImageHandleThe firmware allocated handle for the EFI image.
[in]SystemTableA pointer to the EFI System Table.
Return values
EFI_SUCCESSThe constructor successfully .

Definition at line 1650 of file DxeCapsuleLib.c.

◆ DxeCapsuleLibDestructor()

EFI_STATUS EFIAPI DxeCapsuleLibDestructor ( IN EFI_HANDLE  ImageHandle,
IN EFI_SYSTEM_TABLE SystemTable 
)

The destructor function closes the End of DXE event.

Parameters
ImageHandleThe firmware allocated handle for the EFI image.
SystemTableA pointer to the EFI System Table.
Return values
EFI_SUCCESSThe destructor completed successfully.

Definition at line 1682 of file DxeCapsuleLib.c.

◆ DxeCapsuleLibEndOfDxe()

VOID EFIAPI DxeCapsuleLibEndOfDxe ( IN EFI_EVENT  Event,
IN VOID *  Context 
)

Callback function executed when the EndOfDxe event group is signaled.

Parameters
[in]EventEvent whose notification function is being invoked.
[in]ContextThe pointer to the notification function's context, which is implementation-dependent.

Definition at line 1632 of file DxeCapsuleLib.c.

◆ GetFmpHandleBufferByType()

EFI_STATUS GetFmpHandleBufferByType ( IN EFI_GUID UpdateImageTypeId,
IN UINT64  UpdateHardwareInstance,
OUT UINTN *NoHandles  OPTIONAL,
OUT EFI_HANDLE **HandleBuf  OPTIONAL,
OUT BOOLEAN **ResetRequiredBuf  OPTIONAL 
)

Get FMP handle by ImageTypeId and HardwareInstance.

Parameters
[in]UpdateImageTypeIdUsed to identify device firmware targeted by this update.
[in]UpdateHardwareInstanceThe HardwareInstance to target with this update.
[out]NoHandlesThe number of handles returned in HandleBuf.
[out]HandleBufA pointer to the buffer to return the requested array of handles.
[out]ResetRequiredBufA pointer to the buffer to return reset required flag for the requested array of handles.
Return values
EFI_SUCCESSThe array of handles and their reset required flag were returned in HandleBuf and ResetRequiredBuf, and the number of handles in HandleBuf was returned in NoHandles.
EFI_NOT_FOUNDNo handles match the search.
EFI_OUT_OF_RESOURCESThere is not enough pool memory to store the matching results.

Definition at line 669 of file DxeCapsuleLib.c.

◆ GetFmpImageInfoDescriptorVer()

UINT32 GetFmpImageInfoDescriptorVer ( IN EFI_HANDLE  Handle)

Return FmpImageInfoDescriptorVer by an FMP handle.

Parameters
[in]HandleA FMP handle.
Returns
FmpImageInfoDescriptorVer associated with the FMP.

Definition at line 853 of file DxeCapsuleLib.c.

◆ InitCapsuleVariable()

VOID InitCapsuleVariable ( VOID  )

Initialize capsule related variables.

Definition at line 495 of file DxeCapsuleReportLib.c.

◆ IsCapsuleNameCapsule()

BOOLEAN IsCapsuleNameCapsule ( IN EFI_CAPSULE_HEADER CapsuleHeader)

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

Parameters
[in]CapsuleHeaderA pointer to EFI_CAPSULE_HEADER
Return values
TRUEIt is a capsule name capsule.
FALSEIt 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]CapsuleHeaderA pointer to EFI_CAPSULE_HEADER
Return values
TRUEIt is a system FMP.
FALSEIt is a device FMP.

Definition at line 1473 of file DxeCapsuleLib.c.

◆ IsFmpCapsuleGuid()

BOOLEAN IsFmpCapsuleGuid ( IN EFI_GUID CapsuleGuid)

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

Parameters
[in]CapsuleGuidA pointer to EFI_GUID
Return values
TRUEIt is a FMP capsule GUID.
FALSEIt is not a FMP capsule GUID.

Definition at line 141 of file DxeCapsuleLib.c.

◆ IsNestedFmpCapsule()

BOOLEAN IsNestedFmpCapsule ( IN EFI_CAPSULE_HEADER CapsuleHeader)

Return if there is a FMP header below capsule header.

Parameters
[in]CapsuleHeaderA pointer to EFI_CAPSULE_HEADER
Return values
TRUEThere is a FMP header below capsule header.
FALSEThere is not a FMP header below capsule header

Definition at line 1385 of file DxeCapsuleLib.c.

◆ IsValidCapsuleHeader()

BOOLEAN IsValidCapsuleHeader ( IN EFI_CAPSULE_HEADER CapsuleHeader,
IN UINT64  CapsuleSize 
)

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]CapsuleHeaderPoints to a capsule header.
[in]CapsuleSizeSize of the whole capsule image.

Definition at line 167 of file DxeCapsuleLib.c.

◆ ProcessCapsuleImage()

EFI_STATUS EFIAPI ProcessCapsuleImage ( IN EFI_CAPSULE_HEADER CapsuleHeader)

The firmware implements to process the capsule image.

Caution: This function may receive untrusted input.

Parameters
[in]CapsuleHeaderPoints to a capsule header.
Return values
EFI_SUCESSProcess Capsule Image successfully.
EFI_UNSUPPORTEDCapsule image is not supported by the firmware.
EFI_VOLUME_CORRUPTEDFV volume in the capsule is corrupted.
EFI_OUT_OF_RESOURCESNot enough memory.

Definition at line 1616 of file DxeCapsuleLib.c.

◆ ProcessFmpCapsuleImage()

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

Process Firmware management protocol data capsule.

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.

This function need support nested FMP capsule.

Parameters
[in]CapsuleHeaderPoints to a capsule header.
[in]CapFileNameCapsule file name.
[out]ResetRequiredIndicates whether reset is required or not.
Return values
EFI_SUCESSProcess Capsule Image successfully.
EFI_UNSUPPORTEDCapsule image is not supported by the firmware.
EFI_VOLUME_CORRUPTEDFV volume in the capsule is corrupted.
EFI_OUT_OF_RESOURCESNot enough memory.
EFI_NOT_READYNo FMP protocol to handle this FMP capsule.

UpdateHardwareInstance field was added in Version 2

Definition at line 1204 of file DxeCapsuleLib.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]CapsuleHeaderPoints to a capsule header.
[in]CapFileNameCapsule file name.
[out]ResetRequiredIndicates whether reset is required or not.
Return values
EFI_SUCESSProcess Capsule Image successfully.
EFI_UNSUPPORTEDCapsule image is not supported by the firmware.
EFI_VOLUME_CORRUPTEDFV volume in the capsule is corrupted.
EFI_OUT_OF_RESOURCESNot enough memory.

Definition at line 1553 of file DxeCapsuleLib.c.

◆ RecordCapsuleStatusVariable()

EFI_STATUS RecordCapsuleStatusVariable ( IN EFI_CAPSULE_HEADER CapsuleHeader,
IN EFI_STATUS  CapsuleStatus 
)

Record capsule status variable.

Parameters
[in]CapsuleHeaderThe capsule image header
[in]CapsuleStatusThe capsule process stauts
Return values
EFI_SUCCESSThe capsule status variable is recorded.
EFI_OUT_OF_RESOURCESNo resource to record the capsule status variable.

Record capsule status variable and to local cache.

Parameters
[in]CapsuleHeaderThe capsule image header
[in]CapsuleStatusThe capsule process stauts
Return values
EFI_SUCCESSThe capsule status variable is recorded.
EFI_OUT_OF_RESOURCESNo resource to record the capsule status variable.

Definition at line 199 of file DxeCapsuleReportLib.c.

◆ RecordFmpCapsuleStatus()

VOID RecordFmpCapsuleStatus ( IN EFI_HANDLE Handle  OPTIONAL,
IN EFI_CAPSULE_HEADER CapsuleHeader,
IN EFI_STATUS  CapsuleStatus,
IN UINTN  PayloadIndex,
IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER ImageHeader,
IN CHAR16 *CapFileName  OPTIONAL 
)

Record FMP capsule status.

Parameters
[in]HandleA FMP handle.
[in]CapsuleHeaderThe capsule image header
[in]CapsuleStatusThe capsule process stauts
[in]PayloadIndexFMP payload index
[in]ImageHeaderFMP image header
[in]CapFileNameCapsule file name

Definition at line 1117 of file DxeCapsuleLib.c.

◆ RecordFmpCapsuleStatusVariable()

EFI_STATUS RecordFmpCapsuleStatusVariable ( IN EFI_CAPSULE_HEADER CapsuleHeader,
IN EFI_STATUS  CapsuleStatus,
IN UINTN  PayloadIndex,
IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER ImageHeader,
IN EFI_DEVICE_PATH_PROTOCOL *FmpDevicePath  OPTIONAL,
IN CHAR16 *CapFileName  OPTIONAL 
)

Record FMP capsule status variable.

Parameters
[in]CapsuleHeaderThe capsule image header
[in]CapsuleStatusThe capsule process stauts
[in]PayloadIndexFMP payload index
[in]ImageHeaderFMP image header
[in]FmpDevicePathDevicePath associated with the FMP producer
[in]CapFileNameCapsule file name
Return values
EFI_SUCCESSThe capsule status variable is recorded.
EFI_OUT_OF_RESOURCESNo resource to record the capsule status variable.

Record FMP capsule status variable and to local cache.

Parameters
[in]CapsuleHeaderThe capsule image header
[in]CapsuleStatusThe capsule process stauts
[in]PayloadIndexFMP payload index
[in]ImageHeaderFMP image header
[in]FmpDevicePathDevicePath associated with the FMP producer
[in]CapFileNameCapsule file name
Return values
EFI_SUCCESSThe capsule status variable is recorded.
EFI_OUT_OF_RESOURCESNo resource to record the capsule status variable.

Definition at line 236 of file DxeCapsuleReportLib.c.

◆ SetFmpImageData()

EFI_STATUS SetFmpImageData ( IN EFI_HANDLE  Handle,
IN EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER ImageHeader,
IN UINTN  PayloadIndex 
)

Set FMP image data.

Parameters
[in]HandleA FMP handle.
[in]ImageHeaderThe payload image header.
[in]PayloadIndexThe index of the payload.
Returns
The status of FMP->SetImage.

Definition at line 925 of file DxeCapsuleLib.c.

◆ StartFmpImage()

EFI_STATUS StartFmpImage ( IN VOID *  ImageBuffer,
IN UINTN  ImageSize 
)

Start a UEFI image in the FMP payload.

Parameters
[in]ImageBufferA pointer to the memory location containing a copy of the image to be loaded..
[in]ImageSizeThe size in bytes of ImageBuffer.
Returns
The status of gBS->LoadImage and gBS->StartImage.

Definition at line 1043 of file DxeCapsuleLib.c.

◆ SupportCapsuleImage()

EFI_STATUS EFIAPI SupportCapsuleImage ( IN EFI_CAPSULE_HEADER CapsuleHeader)

Those capsules supported by the firmwares.

Caution: This function may receive untrusted input.

Parameters
[in]CapsuleHeaderPoints to a capsule header.
Return values
EFI_SUCESSInput capsule is supported by firmware.
EFI_UNSUPPORTEDInput capsule is not supported by the firmware.
EFI_INVALID_PARAMETERInput capsule layout is not correct

Definition at line 1501 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]CompletionA value between 1 and 100 indicating the current completion progress of the firmware update
Return values
EFI_SUCESSThe capsule update progress was updated.
EFI_INVALID_PARAMETERCompletion is greater than 100%.

Definition at line 167 of file DxeCapsuleProcessLib.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]CapsuleHeaderPoints to a capsule header.
[out]EmbeddedDriverCountThe EmbeddedDriverCount in the FMP capsule.
Return values
EFI_SUCESSInput capsule is a correct FMP capsule.
EFI_INVALID_PARAMETERInput capsule is not a correct FMP capsule.

Definition at line 204 of file DxeCapsuleLib.c.

Variable Documentation

◆ mDxeCapsuleLibEndOfDxe

BOOLEAN mDxeCapsuleLibEndOfDxe = FALSE

Definition at line 47 of file DxeCapsuleLib.c.

◆ mDxeCapsuleLibEndOfDxeEvent

EFI_EVENT mDxeCapsuleLibEndOfDxeEvent = NULL

Definition at line 48 of file DxeCapsuleLib.c.

◆ mDxeCapsuleLibIsExitBootService

BOOLEAN mDxeCapsuleLibIsExitBootService = FALSE

Definition at line 52 of file DxeCapsuleLib.c.

◆ mEsrtTable

Definition at line 45 of file DxeCapsuleLib.c.

◆ mFmpProgress

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

Definition at line 50 of file DxeCapsuleLib.c.