7208ab143719a2b2923b9db97585d52de000f891
[mirror_edk2.git] / MdeModulePkg / Core / Dxe / Mem / HeapGuard.h
1 /** @file
2 Data type, macros and function prototypes of heap guard feature.
3
4 Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef _HEAPGUARD_H_
16 #define _HEAPGUARD_H_
17
18 //
19 // Following macros are used to define and access the guarded memory bitmap
20 // table.
21 //
22 // To simplify the access and reduce the memory used for this table, the
23 // table is constructed in the similar way as page table structure but in
24 // reverse direction, i.e. from bottom growing up to top.
25 //
26 // - 1-bit tracks 1 page (4KB)
27 // - 1-UINT64 map entry tracks 256KB memory
28 // - 1K-UINT64 map table tracks 256MB memory
29 // - Five levels of tables can track any address of memory of 64-bit
30 // system, like below.
31 //
32 // 512 * 512 * 512 * 512 * 1K * 64b * 4K
33 // 111111111 111111111 111111111 111111111 1111111111 111111 111111111111
34 // 63 54 45 36 27 17 11 0
35 // 9b 9b 9b 9b 10b 6b 12b
36 // L0 -> L1 -> L2 -> L3 -> L4 -> bits -> page
37 // 1FF 1FF 1FF 1FF 3FF 3F FFF
38 //
39 // L4 table has 1K * sizeof(UINT64) = 8K (2-page), which can track 256MB
40 // memory. Each table of L0-L3 will be allocated when its memory address
41 // range is to be tracked. Only 1-page will be allocated each time. This
42 // can save memories used to establish this map table.
43 //
44 // For a normal configuration of system with 4G memory, two levels of tables
45 // can track the whole memory, because two levels (L3+L4) of map tables have
46 // already coverred 37-bit of memory address. And for a normal UEFI BIOS,
47 // less than 128M memory would be consumed during boot. That means we just
48 // need
49 //
50 // 1-page (L3) + 2-page (L4)
51 //
52 // memory (3 pages) to track the memory allocation works. In this case,
53 // there's no need to setup L0-L2 tables.
54 //
55
56 //
57 // Each entry occupies 8B/64b. 1-page can hold 512 entries, which spans 9
58 // bits in address. (512 = 1 << 9)
59 //
60 #define BYTE_LENGTH_SHIFT 3 // (8 = 1 << 3)
61
62 #define GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT \
63 (EFI_PAGE_SHIFT - BYTE_LENGTH_SHIFT)
64
65 #define GUARDED_HEAP_MAP_TABLE_DEPTH 5
66
67 // Use UINT64_index + bit_index_of_UINT64 to locate the bit in may
68 #define GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT 6 // (64 = 1 << 6)
69
70 #define GUARDED_HEAP_MAP_ENTRY_BITS \
71 (1 << GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT)
72
73 #define GUARDED_HEAP_MAP_ENTRY_BYTES \
74 (GUARDED_HEAP_MAP_ENTRY_BITS / 8)
75
76 // L4 table address width: 64 - 9 * 4 - 6 - 12 = 10b
77 #define GUARDED_HEAP_MAP_ENTRY_SHIFT \
78 (GUARDED_HEAP_MAP_ENTRY_BITS \
79 - GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT * 4 \
80 - GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT \
81 - EFI_PAGE_SHIFT)
82
83 // L4 table address mask: (1 << 10 - 1) = 0x3FF
84 #define GUARDED_HEAP_MAP_ENTRY_MASK \
85 ((1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) - 1)
86
87 // Size of each L4 table: (1 << 10) * 8 = 8KB = 2-page
88 #define GUARDED_HEAP_MAP_SIZE \
89 ((1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) * GUARDED_HEAP_MAP_ENTRY_BYTES)
90
91 // Memory size tracked by one L4 table: 8KB * 8 * 4KB = 256MB
92 #define GUARDED_HEAP_MAP_UNIT_SIZE \
93 (GUARDED_HEAP_MAP_SIZE * 8 * EFI_PAGE_SIZE)
94
95 // L4 table entry number: 8KB / 8 = 1024
96 #define GUARDED_HEAP_MAP_ENTRIES_PER_UNIT \
97 (GUARDED_HEAP_MAP_SIZE / GUARDED_HEAP_MAP_ENTRY_BYTES)
98
99 // L4 table entry indexing
100 #define GUARDED_HEAP_MAP_ENTRY_INDEX(Address) \
101 (RShiftU64 (Address, EFI_PAGE_SHIFT \
102 + GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT) \
103 & GUARDED_HEAP_MAP_ENTRY_MASK)
104
105 // L4 table entry bit indexing
106 #define GUARDED_HEAP_MAP_ENTRY_BIT_INDEX(Address) \
107 (RShiftU64 (Address, EFI_PAGE_SHIFT) \
108 & ((1 << GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT) - 1))
109
110 //
111 // Total bits (pages) tracked by one L4 table (65536-bit)
112 //
113 #define GUARDED_HEAP_MAP_BITS \
114 (1 << (GUARDED_HEAP_MAP_ENTRY_SHIFT \
115 + GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT))
116
117 //
118 // Bit indexing inside the whole L4 table (0 - 65535)
119 //
120 #define GUARDED_HEAP_MAP_BIT_INDEX(Address) \
121 (RShiftU64 (Address, EFI_PAGE_SHIFT) \
122 & ((1 << (GUARDED_HEAP_MAP_ENTRY_SHIFT \
123 + GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT)) - 1))
124
125 //
126 // Memory address bit width tracked by L4 table: 10 + 6 + 12 = 28
127 //
128 #define GUARDED_HEAP_MAP_TABLE_SHIFT \
129 (GUARDED_HEAP_MAP_ENTRY_SHIFT + GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT \
130 + EFI_PAGE_SHIFT)
131
132 //
133 // Macro used to initialize the local array variable for map table traversing
134 // {55, 46, 37, 28, 18}
135 //
136 #define GUARDED_HEAP_MAP_TABLE_DEPTH_SHIFTS \
137 { \
138 GUARDED_HEAP_MAP_TABLE_SHIFT + GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT * 3, \
139 GUARDED_HEAP_MAP_TABLE_SHIFT + GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT * 2, \
140 GUARDED_HEAP_MAP_TABLE_SHIFT + GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT, \
141 GUARDED_HEAP_MAP_TABLE_SHIFT, \
142 EFI_PAGE_SHIFT + GUARDED_HEAP_MAP_ENTRY_BIT_SHIFT \
143 }
144
145 //
146 // Masks used to extract address range of each level of table
147 // {0x1FF, 0x1FF, 0x1FF, 0x1FF, 0x3FF}
148 //
149 #define GUARDED_HEAP_MAP_TABLE_DEPTH_MASKS \
150 { \
151 (1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
152 (1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
153 (1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
154 (1 << GUARDED_HEAP_MAP_TABLE_ENTRY_SHIFT) - 1, \
155 (1 << GUARDED_HEAP_MAP_ENTRY_SHIFT) - 1 \
156 }
157
158 //
159 // Memory type to guard (matching the related PCD definition)
160 //
161 #define GUARD_HEAP_TYPE_PAGE BIT0
162 #define GUARD_HEAP_TYPE_POOL BIT1
163
164 //
165 // Debug message level
166 //
167 #define HEAP_GUARD_DEBUG_LEVEL (DEBUG_POOL|DEBUG_PAGE)
168
169 typedef struct {
170 UINT32 TailMark;
171 UINT32 HeadMark;
172 EFI_PHYSICAL_ADDRESS Address;
173 LIST_ENTRY Link;
174 } HEAP_GUARD_NODE;
175
176 /**
177 Internal function. Converts a memory range to the specified type.
178 The range must exist in the memory map.
179
180 @param Start The first address of the range Must be page
181 aligned.
182 @param NumberOfPages The number of pages to convert.
183 @param NewType The new type for the memory range.
184
185 @retval EFI_INVALID_PARAMETER Invalid parameter.
186 @retval EFI_NOT_FOUND Could not find a descriptor cover the specified
187 range or convertion not allowed.
188 @retval EFI_SUCCESS Successfully converts the memory range to the
189 specified type.
190
191 **/
192 EFI_STATUS
193 CoreConvertPages (
194 IN UINT64 Start,
195 IN UINT64 NumberOfPages,
196 IN EFI_MEMORY_TYPE NewType
197 );
198
199 /**
200 Allocate or free guarded memory.
201
202 @param[in] Start Start address of memory to allocate or free.
203 @param[in] NumberOfPages Memory size in pages.
204 @param[in] NewType Memory type to convert to.
205
206 @return VOID.
207 **/
208 EFI_STATUS
209 CoreConvertPagesWithGuard (
210 IN UINT64 Start,
211 IN UINTN NumberOfPages,
212 IN EFI_MEMORY_TYPE NewType
213 );
214
215 /**
216 Set head Guard and tail Guard for the given memory range.
217
218 @param[in] Memory Base address of memory to set guard for.
219 @param[in] NumberOfPages Memory size in pages.
220
221 @return VOID.
222 **/
223 VOID
224 SetGuardForMemory (
225 IN EFI_PHYSICAL_ADDRESS Memory,
226 IN UINTN NumberOfPages
227 );
228
229 /**
230 Unset head Guard and tail Guard for the given memory range.
231
232 @param[in] Memory Base address of memory to unset guard for.
233 @param[in] NumberOfPages Memory size in pages.
234
235 @return VOID.
236 **/
237 VOID
238 UnsetGuardForMemory (
239 IN EFI_PHYSICAL_ADDRESS Memory,
240 IN UINTN NumberOfPages
241 );
242
243 /**
244 Adjust the base and number of pages to really allocate according to Guard.
245
246 @param[in,out] Memory Base address of free memory.
247 @param[in,out] NumberOfPages Size of memory to allocate.
248
249 @return VOID.
250 **/
251 VOID
252 AdjustMemoryA (
253 IN OUT EFI_PHYSICAL_ADDRESS *Memory,
254 IN OUT UINTN *NumberOfPages
255 );
256
257 /**
258 Adjust the start address and number of pages to free according to Guard.
259
260 The purpose of this function is to keep the shared Guard page with adjacent
261 memory block if it's still in guard, or free it if no more sharing. Another
262 is to reserve pages as Guard pages in partial page free situation.
263
264 @param[in,out] Memory Base address of memory to free.
265 @param[in,out] NumberOfPages Size of memory to free.
266
267 @return VOID.
268 **/
269 VOID
270 AdjustMemoryF (
271 IN OUT EFI_PHYSICAL_ADDRESS *Memory,
272 IN OUT UINTN *NumberOfPages
273 );
274
275 /**
276 Adjust address of free memory according to existing and/or required Guard.
277
278 This function will check if there're existing Guard pages of adjacent
279 memory blocks, and try to use it as the Guard page of the memory to be
280 allocated.
281
282 @param[in] Start Start address of free memory block.
283 @param[in] Size Size of free memory block.
284 @param[in] SizeRequested Size of memory to allocate.
285
286 @return The end address of memory block found.
287 @return 0 if no enough space for the required size of memory and its Guard.
288 **/
289 UINT64
290 AdjustMemoryS (
291 IN UINT64 Start,
292 IN UINT64 Size,
293 IN UINT64 SizeRequested
294 );
295
296 /**
297 Check to see if the pool at the given address should be guarded or not.
298
299 @param[in] MemoryType Pool type to check.
300
301
302 @return TRUE The given type of pool should be guarded.
303 @return FALSE The given type of pool should not be guarded.
304 **/
305 BOOLEAN
306 IsPoolTypeToGuard (
307 IN EFI_MEMORY_TYPE MemoryType
308 );
309
310 /**
311 Check to see if the page at the given address should be guarded or not.
312
313 @param[in] MemoryType Page type to check.
314 @param[in] AllocateType Allocation type to check.
315
316 @return TRUE The given type of page should be guarded.
317 @return FALSE The given type of page should not be guarded.
318 **/
319 BOOLEAN
320 IsPageTypeToGuard (
321 IN EFI_MEMORY_TYPE MemoryType,
322 IN EFI_ALLOCATE_TYPE AllocateType
323 );
324
325 /**
326 Check to see if the page at the given address is guarded or not.
327
328 @param[in] Address The address to check for.
329
330 @return TRUE The page at Address is guarded.
331 @return FALSE The page at Address is not guarded.
332 **/
333 BOOLEAN
334 EFIAPI
335 IsMemoryGuarded (
336 IN EFI_PHYSICAL_ADDRESS Address
337 );
338
339 /**
340 Check to see if the page at the given address is a Guard page or not.
341
342 @param[in] Address The address to check for.
343
344 @return TRUE The page at Address is a Guard page.
345 @return FALSE The page at Address is not a Guard page.
346 **/
347 BOOLEAN
348 EFIAPI
349 IsGuardPage (
350 IN EFI_PHYSICAL_ADDRESS Address
351 );
352
353 /**
354 Dump the guarded memory bit map.
355 **/
356 VOID
357 EFIAPI
358 DumpGuardedMemoryBitmap (
359 VOID
360 );
361
362 /**
363 Adjust the pool head position to make sure the Guard page is adjavent to
364 pool tail or pool head.
365
366 @param[in] Memory Base address of memory allocated.
367 @param[in] NoPages Number of pages actually allocated.
368 @param[in] Size Size of memory requested.
369 (plus pool head/tail overhead)
370
371 @return Address of pool head.
372 **/
373 VOID *
374 AdjustPoolHeadA (
375 IN EFI_PHYSICAL_ADDRESS Memory,
376 IN UINTN NoPages,
377 IN UINTN Size
378 );
379
380 /**
381 Get the page base address according to pool head address.
382
383 @param[in] Memory Head address of pool to free.
384
385 @return Address of pool head.
386 **/
387 VOID *
388 AdjustPoolHeadF (
389 IN EFI_PHYSICAL_ADDRESS Memory
390 );
391
392 /**
393 Check to see if the heap guard is enabled for page and/or pool allocation.
394
395 @return TRUE/FALSE.
396 **/
397 BOOLEAN
398 IsHeapGuardEnabled (
399 VOID
400 );
401
402 extern BOOLEAN mOnGuarding;
403
404 #endif