;
; dynHeap.sh
;
; New heap management for Dynamite
;
; © 1994 Straylight
;

;----- Overview -------------------------------------------------------------
;
; Functions provided:
;
;  dh_alloc
;  dh_free
;  dh_freeWithID
;  dh_blockInfo
;  dh_changeID
;  dh_reduce
;  dh_compact
;  dh_lock
;  dh_unlock
;  dh_save
;  dh_load
;  dh_extend
;  dh_midExtend
;  dh_checkHeap
;  dh_changeAnchor
;  dh_dump

		[	:LNOT::DEF:dynHeap__dfn
		GBLL	dynHeap__dfn

; --- dh_alloc ---
;
; On entry:	R0 == pointer to anchor
;		R1 == size to allocate in bytes
;		R2 == ID value to store
;
; On exit:	R0 and R1 preserved
;		R2 == address of block allocated
;
; Use:		Allocates a block from the Dynamite heap.

		IMPORT	dh_alloc

; --- dh_free ---
;
; On entry:	R0 == pointer to anchor of block to free
;
; On exit:	--
;
; Use:		Frees a Dynamite block.

		IMPORT	dh_free

; --- dh_freeWithID ---
;
; On entry:	R0 == ID of all blocks to free
;
; On exit:	--
;
; Use:		Frees all allocated blocks with a given ID number.

		IMPORT	dh_freeWithID

; --- dh_blockInfo ---
;
; On entry:	R0 == address of block anchor
;
; On exit:	R0 preserved
;		R1 == address of block
;		R2 == size of block
;		R3 == block ID
;
; Use:		Returns information about a Dynamite block

		IMPORT	dh_blockInfo

; --- dh_changeID ---
;
; On entry:	R0 == address of anchor block, or 0 for all
;		R1 == new ID
;		R2 == old ID (if R0 == 0)
;
; On exit:	--
;
; Use:		This call is use to change the ID of either an individual
;		block (R0 == address of anchor), or the ID of all the
;		blocks with the ID passed in R2 (if R0 == 0).

		IMPORT	dh_changeID

; --- dh_reduce ---
;
; On entry:	--
;
; On exit:	CS if there was nothing we could do
;
; Use:		Tries to shunt the free space in the heap off the end and
;		back into the operating system's free pool.  It does it a
;		little bit and then stops, rather like those workmen on the
;		M40.

		IMPORT	dh_reduce

; --- dh_compact ---
;
; On entry:	--
;
; On exit:	--
;
; Use:		Does a full compaction of the heap.

		IMPORT	dh_compact

; --- dh_lock ---
;
; On entry:	--
;
; On exit:	R10 corrupted (SWIs don't care about this)
;
; Use:		Locks the heap, so that compaction entirely fails to happen.

		IMPORT	dh_lock

; --- dh_unlock ---
;
; On entry:	--
;
; On exit:	R10 corrupted (SWIs don't care about this)
;
; Use:		Unlocks the heap, so that compaction can happen again, maybe.

		IMPORT	dh_unlock

; --- dh_save ---
;
; On entry:	R0 == mask of registers to save
;
; On exit:	R10, R11 corrupted
;
; Use:		Saves a load of registers on the Dynamite relocation stack.
;		The mask in R0 contains a bit set for each register to save:
;		bit 3 set means save R3 etc.  Since this is a SWI, only
;		R1-R9 can be saved on the stack.

		IMPORT	dh_save

; --- dh_load ---
;
; On entry:	R0 == mask of registers to load
;
; On exit:	R10, R11 corrupted
;
; Use:		Loads a load of registers on the Dynamite relocation stack.
;		The mask in R0 contains a bit set for each register to load:
;		bit 3 set means load R3 etc.  Since this is a SWI, only
;		R1-R9 can be read from the stack.

		IMPORT	dh_load

; --- dh_extend ---
;
; On entry:	R0 == address of block anchor
;		R1 == new size for block
;
; On exit:	R0 preserved
;		R1 == address of block, may have moved
;
; Use:		Changes the size of a block.

		IMPORT	dh_extend

; --- dh_midExtend ---
;
; On entry:	R0 == address of block anchor
;		R1 == byte offset from block start
;		R2 == number of bytes to insert
;
; On exit:	R0 preserved
;		R1 == address of block, may have moved
;
; Use:		Inserts or removes bytes at a given offset into a Dynamite
;		heap block.

		IMPORT	dh_midExtend

; --- dh_checkHeap ---
;
; On entry:	--
;
; On exit:	May return an error
;
; Use:		Checks the current internal format of the heap to make
;		sure that it hasn't been corrupted in any way.
;		If the integrity check fails then an error is returned.

		IMPORT	dh_checkHeap

; --- dh_changeAnchor ---
;
; On entry:	R0 == pointer to anchor for block
;		R1 == address of new anchor
;
; On exit:	--
;
; Use:		Adjusts a block's anchor, in case it moves.

		IMPORT	dh_changeAnchor

; --- dh_dump ---
;
; On entry:	--
;
; On exit:	--
;
; Use:		Outputs a textual description of the dynamite heap, giving
;		details of each block within it.

		IMPORT	dh_dump

		]

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

		END