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

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

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  chunk_create
 *  chunk_destroy
 *  chunk_claim
 *  chunk_makeBinary
 *  chunk_read
 *  chunk_enum
 *  chunk_save
 */

/* --- chunk_create --- *
 *
 * On entry:	--
 *
 * On exit:	R0 == chunk file handle
 *		May return an error
 *
 * Use:		Creates a new chunk file structure and returns a handle to
 *		it.
 */

extern routine chunk_create;

/* --- chunk_destroy --- *
 *
 * On entry:	R0 == chunk file handle
 *
 * On exit:	--
 *
 * Use:		Removes a chunk file structure from memory.  Chunk data in
 *		flex blocks is freed; chunk claimers who free flex blocks
 *		should clear the anchors to 0.
 */

extern routine chunk_destroy;

/* --- chunk_claim --- *
 *
 * On entry:	R0 == chunk file handle
 *		R1 == pointer to chunk name
 *		R2 == pointer to saver routine, or 0 for none, or -1 for no
 *			change
 *		R3 == R10 value to pass to saver
 *		R4 == R12 value to pass to saver
 *
 * On exit:	R1 == chunk handle/anchor
 *		CS if the chunk already existed
 *		May return an error
 *
 * Use:		Claims a chunk, installing a save handler for it.  The chunk
 *		handle returned is actually the address of a flex anchor for
 *		the chunk's data (use flex_size to find the block's size).
 *		If the save handle is 0, the data in the flex block (which
 *		may be modified) is saved directly from the block.  Otherwise
 *		the save routine is expected to save its data, using xsave.
 *
 *		The anchor is followed by 3 unused words -- you can use them
 *		for whatever you want.
 *
 *		Warning: this routine may move flex blocks.
 */

extern routine chunk_claim;

/* --- chunk_makeBinary --- *
 *
 * On entry:	R0 == chunk file handle
 *		R1 == chunk handle
 *
 * On exit:	--
 *
 * Use:		Marks a given chunk as containing binary data.
 */

extern routine chunk_makeBinary;

/* --- chunk_read --- *
 *
 * On entry:	R0 == chunk file handle
 *		R1 == address of a flex anchor
 *
 * On exit:	May return an error
 *
 * Use:		Merges the data contained in the flex block with that already
 *		in the chunk file.  If the chunk file is empty, this is
 *		equivalent to a load.  Data from the flex block is appended
 *		to chunks already loaded where appropriate.
 *
 *		Warning: this routine may move flex blocks.
 */

extern routine chunk_read;

/* --- chunk_enum --- *
 *
 * On entry:	R0 == chunk file handle
 *		R1 == 0 for first call or continuation value
 *
 * On exit:	CC if this isn't over yet, and
 *		  R1 == continuation value for next call
 *		  R2 == pointer to chunk name
 *		else CS and
 *		  R1 == 0
 *		  R2 preserved
 *
 * Use:		Allows you to enumerate the chunks in a chunk file structure.
 */

extern routine chunk_enum;

/* --- chunk_save --- *
 *
 * On entry:	R0 == chunk file handle
 *
 * On exit:	May return an error
 *
 * Use:		Saves a chunk file to xsave's current output.
 */

extern routine chunk_save;

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

#endif