#include "DxeMain.h"
#include "Imem.h"
#include "HeapGuard.h"

Functions
STATIC VOID	SetBits (IN EFI_PHYSICAL_ADDRESS Address, IN UINTN BitNumber, IN UINT64 *BitMap)

STATIC VOID	ClearBits (IN EFI_PHYSICAL_ADDRESS Address, IN UINTN BitNumber, IN UINT64 *BitMap)

STATIC UINT64	GetBits (IN EFI_PHYSICAL_ADDRESS Address, IN UINTN BitNumber, IN UINT64 *BitMap)

UINTN	FindGuardedMemoryMap (IN EFI_PHYSICAL_ADDRESS Address, IN BOOLEAN AllocMapUnit, OUT UINT64 **BitMap)

VOID EFIAPI	SetGuardedMemoryBits (IN EFI_PHYSICAL_ADDRESS Address, IN UINTN NumberOfPages)

VOID EFIAPI	ClearGuardedMemoryBits (IN EFI_PHYSICAL_ADDRESS Address, IN UINTN NumberOfPages)

UINT64	GetGuardedMemoryBits (IN EFI_PHYSICAL_ADDRESS Address, IN UINTN NumberOfPages)

UINTN EFIAPI	GetGuardMapBit (IN EFI_PHYSICAL_ADDRESS Address)

BOOLEAN EFIAPI	IsGuardPage (IN EFI_PHYSICAL_ADDRESS Address)

BOOLEAN EFIAPI	IsMemoryGuarded (IN EFI_PHYSICAL_ADDRESS Address)

VOID EFIAPI	SetGuardPage (IN EFI_PHYSICAL_ADDRESS BaseAddress)

VOID EFIAPI	UnsetGuardPage (IN EFI_PHYSICAL_ADDRESS BaseAddress)

BOOLEAN	IsMemoryTypeToGuard (IN EFI_MEMORY_TYPE MemoryType, IN EFI_ALLOCATE_TYPE AllocateType, IN UINT8 PageOrPool)

BOOLEAN	IsPoolTypeToGuard (IN EFI_MEMORY_TYPE MemoryType)

BOOLEAN	IsPageTypeToGuard (IN EFI_MEMORY_TYPE MemoryType, IN EFI_ALLOCATE_TYPE AllocateType)

BOOLEAN	IsHeapGuardEnabled (UINT8 GuardType)

VOID	SetGuardForMemory (IN EFI_PHYSICAL_ADDRESS Memory, IN UINTN NumberOfPages)

VOID	UnsetGuardForMemory (IN EFI_PHYSICAL_ADDRESS Memory, IN UINTN NumberOfPages)

UINT64	AdjustMemoryS (IN UINT64 Start, IN UINT64 Size, IN UINT64 SizeRequested)

VOID	AdjustMemoryF (IN OUT EFI_PHYSICAL_ADDRESS Memory, IN OUT UINTN NumberOfPages)

VOID	AdjustMemoryA (IN OUT EFI_PHYSICAL_ADDRESS Memory, IN OUT UINTN NumberOfPages)

VOID *	AdjustPoolHeadA (IN EFI_PHYSICAL_ADDRESS Memory, IN UINTN NoPages, IN UINTN Size)

VOID *	AdjustPoolHeadF (IN EFI_PHYSICAL_ADDRESS Memory, IN UINTN NoPages, IN UINTN Size)

EFI_STATUS	CoreConvertPagesWithGuard (IN UINT64 Start, IN UINTN NumberOfPages, IN EFI_MEMORY_TYPE NewType)

VOID	SetAllGuardPages (VOID)

VOID	GetLastGuardedFreePageAddress (OUT EFI_PHYSICAL_ADDRESS *Address)

VOID	MarkFreedPages (IN EFI_PHYSICAL_ADDRESS BaseAddress, IN UINTN Pages)

VOID EFIAPI	GuardFreedPages (IN EFI_PHYSICAL_ADDRESS BaseAddress, IN UINTN Pages)

VOID EFIAPI	GuardFreedPagesChecked (IN EFI_PHYSICAL_ADDRESS BaseAddress, IN UINTN Pages)

VOID	GuardAllFreedPages (VOID)

VOID	MergeGuardPages (IN EFI_MEMORY_DESCRIPTOR *MemoryMapEntry, IN EFI_PHYSICAL_ADDRESS MaxAddress)

BOOLEAN	PromoteGuardedFreePages (OUT EFI_PHYSICAL_ADDRESS StartAddress, OUT EFI_PHYSICAL_ADDRESS EndAddress)

VOID	HeapGuardCpuArchProtocolNotify (VOID)

VOID	Uint64ToBinString (IN UINT64 Value, OUT CHAR8 *BinString)

VOID EFIAPI	DumpGuardedMemoryBitmap (VOID)

Variables
GLOBAL_REMOVE_IF_UNREFERENCED BOOLEAN	mOnGuarding = FALSE

GLOBAL_REMOVE_IF_UNREFERENCED UINT64	mGuardedMemoryMap = 0

GLOBAL_REMOVE_IF_UNREFERENCED UINTN	mMapLevel = 1

GLOBAL_REMOVE_IF_UNREFERENCED UINTN	mLevelShift [GUARDED_HEAP_MAP_TABLE_DEPTH] = GUARDED_HEAP_MAP_TABLE_DEPTH_SHIFTS

GLOBAL_REMOVE_IF_UNREFERENCED UINTN	mLevelMask [GUARDED_HEAP_MAP_TABLE_DEPTH] = GUARDED_HEAP_MAP_TABLE_DEPTH_MASKS

GLOBAL_REMOVE_IF_UNREFERENCED EFI_PHYSICAL_ADDRESS	mLastPromotedPage = BASE_4GB

Detailed Description

UEFI Heap Guard functions.

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

Definition in file HeapGuard.c.

Function Documentation

◆ AdjustMemoryA()

VOID AdjustMemoryA	(	IN OUT EFI_PHYSICAL_ADDRESS *	Memory,
		IN OUT UINTN *	NumberOfPages
	)

Adjust the base and number of pages to really allocate according to Guard.

Parameters

[in,out]	Memory	Base address of free memory.
[in,out]	NumberOfPages	Size of memory to allocate.

Returns: VOID.

Definition at line 982 of file HeapGuard.c.

◆ AdjustMemoryF()

VOID AdjustMemoryF	(	IN OUT EFI_PHYSICAL_ADDRESS *	Memory,
		IN OUT UINTN *	NumberOfPages
	)

Adjust the start address and number of pages to free according to Guard.

The purpose of this function is to keep the shared Guard page with adjacent memory block if it's still in guard, or free it if no more sharing. Another is to reserve pages as Guard pages in partial page free situation.

Parameters

[in,out]	Memory	Base address of memory to free.
[in,out]	NumberOfPages	Size of memory to free.

Returns: VOID.

Definition at line 884 of file HeapGuard.c.

◆ AdjustMemoryS()

UINT64 AdjustMemoryS	(	IN UINT64	Start,
		IN UINT64	Size,
		IN UINT64	SizeRequested
	)

Adjust address of free memory according to existing and/or required Guard.

This function will check if there're existing Guard pages of adjacent memory blocks, and try to use it as the Guard page of the memory to be allocated.

Parameters

[in]	Start	Start address of free memory block.
[in]	Size	Size of free memory block.
[in]	SizeRequested	Size of memory to allocate.

Returns: The end address of memory block found.; 0 if no enough space for the required size of memory and its Guard.

Definition at line 825 of file HeapGuard.c.

◆ AdjustPoolHeadA()

VOID * AdjustPoolHeadA	(	IN EFI_PHYSICAL_ADDRESS	Memory,
		IN UINTN	NoPages,
		IN UINTN	Size
	)

Adjust the pool head position to make sure the Guard page is adjavent to pool tail or pool head.

Parameters

[in]	Memory	Base address of memory allocated.
[in]	NoPages	Number of pages actually allocated.
[in]	Size	Size of memory requested. (plus pool head/tail overhead)

Returns: Address of pool head.

Definition at line 1016 of file HeapGuard.c.

◆ AdjustPoolHeadF()

VOID * AdjustPoolHeadF	(	IN EFI_PHYSICAL_ADDRESS	Memory,
		IN UINTN	NoPages,
		IN UINTN	Size
	)

Get the page base address according to pool head address.

Parameters

[in]	Memory	Head address of pool to free.
[in]	NoPages	Number of pages actually allocated.
[in]	Size	Size of memory requested. (plus pool head/tail overhead)

Returns: Address of pool head.

Definition at line 1047 of file HeapGuard.c.

◆ ClearBits()

STATIC VOID ClearBits	(	IN EFI_PHYSICAL_ADDRESS	Address,
		IN UINTN	BitNumber,
		IN UINT64 *	BitMap
	)

Set corresponding bits in bitmap table to 0 according to the address.

Parameters

[in]	Address	Start address to set for.
[in]	BitNumber	Number of bits to set.
[in]	BitMap	Pointer to bitmap which covers the Address.

Returns: VOID.

Definition at line 113 of file HeapGuard.c.

◆ ClearGuardedMemoryBits()

VOID EFIAPI ClearGuardedMemoryBits	(	IN EFI_PHYSICAL_ADDRESS	Address,
		IN UINTN	NumberOfPages
	)

Clear corresponding bits in bitmap table according to given memory range.

Parameters

[in]	Address	Memory address to unset from.
[in]	NumberOfPages	Number of pages to unset guard.

Returns: VOID.

Definition at line 349 of file HeapGuard.c.

◆ CoreConvertPagesWithGuard()

EFI_STATUS CoreConvertPagesWithGuard	(	IN UINT64	Start,
		IN UINTN	NumberOfPages,
		IN EFI_MEMORY_TYPE	NewType
	)

Allocate or free guarded memory.

Parameters

[in]	Start	Start address of memory to allocate or free.
[in]	NumberOfPages	Memory size in pages.
[in]	NewType	Memory type to convert to.

Returns: VOID.

Definition at line 1079 of file HeapGuard.c.

◆ DumpGuardedMemoryBitmap()

VOID EFIAPI DumpGuardedMemoryBitmap ( VOID )

Dump the guarded memory bit map.

Definition at line 1659 of file HeapGuard.c.

◆ FindGuardedMemoryMap()

UINTN FindGuardedMemoryMap	(	IN EFI_PHYSICAL_ADDRESS	Address,
		IN BOOLEAN	AllocMapUnit,
		OUT UINT64 **	BitMap
	)

Locate the pointer of bitmap from the guarded memory bitmap tables, which covers the given Address.

Parameters

[in]	Address	Start address to search the bitmap for.
[in]	AllocMapUnit	Flag to indicate memory allocation for the table.
[out]	BitMap	Pointer to bitmap which covers the Address.

Returns: The bit number from given Address to the end of current map table.

Definition at line 217 of file HeapGuard.c.

◆ GetBits()

STATIC UINT64 GetBits	(	IN EFI_PHYSICAL_ADDRESS	Address,
		IN UINTN	BitNumber,
		IN UINT64 *	BitMap
	)

Get corresponding bits in bitmap table according to the address.

The value of bit 0 corresponds to the status of memory at given Address. No more than 64 bits can be retrieved in one call.

Parameters

[in]	Address	Start address to retrieve bits for.
[in]	BitNumber	Number of bits to get.
[in]	BitMap	Pointer to bitmap which covers the Address.

Returns: An integer containing the bits information.

Definition at line 168 of file HeapGuard.c.

◆ GetGuardedMemoryBits()

UINT64 GetGuardedMemoryBits	(	IN EFI_PHYSICAL_ADDRESS	Address,
		IN UINTN	NumberOfPages
	)

Retrieve corresponding bits in bitmap table according to given memory range.

Parameters

[in]	Address	Memory address to retrieve from.
[in]	NumberOfPages	Number of pages to retrieve.

Returns: An integer containing the guarded memory bitmap.

Definition at line 385 of file HeapGuard.c.

◆ GetGuardMapBit()

UINTN EFIAPI GetGuardMapBit ( IN EFI_PHYSICAL_ADDRESS Address )

Get bit value in bitmap table for the given address.

Parameters

[in] Address The address to retrieve for.

Returns: 1 or 0.

Definition at line 431 of file HeapGuard.c.

◆ GetLastGuardedFreePageAddress()

VOID GetLastGuardedFreePageAddress ( OUT EFI_PHYSICAL_ADDRESS * Address )

Find the address of top-most guarded free page.

Parameters

[out] Address Start address of top-most guarded free page.

Returns: VOID.

Definition at line 1225 of file HeapGuard.c.

◆ GuardAllFreedPages()

VOID GuardAllFreedPages ( VOID )

Mark all pages freed before CPU Arch Protocol as not-present.

Definition at line 1365 of file HeapGuard.c.

◆ GuardFreedPages()

VOID EFIAPI GuardFreedPages	(	IN EFI_PHYSICAL_ADDRESS	BaseAddress,
		IN UINTN	Pages
	)

Record freed pages as well as mark them as not-present.

Parameters

[in]	BaseAddress	Base address of just freed pages.
[in]	Pages	Number of freed pages.

Returns: VOID.

Definition at line 1295 of file HeapGuard.c.

◆ GuardFreedPagesChecked()

VOID EFIAPI GuardFreedPagesChecked	(	IN EFI_PHYSICAL_ADDRESS	BaseAddress,
		IN UINTN	Pages
	)

Record freed pages as well as mark them as not-present, if enabled.

Parameters

[in]	BaseAddress	Base address of just freed pages.
[in]	Pages	Number of freed pages.

Returns: VOID.

Definition at line 1350 of file HeapGuard.c.

◆ HeapGuardCpuArchProtocolNotify()

VOID HeapGuardCpuArchProtocolNotify ( VOID )

Notify function used to set all Guard pages before CPU Arch Protocol installed.

Definition at line 1604 of file HeapGuard.c.

◆ IsGuardPage()

BOOLEAN EFIAPI IsGuardPage ( IN EFI_PHYSICAL_ADDRESS Address )

Check to see if the page at the given address is a Guard page or not.

Parameters

[in] Address The address to check for.

Returns: TRUE The page at Address is a Guard page.; FALSE The page at Address is not a Guard page.

Definition at line 461 of file HeapGuard.c.

◆ IsHeapGuardEnabled()

BOOLEAN IsHeapGuardEnabled ( UINT8 GuardType )

Check to see if the heap guard is enabled for page and/or pool allocation.

Parameters

[in] GuardType Specify the sub-type(s) of Heap Guard.

Returns: TRUE/FALSE.

Definition at line 674 of file HeapGuard.c.

◆ IsMemoryGuarded()

BOOLEAN EFIAPI IsMemoryGuarded ( IN EFI_PHYSICAL_ADDRESS Address )

Check to see if the page at the given address is guarded or not.

Parameters

[in] Address The address to check for.

Returns: TRUE The page at Address is guarded.; FALSE The page at Address is not guarded.

Definition at line 486 of file HeapGuard.c.

◆ IsMemoryTypeToGuard()

BOOLEAN IsMemoryTypeToGuard	(	IN EFI_MEMORY_TYPE	MemoryType,
		IN EFI_ALLOCATE_TYPE	AllocateType,
		IN UINT8	PageOrPool
	)

Check to see if the memory at the given address should be guarded or not.

Parameters

[in]	MemoryType	Memory type to check.
[in]	AllocateType	Allocation type to check.
[in]	PageOrPool	Indicate a page allocation or pool allocation.

Returns: TRUE The given type of memory should be guarded.; FALSE The given type of memory should not be guarded.

Definition at line 587 of file HeapGuard.c.

◆ IsPageTypeToGuard()

BOOLEAN IsPageTypeToGuard	(	IN EFI_MEMORY_TYPE	MemoryType,
		IN EFI_ALLOCATE_TYPE	AllocateType
	)

Check to see if the page at the given address should be guarded or not.

Parameters

[in]	MemoryType	Page type to check.
[in]	AllocateType	Allocation type to check.

Returns: TRUE The given type of page should be guarded.; FALSE The given type of page should not be guarded.

Definition at line 658 of file HeapGuard.c.

◆ IsPoolTypeToGuard()

BOOLEAN IsPoolTypeToGuard ( IN EFI_MEMORY_TYPE MemoryType )

Check to see if the pool at the given address should be guarded or not.

Parameters

[in] MemoryType Pool type to check.

Returns: TRUE The given type of pool should be guarded.; FALSE The given type of pool should not be guarded.

Definition at line 637 of file HeapGuard.c.

◆ MarkFreedPages()

VOID MarkFreedPages	(	IN EFI_PHYSICAL_ADDRESS	BaseAddress,
		IN UINTN	Pages
	)

Record freed pages.

Parameters

[in]	BaseAddress	Base address of just freed pages.
[in]	Pages	Number of freed pages.

Returns: VOID.

Definition at line 1277 of file HeapGuard.c.

◆ MergeGuardPages()

VOID MergeGuardPages	(	IN EFI_MEMORY_DESCRIPTOR *	MemoryMapEntry,
		IN EFI_PHYSICAL_ADDRESS	MaxAddress
	)

This function checks to see if the given memory map descriptor in a memory map can be merged with any guarded free pages.

Parameters

MemoryMapEntry	A pointer to a descriptor in MemoryMap.
MaxAddress	Maximum address to stop the merge.

Returns: VOID

Definition at line 1476 of file HeapGuard.c.

◆ PromoteGuardedFreePages()

BOOLEAN PromoteGuardedFreePages	(	OUT EFI_PHYSICAL_ADDRESS *	StartAddress,
		OUT EFI_PHYSICAL_ADDRESS *	EndAddress
	)

Put part (at most 64 pages a time) guarded free pages back to free page pool.

Freed memory guard is used to detect Use-After-Free (UAF) memory issue, which makes use of 'Used then throw away' way to detect any illegal access to freed memory. The thrown-away memory will be marked as not-present so that any access to those memory (after free) will be caught by page-fault exception.

The problem is that this will consume lots of memory space. Once no memory left in pool to allocate, we have to restore part of the freed pages to their normal function. Otherwise the whole system will stop functioning.

Parameters

StartAddress	Start address of promoted memory.
EndAddress	End address of promoted memory.

Returns: TRUE Succeeded to promote memory.; FALSE No free memory found.

Definition at line 1531 of file HeapGuard.c.

◆ SetAllGuardPages()

VOID SetAllGuardPages ( VOID )

Set all Guard pages which cannot be set before CPU Arch Protocol installed.

Definition at line 1115 of file HeapGuard.c.

◆ SetBits()

STATIC VOID SetBits	(	IN EFI_PHYSICAL_ADDRESS	Address,
		IN UINTN	BitNumber,
		IN UINT64 *	BitMap
	)

Set corresponding bits in bitmap table to 1 according to the address.

Parameters

[in]	Address	Start address to set for.
[in]	BitNumber	Number of bits to set.
[in]	BitMap	Pointer to bitmap which covers the Address.

Returns: VOID.

Definition at line 57 of file HeapGuard.c.

◆ SetGuardedMemoryBits()

VOID EFIAPI SetGuardedMemoryBits	(	IN EFI_PHYSICAL_ADDRESS	Address,
		IN UINTN	NumberOfPages
	)

Set corresponding bits in bitmap table to 1 according to given memory range.

Parameters

[in]	Address	Memory address to guard from.
[in]	NumberOfPages	Number of pages to guard.

Returns: VOID.

Definition at line 312 of file HeapGuard.c.

◆ SetGuardForMemory()

VOID SetGuardForMemory	(	IN EFI_PHYSICAL_ADDRESS	Memory,
		IN UINTN	NumberOfPages
	)

Set head Guard and tail Guard for the given memory range.

Parameters

[in]	Memory	Base address of memory to set guard for.
[in]	NumberOfPages	Memory size in pages.

Returns: VOID

Definition at line 690 of file HeapGuard.c.

◆ SetGuardPage()

VOID EFIAPI SetGuardPage ( IN EFI_PHYSICAL_ADDRESS BaseAddress )

Set the page at the given address to be a Guard page.

This is done by changing the page table attribute to be NOT PRSENT.

Parameters

[in] BaseAddress Page address to Guard at

Returns: VOID

Definition at line 504 of file HeapGuard.c.

◆ Uint64ToBinString()

VOID Uint64ToBinString	(	IN UINT64	Value,
		OUT CHAR8 *	BinString
	)

Helper function to convert a UINT64 value in binary to a string.

Parameters

[in]	Value	Value of a UINT64 integer.
[out]	BinString	String buffer to contain the conversion result.

Returns: VOID.

Definition at line 1635 of file HeapGuard.c.

◆ UnsetGuardForMemory()

VOID UnsetGuardForMemory	(	IN EFI_PHYSICAL_ADDRESS	Memory,
		IN UINTN	NumberOfPages
	)

Unset head Guard and tail Guard for the given memory range.

Parameters

[in]	Memory	Base address of memory to unset guard for.
[in]	NumberOfPages	Memory size in pages.

Returns: VOID

Definition at line 726 of file HeapGuard.c.

◆ UnsetGuardPage()

VOID EFIAPI UnsetGuardPage ( IN EFI_PHYSICAL_ADDRESS BaseAddress )

Unset the Guard page at the given address to the normal memory.

This is done by changing the page table attribute to be PRSENT.

Parameters

[in] BaseAddress Page address to Guard at.

Returns: VOID.

Definition at line 539 of file HeapGuard.c.

Variable Documentation

◆ mGuardedMemoryMap

GLOBAL_REMOVE_IF_UNREFERENCED UINT64 mGuardedMemoryMap = 0

Definition at line 24 of file HeapGuard.c.

◆ mLastPromotedPage

GLOBAL_REMOVE_IF_UNREFERENCED EFI_PHYSICAL_ADDRESS mLastPromotedPage = BASE_4GB

Definition at line 44 of file HeapGuard.c.

◆ mLevelMask

GLOBAL_REMOVE_IF_UNREFERENCED UINTN mLevelMask[GUARDED_HEAP_MAP_TABLE_DEPTH] = GUARDED_HEAP_MAP_TABLE_DEPTH_MASKS

Definition at line 38 of file HeapGuard.c.

◆ mLevelShift

GLOBAL_REMOVE_IF_UNREFERENCED UINTN mLevelShift[GUARDED_HEAP_MAP_TABLE_DEPTH] = GUARDED_HEAP_MAP_TABLE_DEPTH_SHIFTS

Definition at line 36 of file HeapGuard.c.

◆ mMapLevel

GLOBAL_REMOVE_IF_UNREFERENCED UINTN mMapLevel = 1

Definition at line 31 of file HeapGuard.c.

◆ mOnGuarding

GLOBAL_REMOVE_IF_UNREFERENCED BOOLEAN mOnGuarding = FALSE

Definition at line 17 of file HeapGuard.c.

Functions

Variables

Detailed Description

Function Documentation

◆ AdjustMemoryA()

◆ AdjustMemoryF()

◆ AdjustMemoryS()

◆ AdjustPoolHeadA()

◆ AdjustPoolHeadF()

◆ ClearBits()

◆ ClearGuardedMemoryBits()

◆ CoreConvertPagesWithGuard()

◆ DumpGuardedMemoryBitmap()

◆ FindGuardedMemoryMap()

◆ GetBits()

◆ GetGuardedMemoryBits()

◆ GetGuardMapBit()

◆ GetLastGuardedFreePageAddress()

◆ GuardAllFreedPages()

◆ GuardFreedPages()

◆ GuardFreedPagesChecked()

◆ HeapGuardCpuArchProtocolNotify()

◆ IsGuardPage()

◆ IsHeapGuardEnabled()

◆ IsMemoryGuarded()

◆ IsMemoryTypeToGuard()

◆ IsPageTypeToGuard()

◆ IsPoolTypeToGuard()

◆ MarkFreedPages()

◆ MergeGuardPages()

◆ PromoteGuardedFreePages()

◆ SetAllGuardPages()

◆ SetBits()

◆ SetGuardedMemoryBits()

◆ SetGuardForMemory()

◆ SetGuardPage()

◆ Uint64ToBinString()

◆ UnsetGuardForMemory()

◆ UnsetGuardPage()

Variable Documentation

◆ mGuardedMemoryMap

◆ mLastPromotedPage

◆ mLevelMask

◆ mLevelShift

◆ mMapLevel

◆ mOnGuarding