/*
 * alloc.h
 *
 * [Generated from alloc, 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 __alloc_h
#define __alloc_h

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

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  alloc_register
 *  alloc_useOSHeap
 *  alloc
 *  free
 *  alloc_init
 *  alloc_error
 */

/* --- alloc_register --- *
 *
 * On entry:	R0 == pointer to allocator function
 *		R1 == pointer to free function
 *		R2 == workspace pointer to pass to them in R12
 *
 * On exit:	--
 *
 * Use:		Registers two functions to be used as a heap manager by
 *		alloc and free.
 *
 *		The allocator is entered with R0 as the	size of block
 *		required, and should exit with CC and R0 == pointer to the
 *		block allocated if successful, CS if there wasn't enough
 *		memory and generate any other errors that occur.  Registers
 *		other than R0 must be preserved.
 *
 *		The freer is entered with R0 == pointer to block to free.
 *		It should exit with all registers preserved.  If anything
 *		goes wrong, it should generate an error.
 */

extern routine alloc_register;

/* --- alloc_useOSHeap --- *
 *
 * On entry:	R1 == pointer to OS_Heap-managed heap to use
 *
 * On exit:	--
 *
 * Use:		Registers an OS_Heap heap to use to allocate memory when
 *		alloc is called.
 */

extern routine alloc_useOSHeap;

/* --- alloc --- *
 *
 * On entry:	R0 == size of block to allocate from current heap
 *
 * On exit:	R0 == pointer to block and CC if it all worked
 *		CS if there wasn't enough memory (R0 corrupted)
 *
 * Use:		Allocates R0 bytes from a heap manager.  This routine will
 *		attempt to allocate memory from the current heaps in order
 *		of registration (i.e. the Sapphire OS_Heap first etc.) until
 *		either one which can service the request is found, or all
 *		the heaps have been tried.
 */

extern routine alloc;

/* --- free --- *
 *
 * On entry:	R0 == pointer to block allocated by alloc
 *
 * On exit:	--
 *
 * Use:		Frees a block allocated by alloc, regardless of which heap
 *		it came from.
 */

extern routine free;

/* --- alloc_init --- *
 *
 * On entry:	--
 *
 * On exit:	--
 *
 * Use:		Initialises the alloc system, and sets it up to use the
 *		kernel-provided OS_Heap area.
 */

extern routine alloc_init;

/* --- alloc_error --- *
 *
 * On entry:	--
 *
 * On exit:	V set and R0 == pointer to an error about not having enough
 *		memory.
 *
 * Use:		Returns an error suitable for displaying to a user if there
 *		isn't enough memory left.
 */

extern routine alloc_error;

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

#endif