TianoCore EDK2 master
Loading...
Searching...
No Matches
HeapGuard.h File Reference

Go to the source code of this file.

Data Structures

struct  HEAP_GUARD_NODE
 

Macros

#define BYTE_LENGTH_SHIFT   3
 
#define GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT    (EFI_PAGE_SHIFT - BYTE_LENGTH_SHIFT)
 
#define GUARDED_HEAP_MAP_TABLE_DEPTH   5
 
#define GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT   6
 
#define GUARDED_HEAP_MAP_ENTRY_BITS    (1 << GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT)
 
#define GUARDED_HEAP_MAP_ENTRY_BYTES    (GUARDED_HEAP_MAP_ENTRY_BITS / 8)
 
#define GUARDED_HEAP_MAP_ENTRY_SHIFT
 
#define GUARDED_HEAP_MAP_ENTRY_MASK    ((1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) - 1)
 
#define GUARDED_HEAP_MAP_SIZE    ((1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) * GUARDED_HEAP_MAP_ENTRY_BYTES)
 
#define GUARDED_HEAP_MAP_UNIT_SIZE    (GUARDED_HEAP_MAP_SIZE * 8 * EFI_PAGE_SIZE)
 
#define GUARDED_HEAP_MAP_ENTRIES_PER_UNIT    (GUARDED_HEAP_MAP_SIZE / GUARDED_HEAP_MAP_ENTRY_BYTES)
 
#define GUARDED_HEAP_MAP_ENTRY_INDEX(Address)
 
#define GUARDED_HEAP_MAP_ENTRY_BIT_INDEX(Address)
 
#define GUARDED_HEAP_MAP_BITS
 
#define GUARDED_HEAP_MAP_BIT_INDEX(Address)
 
#define GUARDED_HEAP_MAP_TABLE_SHIFT
 
#define GUARDED_HEAP_MAP_TABLE_DEPTH_SHIFTS
 
#define GUARDED_HEAP_MAP_TABLE_DEPTH_MASKS
 
#define GUARD_HEAP_TYPE_PAGE   BIT0
 
#define GUARD_HEAP_TYPE_POOL   BIT1
 
#define GUARD_HEAP_TYPE_FREED   BIT4
 
#define GUARD_HEAP_TYPE_ALL    (GUARD_HEAP_TYPE_PAGE|GUARD_HEAP_TYPE_POOL|GUARD_HEAP_TYPE_FREED)
 
#define HEAP_GUARD_DEBUG_LEVEL   (DEBUG_POOL|DEBUG_PAGE)
 

Functions

EFI_STATUS CoreConvertPages (IN UINT64 Start, IN UINT64 NumberOfPages, IN EFI_MEMORY_TYPE NewType)
 
EFI_STATUS CoreConvertPagesWithGuard (IN UINT64 Start, IN UINTN NumberOfPages, IN EFI_MEMORY_TYPE NewType)
 
VOID SetGuardForMemory (IN EFI_PHYSICAL_ADDRESS Memory, IN UINTN NumberOfPages)
 
VOID UnsetGuardForMemory (IN EFI_PHYSICAL_ADDRESS Memory, IN UINTN NumberOfPages)
 
VOID AdjustMemoryA (IN OUT EFI_PHYSICAL_ADDRESS *Memory, IN OUT UINTN *NumberOfPages)
 
VOID AdjustMemoryF (IN OUT EFI_PHYSICAL_ADDRESS *Memory, IN OUT UINTN *NumberOfPages)
 
UINT64 AdjustMemoryS (IN UINT64 Start, IN UINT64 Size, IN UINT64 SizeRequested)
 
BOOLEAN IsPoolTypeToGuard (IN EFI_MEMORY_TYPE MemoryType)
 
BOOLEAN IsPageTypeToGuard (IN EFI_MEMORY_TYPE MemoryType, IN EFI_ALLOCATE_TYPE AllocateType)
 
BOOLEAN EFIAPI IsMemoryGuarded (IN EFI_PHYSICAL_ADDRESS Address)
 
BOOLEAN EFIAPI IsGuardPage (IN EFI_PHYSICAL_ADDRESS Address)
 
VOID EFIAPI DumpGuardedMemoryBitmap (VOID)
 
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)
 
BOOLEAN IsHeapGuardEnabled (UINT8 GuardType)
 
VOID HeapGuardCpuArchProtocolNotify (VOID)
 
VOID MergeGuardPages (IN EFI_MEMORY_DESCRIPTOR *MemoryMapEntry, IN EFI_PHYSICAL_ADDRESS MaxAddress)
 
VOID EFIAPI GuardFreedPagesChecked (IN EFI_PHYSICAL_ADDRESS BaseAddress, IN UINTN Pages)
 
BOOLEAN PromoteGuardedFreePages (OUT EFI_PHYSICAL_ADDRESS *StartAddress, OUT EFI_PHYSICAL_ADDRESS *EndAddress)
 
 STATIC_ASSERT (RUNTIME_PAGE_ALLOCATION_GRANULARITY==EFI_PAGE_SIZE||(((FixedPcdGet64(PcdHeapGuardPageType) &0x461)==0) &&((FixedPcdGet64(PcdHeapGuardPoolType) &0x461)==0)), "Unsupported Heap Guard configuration on system with greater than EFI_PAGE_SIZE RUNTIME_PAGE_ALLOCATION_GRANULARITY")
 

Variables

BOOLEAN mOnGuarding
 

Detailed Description

Data type, macros and function prototypes of heap guard feature.

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

Definition in file HeapGuard.h.

Macro Definition Documentation

◆ BYTE_LENGTH_SHIFT

#define BYTE_LENGTH_SHIFT   3

Definition at line 54 of file HeapGuard.h.

◆ GUARD_HEAP_TYPE_ALL

#define GUARD_HEAP_TYPE_ALL    (GUARD_HEAP_TYPE_PAGE|GUARD_HEAP_TYPE_POOL|GUARD_HEAP_TYPE_FREED)

Definition at line 158 of file HeapGuard.h.

◆ GUARD_HEAP_TYPE_FREED

#define GUARD_HEAP_TYPE_FREED   BIT4

Definition at line 157 of file HeapGuard.h.

◆ GUARD_HEAP_TYPE_PAGE

#define GUARD_HEAP_TYPE_PAGE   BIT0

Definition at line 155 of file HeapGuard.h.

◆ GUARD_HEAP_TYPE_POOL

#define GUARD_HEAP_TYPE_POOL   BIT1

Definition at line 156 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_BIT_INDEX

#define GUARDED_HEAP_MAP_BIT_INDEX (   Address)
Value:
(RShiftU64 (Address, EFI_PAGE_SHIFT) \
& ((1 << (GUARDED_HEAP_MAP_ENTRY_SHIFT \
+ GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT)) - 1))
UINT64 EFIAPI RShiftU64(IN UINT64 Operand, IN UINTN Count)
Definition: RShiftU64.c:28

Definition at line 114 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_BITS

#define GUARDED_HEAP_MAP_BITS
Value:
(1 << (GUARDED_HEAP_MAP_ENTRY_SHIFT \
+ GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT))

Definition at line 107 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRIES_PER_UNIT

#define GUARDED_HEAP_MAP_ENTRIES_PER_UNIT    (GUARDED_HEAP_MAP_SIZE / GUARDED_HEAP_MAP_ENTRY_BYTES)

Definition at line 90 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRY_BIT_INDEX

#define GUARDED_HEAP_MAP_ENTRY_BIT_INDEX (   Address)
Value:
(RShiftU64 (Address, EFI_PAGE_SHIFT) \
& ((1 << GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT) - 1))

Definition at line 100 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT

#define GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT   6

Definition at line 62 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRY_BITS

#define GUARDED_HEAP_MAP_ENTRY_BITS    (1 << GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT)

Definition at line 64 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRY_BYTES

#define GUARDED_HEAP_MAP_ENTRY_BYTES    (GUARDED_HEAP_MAP_ENTRY_BITS / 8)

Definition at line 67 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRY_INDEX

#define GUARDED_HEAP_MAP_ENTRY_INDEX (   Address)
Value:
(RShiftU64 (Address, EFI_PAGE_SHIFT \
+ GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT) \
& GUARDED_HEAP_MAP_ENTRY_MASK)

Definition at line 94 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRY_MASK

#define GUARDED_HEAP_MAP_ENTRY_MASK    ((1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) - 1)

Definition at line 78 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_ENTRY_SHIFT

#define GUARDED_HEAP_MAP_ENTRY_SHIFT
Value:
(GUARDED_HEAP_MAP_ENTRY_BITS \
- GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT * 4 \
- GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT \
- EFI_PAGE_SHIFT)

Definition at line 71 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_SIZE

#define GUARDED_HEAP_MAP_SIZE    ((1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) * GUARDED_HEAP_MAP_ENTRY_BYTES)

Definition at line 82 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_TABLE_DEPTH

#define GUARDED_HEAP_MAP_TABLE_DEPTH   5

Definition at line 59 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_TABLE_DEPTH_MASKS

#define GUARDED_HEAP_MAP_TABLE_DEPTH_MASKS
Value:
{ \
(1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
(1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
(1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
(1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
(1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) - 1 \
}

Definition at line 143 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_TABLE_DEPTH_SHIFTS

#define GUARDED_HEAP_MAP_TABLE_DEPTH_SHIFTS
Value:
{ \
GUARDED_HEAP_MAP_TABLE_SHIFT + GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT * 3, \
GUARDED_HEAP_MAP_TABLE_SHIFT + GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT * 2, \
GUARDED_HEAP_MAP_TABLE_SHIFT + GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT, \
GUARDED_HEAP_MAP_TABLE_SHIFT, \
EFI_PAGE_SHIFT + GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT \
}

Definition at line 130 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT

#define GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT    (EFI_PAGE_SHIFT - BYTE_LENGTH_SHIFT)

Definition at line 56 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_TABLE_SHIFT

#define GUARDED_HEAP_MAP_TABLE_SHIFT
Value:
(GUARDED_HEAP_MAP_ENTRY_SHIFT + GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT \
+ EFI_PAGE_SHIFT)

Definition at line 122 of file HeapGuard.h.

◆ GUARDED_HEAP_MAP_UNIT_SIZE

#define GUARDED_HEAP_MAP_UNIT_SIZE    (GUARDED_HEAP_MAP_SIZE * 8 * EFI_PAGE_SIZE)

Definition at line 86 of file HeapGuard.h.

◆ HEAP_GUARD_DEBUG_LEVEL

#define HEAP_GUARD_DEBUG_LEVEL   (DEBUG_POOL|DEBUG_PAGE)

Definition at line 164 of file HeapGuard.h.

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]MemoryBase address of free memory.
[in,out]NumberOfPagesSize 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]MemoryBase address of memory to free.
[in,out]NumberOfPagesSize 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]StartStart address of free memory block.
[in]SizeSize of free memory block.
[in]SizeRequestedSize 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]MemoryBase address of memory allocated.
[in]NoPagesNumber of pages actually allocated.
[in]SizeSize of memory requested. (plus pool head/tail overhead)
Returns
Address of pool head.

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

Parameters
[in]MemoryBase address of memory allocated.
[in]NoPagesNumber of pages actually allocated.
[in]SizeSize 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]MemoryHead address of pool to free.
[in]NoPagesNumber of pages actually allocated.
[in]SizeSize of memory requested. (plus pool head/tail overhead)
Returns
Address of pool head.

Definition at line 1047 of file HeapGuard.c.

◆ CoreConvertPages()

EFI_STATUS CoreConvertPages ( IN UINT64  Start,
IN UINT64  NumberOfPages,
IN EFI_MEMORY_TYPE  NewType 
)

Internal function. Converts a memory range to the specified type. The range must exist in the memory map.

Parameters
StartThe first address of the range Must be page aligned.
NumberOfPagesThe number of pages to convert.
NewTypeThe new type for the memory range.
Return values
EFI_INVALID_PARAMETERInvalid parameter.
EFI_NOT_FOUNDCould not find a descriptor cover the specified range or convertion not allowed.
EFI_SUCCESSSuccessfully converts the memory range to the specified type.

Internal function. Converts a memory range to the specified type. The range must exist in the memory map.

Parameters
StartThe first address of the range Must be page aligned
NumberOfPagesThe number of pages to convert
NewTypeThe new type for the memory range
Return values
EFI_INVALID_PARAMETERInvalid parameter
EFI_NOT_FOUNDCould not find a descriptor cover the specified range or convertion not allowed.
EFI_SUCCESSSuccessfully converts the memory range to the specified type.

Definition at line 1080 of file Page.c.

◆ CoreConvertPagesWithGuard()

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

Allocate or free guarded memory.

Parameters
[in]StartStart address of memory to allocate or free.
[in]NumberOfPagesMemory size in pages.
[in]NewTypeMemory 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.

◆ 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]BaseAddressBase address of just freed pages.
[in]PagesNumber 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 after CPU Arch Protocol installed.

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]AddressThe 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]GuardTypeSpecify 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]AddressThe 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.

◆ 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]MemoryTypePage type to check.
[in]AllocateTypeAllocation 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]MemoryTypePool 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.

◆ 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
MemoryMapEntryA pointer to a descriptor in MemoryMap.
MaxAddressMaximum 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
StartAddressStart address of promoted memory.
EndAddressEnd address of promoted memory.
Returns
TRUE Succeeded to promote memory.
FALSE No free memory found.

Definition at line 1531 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]MemoryBase address of memory to set guard for.
[in]NumberOfPagesMemory size in pages.
Returns
VOID.

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

Parameters
[in]MemoryBase address of memory to set guard for.
[in]NumberOfPagesMemory size in pages.
Returns
VOID

Definition at line 690 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]MemoryBase address of memory to unset guard for.
[in]NumberOfPagesMemory size in pages.
Returns
VOID.

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

Parameters
[in]MemoryBase address of memory to unset guard for.
[in]NumberOfPagesMemory size in pages.
Returns
VOID

Definition at line 726 of file HeapGuard.c.

Variable Documentation

◆ mOnGuarding

BOOLEAN mOnGuarding
extern

Definition at line 17 of file HeapGuard.c.