1/** @file
2Header file for memory allocation tracking functions.
3
4Copyright (c) 2004 - 2014, Intel Corporation. All rights reserved.<BR>
5This program and the accompanying materials
6are licensed and made available under the terms and conditions of the BSD License
7which accompanies this distribution.  The full text of the license may be found at
8http://opensource.org/licenses/bsd-license.php
9
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13**/
14
15#ifndef _MYALLOC_H_
16#define _MYALLOC_H_
17
18#include <stdio.h>
19#include <stdlib.h>
20#include <string.h>
21
22#include <Common/BaseTypes.h>
23
24//
25// Default operation is to use the memory allocation tracking functions.
26// To over-ride add "#define USE_MYALLOC 0" to your program header and/or
27// source files as needed.  Or, just do not include this header file in
28// your project.
29//
30#ifndef USE_MYALLOC
31#define USE_MYALLOC 1
32#endif
33
34#if USE_MYALLOC
35//
36// Replace C library allocation routines with MyAlloc routines.
37//
38#define malloc(size)        MyAlloc ((size), __FILE__, __LINE__)
39#define calloc(count, size) MyAlloc ((count) * (size), __FILE__, __LINE__)
40#define realloc(ptr, size)  MyRealloc ((ptr), (size), __FILE__, __LINE__)
41#define free(ptr)           MyFree ((ptr), __FILE__, __LINE__)
42#define alloc_check(final)  MyCheck ((final), __FILE__, __LINE__)
43
44//
45// Structure for checking/tracking memory allocations.
46//
47typedef struct MyAllocStruct {
48  UINTN                 Cksum;
49  struct MyAllocStruct  *Next;
50  UINTN                 Line;
51  UINTN                 Size;
52  UINT8                 *File;
53  UINT8                 *Buffer;
54} MY_ALLOC_STRUCT;
55//
56// Cksum := (UINTN)This + (UINTN)Next + Line + Size + (UINTN)File +
57//          (UINTN)Buffer;
58//
59// Next := Pointer to next allocation structure in the list.
60//
61// Line := __LINE__
62//
63// Size := Size of allocation request.
64//
65// File := Pointer to __FILE__ string stored immediately following
66//         MY_ALLOC_STRUCT in memory.
67//
68// Buffer := Pointer to UINT32 aligned storage immediately following
69//           the NULL terminated __FILE__ string.  This is UINT32
70//           aligned because the underflow signature is 32-bits and
71//           this will place the first caller address on a 64-bit
72//           boundary.
73//
74//
75// Signatures used to check for buffer overflow/underflow conditions.
76//
77#define MYALLOC_HEAD_MAGIK  0xBADFACED
78#define MYALLOC_TAIL_MAGIK  0xDEADBEEF
79
80VOID
81MyCheck (
82  BOOLEAN      Final,
83  UINT8        File[],
84  UINTN        Line
85  )
86;
87//
88// *++
89// Description:
90//
91//  Check for corruptions in the allocated memory chain.  If a corruption
92//  is detection program operation stops w/ an exit(1) call.
93//
94// Parameters:
95//
96//  Final := When FALSE, MyCheck() returns if the allocated memory chain
97//           has not been corrupted.  When TRUE, MyCheck() returns if there
98//           are no un-freed allocations.  If there are un-freed allocations,
99//           they are displayed and exit(1) is called.
100//
101//
102//  File := Set to __FILE__ by macro expansion.
103//
104//  Line := Set to __LINE__ by macro expansion.
105//
106// Returns:
107//
108//  n/a
109//
110// --*/
111//
112VOID  *
113MyAlloc (
114  UINTN      Size,
115  UINT8      File[],
116  UINTN      Line
117  )
118;
119//
120// *++
121// Description:
122//
123//  Allocate a new link in the allocation chain along with enough storage
124//  for the File[] string, requested Size and alignment overhead.  If
125//  memory cannot be allocated or the allocation chain has been corrupted,
126//  exit(1) will be called.
127//
128// Parameters:
129//
130//  Size := Number of bytes (UINT8) requested by the called.
131//          Size cannot be zero.
132//
133//  File := Set to __FILE__ by macro expansion.
134//
135//  Line := Set to __LINE__ by macro expansion.
136//
137// Returns:
138//
139//  Pointer to the caller's buffer.
140//
141// --*/
142//
143VOID  *
144MyRealloc (
145  VOID       *Ptr,
146  UINTN      Size,
147  UINT8      File[],
148  UINTN      Line
149  )
150;
151//
152// *++
153// Description:
154//
155//  This does a MyAlloc(), memcpy() and MyFree().  There is no optimization
156//  for shrinking or expanding buffers.  An invalid parameter will cause
157//  MyRealloc() to fail with a call to exit(1).
158//
159// Parameters:
160//
161//  Ptr := Pointer to the caller's buffer to be re-allocated.
162//         Ptr cannot be NULL.
163//
164//  Size := Size of new buffer.  Size cannot be zero.
165//
166//  File := Set to __FILE__ by macro expansion.
167//
168//  Line := Set to __LINE__ by macro expansion.
169//
170// Returns:
171//
172//  Pointer to new caller's buffer.
173//
174// --*/
175//
176VOID
177MyFree (
178  VOID       *Ptr,
179  UINT8      File[],
180  UINTN      Line
181  )
182;
183//
184// *++
185// Description:
186//
187//  Release a previously allocated buffer.  Invalid parameters will cause
188//  MyFree() to fail with an exit(1) call.
189//
190// Parameters:
191//
192//  Ptr := Pointer to the caller's buffer to be freed.
193//         A NULL pointer will be ignored.
194//
195//  File := Set to __FILE__ by macro expansion.
196//
197//  Line := Set to __LINE__ by macro expansion.
198//
199// Returns:
200//
201//  n/a
202//
203// --*/
204//
205#else /* USE_MYALLOC */
206
207//
208// Nothing to do when USE_MYALLOC is zero.
209//
210#define alloc_check(final)
211
212#endif /* USE_MYALLOC */
213#endif /* _MYALLOC_H_ */
214
215/* eof - MyAlloc.h */
216