Memory Allocation Concept

Allocate a Block of Memory          - ALLOC
Initialize Memory Allocation System - IALLOC
Check for Top of Available Memory   - GMEMTOP
-------------------------------------------------------------
		Memory Allocation Concept

The concept of memory allocation with these routines is
relatively simple; SYSLIB routines provide primative memory
allocation/deallocation capabilities, but you stay in control.

The basic idea is to reserve a buffer in memory from which to
take bits and pieces from at a time.  The bounding addresses
of this buffer are specified (or set by default) by the IALLOC
routine, and the ALLOC routine is used to obtain subbuffers
from this larger buffer when needed.  ALLOC constantly checks
to see if the buffer has enough space left to grant the request
for a subbuffer, and if it does, the subbuffer is provided.

The largest buffer which may be reserved by the IALLOC routine
is that buffer which extends from the end of the program to
just below the CCP.  This buffer is selected if IALLOC is
called with A=0.

The following illustrates use of the largest buffer possible:

	XOR	A		; Select Full Buffer
	CALL	IALLOC
	...
	LD	DE,1024		; Request 1K
	CALL	ALLOC
	JR	Z,MEMOVFL	; Abort if Memory Overflow
	LD	(BUF1),HL	; Set Pointer to 1st Subbuffer
	...
	LD	DE,36		; Request 36 bytes
	CALL	ALLOC
	JR	Z,MEMOVFL	; Abort if Memory Overflow
	LD	(BUF2),HL	; Set Pointer to 2nd Subbuffer
	...

This memory allocation scheme also permits the division of
memory into a group of buffers.  One buffer may be allocated,
its address preserved, another buffer may be allocated, its
address preserved, and then subsequent calls to IALLOC may be
used to select one buffer or the other.  Each call to IALLOC
frees the entire buffer area, so care should be taken in doing
this.  For example:

	...
	CALL	CODEND		; Use Codend as First Buffer
	LD	(BUF1),HL
	EX	DE,HL		; Address in DE
	LD	HL,1024		; 1K for this buffer
	ADD	HL,DE		; HL pts to after this buffer
	EX	DE,HL		; HL is start, DE is end
	LD	A,3		; Select Start and End
	CALL	IALLOC
	...
Example, Con't

	...
	CALL	ALLOC		; Calls to ALLOC
	...
	LD	HL,(BUF1)	; Pt to 1st Buffer
	LD	DE,1024		; Set 2nd Buffer
	ADD	HL,DE		; Pt to 2nd Buffer
	LD	(BUF2),HL
	EX	DE,HL
	ADD	HL,DE		; Pt to end of 2nd 1K Buffer
	EX	DE,HL		; HL is start, DE is end
	LD	A,3		; Select Start and End
	CALL	IALLOC
	...
	CALL	ALLOC		; Calls to ALLOC
	...

ALLOC - Allocate a Block of Memory

  ENTRY: DE = Number of bytes requested
  EXIT : HL = Address of first byte allocated
	  A <> 0, Zero Flag Reset (NZ) if request granted
	      A = 0, Zero Flag Set (Z) if not enough space
  USES : AF,HL

 Usage:  This routine is used to allocate a block of memory
  from the larger block reserved by IALLOC.  Block sizes may be
  as small as one byte, or as large as the entire buffer.  If
  the memory request is granted, the starting address is
  returned.  Note: A call to IALLOC must be made before
  calling ALLOC.

IALLOC - Initialize Memory Allocation Buffer

  ENTER: HL = Possible Starting Address of Buffer
	 DE = Possible Ending Address of Buffer
	  A = Selection Code:
		Bit 0 - 1 = Use HL as Starting Address
			0 = Use CODEND Value
		Bit 1 - 1 = Use DE as Ending Address
			0 = Use CCP-1
  EXIT : None
  USES : None

 Usage:  This routine is used to initialize the buffer from
  which memory is allocated via calls to ALLOC.  You may
  specify the bounds of this buffer, or use default bounds
  set by IALLOC.

GETMTOP - Return the highest TPA byte below the CCP.

  ENTER: None
  EXIT : HL - Contains the highest byte below CCP
  USES : HL,AF

 Usage:  This routine is commonly used to obtain the top of
  available memory in routines which exit back to the Command
  Processor with a simple RETurn instruction instead of a Warm
  Boot.  This routine returns the highest available memory
  location beneath the Command Processor to avoid overwriting
  it.  Note: If you are writing for a ZCPR3 environment, use
  the corresponding GZMTOP routine in Z3LIB.