annotate stitch/wrap.h @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

/*
    wrap.h
    ======

    wrap alocations with debugging information for program verifiaction.

*/

/*
    The following routines "wrap" memory with a frame as it is  allocated.
    The  information  in the frame is sufficient to check if the bounds of
    the alloacation have been exceeded.  Part of the frame is  used  as  a
    pointer for a linked list  which  is  also  assembled  containing  all
    allocated  memory  chunks.  This  enables  a  call  at any time to the
    routine "checkWrapping()" to examine all  the  frames  of  all  memory
    allocations for corruption while an application runs.


	Memory map of a framed allocation after "wrapping"

		   +--------------+
	   head--> | struct _head |
		   +--------------+
	wrapped--> |  user data   |
		   |      .       |
		   |      .       |
		   |      .       |
		   |              |
		   +--------------+
	   tail--> | struct _tail |
		   +--------------+


    On allocation the  pointer  returned  from  tyhe  system  becomes  the
    pointer  to  in instance of the stucture "_head".  A tail structure is
    then constructed containing a repeat of the size feild of  the  header
    for  consistency  checking  and a pointer to the previous allocation's
    frame.  The user receives a pointer to  the  memory  bytes  availiable
    after  the  head  structure  and  is therefore unaware of the wrapping
    process.  On deallocation or reallocation the framed memory is  simply
    unwrapped  by the reverse process checking for corruption before being
    passed to the system memory allocation routines.

*/

/* bits rounded up in alligning the tail structure */

#define BITS_ROUND 4

/* rounds up byte size specification to ensure tail structure's elements are aligned */

#define ROUNDUP( _size ) ( ( _size ) + ( 1 << BITS_ROUND ) - 1 >> BITS_ROUND << BITS_ROUND )

/* Calculates the size required for the wrapped allocation including frame. */

#define WRAPPED_SIZE( _size ) ( ROUNDUP( sizeof ( struct _head ) ) + ROUNDUP( _size ) + sizeof( struct _tail ) )


struct _head { char *where ; struct _head **pointing, *previous ; unsigned size ; } ;
struct _tail { unsigned size ; } ;

extern Pointer wrap( /* char   *mem, unsigned size, char where[] */ ) ;
extern char *unwrap( /* Pointer mem, unsigned size               */ ) ;