BaseTools/Source/C/Common/MyAlloc.h

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