;
; alloc.sh
;
; Redirectable memory allocation
;
; © 1994-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;----- Overview -------------------------------------------------------------
;
; Functions provided:
;
;  alloc_register
;  alloc_useOSHeap
;  alloc
;  free
;  alloc_init
;  alloc_error

		[	:LNOT::DEF:alloc__dfn
		GBLL	alloc__dfn

; --- 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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	free

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

		IMPORT	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.

		IMPORT	alloc_error

		]

;----- That's all, folks ----------------------------------------------------

		END