tomwalters@0: /*
tomwalters@0:     wrap.h
tomwalters@0:     ======
tomwalters@0: 
tomwalters@0:     wrap alocations with debugging information for program verifiaction.
tomwalters@0: 
tomwalters@0: */
tomwalters@0: 
tomwalters@0: /*
tomwalters@0:     The following routines "wrap" memory with a frame as it is  allocated.
tomwalters@0:     The  information  in the frame is sufficient to check if the bounds of
tomwalters@0:     the alloacation have been exceeded.  Part of the frame is  used  as  a
tomwalters@0:     pointer for a linked list  which  is  also  assembled  containing  all
tomwalters@0:     allocated  memory  chunks.  This  enables  a  call  at any time to the
tomwalters@0:     routine "checkWrapping()" to examine all  the  frames  of  all  memory
tomwalters@0:     allocations for corruption while an application runs.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 	Memory map of a framed allocation after "wrapping"
tomwalters@0: 
tomwalters@0: 		   +--------------+
tomwalters@0: 	   head--> | struct _head |
tomwalters@0: 		   +--------------+
tomwalters@0: 	wrapped--> |  user data   |
tomwalters@0: 		   |      .       |
tomwalters@0: 		   |      .       |
tomwalters@0: 		   |      .       |
tomwalters@0: 		   |              |
tomwalters@0: 		   +--------------+
tomwalters@0: 	   tail--> | struct _tail |
tomwalters@0: 		   +--------------+
tomwalters@0: 
tomwalters@0: 
tomwalters@0:     On allocation the  pointer  returned  from  tyhe  system  becomes  the
tomwalters@0:     pointer  to  in instance of the stucture "_head".  A tail structure is
tomwalters@0:     then constructed containing a repeat of the size feild of  the  header
tomwalters@0:     for  consistency  checking  and a pointer to the previous allocation's
tomwalters@0:     frame.  The user receives a pointer to  the  memory  bytes  availiable
tomwalters@0:     after  the  head  structure  and  is therefore unaware of the wrapping
tomwalters@0:     process.  On deallocation or reallocation the framed memory is  simply
tomwalters@0:     unwrapped  by the reverse process checking for corruption before being
tomwalters@0:     passed to the system memory allocation routines.
tomwalters@0: 
tomwalters@0: */
tomwalters@0: 
tomwalters@0: /* bits rounded up in alligning the tail structure */
tomwalters@0: 
tomwalters@0: #define BITS_ROUND 4
tomwalters@0: 
tomwalters@0: /* rounds up byte size specification to ensure tail structure's elements are aligned */
tomwalters@0: 
tomwalters@0: #define ROUNDUP( _size ) ( ( _size ) + ( 1 << BITS_ROUND ) - 1 >> BITS_ROUND << BITS_ROUND )
tomwalters@0: 
tomwalters@0: /* Calculates the size required for the wrapped allocation including frame. */
tomwalters@0: 
tomwalters@0: #define WRAPPED_SIZE( _size ) ( ROUNDUP( sizeof ( struct _head ) ) + ROUNDUP( _size ) + sizeof( struct _tail ) )
tomwalters@0: 
tomwalters@0: 
tomwalters@0: struct _head { char *where ; struct _head **pointing, *previous ; unsigned size ; } ;
tomwalters@0: struct _tail { unsigned size ; } ;
tomwalters@0: 
tomwalters@0: extern Pointer wrap( /* char   *mem, unsigned size, char where[] */ ) ;
tomwalters@0: extern char *unwrap( /* Pointer mem, unsigned size               */ ) ;
tomwalters@0: 
tomwalters@0: