BaseTools: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / BaseTools / Source / C / Common / MyAlloc.h

/** @file\r
Header file for memory allocation tracking functions.\r
\r
Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _MYALLOC_H_\r
#define _MYALLOC_H_\r
\r
#include <stdio.h>\r
#include <stdlib.h>\r
#include <string.h>\r
\r
#include <Common/BaseTypes.h>\r
\r
//\r
// Default operation is to use the memory allocation tracking functions.\r
// To over-ride add "#define USE_MYALLOC 0" to your program header and/or\r
// source files as needed.  Or, just do not include this header file in\r
// your project.\r
//\r
#ifndef USE_MYALLOC\r
#define USE_MYALLOC 1\r
#endif\r
\r
#if USE_MYALLOC\r
//\r
// Replace C library allocation routines with MyAlloc routines.\r
//\r
#define malloc(size)        MyAlloc ((size), __FILE__, __LINE__)\r
#define calloc(count, size) MyAlloc ((count) * (size), __FILE__, __LINE__)\r
#define realloc(ptr, size)  MyRealloc ((ptr), (size), __FILE__, __LINE__)\r
#define free(ptr)           MyFree ((ptr), __FILE__, __LINE__)\r
#define alloc_check(final)  MyCheck ((final), __FILE__, __LINE__)\r
\r
//\r
// Structure for checking/tracking memory allocations.\r
//\r
typedef struct MyAllocStruct {\r
  UINTN                 Cksum;\r
  struct MyAllocStruct  *Next;\r
  UINTN                 Line;\r
  UINTN                 Size;\r
  UINT8                 *File;\r
  UINT8                 *Buffer;\r
} MY_ALLOC_STRUCT;\r
//\r
// Cksum := (UINTN)This + (UINTN)Next + Line + Size + (UINTN)File +\r
//          (UINTN)Buffer;\r
//\r
// Next := Pointer to next allocation structure in the list.\r
//\r
// Line := __LINE__\r
//\r
// Size := Size of allocation request.\r
//\r
// File := Pointer to __FILE__ string stored immediately following\r
//         MY_ALLOC_STRUCT in memory.\r
//\r
// Buffer := Pointer to UINT32 aligned storage immediately following\r
//           the NULL terminated __FILE__ string.  This is UINT32\r
//           aligned because the underflow signature is 32-bits and\r
//           this will place the first caller address on a 64-bit\r
//           boundary.\r
//\r
//\r
// Signatures used to check for buffer overflow/underflow conditions.\r
//\r
#define MYALLOC_HEAD_MAGIK  0xBADFACED\r
#define MYALLOC_TAIL_MAGIK  0xDEADBEEF\r
\r
VOID\r
MyCheck (\r
  BOOLEAN      Final,\r
  UINT8        File[],\r
  UINTN        Line\r
  )\r
;\r
//\r
// *++\r
// Description:\r
//\r
//  Check for corruptions in the allocated memory chain.  If a corruption\r
//  is detection program operation stops w/ an exit(1) call.\r
//\r
// Parameters:\r
//\r
//  Final := When FALSE, MyCheck() returns if the allocated memory chain\r
//           has not been corrupted.  When TRUE, MyCheck() returns if there\r
//           are no un-freed allocations.  If there are un-freed allocations,\r
//           they are displayed and exit(1) is called.\r
//\r
//\r
//  File := Set to __FILE__ by macro expansion.\r
//\r
//  Line := Set to __LINE__ by macro expansion.\r
//\r
// Returns:\r
//\r
//  n/a\r
//\r
// --*/\r
//\r
VOID  *\r
MyAlloc (\r
  UINTN      Size,\r
  UINT8      File[],\r
  UINTN      Line\r
  )\r
;\r
//\r
// *++\r
// Description:\r
//\r
//  Allocate a new link in the allocation chain along with enough storage\r
//  for the File[] string, requested Size and alignment overhead.  If\r
//  memory cannot be allocated or the allocation chain has been corrupted,\r
//  exit(1) will be called.\r
//\r
// Parameters:\r
//\r
//  Size := Number of bytes (UINT8) requested by the called.\r
//          Size cannot be zero.\r
//\r
//  File := Set to __FILE__ by macro expansion.\r
//\r
//  Line := Set to __LINE__ by macro expansion.\r
//\r
// Returns:\r
//\r
//  Pointer to the caller's buffer.\r
//\r
// --*/\r
//\r
VOID  *\r
MyRealloc (\r
  VOID       *Ptr,\r
  UINTN      Size,\r
  UINT8      File[],\r
  UINTN      Line\r
  )\r
;\r
//\r
// *++\r
// Description:\r
//\r
//  This does a MyAlloc(), memcpy() and MyFree().  There is no optimization\r
//  for shrinking or expanding buffers.  An invalid parameter will cause\r
//  MyRealloc() to fail with a call to exit(1).\r
//\r
// Parameters:\r
//\r
//  Ptr := Pointer to the caller's buffer to be re-allocated.\r
//         Ptr cannot be NULL.\r
//\r
//  Size := Size of new buffer.  Size cannot be zero.\r
//\r
//  File := Set to __FILE__ by macro expansion.\r
//\r
//  Line := Set to __LINE__ by macro expansion.\r
//\r
// Returns:\r
//\r
//  Pointer to new caller's buffer.\r
//\r
// --*/\r
//\r
VOID\r
MyFree (\r
  VOID       *Ptr,\r
  UINT8      File[],\r
  UINTN      Line\r
  )\r
;\r
//\r
// *++\r
// Description:\r
//\r
//  Release a previously allocated buffer.  Invalid parameters will cause\r
//  MyFree() to fail with an exit(1) call.\r
//\r
// Parameters:\r
//\r
//  Ptr := Pointer to the caller's buffer to be freed.\r
//         A NULL pointer will be ignored.\r
//\r
//  File := Set to __FILE__ by macro expansion.\r
//\r
//  Line := Set to __LINE__ by macro expansion.\r
//\r
// Returns:\r
//\r
//  n/a\r
//\r
// --*/\r
//\r
#else /* USE_MYALLOC */\r
\r
//\r
// Nothing to do when USE_MYALLOC is zero.\r
//\r
#define alloc_check(final)\r
\r
#endif /* USE_MYALLOC */\r
#endif /* _MYALLOC_H_ */\r
\r
/* eof - MyAlloc.h */\r