#include <Uefi.h>
#include <PiPei.h>
#include <Guid/CapsuleVendor.h>
#include <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>
#include <Library/PrintLib.h>
#include <Library/BaseLib.h>
#include "CommonHeader.h"

Macros
#define	MIN_COALESCE_ADDR (1024 * 1024)

Functions
UINT8 *	FindFreeMem (EFI_CAPSULE_BLOCK_DESCRIPTOR BlockList, UINT8 MemBase, UINTN MemSize, UINTN DataSize)

EFI_CAPSULE_BLOCK_DESCRIPTOR *	RelocateBlockDescriptors (IN EFI_PEI_SERVICES *PeiServices, IN EFI_CAPSULE_BLOCK_DESCRIPTOR BlockList, IN UINTN NumDescriptors, IN UINT8 *MemBase, IN UINTN MemSize)

BOOLEAN	IsCapsuleCorrupted (IN EFI_CAPSULE_HEADER *CapsuleHeader)

BOOLEAN	IsOverlapped (UINT8 Buff1, UINTN Size1, UINT8 Buff2, UINTN Size2)

EFI_STATUS	GetCapsuleInfo (IN EFI_CAPSULE_BLOCK_DESCRIPTOR Desc, IN OUT UINTN NumDescriptors OPTIONAL, IN OUT UINTN CapsuleSize OPTIONAL, IN OUT UINTN CapsuleNumber OPTIONAL)

BOOLEAN	ValidateCapsuleByMemoryResource (IN MEMORY_RESOURCE_DESCRIPTOR *MemoryResource, IN EFI_PHYSICAL_ADDRESS Address, IN UINT64 Size)

EFI_CAPSULE_BLOCK_DESCRIPTOR *	ValidateCapsuleIntegrity (IN EFI_CAPSULE_BLOCK_DESCRIPTOR BlockList, IN MEMORY_RESOURCE_DESCRIPTOR MemoryResource)

VOID	CapsuleTestPatternPreCoalesce (IN EFI_PEI_SERVICES *PeiServices, IN EFI_CAPSULE_BLOCK_DESCRIPTOR Desc)

EFI_STATUS	BuildCapsuleDescriptors (IN EFI_PHYSICAL_ADDRESS BlockListBuffer, IN MEMORY_RESOURCE_DESCRIPTOR MemoryResource, OUT EFI_CAPSULE_BLOCK_DESCRIPTOR **BlockDescriptorList)

EFI_STATUS EFIAPI	CapsuleDataCoalesce (IN EFI_PEI_SERVICES *PeiServices, IN EFI_PHYSICAL_ADDRESS BlockListBuffer, IN MEMORY_RESOURCE_DESCRIPTOR MemoryResource, IN OUT VOID MemoryBase, IN OUT UINTN MemorySize)

Detailed Description

The logic to process capsule.

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

CapsuleDataCoalesce() will do basic validation before coalesce capsule data into memory.

(C) Copyright 2014 Hewlett-Packard Development Company, L.P.
Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file CapsuleCoalesce.c.

Macro Definition Documentation

◆ MIN_COALESCE_ADDR

#define MIN_COALESCE_ADDR (1024 * 1024)

Definition at line 30 of file CapsuleCoalesce.c.

Function Documentation

◆ BuildCapsuleDescriptors()

EFI_STATUS BuildCapsuleDescriptors	(	IN EFI_PHYSICAL_ADDRESS *	BlockListBuffer,
		IN MEMORY_RESOURCE_DESCRIPTOR *	MemoryResource,
		OUT EFI_CAPSULE_BLOCK_DESCRIPTOR **	BlockDescriptorList
	)

Checks for the presence of capsule descriptors. Get capsule descriptors from variable CapsuleUpdateData, CapsuleUpdateData1, CapsuleUpdateData2...

Parameters

BlockListBuffer	Pointer to the buffer of capsule descriptors variables
MemoryResource	Pointer to the buffer of memory resource descriptor.
BlockDescriptorList	Pointer to the capsule descriptors list

Return values

EFI_SUCCESS	a valid capsule is present
EFI_NOT_FOUND	if a valid capsule is not present

Definition at line 890 of file CapsuleCoalesce.c.

◆ CapsuleDataCoalesce()

EFI_STATUS EFIAPI CapsuleDataCoalesce	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_PHYSICAL_ADDRESS *	BlockListBuffer,
		IN MEMORY_RESOURCE_DESCRIPTOR *	MemoryResource,
		IN OUT VOID **	MemoryBase,
		IN OUT UINTN *	MemorySize
	)

The function to coalesce a fragmented capsule in memory.

Memory Map for coalesced capsule: MemBase + -—>+------------------------—+<--------—+ MemSize | ----------------------— | | | | Capsule [Num-1] | | | | ----------------------— | | | | ................ | | | | ----------------------— | | | | Capsule [1] | | | | ----------------------— | | | | Capsule [0] | | | | ----------------------— | | | Capsule Image | | CapsuleImageBase-->+------------------------—+ | ----------------------— | | | | CapsuleOffset[Num-1] | | | | ----------------------— | | | | ................ | | CapsuleSize | ----------------------— | | | | CapsuleOffset[1] | | | | ----------------------— | | | | CapsuleOffset[0] | | | |------------------------—| | | | CapsuleNumber | | | | ----------------------— | | | | CapsuleAllImageSize | | | | ----------------------— | | | PrivateData | | DestPtr -—>+------------------------—+<--------—+ | | | | FreeMem | FreeMemSize | | | FreeMemBase —>+------------------------—+<--------—+ | Terminator | +------------------------—+ | BlockDescriptor n | +------------------------—+ | ................. | +------------------------—+ | BlockDescriptor 1 | +------------------------—+ | BlockDescriptor 0 | +------------------------—+ | PrivateDataDesc 0 | MemBase -—>+------------------------—+<--— BlockList

Caution: This function may receive untrusted input. The capsule data is external input, so this routine will do basic validation before coalesce capsule data into memory.

Parameters

PeiServices	General purpose services available to every PEIM.
BlockListBuffer	Pointer to the buffer of Capsule Descriptor Variables.
MemoryResource	Pointer to the buffer of memory resource descriptor.
MemoryBase	Pointer to the base of a block of memory that we can walk all over while trying to coalesce our buffers. On output, this variable will hold the base address of a coalesced capsule.
MemorySize	Size of the memory region pointed to by MemoryBase. On output, this variable will contain the size of the coalesced capsule.

Return values

EFI_NOT_FOUND	If we could not find the capsule descriptors.
EFI_BUFFER_TOO_SMALL	If we could not coalesce the capsule in the memory region provided to us.
EFI_SUCCESS	Processed the capsule successfully.

Definition at line 1019 of file CapsuleCoalesce.c.

◆ CapsuleTestPatternPreCoalesce()

VOID CapsuleTestPatternPreCoalesce	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_CAPSULE_BLOCK_DESCRIPTOR *	Desc
	)

Try to verify the integrity of a capsule test pattern before the capsule gets coalesced. This can be useful in narrowing down where capsule data corruption occurs.

The test pattern mode fills in memory with a counting UINT32 value. If the capsule is not divided up in a multiple of 4-byte blocks, then things get messy doing the check. Therefore there are some cases here where we just give up and skip the pre-coalesce check.

Parameters

PeiServices	PEI services table
Desc	Pointer to capsule descriptors

Definition at line 803 of file CapsuleCoalesce.c.

◆ FindFreeMem()

UINT8 * FindFreeMem	(	EFI_CAPSULE_BLOCK_DESCRIPTOR *	BlockList,
		UINT8 *	MemBase,
		UINTN	MemSize,
		UINTN	DataSize
	)

Given a pointer to the capsule block list, info on the available system memory, and the size of a buffer, find a free block of memory where a buffer of the given size can be copied to safely.

Parameters

BlockList	Pointer to head of capsule block descriptors
MemBase	Pointer to the base of memory in which we want to find free space
MemSize	The size of the block of memory pointed to by MemBase
DataSize	How big a free block we want to find

Returns: A pointer to a memory block of at least DataSize that lies somewhere between MemBase and (MemBase + MemSize). The memory pointed to does not contain any of the capsule block descriptors or capsule blocks pointed to by the BlockList.

Definition at line 157 of file CapsuleCoalesce.c.

◆ GetCapsuleInfo()

EFI_STATUS GetCapsuleInfo	(	IN EFI_CAPSULE_BLOCK_DESCRIPTOR *	Desc,
		IN OUT UINTN *NumDescriptors	OPTIONAL,
		IN OUT UINTN *CapsuleSize	OPTIONAL,
		IN OUT UINTN *CapsuleNumber	OPTIONAL
	)

Given a pointer to a capsule block descriptor, traverse the list to figure out how many legitimate descriptors there are, and how big the capsule it refers to is.

Parameters

Desc	Pointer to the capsule block descriptors
NumDescriptors	Optional pointer to where to return the number of capsule data descriptors, whose Length is non-zero.
CapsuleSize	Optional pointer to where to return the capsule image size
CapsuleNumber	Optional pointer to where to return the number of capsule

Return values

EFI_NOT_FOUND	No descriptors containing data in the list
EFI_SUCCESS	Return data is valid

Definition at line 659 of file CapsuleCoalesce.c.

◆ IsCapsuleCorrupted()

BOOLEAN IsCapsuleCorrupted ( IN EFI_CAPSULE_HEADER * CapsuleHeader )

Check every capsule header.

Parameters

CapsuleHeader The pointer to EFI_CAPSULE_HEADER

Return values

FALSE	Capsule is OK
TRUE	Capsule is corrupted

Definition at line 764 of file CapsuleCoalesce.c.

◆ IsOverlapped()

BOOLEAN IsOverlapped	(	UINT8 *	Buff1,
		UINTN	Size1,
		UINT8 *	Buff2,
		UINTN	Size2
	)

Determine if two buffers overlap in memory.

Parameters

Buff1	pointer to first buffer
Size1	size of Buff1
Buff2	pointer to second buffer
Size2	size of Buff2

Return values

TRUE	Buffers overlap in memory.
FALSE	Buffer doesn't overlap.

Definition at line 626 of file CapsuleCoalesce.c.

◆ RelocateBlockDescriptors()

EFI_CAPSULE_BLOCK_DESCRIPTOR * RelocateBlockDescriptors	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_CAPSULE_BLOCK_DESCRIPTOR *	BlockList,
		IN UINTN	NumDescriptors,
		IN UINT8 *	MemBase,
		IN UINTN	MemSize
	)

The capsule block descriptors may be fragmented and spread all over memory. To simplify the coalescing of capsule blocks, first coalesce all the capsule block descriptors low in memory.

The descriptors passed in can be fragmented throughout memory. Here they are relocated into memory to turn them into a contiguous (null terminated) array.

Parameters

PeiServices	pointer to PEI services table
BlockList	pointer to the capsule block descriptors
NumDescriptors	number of capsule data block descriptors, whose Length is non-zero.
MemBase	base of system memory in which we can work
MemSize	size of the system memory pointed to by MemBase

Return values

NULL	could not relocate the descriptors
Pointer	to the base of the successfully-relocated block descriptors.

Definition at line 467 of file CapsuleCoalesce.c.

◆ ValidateCapsuleByMemoryResource()

BOOLEAN ValidateCapsuleByMemoryResource	(	IN MEMORY_RESOURCE_DESCRIPTOR *	MemoryResource,
		IN EFI_PHYSICAL_ADDRESS	Address,
		IN UINT64	Size
	)

Validate capsule by MemoryResource.

Parameters

MemoryResource	Pointer to the buffer of memory resource descriptor.
Address	Address to be validated.
Size	Size to be validated.

Return values

TRUE	No memory resource descriptor reported in HOB list before capsule Coalesce, or it is valid in one MemoryResource. FALSE It is not in any MemoryResource.

Definition at line 247 of file CapsuleCoalesce.c.

◆ ValidateCapsuleIntegrity()

EFI_CAPSULE_BLOCK_DESCRIPTOR * ValidateCapsuleIntegrity	(	IN EFI_CAPSULE_BLOCK_DESCRIPTOR *	BlockList,
		IN MEMORY_RESOURCE_DESCRIPTOR *	MemoryResource
	)

Check the integrity of the capsule descriptors.

Parameters

BlockList	Pointer to the capsule descriptors
MemoryResource	Pointer to the buffer of memory resource descriptor.

Return values

NULL	BlockList is not valid.
LastBlockDesc	Last one Block in BlockList

Definition at line 310 of file CapsuleCoalesce.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MIN_COALESCE_ADDR

Function Documentation

◆ BuildCapsuleDescriptors()

◆ CapsuleDataCoalesce()

◆ CapsuleTestPatternPreCoalesce()

◆ FindFreeMem()

◆ GetCapsuleInfo()

◆ IsCapsuleCorrupted()

◆ IsOverlapped()

◆ RelocateBlockDescriptors()

◆ ValidateCapsuleByMemoryResource()

◆ ValidateCapsuleIntegrity()