/*
 * heap.h
 *
 * [Generated from heap, 25 September 1996]
 */

#if !defined(__CC_NORCROFT) || !defined(__arm)
  #error You must use the Norcroft ARM Compiler for Sapphire programs
#endif

#pragma include_only_once
#pragma force_top_level

#ifndef __heap_h
#define __heap_h

#ifndef __sapphire_h
  #include "sapphire.h"
#endif

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  heap_init
 *  heap_useHeap
 *  heap_info
 *  heap_alloc
 *  heap_free
 *  heap_reAlloc
 */

/* --- heap_init --- *
 *
 * On entry:	--
 *
 * On exit:	--
 *
 * Use:		Initialises the heap system for use.
 */

extern routine heap_init;

/* --- heap_useHeap --- *
 *
 * On entry:	--
 *
 * On exit:	--
 *
 * Use:		Registers the resizing heap as the current allocator.
 */

extern routine heap_useHeap;

/* --- heap_info --- *
 *
 * On entry:	--
 *
 * On exit:	R0 == current heap size
 *		R1 == amount of memory free in the heap
 *		R2 == size of the largest block free
 *
 * Use:		Describes the heap's current status.
 */

extern routine heap_info;

/* --- heap_alloc --- *
 *
 * On entry:	R0 == size of block wanted
 *
 * On exit:	CC if enough memory was found and
 *		  R0 == pointer to the block allocated
 *		else CS and
 *		  R0 corrupted
 *
 * Use:		Allocates a block of at least a given size from a heap.  If
 *		the heap is not big enough, more is claimed from the
 *		operating system.
 */

extern routine heap_alloc;

/* --- heap_free --- *
 *
 * On entry:	R0 == pointer to a block created with heap_alloc
 *
 * On exit:	--
 *
 * Use:		Frees a block allocated using heap_alloc.  It tries to
 *		shrink the heap as much as possible afterwards.
 */

extern routine heap_free;

/* --- heap_reAlloc --- *
 *
 * On entry:	R0 == pointer to block whose size we want to change
 *		R1 == the new size of the block
 *
 * On exit:	CC if block was resized, and
 *		  R0 == pointer to the block (which may have moved)
 *		else CS and
 *		  R0 corrupted
 *
 * Use:		Changes the size of a heap block.  If possible, the block's
 *		position is unchanged, but this may not always be the case.
 *
 *		Note that changing a block's size to 0 is permitted.
 */

extern routine heap_reAlloc;

/*----- That's all, folks -------------------------------------------------*/

#endif